[Rest2web-develop] build a file without embedded restindex

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

Michael Foord wrote - 2007-12-13 13:59
> G. Milde wrote:
> > Dear List,
> >
> > However, if there is a (restructured) text file I want rest2web to
> > build but cannot include a restindex in, I have a problem.
 
> Note that the restindex can be embedded in a page inside a ReST comment
> - that way pages can still remain valid ReST files whilst having a
> restindex. Does that help?

Unfortunately not, as the restriction is that this must be the *first*
comment in the rst file :-(

My examples are "literate code" that can be translated between code
format and text format (in both directions!). Not knowing about the
rest2web use of the first comment for a restindex, the PyLit_ converter
has its own special use of the leading comment in a text source file: 

in the text->code conversion a leading header is converted to code --
this means a restindex in the first comment would need to be valid
(Python-, say) code.

Why?

Text2Code.header_handler
~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes code needs to remain on the first line(s) of the document to be
valid. The most common example is the "shebang" line that tells a POSIX
shell how to process an executable file::

  #!/usr/bin/env python
  
In Python, the special comment to indicate the encoding, e.g. 
``# -*- coding: iso-8859-1 -*-``, must occure before any other comment 
or code too.

If we want to keep the line numbers in sync for text and code source, the
reStructured Text markup for these header lines must start at the same line
as the first header line. Therfore, header lines could not be marked as
literal block (this would require the ``::`` and an empty line above the
code_block).

OTOH, a comment may start at the same line as the comment marker and it
includes subsequent indented lines. 

With a header converted to comment in the text source, the advantages

* line numbers are kept
* the "normal" code_block conversion rules (indent/unindent by
  `codeindent` apply
* greater flexibility: you can hide a repeating header in a project
  consisting of many source files.

set off the disadvantages

- it may come as surprise if a part of the file is not "printed",
- one more syntax element to learn for rst newbees to start with pylit,
  (however, starting from the code source, this will be auto-generated)


.. _PyLit: http://pylit.berlios.de/

IMO, there are several ways of reconciling PyLit and rest2web:

1. Lower the restrictions on the `restindex in rst comment`, e.g.:

   a) use the first restindex anywhere in any rst comment
     
      most flexible but maybe slow
   
   b) use a restindex if it starts at the same line as the comment
      indicator, i.e. scan the file for ``^\.\. +restindex`` lines.
     
      faster but more restrictive and not backwards compatible.
   
2. Add a `source` keyword to the restindex syntax to allow building a
   file from the restindex.txt, e.g. ::

      restindex
      source: pylit.py.txt
      build: yes
      target: pylit.py.html
      /restindex


3. (just for completeness) Allow commented restindices with comments
   other than rst, e.g. in a pylit.py.txt file::
   
      ..  #!/usr/bin/env python
        # -*- coding: iso-8859-1 -*-
        # 
        #  restindex
        #  source: pylit.py.txt
        #  build: yes
        #  target: pylit.py.html
        #  /restindex

   (not really feasible, as the comment indicator will vary for different
   source code languages...)


 
Timo Kankare  wrote 2007-12-13 17:55
 
> Can you use the include directive? Something like
> 
> restindex
> crumb: pylit.py
> format: rest
> target: pylit.py.html
> /restindex
> 
> .. include:: pylit.py.txt

This should indeed work. However, I would need a "dummy" text file for
every literate source example, so in the long run I'd prefer one of the
above rest2web expansions.

Thanks

Günter