rest2web-develop

[Rest2web-develop] build a file without embedded restindex

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

Dear List,

how can I specify the source of a file in the restindex.txt file?

* if the restindex is embedded in a source file there is no need to
  specify it.

* for a restindex in restindex.txt, where the target already exists,
  there is no need either.

However, if there is a (restructured) text file I want rest2web to build but
cannot include a restindex in, I have a problem.

I would assume something like

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

but there is no mention of a "souce" keyword for the restindex.

My current workaround is to manually convert the txt to html with
docutils and a restindex.txt like::

  restindex
      crumb: pylit.py
      target: pylit.py.html
      file: pylit.py
      file: pylit.py.txt
      file: pylit.py.html
      
      file: 99bottles.py
      file: 99bottles.py.txt
      file: 99bottles.py.html
      # ... and 24 more files ...
  /restindex
      

Background
----------

in my rest2web built site ( http://pylit.berlios.de/ ) I have lot of
examples of "literate python scripts" which are reStructured text with some
special requiremens to be compatible with the pylit txt<->code converter.

Especially, the first comment is considered to be the file header. See
http://pylit.berlios.de/tutorial/index.html#file-headers for the rationale.
  
  
Thanks

Günter  

[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

Re: [Rest2web-develop] build a file without embedded restindex

[Michael F. <fuz...@vo...>]

G. Milde wrote:
> [snipped and understood...]
>
>  
> 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.
>   

But given that you want to specify an explicit 'source: pylit.py.txt' 
don't you already have that text file?

That aside, patches welcomed... Modifying restindex.txt to allow the 
specifying of a source shouldn't be too hard but I doubt I will have 
time for a while. I have certainly noted the feature request though.

Michael
http://www.manning.com/foord



> Thanks
>
> Günter
>
> -------------------------------------------------------------------------
> SF.Net email is sponsored by:
> Check out the new SourceForge.net Marketplace.
> It's the best place to buy or sell services
> for just about anything Open Source.
> http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace
> _______________________________________________
> Rest2web-develop mailing list
> Res...@li...
> https://lists.sourceforge.net/lists/listinfo/rest2web-develop
>
>   

Re: [Rest2web-develop] build a file without embedded restindex

[Timo K. <Tim...@ko...>]

On Thu, Dec 20, 2007 at 11:22:57AM +0100, G. Milde wrote:
> 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.

Well, yes, extra files are needed...  I don't know if that is a
problem.  I like the possibility to add, move and remove pages without
maintaining central index file.  And with proper naming (like
pylit.py.index.txt) it would be easy to found index information.

Timppa

Re: [Rest2web-develop] [python] build a file without embedded restindex

[Michael F. <fuz...@vo...>]

G. Milde wrote:
> Dear List,
>
> how can I specify the source of a file in the restindex.txt file?
>
> * if the restindex is embedded in a source file there is no need to
>   specify it.
>
> * for a restindex in restindex.txt, where the target already exists,
>   there is no need either.
>
> However, if there is a (restructured) text file I want rest2web to build but
> cannot include a restindex in, I have a problem.
>
>   

Hmmm... interesting usecase - but that is not the purpose of the 
restindex.txt file.

From:
http://www.voidspace.org.uk/python/rest2web/special_files.html#restindex-txt

restindex.txt
If you are only using rest2web to generate part of a website then you 
may want to include in your indexes pages that rest2web isn't building.

The restindex is only (currently) for files that rest2web *isn't* 
building - not an external way of specifying a restindex.

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?

Michael
http://www.manning.com/foord

> I would assume something like
>
>   restindex
>       crumb:  pylit.py
>       source: pylit.py.txt
>       build:  yes
>       target: pylit.py.html
>       file:   pylit.py
>   /restindex
>
> but there is no mention of a "souce" keyword for the restindex.
>
> My current workaround is to manually convert the txt to html with
> docutils and a restindex.txt like::
>
>   restindex
>       crumb: pylit.py
>       target: pylit.py.html
>       file: pylit.py
>       file: pylit.py.txt
>       file: pylit.py.html
>       
>       file: 99bottles.py
>       file: 99bottles.py.txt
>       file: 99bottles.py.html
>       # ... and 24 more files ...
>   /restindex
>       
>
> Background
> ----------
>
> in my rest2web built site ( http://pylit.berlios.de/ ) I have lot of
> examples of "literate python scripts" which are reStructured text with some
> special requiremens to be compatible with the pylit txt<->code converter.
>
> Especially, the first comment is considered to be the file header. See
> http://pylit.berlios.de/tutorial/index.html#file-headers for the rationale.
>   
>   
> Thanks
>
> Günter  
>
>
> -------------------------------------------------------------------------
> SF.Net email is sponsored by:
> Check out the new SourceForge.net Marketplace.
> It's the best place to buy or sell services
> for just about anything Open Source.
> http://ad.doubleclick.net/clk;164216239;13503038;w?http://sf.net/marketplace
> _______________________________________________
> Rest2web-develop mailing list
> Res...@li...
> https://lists.sourceforge.net/lists/listinfo/rest2web-develop
>
>   

Re: [Rest2web-develop] build a file without embedded restindex

[Timo K. <Tim...@ko...>]

On Thu, Dec 13, 2007 at 02:39:32PM +0100, G. Milde wrote:
> Dear List,
> 
> how can I specify the source of a file in the restindex.txt file?
> 
> However, if there is a (restructured) text file I want rest2web to build but
> cannot include a restindex in, I have a problem.
> 
> I would assume something like
> 
>   restindex
>       crumb:  pylit.py
>       source: pylit.py.txt
>       build:  yes
>       target: pylit.py.html
>       file:   pylit.py
>   /restindex
> 
> but there is no mention of a "souce" keyword for the restindex.

Can you use include directive? Something like 

  restindex
      crumb:  pylit.py
      format: rest
      target: pylit.py.html
  /restindex

  .. include:: pylit.py.txt



Timppa