Re: [Docutils-users] Don't enumerate chapter in rst2latex

[G. M. <mi...@us...>]

On  5.05.08, Alan G Isaac wrote:
> On Mon, 5 May 2008, (CEST) gr...@us... wrote
> > On Sat, 3 May 2008, Manuel Kaufmann wrote: 

> >> Hi, I'm trying to don't enumerate some chapters in .tex generation
> >> file. I would get an equivalent in LaTeX at:
> >> \chapter*{Introduction} 
> >> I don't know how to write that in the .rst file 

> > me neither

Although the original questions relates only to the generated .tex file
and uses LaTeX code as example, the problem of one unnumbered section
in an otherwise section-numbering document is independent of the output
format.

I would suggest the usual rst syntax for class attributes, i.e.::

  .. sectnum:: 
  
  heading 
  ---------------------------------------------------------------
  The above directive lets rst number all sections, also this one

  .. class:: numberless
  
  heading sans number
  --------------------------------------------
  This section stands out by beeing unnumbered
  
  one more numbered section header
  --------------------------------
  section content


The precedence case for this is the "borderless" table::

  .. class:: borderless
  
  ===== ========== =========================================================
  2.3   2008-01-11 * section headings: allow for adorning with overline,
                   * split outline and section functions to rst-outline.sl,
  2.3.1 2008-01-22 * made export_cmds static for better testing
                     and configuring.
  ===== ========== =========================================================

which works via a CSS definition for HTML and is specially handled by the
latex writer.

To implement a "do not number this section" class attribute:

* we would need to agree on a canonical (and documented) name, e.g. one of:

  | numberless, nonumber, no-number
  
  cf. the table without frames/borders:
  
  | borderless, noborder, no-border 
  | frameless, noframe, no-frame
  
* Writers must suppress the docutiles-generated number, if the
  section has the class attribute
  
* The latex2e writer must use the starred version of the section command
  if "latex numbering" is used for the document.


> What we would like to do is set a class ``starred`` on the 
> header and in the style file specify that produces the 
> starred version.  This would be useful for other commands 
> too.  Possible?

Kind of.

* This would be a LaTeX only solution, for LaTeX powerusers.

  - Generally, docutils should avoid output-format specific behaviour.
  
  + The docutils documentation explicitely mentions that writers can
    ignore class arguments they do not know of. 
    
    The other way round, you could argument that it is in line with
    established docutils conventions to define a class argument
    ``starred``, say, that is only recognized by the latex2e writer (the
    html writer would simply add 'starred' to the class argument list and
    as long as there is no special rule in a CSS style sheet, no effect
    would be seen).

* The processing of the ``starred`` class argument must happen in the
  latex writer, not on a style sheet. (This is a fundamental difference
  between LaTeX and HTML/CSS.) Compare the way ``borderless`` tables
  are handled by the html and latex writers.
  
* Although for the LaTeX power end user one common ``starred`` class
  argument for a whole set of different syntax elements looks generic and
  "the right way", implementation would require an ``if`` clause for
  every supported doctree object (or latex command) and additional
  considerations on how to handle special cases (e.g. section
  commands are starred by default, only in case of "use latex toc", the
  non-starred versions are used).
  
* ``starred`` is neither mnemonic nor informative for the non-expert.

I vote for ``numberless``.

Günter