[DOC-SIG] Library reference manual debate

[Case Roole]

Guido wrote:

> One final note: I looked at Perl's POD (Plain Old Documentation) for a
> few seconds.  It's more limited than TIM and uses physical markup
> (e.g. B<words in bold>), but has one feature that I like: a block of
> indented text offset by blank lines (I believe) is automatically
> interpreted as a code sample block (verbatim in LaTeX terms,
> @codeexample in TIM).  This makes POD source remarkably readable.  I
> presume that it would be trivial to add this to the TIM front-end.  (I
> particularly like this idea because it's the same convention that I
> used in the Python FAQ wizard. :-)

Just wondering: for HTML generation I use "megatags", non-HTML tags in
documents that are otherwise HTML. An SGML parser (derived from the one
in sgmllib) lets pure HTML pass, but fetches and processes the data 
embedded in these megatags (example below). This is decidedly not pure 
SGML or pure HTML, but the *code is extremely readable*. Is this what 
everybody is using the SGMLParser for, is it irrelevant for the matter 
discussed here, or is this a good idea?

cjr

------------------------------------------------------------
Example:

For my curriculum vitea I wanted a list of labels and values. It seemed
best to me to use a table with labels represented as table headers and 
values as table descriptions. Both are aligned to the center of the table
which is a default that can be changed by setting the attributes
'left_align' and 'right_align'. Attributes of the table can be set by using,
e.g. 'table_border'. (This approach is entirely derived from Pmw's naming 
conventions.)

Here is what I write:

<ENTRYFORM>
naam                  =  Cornelis Jan Roele
email                 =  <MAILTAG email="cjr@bound.xs4all.nl">
geboortedatum         =  9 januari 1967
geboorteplaats        =  Doetinchem,
straat en nummer      =  Spitsbergenstraat 67
postcode/woonplaats   =  1013 CL &nbsp; AMSTERDAM
telefoon              =  020-684.62.95
</ENTRYFORM>

NB the mailtag is another "megatag".
And this is what the parser generates:

<!--   Spin.EntryForm MegaTag -->
<TABLE border="0" align="center">
  <TR>
    <TH align="right">naam:  </TH>
    <TD align="left">Cornelis Jan Roele</TD>
  </TR>
  <TR>
    <TH align="right">email:  </TH>
    <TD align="left">&lt;<A HREF="mailto:cjr@bound.xs4all.nl">cjr@bound.xs4all.nl</A>&gt;</TD>
  </TR>
  <TR>
    <TH align="right">geboortedatum:  </TH>
    <TD align="left">9 januari 1967</TD>
  </TR>
  <TR>
    <TH align="right">geboorteplaats:  </TH>
    <TD align="left">Doetinchem'),</TD>
  </TR>
  <TR>
    <TH align="right">straat en nummer:  </TH>
    <TD align="left">Spitsbergenstraat 67</TD>
  </TR>
  <TR>
    <TH align="right">postcode/woonplaats:  </TH>
    <TD align="left">1013 CL &nbsp; AMSTERDAM</TD>
  </TR>
  <TR>
    <TH align="right">telefoon:  </TH>
    <TD align="left">020-684.62.95</TD>
  </TR>
</TABLE>



-- 
Case Roole <cjr@bound.xs4all.nl>


_______________
DOC-SIG  - SIG for the Python Documentation Project

send messages to: doc-sig@python.org
administrivia to: doc-sig-request@python.org
_______________