setting local variables

setting local variables

[Eric Abrahamsen]

Hi there,

I'm writing an Emacs manual in Org, using
https://github.com/tarsius/ox-texinfo-plus to make things a bit easier.

I'm trying to locally set `sentence-end-double-space' to t, to conform
to the Emacs manual style. If I set it at the top of the file with:

-*- sentence-end-double-space: t -*-

That line appears in the exported *.texi/*.info files (which I don't
think it should!).

I'm not able to set it at the bottom of the file, either, with a "Local
Variables:" section, as the Org comment syntax isn't recognized by
emacs (or maybe it's the indentation?), and the elisp comment syntax is
exported literally.

How do you all set local variables in Org files to be exported?

Thanks,
Eric

Re: setting local variables

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 875 bytes --]

On Wed, Aug 2, 2017, 5:54 PM Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

>
> I'm trying to locally set `sentence-end-double-space' to t, to conform
> to the Emacs manual style. If I set it at the top of the file with:
>
> -*- sentence-end-double-space: t -*-
>

It should be the very first line and prefixed with Org comment characters
"# ".

That line appears in the exported *.texi/*.info files (which I don't
> think it should!).
>

May be you missed out the "# "?

How do you all set local variables in Org files to be exported?
>

I put this at the bottom of each Org file and it works well:


=====
* Footnotes
* COMMENT Local Variables :ARCHIVE:
# Local Variables:
# fill-column: 70
# eval: (auto-fill-mode 1)
# End:
=====

(Pre-adding empty Footnotes section too so that if I add footnotes, the
file-end comments don't end up in Footnotes.)

> --

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1948 bytes --]

Re: setting local variables

[Eric Abrahamsen]

Kaushal Modi <kaushal.modi@gmail.com> writes:

> On Wed, Aug 2, 2017, 5:54 PM Eric Abrahamsen <eric@ericabrahamsen.net> wrote:
>
>  I'm trying to locally set `sentence-end-double-space' to t, to conform
>  to the Emacs manual style. If I set it at the top of the file with:
>
>  -*- sentence-end-double-space: t -*-
>
> It should be the very first line and prefixed with Org comment characters "# ".

Bah, I should have known that -- I wasn't adding the comment character.
Thanks for setting me straight!

Eric

Re: setting local variables

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> I'm writing an Emacs manual in Org, using
> https://github.com/tarsius/ox-texinfo-plus to make things a bit
> easier.

I don't know that library, but as a biased POV, it would be nice to use
"ox-texinfo" and let us know about its shortcomings. Just saying.

Regards,

-- 
Nicolas Goaziou

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> I'm writing an Emacs manual in Org, using
>> https://github.com/tarsius/ox-texinfo-plus to make things a bit
>> easier.
>
> I don't know that library, but as a biased POV, it would be nice to use
> "ox-texinfo" and let us know about its shortcomings. Just saying.

Oh I don't think it's about shortcomings, just about having a version
that's tweaked specifically for writing Emacs manuals. I _really_ want
my packages to have info manuals, and I _really_ don't want to learn how
to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
lot of work. Then I noticed that the Magit manuals used this
texinfo-plus thing, and it seemed good enough.

I think what might be nice would be to have another exporter, derived
from ox-texinfo, specifically for writing Emacs manuals, that helps
authors conform to the Emacs manual conventions. The way texinfo-plus
handles lists of keybindings/user options/etc is nice, and it appears to
set up the indexes for you, you only have to add concept index entries
manually.

Does that sound feasible? It would be great if this was available out of
the box.

Eric

Re: setting local variables

[Nicolas Goaziou]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Oh I don't think it's about shortcomings, just about having a version
> that's tweaked specifically for writing Emacs manuals. I _really_ want
> my packages to have info manuals, and I _really_ don't want to learn how
> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
> lot of work. Then I noticed that the Magit manuals used this
> texinfo-plus thing, and it seemed good enough.

I think "ox-texinfo" is (almost) able to write Emacs manuals.

IMO, you are comparing oranges and apples. Org's manual is historically
written as a (very convoluted) pure Texinfo document, with many macros
and different authors. Trying to convert it to Org for an Org to Texinfo
process is bound to be painful. OTOH, Magit's manual is probably more
straightforward, i.e., written as an Org document from the beginning,
with simpler requirements.

In both cases, you cannot eschew learning a bit of Texinfo, if only for
the various indices commands and the installation part in the Info
directory.

> I think what might be nice would be to have another exporter, derived
> from ox-texinfo, specifically for writing Emacs manuals, that helps
> authors conform to the Emacs manual conventions. The way texinfo-plus
> handles lists of keybindings/user options/etc is nice, and it appears to
> set up the indexes for you, you only have to add concept index entries
> manually.

AFAIU, the way texinfo-plus handles lists of ... is certainly nice, but
it's unrelated to Emacs manual conventions. It helps authors conform
Magit's author conventions. Those are fine, but I'm pretty sure not all
Emacs manuals follow them (Org doesn't, obviously).

> Does that sound feasible? It would be great if this was available out of
> the box.

Even though such specialized back-ends are a good thing, I don't think
Org needs another Texinfo back-end in core, however.

"ox-texinfo.el" is really getting better. It is very versatile so it can
bend to almost any convention.

I won't pretend it makes learning Texinfo useless, though, because you
need to learn it to write good manuals. The devil is in the details, and
those are sometimes located at the Texinfo level.

Regards,

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> Oh I don't think it's about shortcomings, just about having a version
>> that's tweaked specifically for writing Emacs manuals. I _really_ want
>> my packages to have info manuals, and I _really_ don't want to learn how
>> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
>> lot of work. Then I noticed that the Magit manuals used this
>> texinfo-plus thing, and it seemed good enough.
>
> I think "ox-texinfo" is (almost) able to write Emacs manuals.
>
> IMO, you are comparing oranges and apples. Org's manual is historically
> written as a (very convoluted) pure Texinfo document, with many macros
> and different authors. Trying to convert it to Org for an Org to Texinfo
> process is bound to be painful. OTOH, Magit's manual is probably more
> straightforward, i.e., written as an Org document from the beginning,
> with simpler requirements.
>
> In both cases, you cannot eschew learning a bit of Texinfo, if only for
> the various indices commands and the installation part in the Info
> directory.

Well, I'll admit laziness has been my major motivation throughout the
whole process.

>> I think what might be nice would be to have another exporter, derived
>> from ox-texinfo, specifically for writing Emacs manuals, that helps
>> authors conform to the Emacs manual conventions. The way texinfo-plus
>> handles lists of keybindings/user options/etc is nice, and it appears to
>> set up the indexes for you, you only have to add concept index entries
>> manually.
>
> AFAIU, the way texinfo-plus handles lists of ... is certainly nice, but
> it's unrelated to Emacs manual conventions. It helps authors conform
> Magit's author conventions. Those are fine, but I'm pretty sure not all
> Emacs manuals follow them (Org doesn't, obviously).

The main thing I was after was semi-automated indexing (obviously some
of it you have to do yourself). I just looked more closely at the texi
output that texinfo-plus produced, and it seems to only be doing concept
and key indexing, not function or variable indexing. So that's not as
helpful as I thought.

>> Does that sound feasible? It would be great if this was available out of
>> the box.
>
> Even though such specialized back-ends are a good thing, I don't think
> Org needs another Texinfo back-end in core, however.
>
> "ox-texinfo.el" is really getting better. It is very versatile so it can
> bend to almost any convention.
>
> I won't pretend it makes learning Texinfo useless, though, because you
> need to learn it to write good manuals. The devil is in the details, and
> those are sometimes located at the Texinfo level.

I guess what I'm missing is clear guidelines on how to write manuals for
Emacs. I did look around, didn't find anything, and then just decided I
would use the easiest solution to hand, even if it wasn't ideal. If I
had a clear sense of what I was working towards, I'd probably put in the
time to learn the basics of texi and ox-texinfo. I guess I'll ask on
emacs.help.

At any rate, all this was in no way meant to be a criticism of
ox-texinfo, which I obviously haven't taken the time to learn...

Eric

Re: setting local variables

[Eric Abrahamsen]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> Oh I don't think it's about shortcomings, just about having a version
>>> that's tweaked specifically for writing Emacs manuals. I _really_ want
>>> my packages to have info manuals, and I _really_ don't want to learn how
>>> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
>>> lot of work. Then I noticed that the Magit manuals used this
>>> texinfo-plus thing, and it seemed good enough.
>>
>> I think "ox-texinfo" is (almost) able to write Emacs manuals.
>>
>> IMO, you are comparing oranges and apples. Org's manual is historically
>> written as a (very convoluted) pure Texinfo document, with many macros
>> and different authors. Trying to convert it to Org for an Org to Texinfo
>> process is bound to be painful. OTOH, Magit's manual is probably more
>> straightforward, i.e., written as an Org document from the beginning,
>> with simpler requirements.
>>
>> In both cases, you cannot eschew learning a bit of Texinfo, if only for
>> the various indices commands and the installation part in the Info
>> directory.
>
> Well, I'll admit laziness has been my major motivation throughout the
> whole process.
>
>>> I think what might be nice would be to have another exporter, derived
>>> from ox-texinfo, specifically for writing Emacs manuals, that helps
>>> authors conform to the Emacs manual conventions. The way texinfo-plus
>>> handles lists of keybindings/user options/etc is nice, and it appears to
>>> set up the indexes for you, you only have to add concept index entries
>>> manually.
>>
>> AFAIU, the way texinfo-plus handles lists of ... is certainly nice, but
>> it's unrelated to Emacs manual conventions. It helps authors conform
>> Magit's author conventions. Those are fine, but I'm pretty sure not all
>> Emacs manuals follow them (Org doesn't, obviously).
>
> The main thing I was after was semi-automated indexing (obviously some
> of it you have to do yourself). I just looked more closely at the texi
> output that texinfo-plus produced, and it seems to only be doing concept
> and key indexing, not function or variable indexing. So that's not as
> helpful as I thought.

And regarding the lists of commands and keys, what would be the
recommended way of making a list of @deffns and corresponding index
entries? Perhaps it would be enough to expand the example document in
the texinfo section of the Org manual.

Eric

Re: setting local variables

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> And regarding the lists of commands and keys, what would be the
> recommended way of making a list of @deffns and corresponding index
> entries?

I don't know what is a list of @deffns. In any case, you can something
like this:

  #+attr_texinfo: :options category name arguments...
  #+begin_deffn
  ...
  #+end_deffn

AFAIU, @deffn takes care of indexing "name".

> Perhaps it would be enough to expand the example document in
> the texinfo section of the Org manual.

The point of the example document in the Org manual is to be the exact
equivalent to the example in the Texinfo example. The latter doesn't use
"@deffn" commands.

Regards,

-- 
Nicolas Goaziou

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> And regarding the lists of commands and keys, what would be the
>> recommended way of making a list of @deffns and corresponding index
>> entries?
>
> I don't know what is a list of @deffns. In any case, you can something
> like this:
>
>   #+attr_texinfo: :options category name arguments...
>
>   #+begin_deffn
>   ...
>   #+end_deffn
>
> AFAIU, @deffn takes care of indexing "name".

I just meant that it's very common when writing manuals to have lists of
commands, keys, user options, etc. The texinfo-plus output doesn't quite
look like the Emacs manuals, but it produces something that works.

For example, the below looks like something you'd find in an Emacs
manual.

#+BEGIN_SRC texinfo
  @table @kbd
  @item C-x C-f
  @kindex C-x C-f
  @findex find-file
  Visit a file (@code{find-file}).
  @item C-x C-r
  @kindex C-x C-r
  @findex find-file-read-only
  Visit a file for viewing, without allowing changes to it
  (@code{find-file-read-only}).
  @end table
#+END_SRC

This gets me some of the way:

#+BEGIN_SRC org
#+ATTR_TEXINFO: :options @kbd
#+begin_table
- C-x C-f
#+KINDEX: C-x C-f
Visit a file (@code{find-file}).
- C-x C-r
  #+KINDEX: C-x C-r
  #+FINDEX: find-file-read-only
  Visit a file for viewing, without allowing changes to it
#+end_table
#+END_SRC

But the items are exported incorrectly, with each list item in its own
itemize environment. How would I get something closer to the texinfo
output above?

>> Perhaps it would be enough to expand the example document in
>> the texinfo section of the Org manual.
>
> The point of the example document in the Org manual is to be the exact
> equivalent to the example in the Texinfo example. The latter doesn't use
> "@deffn" commands.

Okay, I see.

On the one hand, it isn't Org's job to teach people how to write Emacs
manuals. On the other hand, if there's a nice solution

Thanks,
Eric

Re: setting local variables

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> For example, the below looks like something you'd find in an Emacs
> manual.
>
> #+BEGIN_SRC texinfo
>   @table @kbd
>   @item C-x C-f
>   @kindex C-x C-f
>   @findex find-file
>   Visit a file (@code{find-file}).
>   @item C-x C-r
>   @kindex C-x C-r
>   @findex find-file-read-only
>   Visit a file for viewing, without allowing changes to it
>   (@code{find-file-read-only}).
>   @end table
> #+END_SRC

[...]

> But the items are exported incorrectly, with each list item in its own
> itemize environment. How would I get something closer to the texinfo
> output above?

  #+attr_texinfo: :indic @kbd
  - C-x C-f :: 

       #+kindex: C-x C-f
       Visit a file (~find-file~).

  - C-x C-r ::

       #+kindex: C-x C-r
       #+findex: find-file-read-only
       Visit a file for viewing, without allowing changes to it
       (~find-file-read-only~).


Regards,

-- 
Nicolas Goaziou

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> For example, the below looks like something you'd find in an Emacs
>> manual.
>>
>> #+BEGIN_SRC texinfo
>>   @table @kbd
>>   @item C-x C-f
>>   @kindex C-x C-f
>>   @findex find-file
>>   Visit a file (@code{find-file}).
>>   @item C-x C-r
>>   @kindex C-x C-r
>>   @findex find-file-read-only
>>   Visit a file for viewing, without allowing changes to it
>>   (@code{find-file-read-only}).
>>   @end table
>> #+END_SRC
>
> [...]
>
>> But the items are exported incorrectly, with each list item in its own
>> itemize environment. How would I get something closer to the texinfo
>> output above?
>
>   #+attr_texinfo: :indic @kbd
>   - C-x C-f :: 
>
>        #+kindex: C-x C-f
>        Visit a file (~find-file~).
>
>
>   - C-x C-r ::
>
>        #+kindex: C-x C-r
>        #+findex: find-file-read-only
>
>        Visit a file for viewing, without allowing changes to it
>        (~find-file-read-only~).

Thank you!
Eric

Re: setting local variables

[Rasmus]

Hi,

(Sorry for replying to this old thread which I am only reading now)

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

>>> I'm writing an Emacs manual in Org, using
>>> https://github.com/tarsius/ox-texinfo-plus to make things a bit
>>> easier.
>>
>> I don't know that library, but as a biased POV, it would be nice to use
>> "ox-texinfo" and let us know about its shortcomings. Just saying.
>
> Oh I don't think it's about shortcomings, just about having a version
> that's tweaked specifically for writing Emacs manuals. I _really_ want
> my packages to have info manuals, and I _really_ don't want to learn how
> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
> lot of work. Then I noticed that the Magit manuals used this
> texinfo-plus thing, and it seemed good enough.

It was Thomas S. Dye who ported the Org manual in Org

    https://github.com/tsdye/orgmanual

FWIW I like to see general tweaks added directly to ox-texinfo to the
extend it’s feasible.

Rasmus

-- 
In theory, practice and theory are the same. In practice they are not

Re: setting local variables

[Eric Abrahamsen]

Rasmus <rasmus@gmx.us> writes:

> Hi,
>
> (Sorry for replying to this old thread which I am only reading now)
>
> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>>>> I'm writing an Emacs manual in Org, using
>>>> https://github.com/tarsius/ox-texinfo-plus to make things a bit
>>>> easier.
>>>
>>> I don't know that library, but as a biased POV, it would be nice to use
>>> "ox-texinfo" and let us know about its shortcomings. Just saying.
>>
>> Oh I don't think it's about shortcomings, just about having a version
>> that's tweaked specifically for writing Emacs manuals. I _really_ want
>> my packages to have info manuals, and I _really_ don't want to learn how
>> to write texinfo. I saw Rasmus' Org manual in org, and it looked like a
>> lot of work. Then I noticed that the Magit manuals used this
>> texinfo-plus thing, and it seemed good enough.
>
> It was Thomas S. Dye who ported the Org manual in Org
>
>     https://github.com/tsdye/orgmanual
>
> FWIW I like to see general tweaks added directly to ox-texinfo to the
> extend it’s feasible.

Oops, sorry about that.

Later I removed my manual's dependency on ox-texinfo+, and went with
plain Org export functionality. It looks a lot better now, and is more
correct, but it took me a good half day to learn texinfo and do the
work. I knew I'd have to do that at some point, so that's fine, I was
just putting it off.

The only real problem I encountered was that links to external Info
manuals did not export correctly, and couldn't be followed. I gave up on
learning the exact syntax of texinfo's @[px]ref commands because it was
dinnertime, but I can figure out what went wrong and maybe provide a
patch.

The other thing I'd like to know is how to "inline" sections (ie output
several sections on a single page), but still have links to those
sections work correctly.

That problem and most others could probably be "solved" by expanding the
docs. For instance, regarding the sectioning problem, "12.14.6 Headings
and sectioning structure" in the Org manual says:

  If an Org headline’s level has no associated Texinfo structuring
  command, or is below a certain threshold (*note Export settings), then
  the Texinfo export back-end makes it into a list item.

Why a list item? Plenty of Info manuals have multiple sub-headings on a
single page, how do we do that?

In general, I think the texinfo part of the Org manual could benefit
from some beefing up, and I'd be happy to provide suggestions.

Eric

Re: setting local variables

[Rasmus]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> The only real problem I encountered was that links to external Info
> manuals did not export correctly, and couldn't be followed. I gave up on
> learning the exact syntax of texinfo's @[px]ref commands because it was
> dinnertime, but I can figure out what went wrong and maybe provide a
> patch.

I am not sure either.  I couldn’t get cross-referencing working.

    http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Cross-References

The texinfo part of the Org manual could use a section on
cross-referencing

> The other thing I'd like to know is how to "inline" sections (ie output
> several sections on a single page), but still have links to those
> sections work correctly.

Are you talking about info pages now?  Because in pdf and html it’s not an
issue as far as I’m aware.

> That problem and most others could probably be "solved" by expanding the
> docs. For instance, regarding the sectioning problem, "12.14.6 Headings
> and sectioning structure" in the Org manual says:
>
>   If an Org headline’s level has no associated Texinfo structuring
>   command, or is below a certain threshold (*note Export settings), then
>   the Texinfo export back-end makes it into a list item.
>
> Why a list item? Plenty of Info manuals have multiple sub-headings on a
> single page, how do we do that?

Could you provide an example?  I have mostly seen numbered sections
without subtitles

    NN.mm title

    text

    menu

> In general, I think the texinfo part of the Org manual could benefit
> from some beefing up, and I'd be happy to provide suggestions.

I would agree, but perhaps I’m biased since I don’t have much of a working
knowledge of texinfo other than enough to add sections to an existing
manual.

You could look at the texinfo manual and see if we are missing something

    http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html

On the top of my head it would be good to have a cross-referencing
section, though I think that there may not be support for too
sophisticated referencing, at least judging from ‘org-texinfo--@ref’.

Another area that seems slightly lacking is support for all markings, so
perhaps there could be a section on accessing your favorite via
‘org-texinfo-text-markup-alist’ (if ‘org-texinfo--text-markup’ supports
it) and the rest via macros, if necessary.

    http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Marking-Text

Thanks,
Rasmus

-- 
There are known knowns; there are things we know that we know

Re: setting local variables

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> The only real problem I encountered was that links to external Info
>> manuals did not export correctly, and couldn't be followed. I gave up on
>> learning the exact syntax of texinfo's @[px]ref commands because it was
>> dinnertime, but I can figure out what went wrong and maybe provide a
>> patch.
>
> I am not sure either.  I couldn’t get cross-referencing working.
>
>     http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Cross-References
>
> The texinfo part of the Org manual could use a section on
> cross-referencing

IIRC, cross-referencing is straightforward. It should just work.

>> The other thing I'd like to know is how to "inline" sections (ie output
>> several sections on a single page), but still have links to those
>> sections work correctly.
>
> Are you talking about info pages now?  Because in pdf and html it’s not an
> issue as far as I’m aware.

The OP is probably talking about @heading and al. 

There is actually no way to specify such a "nodeless" heading (more
exactly, an unnumbered heading that doesn't appear in the table of
contents), because I couldn't find any appealing syntax (i.e., not too
low level, and, if possible, generic enough).

I agree this is the last major issue in this export back-end.

> I would agree, but perhaps I’m biased since I don’t have much of a working
> knowledge of texinfo other than enough to add sections to an existing
> manual.
>
> You could look at the texinfo manual and see if we are missing something
>
>     http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html
>
> On the top of my head it would be good to have a cross-referencing
> section, though I think that there may not be support for too
> sophisticated referencing, at least judging from ‘org-texinfo--@ref’.

What it sophisticated referencing? "ox-texinfo" supports internal and
external links without specific syntax. @pxref and @xref is just
syntactic sugar over @ref.

"ox-texinfo.el" supports @email, @ref and @uref.

> Another area that seems slightly lacking is support for all markings, so
> perhaps there could be a section on accessing your favorite via
> ‘org-texinfo-text-markup-alist’ (if ‘org-texinfo--text-markup’ supports
> it) and the rest via macros, if necessary.
>
>     http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Marking-Text

IMO, advanced marking is not needed, at least out of the box. For
example, @kbd{M-@key{TAB}} in Texinfo is morally equivalent to ~M-<TAB>~
in Org, as long as the document targets info.

If you absolutely need @kbd, you can use a macro.

Regards,

-- 
Nicolas Goaziou

Re: setting local variables

[Rasmus]

Hi,

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>>
>>> The only real problem I encountered was that links to external Info
>>> manuals did not export correctly, and couldn't be followed. I gave up on
>>> learning the exact syntax of texinfo's @[px]ref commands because it was
>>> dinnertime, but I can figure out what went wrong and maybe provide a
>>> patch.
>>
>> I am not sure either.  I couldn’t get cross-referencing working.
>>
>>     http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Cross-References
>>
>> The texinfo part of the Org manual could use a section on
>> cross-referencing
>
> IIRC, cross-referencing is straightforward. It should just work.

I could not get it to work.  I tried stuff like "[[(org) Tables]]",
"[[*(org) Tables]]" and , [[texinfo:(org) tables]].

It is always unresolved.  I couldn’t think of any other way of referencing
an external manual, even skimming ox-texinfo.el, so it is not
straightforward to me.

>>> The other thing I'd like to know is how to "inline" sections (ie output
>>> several sections on a single page), but still have links to those
>>> sections work correctly.
>>
>> Are you talking about info pages now?  Because in pdf and html it’s not an
>> issue as far as I’m aware.
>
> The OP is probably talking about @heading and al. 
>
> There is actually no way to specify such a "nodeless" heading (more
> exactly, an unnumbered heading that doesn't appear in the table of
> contents), because I couldn't find any appealing syntax (i.e., not too
> low level, and, if possible, generic enough).
>
> I agree this is the last major issue in this export back-end.

That is why I asked for a reference as I do not remember having seen such
a layout in an info page.  If we know of an example, it might not be hard
to implement.

> What it sophisticated referencing? "ox-texinfo" supports internal and
> external links without specific syntax. @pxref and @xref is just
> syntactic sugar over @ref.
>
> "ox-texinfo.el" supports @email, @ref and @uref.

I don’t know as I am not a texinfo expert, but in the texinfo manual they
tell you to be vary of @ref.  It is probably a bit over the top.

    The @ref command can tempt writers to express themselves in a manner
    that is suitable for a printed manual but looks awkward in the Info
    format. Bear in mind that your audience could be using both the
    printed and the Info format. For example:

    Sea surges are described in @ref{Hurricanes}.

    looks ok in the printed output:

        Sea surges are described in Section 6.7 [Hurricanes], page 72. 

    but is awkward to read in Info, “note” being a verb:

    Sea surges are described in *note Hurricanes::.

Also, does Org support all four @ref arguments?  In either case, these are
questions that I find reasonable and cannot find the answer to in the
manual.

>> Another area that seems slightly lacking is support for all markings, so
>> perhaps there could be a section on accessing your favorite via
>> ‘org-texinfo-text-markup-alist’ (if ‘org-texinfo--text-markup’ supports
>> it) and the rest via macros, if necessary.
>>
>>     http://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#Marking-Text
>
> IMO, advanced marking is not needed, at least out of the box. For
> example, @kbd{M-@key{TAB}} in Texinfo is morally equivalent to ~M-<TAB>~
> in Org, as long as the document targets info.
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

I guess the idea of Texinfo is produce info, html, and paper manuals
consistently, though.  I personally agree, but just look at the Org manual
and the fuss about @code vs @samp (which, I believe, are also displayed in
the same way).  Texinfo is proudly pedantic.  People exporting to Texinfo
might care about @kbd{} vs @code{} and explaining how to get such
fine-grained control would be a fine thing to document in the manual IMO.

Rasmus

-- 
Hooray!

Re: setting local variables

[Nicolas Goaziou]

Rasmus <rasmus@gmx.us> writes:

> I could not get it to work.  I tried stuff like "[[(org) Tables]]",
> "[[*(org) Tables]]" and , [[texinfo:(org) tables]].

You are talking about a special case for cross-referencing (which could
include internal reference, URL referencess). This is the job of
"org-info.el":

  [[info:org#tables]]

> It is always unresolved.  I couldn’t think of any other way of referencing
> an external manual, even skimming ox-texinfo.el, so it is not
> straightforward to me.

See 

  [[info:org#External links]]

oops, I mean 

  (info "(org) External links")

;)

> That is why I asked for a reference as I do not remember having seen such
> a layout in an info page.  If we know of an example, it might not be hard
> to implement.

The problem is not implementing it, really. It is about finding a way to
integrate it with Org syntax.

"org.texi" uses a lot of "@subheading" and related. See for example

  (info "(org) Installation")

"Using Emacs packaging system", "Downloading Org as an archive" and
"Using Org's git repository" are three examples of such layout.

>> What it sophisticated referencing? "ox-texinfo" supports internal and
>> external links without specific syntax. @pxref and @xref is just
>> syntactic sugar over @ref.
>>
>> "ox-texinfo.el" supports @email, @ref and @uref.
>
> I don’t know as I am not a texinfo expert, but in the texinfo manual they
> tell you to be vary of @ref.  It is probably a bit over the top.
>
>     The @ref command can tempt writers to express themselves in a manner
>     that is suitable for a printed manual but looks awkward in the Info
>     format. Bear in mind that your audience could be using both the
>     printed and the Info format. For example:
>
>     Sea surges are described in @ref{Hurricanes}.
>
>     looks ok in the printed output:
>
>         Sea surges are described in Section 6.7 [Hurricanes], page 72. 
>
>     but is awkward to read in Info, “note” being a verb:
>
>     Sea surges are described in *note Hurricanes::.

In Org, just write

  For sea surges, see [[*Hurricanes]]

E.g., insert the "see" manually.

> Also, does Org support all four @ref arguments?  In either case, these are
> questions that I find reasonable and cannot find the answer to in the
> manual.

The manual is not targeted to Texinfo experts. The difference between
@ref arguments are subtle. At this point, I suggest to generate some
template with Org and tweak the result.

BTW, Org supports @ref with 1 argument and with arguments 1 and 3. There
is no way in Org to distinguish between online label and printed label.
The fourth and fifth arguments are not supported either, for the same
reason. You need to insert raw Texinfo code to achieve this.

> I guess the idea of Texinfo is produce info, html, and paper manuals
> consistently, though.  I personally agree, but just look at the Org manual
> and the fuss about @code vs @samp (which, I believe, are also displayed in
> the same way).

@code and @samp are not a problem, being respectively ~...~ and =...=.

> Texinfo is proudly pedantic. People exporting to Texinfo might care
> about @kbd{} vs @code{} and explaining how to get such fine-grained
> control would be a fine thing to document in the manual IMO.

Patch welcome!

Also, two emphasis markers are unused in "ox-texinfo.el": _..._ and
+...+. Another solution would be to use them for Texinfo special markup.
However, it feels awkward to provide this by default.

Regards,

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Rasmus <rasmus@gmx.us> writes:
>
>> I could not get it to work.  I tried stuff like "[[(org) Tables]]",
>> "[[*(org) Tables]]" and , [[texinfo:(org) tables]].
>
> You are talking about a special case for cross-referencing (which could
> include internal reference, URL referencess). This is the job of
> "org-info.el":
>
>   [[info:org#tables]]

I think I ran into trouble just doing a simple `org-store-link' from an
Info file, then `org-insert-link' in the Org mode manual.

That produced:

[[info:org#Installation][info:org#Installation]] -->
@ref{Installation,@ref{Installation,,,org,},,org,} -->
*note *note (org)Installation::: (org)Installation.

Of course, I should have edited the description part of the link:

[[info:org#Installation][Installation]] -->
@ref{Installation,Installation,,org,} -->
*note Installation(org).

Much better.

I did once manage to produce a link that didn't follow to its
destination, I think just using org-store|insert-link, but of course now
can't reproduce.

Anyway, I don't know if the above is actually a bug or not.

[...]

>> That is why I asked for a reference as I do not remember having seen such
>> a layout in an info page.  If we know of an example, it might not be hard
>> to implement.
>
> The problem is not implementing it, really. It is about finding a way to
> integrate it with Org syntax.
>
> "org.texi" uses a lot of "@subheading" and related. See for example
>
>   (info "(org) Installation")
>
> "Using Emacs packaging system", "Downloading Org as an archive" and
> "Using Org's git repository" are three examples of such layout.

Why not just change the behavior of `org-export-headline-levels' for
texinfo output? We can already make plain lists, it doesn't seem useful
to me to also turn minor headings into lists. Since texinfo has the
concept of pages, why not just inline headings below H: level?

[...]

> The manual is not targeted to Texinfo experts. The difference between
> @ref arguments are subtle. At this point, I suggest to generate some
> template with Org and tweak the result.

I agree that Org doesn't need to support all the subtleties, but I did
find the out-of-the-box `org-store|insert-link' pretty confusing.

[...]

> IMO, advanced marking is not needed, at least out of the box. For
> example, @kbd{M-@key{TAB}} in Texinfo is morally equivalent to
> ~M-<TAB>~ in Org, as long as the document targets info.

Morally equivalent in that they're typeset the same, right? I decided to
embrace texinfo pedantry and make a kbd macro :)

> Patch welcome!
>
> Also, two emphasis markers are unused in "ox-texinfo.el": _..._ and
> +...+. Another solution would be to use them for Texinfo special markup.
> However, it feels awkward to provide this by default.

I'd be happy to provide a patch, and I think we should mention
`org-texinfo-text-markup-alist', as well. Then we can say "here's how
Org's basic markup elements are translated, here's a defcustom you can
play with, and failing that you can also make a macro".

To be honest I don't know how the markup alist is supposed to work,
though. If I mark up a phrase /like so/, shouldn't that count as
"italic", and get transformed into @emph{like so}? Right now it goes
through unchanged into the Info file, which doesn't seem right, since
the Texinfo manual seems to indicate that _this_ is the proper way to do
emphasis.

The other thing I'd like to expand is the "Plain lists in Texinfo
export" section. First of all, it's about definition lists, not plain
lists, which I found confusing. Also, I think it just needs to have more
basic information in it, unless you already know texinfo well, it's hard
to know what it's telling you.

Eric

Re: setting local variables

[Nicolas Goaziou]

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> I think I ran into trouble just doing a simple `org-store-link' from an
> Info file, then `org-insert-link' in the Org mode manual.
>
> That produced:
>
> [[info:org#Installation][info:org#Installation]] -->
> @ref{Installation,@ref{Installation,,,org,},,org,} -->
> *note *note (org)Installation::: (org)Installation.

This bug was fixed months ago, when we removed support for nested links.

> Why not just change the behavior of `org-export-headline-levels' for
> texinfo output? We can already make plain lists, it doesn't seem useful
> to me to also turn minor headings into lists. Since texinfo has the
> concept of pages, why not just inline headings below H: level?

We can certainly do that, but that doesn't solve the real problem. Such
headings could be generated at any level. Conversely, you may want to
have a deeper level in some section, so H:4 would be mandatory.

Maybe UNNUMBERED property could imply a "not in TOC" clause in every
back-end (I assume this is difficult to implement for LaTeX, though). In
that case, UNNUMBERED would be a generic answer the problem.

Or UNNUMBERED could imply "not in TOC" in "ox-texinfo.el", but that's
less good, IMO.

>> IMO, advanced marking is not needed, at least out of the box. For
>> example, @kbd{M-@key{TAB}} in Texinfo is morally equivalent to
>> ~M-<TAB>~ in Org, as long as the document targets info.
>
> Morally equivalent in that they're typeset the same, right?

Correct.

> I decided to embrace texinfo pedantry and make a kbd macro :)

I think it really matters if you're going to use the Texinfo file to
produce other formats than "info" (e.g., you're writing a GNU manual).
If that's only for the "info" part, ~M-<TAB>~ is infinitely more
readable.

> I'd be happy to provide a patch, and I think we should mention
> `org-texinfo-text-markup-alist', as well. Then we can say "here's how
> Org's basic markup elements are translated, here's a defcustom you can
> play with, and failing that you can also make a macro".

Sounds good.

> To be honest I don't know how the markup alist is supposed to work,
> though. If I mark up a phrase /like so/, shouldn't that count as
> "italic", and get transformed into @emph{like so}?

It should, and it does.

> Right now it goes through unchanged into the Info file, which doesn't
> seem right, since the Texinfo manual seems to indicate that _this_ is
> the proper way to do emphasis.

I cannot reproduce the problem.

> The other thing I'd like to expand is the "Plain lists in Texinfo
> export" section. First of all, it's about definition lists, not plain
> lists, which I found confusing. Also, I think it just needs to have more
> basic information in it, unless you already know texinfo well, it's hard
> to know what it's telling you.

Agreed.

Regards,

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Eric Abrahamsen <eric@ericabrahamsen.net> writes:
>
>> I think I ran into trouble just doing a simple `org-store-link' from an
>> Info file, then `org-insert-link' in the Org mode manual.
>>
>> That produced:
>>
>> [[info:org#Installation][info:org#Installation]] -->
>> @ref{Installation,@ref{Installation,,,org,},,org,} -->
>> *note *note (org)Installation::: (org)Installation.
>
> This bug was fixed months ago, when we removed support for nested links.

Bah, sorry. I'm on org-plus-contrib.

>> Why not just change the behavior of `org-export-headline-levels' for
>> texinfo output? We can already make plain lists, it doesn't seem useful
>> to me to also turn minor headings into lists. Since texinfo has the
>> concept of pages, why not just inline headings below H: level?
>
> We can certainly do that, but that doesn't solve the real problem. Such
> headings could be generated at any level. Conversely, you may want to
> have a deeper level in some section, so H:4 would be mandatory.
>
> Maybe UNNUMBERED property could imply a "not in TOC" clause in every
> back-end (I assume this is difficult to implement for LaTeX, though). In
> that case, UNNUMBERED would be a generic answer the problem.
>
> Or UNNUMBERED could imply "not in TOC" in "ox-texinfo.el", but that's
> less good, IMO.

Right, the headline-levels approach is not very graceful. I like
using UNNUMBERED, that seems conceptually correct.

>>> IMO, advanced marking is not needed, at least out of the box. For
>>> example, @kbd{M-@key{TAB}} in Texinfo is morally equivalent to
>>> ~M-<TAB>~ in Org, as long as the document targets info.
>>
>> Morally equivalent in that they're typeset the same, right?
>
> Correct.
>
>> I decided to embrace texinfo pedantry and make a kbd macro :)
>
> I think it really matters if you're going to use the Texinfo file to
> produce other formats than "info" (e.g., you're writing a GNU manual).
> If that's only for the "info" part, ~M-<TAB>~ is infinitely more
> readable.

I don't think anything needs to be done here, it's just a matter of what
authors want.

>> I'd be happy to provide a patch, and I think we should mention
>> `org-texinfo-text-markup-alist', as well. Then we can say "here's how
>> Org's basic markup elements are translated, here's a defcustom you can
>> play with, and failing that you can also make a macro".
>
> Sounds good.
>
>> To be honest I don't know how the markup alist is supposed to work,
>> though. If I mark up a phrase /like so/, shouldn't that count as
>> "italic", and get transformed into @emph{like so}?
>
> It should, and it does.
>
>> Right now it goes through unchanged into the Info file, which doesn't
>> seem right, since the Texinfo manual seems to indicate that _this_ is
>> the proper way to do emphasis.
>
> I cannot reproduce the problem.

I'll assume it's something version related, or local.

>> The other thing I'd like to expand is the "Plain lists in Texinfo
>> export" section. First of all, it's about definition lists, not plain
>> lists, which I found confusing. Also, I think it just needs to have more
>> basic information in it, unless you already know texinfo well, it's hard
>> to know what it's telling you.
>
> Agreed.

Great, I'll do this in the next couple of days.

Thanks,
Eric

Re: setting local variables

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Maybe UNNUMBERED property could imply a "not in TOC" clause in every
> back-end (I assume this is difficult to implement for LaTeX, though). In
> that case, UNNUMBERED would be a generic answer the problem.

Speaking of LaTeX: not-in-toc and unnumbered is easy enough in LaTeX as
it’s just section*.  It’s what it does now.  Unnumbered and in-the-toc is
harder, but e.g. KOMA-Script has it built in with \addpart{}, \addchap{}
(and maybe \addsec{}).  To add unnumbered headings in plain latex one
would have to add \addcontentsline{toc}{level}{title}.  Users have some
control over the matter in ox-latex via ox-latex-classes.

ox-odt, ox-html and ox-ascii all seem to add unnumbered headings to the
toc.

> Or UNNUMBERED could imply "not in TOC" in "ox-texinfo.el", but that's
> less good, IMO.

One nice thing about this, I guess, is that it might allow you to use the
"num" option to select which headings are kept out of the toc?

Rasmus

-- 
There are known knowns; there are things we know that we know

Re: setting local variables

[Nicolas Goaziou]

Hello,

Rasmus <rasmus@gmx.us> writes:

> Speaking of LaTeX: not-in-toc and unnumbered is easy enough in LaTeX
> as it’s just section*.

Great.

> ox-odt, ox-html and ox-ascii all seem to add unnumbered headings to the
> toc.

These are trivial to handle, since they use
`org-export-collect-headlines' to build TOC. We just need to change this
function.

>> Or UNNUMBERED could imply "not in TOC" in "ox-texinfo.el", but that's
>> less good, IMO.
>
> One nice thing about this, I guess, is that it might allow you to use the
> "num" option to select which headings are kept out of the toc?

IIURC, num:N would be equivalent to toc:N. Maybe we could remove the
latter.

So, any objection to have all major back-ends ignoring unnumbered trees
from TOC, and make that an Org specificity?

Regards,

-- 
Nicolas Goaziou

Re: setting local variables

[Eric Abrahamsen]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:


[...]

> So, any objection to have all major back-ends ignoring unnumbered trees
> from TOC, and make that an Org specificity?

Sounds good!

Re: setting local variables

[Nicolas Goaziou]

Hello,

Eric Abrahamsen <eric@ericabrahamsen.net> writes:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>> So, any objection to have all major back-ends ignoring unnumbered trees
>> from TOC, and make that an Org specificity?
>
> Sounds good!

Done in master.

Thank you for the feedback.

Regards,

-- 
Nicolas Goaziou

Re: setting local variables

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 1225 bytes --]

On Thu, Sep 7, 2017 at 5:01 PM, Eric Abrahamsen <eric@ericabrahamsen.net>
wrote:

> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>
>
> [...]
>
> > So, any objection to have all major back-ends ignoring unnumbered trees
> > from TOC, and make that an Org specificity?
>


Hi Nicolas,

OK, now I have read this thread.

I do object to removing unnumbered headers from the toc.  It breaks
documented and used behaviour and aI see no pressing reason to change it. I
find, for compact documents, it works extremely well to have a toc that has
no numbers - in fact, in many cases I find numbered tocs even annoying.  In
particular, it works really well in websites, where I use it constantly.

I am sorry that I did not see this earlier - but I really think this change
should be reverted.  If there is a desire to have sections that are not put
into the toc, it should be separated from the num: and toc: switches and
depend, for example on properties instead.

The fact that in LaTeX "unnumbered" is linked to the question if something
is in the toc is some kind of mistake, this behaviour is very specific to
LaTeX-like systems (including TeXInfo), but it is not a very logical system
IMO.

Carsten


>
> Sounds good!
>
>
>

[-- Attachment #2: Type: text/html, Size: 1961 bytes --]

Re: setting local variables

[Scott Randby]

On 09/20/2017 12:17 PM, Carsten Dominik wrote:
> On Thu, Sep 7, 2017 at 5:01 PM, Eric Abrahamsen <eric@ericabrahamsen.net>
> wrote:
> 
>> Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:
>>
>>
>> [...]
>>
>>> So, any objection to have all major back-ends ignoring unnumbered trees
>>> from TOC, and make that an Org specificity?
>>
> 
> 
> Hi Nicolas,
> 
> OK, now I have read this thread.
> 
> I do object to removing unnumbered headers from the toc.  It breaks
> documented and used behaviour and aI see no pressing reason to change it. I
> find, for compact documents, it works extremely well to have a toc that has
> no numbers - in fact, in many cases I find numbered tocs even annoying.  In
> particular, it works really well in websites, where I use it constantly.
> 
> I am sorry that I did not see this earlier - but I really think this change
> should be reverted.  If there is a desire to have sections that are not put
> into the toc, it should be separated from the num: and toc: switches and
> depend, for example on properties instead.
> 
> The fact that in LaTeX "unnumbered" is linked to the question if something
> is in the toc is some kind of mistake, this behaviour is very specific to
> LaTeX-like systems (including TeXInfo), but it is not a very logical system
> IMO.
> 
> Carsten

I have to agree with Carsten. I use unnumbered table of contents all the time in web pages. Almost all of my Org files that generate web pages have the following:

#+options: num:nil toc:t

The change should be reverted. I wish I had paid attention to this thread. I thought it was about something else.

Scott Randby

> 
> 
>>
>> Sounds good!
>>
>>
>>
> 

Re: setting local variables

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 1365 bytes --]

On Wed, Sep 20, 2017, 2:43 PM Scott Randby <srandby@gmail.com> wrote:

>
>
> On 09/20/2017 12:17 PM, Carsten Dominik wrote:
> > On Thu, Sep 7, 2017 at 5:01 PM, Eric Abrahamsen <eric@ericabrahamsen.net
> >
> > wrote:
> > I do object to removing unnumbered headers from the toc.


I believe this change was made to fix the case of mixed numbered and
unnumbered headings in the TOC.

Please see the other thread[1] where I suggest supporting the "case 3"
where we want TOC where all headings are numbered i.e. the case of num:nil.

 It

breaks
> > documented and used behaviour and aI see no pressing reason to change
> it. I
> > find, for compact documents, it works extremely well to have a toc that
> has
> > no numbers - in fact, in many cases I find numbered tocs even annoying.
> In
> > particular, it works really well in websites, where I use it constantly.
>

Mine is the same use case and the num:nil case covers that.

 I have to agree with Carsten. I use unnumbered table of contents all the
> time in web pages. Almost all of my Org files that generate web pages have
> the following:
>
> #+options: num:nil toc:t
>

@Scott Please see that other thread[1]. I have this exact use case. And if
the case 3 discussed in that thread is supported all should be good.

[1]: http://lists.gnu.org/archive/html/emacs-orgmode/2017-09/msg00497.html
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 2526 bytes --]

Re: setting local variables

[Eric S Fraga]

[-- Attachment #1: Type: text/plain, Size: 704 bytes --]

On Wednesday, 20 Sep 2017 at 14:42, Scott Randby wrote:

[...]

> I have to agree with Carsten. I use unnumbered table of contents all
> the time in web pages. Almost all of my Org files that generate web
> pages have the following:
>
> #+options: num:nil toc:t

Ditto.  I find a short TOC for web pages very useful and could not
figure out why such tables had disappeared from my web pages!

>
> The change should be reverted. I wish I had paid attention to this
> thread. I thought it was about something else.

I also hadn't been following this thread and hadn't realised it had
morphed into a discussion about toc.  

Thanks,
eric

-- 
: Eric S Fraga via Emacs 26.0.50, Org release_9.0.9-573-g09e612

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 194 bytes --]

Re: setting local variables

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 1872 bytes --]

Hi everyone,



On Thu, Sep 21, 2017 at 1:16 AM, Kaushal Modi <kaushal.modi@gmail.com>
wrote:

> On Wed, Sep 20, 2017, 2:43 PM Scott Randby <srandby@gmail.com> wrote:
>
>>
>>
>> On 09/20/2017 12:17 PM, Carsten Dominik wrote:
>> > On Thu, Sep 7, 2017 at 5:01 PM, Eric Abrahamsen <
>> eric@ericabrahamsen.net>
>> > wrote:
>> > I do object to removing unnumbered headers from the toc.
>
>
> I believe this change was made to fix the case of mixed numbered and
> unnumbered headings in the TOC.
>
> Please see the other thread[1] where I suggest supporting the "case 3"
> where we want TOC where all headings are numbered i.e. the case of num:nil.
>

This would address my main concern and make it usable, yes.

It is another question if the association of unnumbered and not toc-listed
is a useful one in general.  The cleanest would be to have properties like
NO_TOC_LISTING and NOT_NUMBERED or so to allow local control.  Conflating
it with the global switches I find a bit confusing.

Carsten


>
>  It
>
> breaks
>> > documented and used behaviour and aI see no pressing reason to change
>> it. I
>> > find, for compact documents, it works extremely well to have a toc that
>> has
>> > no numbers - in fact, in many cases I find numbered tocs even
>> annoying.  In
>> > particular, it works really well in websites, where I use it constantly.
>>
>
> Mine is the same use case and the num:nil case covers that.
>
>  I have to agree with Carsten. I use unnumbered table of contents all the
>> time in web pages. Almost all of my Org files that generate web pages have
>> the following:
>>
>> #+options: num:nil toc:t
>>
>
> @Scott Please see that other thread[1]. I have this exact use case. And if
> the case 3 discussed in that thread is supported all should be good.
>
> [1]: http://lists.gnu.org/archive/html/emacs-orgmode/2017-09/msg00497.html
> --
>
> Kaushal Modi
>

[-- Attachment #2: Type: text/html, Size: 3726 bytes --]

Re: setting local variables

[Rasmus]

Carsten Dominik <dominik@uva.nl> writes:

>> I believe this change was made to fix the case of mixed numbered and
>> unnumbered headings in the TOC.
>>
>> Please see the other thread[1] where I suggest supporting the "case 3"
>> where we want TOC where all headings are numbered i.e. the case of num:nil.
>
> This would address my main concern and make it usable, yes.
>
> It is another question if the association of unnumbered and not toc-listed
> is a useful one in general.  The cleanest would be to have properties like
> NO_TOC_LISTING and NOT_NUMBERED or so to allow local control.  Conflating
> it with the global switches I find a bit confusing.

AFAIK NOT_NUMBERED is the UNNUMBERED property.

To support an UNNUMBERED and "UNTOCED" entry in ox-latex /in general/, we
would need to have something like KOMA-Script’s \addsec.  Alternatively,
one can manually add \addcontentsline{toc}{LEVEL}{NAME}, but these are not
indented (see https://tex.stackexchange.com/a/212439/3878).  Also, headers
aren’t updated, though this is less of a concern.

Otherwise, this can only be archived by setting the secnumdepth counter to
a sufficiently low value (say 0 for unnumbered chapters) in which case
everything below that number is also unnumbered.

Rasmus

-- 
I almost cut my hair, it happened just the other day

Re: setting local variables

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 1681 bytes --]

On Thu, Sep 21, 2017 at 11:39 AM, Rasmus <rasmus@gmx.us> wrote:

> Carsten Dominik <dominik@uva.nl> writes:
>
> >> I believe this change was made to fix the case of mixed numbered and
> >> unnumbered headings in the TOC.
> >>
> >> Please see the other thread[1] where I suggest supporting the "case 3"
> >> where we want TOC where all headings are numbered i.e. the case of
> num:nil.
> >
> > This would address my main concern and make it usable, yes.
> >
> > It is another question if the association of unnumbered and not
> toc-listed
> > is a useful one in general.  The cleanest would be to have properties
> like
> > NO_TOC_LISTING and NOT_NUMBERED or so to allow local control.  Conflating
> > it with the global switches I find a bit confusing.
>
> AFAIK NOT_NUMBERED is the UNNUMBERED property.
>
> To support an UNNUMBERED and "UNTOCED" entry in ox-latex /in general/, we
> would need to have something like KOMA-Script’s \addsec.  Alternatively,
> one can manually add \addcontentsline{toc}{LEVEL}{NAME}, but these are not
> indented (see https://tex.stackexchange.com/a/212439/3878).  Also, headers
> aren’t updated, though this is less of a concern.
>
> Otherwise, this can only be archived by setting the secnumdepth counter to
> a sufficiently low value (say 0 for unnumbered chapters) in which case
> everything below that number is also unnumbered.
>

Hi Rasmus,

yes, I am aware that LaTeX does use unnumbered for this, but this is
backend specific implementation, and not an argument about the logic of
this approach.

Carsten


>
> Rasmus
>
> --
> I almost cut my hair, it happened just the other day
>
>
>

[-- Attachment #2: Type: text/html, Size: 2517 bytes --]

Re: setting local variables

[Scott Randby]

On 09/20/2017 07:16 PM, Kaushal Modi wrote:
>  I have to agree with Carsten. I use unnumbered table of contents all the
>> time in web pages. Almost all of my Org files that generate web pages have
>> the following:
>>
>> #+options: num:nil toc:t
>>
> 
> @Scott Please see that other thread[1]. I have this exact use case. And if
> the case 3 discussed in that thread is supported all should be good.
> 
> [1]: http://lists.gnu.org/archive/html/emacs-orgmode/2017-09/msg00497.html
> 

Okay, I don't really understand the issue being discussed in the thread, but if num:nil gives me an unnumbered table of contents after HTML export, I'm good. I also export to LaTeX, but I recognize that there are issues with LaTeX table of contents and I just work around them.

I need to sit down and read the Org manual. For years, I've been using toc:t and getting more in the table of contents than I wanted. Discovering that I can use something like toc:1 was exactly what I needed a long time ago. I know there are other things in Org that I want now and just don't know about. There are disadvantages to my haphazard approach to Org.

Scott

Re: setting local variables

[Nicolas Goaziou]

Hello,

Carsten Dominik <dominik@uva.nl> writes:

> yes, I am aware that LaTeX does use unnumbered for this, but this is
> backend specific implementation, and not an argument about the logic of
> this approach.

Fair enough. I reverted the commit.

I think a :NOTOC: property to ignore headlines from TOC is an acceptable
solution, even though it add yet another property.

I also suggest to classify LaTeX issue as "wontfix".

Any objection?

Regards, 

-- 
Nicolas Goaziou

Re: setting local variables

[Kaushal Modi]

[-- Attachment #1: Type: text/plain, Size: 580 bytes --]

On Thu, Sep 21, 2017 at 3:23 PM Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Fair enough. I reverted the commit.
>

Thanks!


> I think a :NOTOC: property to ignore headlines from TOC is an acceptable
> solution, even though it add yet another property.
>

+1 for :NOTOC:
With that it will be very clear what to expect in the exported formats.


> I also suggest to classify LaTeX issue as "wontfix".
> Any objection?
>

I don't use LaTeX exporter that heavily. If I do, I keep all headings
numbered and also in TOC. So I cannot yet grasp the LaTeX issue.
-- 

Kaushal Modi

[-- Attachment #2: Type: text/html, Size: 1286 bytes --]

Re: setting local variables

[Carsten Dominik]

[-- Attachment #1: Type: text/plain, Size: 623 bytes --]

Hi Nicolas,

thanks!

Carsten

On Thu, Sep 21, 2017 at 9:21 PM, Nicolas Goaziou <mail@nicolasgoaziou.fr>
wrote:

> Hello,
>
> Carsten Dominik <dominik@uva.nl> writes:
>
> > yes, I am aware that LaTeX does use unnumbered for this, but this is
> > backend specific implementation, and not an argument about the logic of
> > this approach.
>
> Fair enough. I reverted the commit.
>
> I think a :NOTOC: property to ignore headlines from TOC is an acceptable
> solution, even though it add yet another property.
>
> I also suggest to classify LaTeX issue as "wontfix".
>
> Any objection?
>
> Regards,
>
> --
> Nicolas Goaziou
>

[-- Attachment #2: Type: text/html, Size: 1177 bytes --]

Re: setting local variables

[Rasmus]

Nicolas Goaziou <mail@nicolasgoaziou.fr> writes:

> Hello,
>
> Carsten Dominik <dominik@uva.nl> writes:
>
>> yes, I am aware that LaTeX does use unnumbered for this, but this is
>> backend specific implementation, and not an argument about the logic of
>> this approach.
>
> Fair enough. I reverted the commit.
>
> I think a :NOTOC: property to ignore headlines from TOC is an acceptable
> solution, even though it add yet another property.
>
> I also suggest to classify LaTeX issue as "wontfix".

IMO, in ox-latex, "num" should only affect secnumdepth.  I don’t think the
current behavior is very good.

Having numbered and unnumbered in the TOC can be archived using
e.g. KOMA-Script (there’s also a sty on github breaking out the relevant
part of of KOMA-Script) and adding a new class to org-latex-classes.


-- 
Hvor meget poesi tror De kommer ud af et glas isvand?