docutils-develop Mailing List for Docutils: Documentation Utilities (Page 420)

On Sun, Aug 04, 2002, David Goodger wrote:
> Aahz wrote:
>>
>> Now, how do I add a new directive?  (For index tags.)
> 
> Take a look at docutils/parsers/rst/directives/images.py for relevant
> examples.  If you could show us some concrete examples of what you want, it
> would be easier to advise.

After a quick skim of images.py: So, in other words, in order to add a
new directive, I'm going to have to understand how the state machine
works?

> In the index, combined with other entries, it might look like this::
> 
>     statement syntax
>         expression statements ..... 56
>         assignment ................ 57
>         simple statements ......... 58
>         compound statements ....... 60

Note that currently I don't care about reST generating the actual index;
I'm only interested in emitting index tags for OpenOffice.  That goes
double because OpenOffice will be converted to Word and thence to Frame
before the index gets generated.

(Yes, I'm ignoring your questions about requirements for now; I'm more
interested in hacking up something which gives minimal results.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Aahz wrote:
> Now, how do I add a new directive?  (For index tags.)

Take a look at docutils/parsers/rst/directives/images.py for relevant
examples.  If you could show us some concrete examples of what you want, it
would be easier to advise.

Were I writing a book with an index, I guess I'd need two different kinds of
index tags: inline/implicit and out-of-line/explicit.  For example::

    In this `paragraph`:index:, several words are being
    `marked`:index: inline as implicit `index`:index:
    entries.

    .. index:: markup
    .. index:: syntax

    The explicit index directives above would refer to
    this paragraph.

The words "paragraph", "marked", and "index" would become index entries
pointing at the words in the first paragraph.  The index entries appear
verbatim in the text.  (Don't worry about the ugly ":index:" part; if
indexing is the only application of interpreted text in your documents, it
can be implicit and omitted.)  The two directives provide manual indexing,
where the index entry words ("markup" and "syntax") do not appear in the
main text.  We could combine the two directives into one::

    .. index:: markup; syntax

Semicolons instead of commas because commas could *be* part of the index
entry, like::

    .. index:: van Rossum, Guido

Sometimes index entries have multiple levels.  Given::

    .. index:: statement syntax: expression statements

In the index, combined with other entries, it might look like this::

    statement syntax
        expression statements ..... 56
        assignment ................ 57
        simple statements ......... 58
        compound statements ....... 60

How does all that sound?  These are just my initial ideas.  Nothing's been
implemented yet, so tell us your requirements to get them incorporated.
Last time around, you mentioned "see / see also" index entries; I'm
unfamiliar with the semantics of these.  I guess I'll be reading more of the
DocBook docs, a great reference for this type of thing (although the DocBook
implementation is not always ideal).

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Aahz wrote:
> I was a bit confused about the relationship between write() and
> translate(); I think the latter might be better named "visit()".

I think of "visit()" as an abstract tree traversal operation: the mechanics.
"translate()" is what the "visit" is actually accomplishing: semantics.
Perhaps "transform()" would have been better, but it was already taken. ;-)

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Fri, Aug 02, 2002, David Goodger wrote:
> Aahz wrote:
>> 
>> My primary interest -- I think -- is in a Writer class, because I'm
>> trying to create OpenOffice documents.
> 
> OpenOffice docs are XML; internal Docutils document trees are
> equivalent to DOM trees, which is XML.  Guess what?  You're becoming
> an XML geek. ;-)

<sour look>  Yes, I knew that already.  Fortunately, I think I mostly
don't need to actually understand what I'm doing.

> A Writer walks the internal document tree, and translates each node
> or group of nodes into the target (OpenOffice) structure.  To write
> a Writer, you have to understand both the Docutils document tree and
> the target format.  I believe the OpenOffice document structure has
> some documentation (how good, I don't know).  The Docutils document
> tree is documented in spec/docutils.dtd, which is current but skeletal
> (it's only a gross structure description; it says nothing about
> semantics or internal node attributes), and in spec/doctree.txt, which
> is incomplete.  To get something more complete and fleshed-out, ask
> questions.  I'll be happy to answer, and those answers will go into
> the docs.  I'll try to work on the docs too, but it will go faster
> with prompting from you.

I was a bit confused about the relationship between write() and
translate(); I think the latter might be better named "visit()".

I'm less using the OpenOffice docs than I am writing OpenOffice
documents and examining the XML output.  

> Start by examining the most complete Writer module we have,
> docutils/writers/html4css1.py.  Take the output from processing a
> document with tools/docutils-xml.py, and compare to the output from
> tools/html.py.  The HTMLTranslator class in html4css1.py traverses
> the tree given by the docutils-xml.py output, which is equivalent
> to the internal document tree, using a Visitor pattern.  Every node
> in the document tree triggers a "visit_node" method on entry, and a
> "depart_node" method on exit.  These methods build a target format
> document one piece at a time.

Okay, got that.  It's not that different from sgmllib.

Now, how do I add a new directive?  (For index tags.)
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

Aahz wrote:
> Okay, so there's simple docs on writing documents in reST, but I'm
> having difficulty figuring out how to write tools for processing reST
> without understanding the whole system, particularly given that I'm not
> exactly an XML geek.

A "How a Writer works & how to write one" document is on the to-do list, but
that's all so far.

> My primary interest -- I think -- is in a Writer class, because I'm
> trying to create OpenOffice documents.

OpenOffice docs are XML; internal Docutils document trees are equivalent to
DOM trees, which is XML.  Guess what?  You're becoming an XML geek. ;-)

A Writer walks the internal document tree, and translates each node or group
of nodes into the target (OpenOffice) structure.  To write a Writer, you
have to understand both the Docutils document tree and the target format.  I
believe the OpenOffice document structure has some documentation (how good,
I don't know).  The Docutils document tree is documented in
spec/docutils.dtd, which is current but skeletal (it's only a gross
structure description; it says nothing about semantics or internal node
attributes), and in spec/doctree.txt, which is incomplete.  To get something
more complete and fleshed-out, ask questions.  I'll be happy to answer, and
those answers will go into the docs.  I'll try to work on the docs too, but
it will go faster with prompting from you.

Start by examining the most complete Writer module we have,
docutils/writers/html4css1.py.  Take the output from processing a document
with tools/docutils-xml.py, and compare to the output from tools/html.py.
The HTMLTranslator class in html4css1.py traverses the tree given by the
docutils-xml.py output, which is equivalent to the internal document tree,
using a Visitor pattern.  Every node in the document tree triggers a
"visit_node" method on entry, and a "depart_node" method on exit.  These
methods build a target format document one piece at a time.

Next, ask questions.  Iterate.  Continual incremental improvement.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Okay, so there's simple docs on writing documents in reST, but I'm
having difficulty figuring out how to write tools for processing reST
without understanding the whole system, particularly given that I'm not
exactly an XML geek.

My primary interest -- I think -- is in a Writer class, because I'm
trying to create OpenOffice documents.
-- 
Aahz (aa...@py...)           <*>         http://www.pythoncraft.com/

Project Vote Smart: http://www.vote-smart.org/

[In private correspondence, I asked Adam to describe the process he's
using to generate his website pages, each a collection of
subdocuments.]

This is important for the following reasons:

- If you're using Docutils to process multiple source text documents,
  then you combine the resulting HTML, you must be stripping off the
  <html>, <head>, etc. parts.  So it should be easy to also remove the
  <table class="docinfo"> too, and a "--no-docinfo" option isn't
  necessary.

- If you're combining multiple text sources first and then using
  Docutils to process that all at once, there's a different issue.
  Only the first subdocument's bibliographic field list will be
  interpreted as "docinfo", so the others will have to be removed
  somehow (they're just ordinary field_list elements now), and a
  "--no-docinfo" option wouldn't work.

Either way, it looks like you'll need a custom solution, probably a
"Reader" that understands the context of your site (the process behind
it), and definitely a custom front end.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Fri, 2 Aug 2002 2:59 pm, Richard Jones wrote:
> On Fri, 2 Aug 2002 1:53 pm, David Goodger wrote:
> > There's an interesting thread I started on Python-Dev called
> > "Docutils/reStructuredText is ready to process PEPs".  It begins here:
> > http://mail.python.org/pipermail/python-dev/2002-August/027192.html
>
> Simple answer to Ping's complaint ("It's too flexible") ... scrape a
> different version of the spec. At each step of the functionality, present
> "the way to do it" with a little pointer off to "the variations you may use
> in doing it this way" :)

Already done, ignore me ;)


   Richard

On Fri, 2 Aug 2002 1:53 pm, David Goodger wrote:
> There's an interesting thread I started on Python-Dev called
> "Docutils/reStructuredText is ready to process PEPs".  It begins here:
> http://mail.python.org/pipermail/python-dev/2002-August/027192.html

Simple answer to Ping's complaint ("It's too flexible") ... scrape a different 
version of the spec. At each step of the functionality, present "the way to 
do it" with a little pointer off to "the variations you may use in doing it 
this way" :)

People are definitely uncomfortable with the flexibility you've given them. 
Unfortunate :)


    Richard

There's an interesting thread I started on Python-Dev called
"Docutils/reStructuredText is ready to process PEPs".  It begins here:
http://mail.python.org/pipermail/python-dev/2002-August/027192.html

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Adam]
>> No, the output is *not* legal HTML 4 since it is in a XML syntax,
>> not SGML one. There are some differences between XML and SGML in
>> what is allowed. For example empty tags like <this/> do not exist
>> in SGML, and therefore browsers that don't support XHTML (and
>> hence XML) might get confused.

[Dethe]
> While this is true, browsers specifically ignore attributes they
> don't recognize.  By putting a space between the final attribute or
> tagname and the trailing slash (like <this /> or <this
> example="true" /> instead of <this/> older browsers will treat it as
> an unknown attribute and ignore it.

Thanks for clearing that up, Dethe, from a practical angle I hadn't
heard before.  So although perhaps not strictly legal HTML, XHTML is
compatible with HTML 4.  (I won't get into how XML is supposed to be
legal SGML [given suitable low-level magic].)

I was asked to make the writer XHTML-compliant some time ago and
didn't see any harm.  It probably doesn't matter either way; by their
very nature, browsers (and any software dealing with HTML) have to be
lenient and forgiving.

Until there's a concrete example of a modern browser (one which
supports HTML 4 & CSS) which does *not* support XHTML, I'm not
concerned.  I doubt if I'll be concerned even if there *is* such an
example. ;-)

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Adam Chodorowski wrote:
> That will not work, since the point is that I want the bibliographic
> fields not display only for *some* output formats. The output files
> that are intended to be standalone (for example PDF or simple HTML)
> should contain the fields, but the files intended for tight
> integration into a website should not.
> 
> So the bibliographic information needs to be there in the input; I
> just want to disable it in some (one, actually) of the output
> formats.

It definitely sounds like a custom solution or a templating system is
called for.  I'd much rather see the beginnings of a new,
comprehensive templating system than start down the path of adding
questionable features to html4css1.py.  In any case, if that one
option *is* all you really need, you can easily derive a new writer
from html4css1.py (that's what pep_html.py does).

> I'm also tinkering with the idea to write plaintext (no, this
> isn't as silly as it would seem ;-)) and AmigaGuide writers.

Not silly at all.  Plaintext would be welcome; a *reStructuredText*
writer would be *very* welcome indeed!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

On Thu, 2002-08-01 at 03:06, Adam Chodorowski wrote:
> No, the output is *not* legal HTML 4 since it is in a XML syntax, not SGML
> one. There are some differences between XML and SGML in what is allowed. For
> example empty tags like <this/> do not exist in SGML, and therefore browsers
> that don't support XHTML (and hence XML) might get confused.    

While this is true, browsers specifically ignore attributes they don't
recognize.  By putting a space between the final attribute or tagname
and the trailing slash (like <this /> or <this example="true" /> instead
of <this/> older browsers will treat it as an unknown attribute and
ignore it.

The only browser I'm aware of which still had trouble with XHTML 1.0
after the application of this convention was an old version of the AOL
browser.  This is based on following the discussion on the XHTML mailing
list for some time.

> > Do you know of a browser that doesn't support Docutils' (X)HTML output but >
> > *does* support HTML 4?

See above.

-- Dethe

Dethe Elza (Dad...@li...)
Weblog: http://livingcode.manilasites.com

On Wed, 31 Jul 2002 19:58:40 -0400 David Goodger
<go...@us...> wrote:

> [Adam]
> >>> I have added an option to disable inclusion of the docinfo section
> >>> in the generated documents.
> 
> [David]
> >> What's the motivation?
> 
> [Adam]
> > The reason is mostly esthetic: while bibliographic information is
> > normally displayed when the document is used standalone and
> > especially when it is in printed (or equivalent, like ebook)
> > form. However, with online content you don't normally do this, but
> > have that information hidden or put somewhere else. I'm working on a
> > website were a lot of documentation is presented, and IMHO the
> > bibliographic information is irrelevant there.
> 
> Do the documents you're processing have to include bibliographic
> fields in their source?  If you're using them just to keep track of
> details for writing/editing purposes, how about putting that
> information in comments?

That will not work, since the point is that I want the bibliographic fields
not display only for *some* output formats. The output files that are intended
to be standalone (for example PDF or simple HTML) should contain the fields,
but the files intended for tight integration into a website should not.    

So the bibliographic information needs to be there in the input; I just want
to disable it in some (one, actually) of the output formats. 

> > Actually, I'm not totally sure myself which is better in all
> > contextes, but I thought it would be a usefull option to have.
> 
> Doesn't feel right to me.  The html4css1.py HTML writer was never
> intended to be a total solution, just a basic example.  I don't want
> it to grow so many options, at least not right now.
> 
> Perhaps what you need is something more configurable?  Perhaps a
> derivative writer is what you need; see pep_html.py for an example
> subclassing the classes in the html4css1.py module.  Or a specialized
> reader that understands the context of your files and how they fit
> together.  If you want radically different HTML from what html4css1.py
> gives you, it may be time to start working on a templating system.

Actually, I *do* want radically different HTML than html4css1 gives me, but
for other reasons. :) [#] 

> > For example, you can already disable generator and time/datestamps,
> > which are also metadata.
> 
> But those are a different kind of metadata, generated *by* the
> processing system.  You have to explicitly ask for them.  They're not
> in the source document.

True. 
 
> BTW, what's Swedish for "dedication"?  (New bibliographic field needs
> translation.)

It's "dedikation". :) Actually, you can also use "tillägnan", but "dedikation"
is more common. I've added this to docutils/languages/sv.py.


.. [#] I will most probably starting on a HTML writer that only outputs pure  
     HTML 4.01 (transitional) documents, that don't require CSS to display    
   correctly [instead I will use tables for layout]. The reason for this 
       is that a large portion of the intended audience use browsers that     
  don't support CSS. 

       I'm also tinkering with the idea to write plaintext (no, this isn't as 
      silly as it would seem ;-)) and AmigaGuide writers.

---
Adam Chodorowski <ad...@ch...>

Do not meddle in the affairs of wizards, for you are crunchy and good
with ketchup.
    -- Aleister Crowley

On Wed, 31 Jul 2002 19:51:30 -0400 David Goodger
<go...@us...> wrote:

[...]
 
> AFAICT the output is legal HTML 4.  

No, the output is *not* legal HTML 4 since it is in a XML syntax, not SGML
one. There are some differences between XML and SGML in what is allowed. For
example empty tags like <this/> do not exist in SGML, and therefore browsers
that don't support XHTML (and hence XML) might get confused.    

> Do you know of a browser that doesn't support Docutils' (X)HTML output but >
> *does* support HTML 4?

I'm not sure since I'm unable to test, but I have a feeling most AmigaOS
browsers do not support XHTML but do support HTML 4. For example, they have
mostly very spotty CSS support, so it wouldn't suprise. Whether or not this
results in bad display, I don't know (don't have the possibility to test it
right now; I might do so this weekend).

---
Adam Chodorowski <ad...@ch...>

Windows is a 32 bit patch to a 16 bit GUI based on a 8 bit operating
system, written for a 4 bit processor by a 2 bit company which cannot
stand 1 bit of competition.

The purpose of the Docutils project is to create a set of tools for
processing plaintext documentation into useful formats, such as HTML,
XML, and TeX.  It is the subject of PEPs 256 & 258.  Docutils
currently supports input from standalone files and PEPs; the emphasis
for release 0.3 will be support for inline documentation from Python
modules and packages.  Docutils uses the reStructuredText markup, the
subject of PEP 287; but other markups are possible.  It currently
produces simple HTML for CSS and Docutils-native XML.  PDF and DocBook
XML are under development, and other formats will become available in
time.

Quick link to the download:

    http://prdownloads.sourceforge.net/docutils/docutils-0.2.tar.gz

Docutils home page: http://docutils.sourceforge.net/

There have been many improvements since release 0.1:

* The front-end tools have increased in number and now have support
  for command-line options (thanks to Greg Ward's Optik) and
  configuration files.

* Added PEP processing (see http://docutils.sf.net/spec/pep-0287.html
  for an example).  Under consideration by PythonLabs and Python-Dev
  for python.org use.

* Added a new "simple tables" construct to reStructuredText.

* Improved the generated HTML.  Now XHTML-compatible.  Improved
  stylesheet support

* Unicode and input/output encoding support.

* Swedish and German output support (boilerplate translations; thanks
  to Adam Chodorowski and Gunnar Schwant).

* Lots of internal improvements.

To subscribe to the mailing lists:

* Development discussions (doc...@li...):
  http://lists.sourceforge.net/lists/listinfo/docutils-develop

* CVS checkin messages:
  http://lists.sourceforge.net/lists/listinfo/docutils-checkins

High-level discussions take place on the Python Doc-SIG mailing list:
http://mail.python.org/mailman/listinfo/doc-sig,
mailto:Do...@py...

User documentation:

* A ReStructuredText Primer (gentle introduction):
  http://docutils.sf.net/docs/rst/quickstart.html

* Quick reStructuredText (user reference):
  http://docutils.sf.net/docs/rst/quickref.html

* Docutils Front-End Tools: http://docutils.sf.net/docs/tools.html

Further details here:

* Docutils README: http://docutils.sf.net/README.html

* Docutils History: http://docutils.sf.net/HISTORY.html

* Copying Docutils: http://docutils.sf.net/COPYING.html

There is still much work to be done.  Contributors are welcome!

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

[Adam]
>>> I have added an option to disable inclusion of the docinfo section
>>> in the generated documents.

[David]
>> What's the motivation?

[Adam]
> The reason is mostly esthetic: while bibliographic information is
> normally displayed when the document is used standalone and
> especially when it is in printed (or equivalent, like ebook)
> form. However, with online content you don't normally do this, but
> have that information hidden or put somewhere else. I'm working on a
> website were a lot of documentation is presented, and IMHO the
> bibliographic information is irrelevant there.

Do the documents you're processing have to include bibliographic
fields in their source?  If you're using them just to keep track of
details for writing/editing purposes, how about putting that
information in comments?

> Actually, I'm not totally sure myself which is better in all
> contextes, but I thought it would be a usefull option to have.

Doesn't feel right to me.  The html4css1.py HTML writer was never
intended to be a total solution, just a basic example.  I don't want
it to grow so many options, at least not right now.

Perhaps what you need is something more configurable?  Perhaps a
derivative writer is what you need; see pep_html.py for an example
subclassing the classes in the html4css1.py module.  Or a specialized
reader that understands the context of your files and how they fit
together.  If you want radically different HTML from what html4css1.py
gives you, it may be time to start working on a templating system.

The HTML writer breaks up the output document into several pieces.  It
would be easy to make the docinfo a separate piece as well, which
would make life easy for a derivative writer.

> You can see the bibliographic fields as meta-information about the
> document: it's information about the document, not part of the
> document itself. As such, sometimes you might not want it in the
> output.

It could be argued that bibliographic fields are as much part of a
document as the title or 5th paragraph.  But I take your point.

> For example, you can already disable generator and time/datestamps,
> which are also metadata.

But those are a different kind of metadata, generated *by* the
processing system.  You have to explicitly ask for them.  They're not
in the source document.

>> Also, the docinfo fields will be removed from the document
>> entirely, losing information.  Do you want it all gone?  Why?
> 
> I don't want it to show up in the output (see above).

Then why do you have it in the input?  I'm not being argumentative;
I'd just like a clear use case.

BTW, what's Swedish for "dedication"?  (New bibliographic field needs
translation.)  TIA

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Adam Chodorowski wrote:
> Shouldn't the "html4css1" writer be renamed to "xhtml"?  That's
> namely the output it generates, and there is a *lot* of difference
> (when it comes to browser support) between HTML 4 and XHTML.

It's XHTML-compatible HTML 4 output (or is intended to be).  It
doesn't use any non-HTML tags.  I don't see a need to change the
module name, but it'd be easy to add an alias 'xhtml'->'html4css1' (in
docutils/writers/__init__.py, ``_writer_aliases``).

AFAICT the output is legal HTML 4.  Do you know of a browser that
doesn't support Docutils' (X)HTML output but *does* support HTML 4?

From the XHTML spec (http://www.w3.org/TR/2001/WD-xhtml1-20011004):

    [XHTML] is intended to be used as a language for content that is
    both XML-conforming and, if some simple guidelines are followed,
    operates in HTML 4 conforming user agents.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Adam Chodorowski wrote:
> I noticed that the 'raw' directive doesn't work. Any special reason,

No.

> or is it simply not implemented yet?

Bingo.  It's on the to-do list.  I've added "**NOT IMPLEMENTED YET**"
to the relevant directives in the docs (spec/rst/directives.txt).

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Hi.

I noticed that the 'raw' directive doesn't work. Any special reason, or is it
simply not implemented yet?

---
Adam Chodorowski <ad...@ch...>

Real Programmers don't play tennis, or any other sport that requires
you to change clothes.  Mountain climbing is OK, and real programmers
wear their climbing boots to work in case a mountain should suddenly
spring up in the middle of the machine room.

Hi.

Shouldn't the "html4css1" writer be renamed to "xhtml"? That's namely the
output it generates, and there is a *lot* of difference (when it comes to
browser support) between HTML 4 and XHTML. 

---
Adam Chodorowski <ad...@ch...>

Ludwig Boltzmann, who spent much of his life studying statistical mechanics, 
died in 1906, by his own hand. Paul Ehrenfest, carrying on the work, died 
similarly in 1933. Now it is our turn to study statistical mechanics.
    -- David L. Goodstein "States of Matter"

On Fri, 26 Jul 2002 22:56:16 -0400 David Goodger
<go...@us...> wrote:

> > I have added an option to disable inclusion of the docinfo section
> > in the generated documents.
> 
> What's the motivation?  (Why do you want to do this?  What purpose
> does it serve?)  I'd like to know because I suspect that this may not
> be the best solution.  It depends on what you want to do and why.  I'd
> rather hear it from you and not speculate.

The immediate goal of the option is to remove the bibliographic fields from
the output. The reason is mostly esthetic: while bibliographic information is
normally displayed when the document is used standalone and especially when it
is in printed (or equivalent, like ebook) form. However, with online content
you don't normally do this, but have that information hidden or put somewhere
else. I'm working on a website were a lot of documentation is presented, and
IMHO the bibliographic information is irrelevant there. Actually, I'm not
totally sure myself which is better in all contextes, but I thought it would
be a usefull option to have.

You can see the bibliographic fields as meta-information about the document:
it's information about the document, not part of the document itself. As such,
sometimes you might not want it in the output. For example, you can already
disable generator and time/datestamps, which are also metadata.   

> > You can see the relevant changes in the diffs below.  If nobody
> > objects, I would like to commit this to CVS...
> 
> The patch as it stands will *do* the processing, then throw it away
> (if --no-docinfo is passed).  Not very efficient, even for me ;-).

No, but that was the easiest place to put it since it required the least
code-digging. :-) Since the bibliographic fields are a very small part of the
whole document normally, I thought that it really didn't matter. But sure, the
clean way would be to disable the actual processing. 

> Also, the docinfo fields will be removed from the document entirely,
> losing information.  Do you want it all gone?  Why?

I don't want it to show up in the output (see above).
 
> Why not just leave the fields as a generic field list?  To do that,
> insert this before the first lines of
> docutils.transforms.frontmatter.DocInfo.transform::
> 
>     if not document.options.docinfo:
>         return

The intention is not to change the way the bibliographic fields are rendered,
but remove them from the output altogether (as said above) so this wouldn't
work.
 
---
Adam Chodorowski <ad...@ch...>

You can safely assume that you've created God in your own image when it 
turns out that God hates all the same people you do.
    -- Anne Lamott

[David]
>> Perhaps, in addition to the current fixed set of recognized fields,
>> we could have a generic bibliographic field where both the field
>> name and the field body are user-specified.

[Adam]
> Yes, I think this is a very good idea. People are bound to come up
> with some extra bibliographic fields they would like to use, so this
> is the only good way to accomodate all of them.

A generic docinfo field is implemented in the latest CVS & snapshots.
This causes some behavior to change.  Previously, any unrecognized
fields were split off from the docinfo and became a separate
(ordinary) field list.  No longer; now they become generic fields.

I've also added "Dedication" as a registered field.  Like "Abstract",
"Dedication" is turned into a topic, but with 'class="dedication"' so
that it can be independently styled.

> However, there is a slight problem for handling fields which contain
> list of eg. names (as "authors" does and "translators" would do) as
> this is a totally specialized thing currently. I think it would make
> sense to create a general inline markup for "horizontal lists"
> (field lists, bulleted lists, etc being vertical ones) one could use
> in this (and other cases). This way people could even add their own
> "authors"-style bibliographic fields, and get them processed
> automatically in a similar way...

The "authors" field processing transforms a list into multiple
"author" elements.  In other words it takes a single plural field
containing a list and transforms it into multiple single fields.  Some
kind of mapping of plural to singular forms is required (currently
"authors" -> "author" is hard-coded).  I don't see how to automate
such a transform on arbitrary fields.  Field names ending in "s" isn't
a sufficient criterion, even in English ;-).  In any case, I'm not
sure that more special-casing is a good idea.

I suggest simply using a bullet list if you want a vertical list, or
punctuation-separation if you want a horizontal list::

    :Translators: - Me
                  - Myself
                  - I
    :Translators: Me; Myself; I

This should be easily understood by readers.  Is there any reason the
underlying markup should be more specific?

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Adam Chodorowski wrote:
> I have added an option to disable inclusion of the docinfo section
> in the generated documents.

What's the motivation?  (Why do you want to do this?  What purpose
does it serve?)  I'd like to know because I suspect that this may not
be the best solution.  It depends on what you want to do and why.  I'd
rather hear it from you and not speculate.

> You can see the relevant changes in the diffs below.  If nobody
> objects, I would like to commit this to CVS...

The patch as it stands will *do* the processing, then throw it away
(if --no-docinfo is passed).  Not very efficient, even for me ;-).
Also, the docinfo fields will be removed from the document entirely,
losing information.  Do you want it all gone?  Why?

Why not just leave the fields as a generic field list?  To do that,
insert this before the first lines of
docutils.transforms.frontmatter.DocInfo.transform::

    if not document.options.docinfo:
        return

In any case, please first give us the rationale behind your desire for
this option.

-- 
David Goodger  <go...@us...>  Open-source projects:
  - Python Docutils: http://docutils.sourceforge.net/
    (includes reStructuredText: http://docutils.sf.net/rst.html)
  - The Go Tools Project: http://gotools.sourceforge.net/

Hi.

I have added an option to disable inclusion of the docinfo section in the
generated documents. You can see the relevant changes in the diffs below.
If nobody objects, I would like to commit this to CVS...

diff -u -r1.12 frontend.py
--- frontend.py	25 Jul 2002 01:47:58 -0000	1.12
+++ frontend.py	26 Jul 2002 10:40:24 -0000
@@ -52,6 +52,10 @@
          ('Do not include a "View document source" link.',
           ['--no-source-link'], {'action': 'store_false',
                                  'dest': 'source_link'}),
+         ('Include the docinfo section. This is the default.',
+          ['--docinfo'], {'action': 'store_true', 'default': 1}),
+         ('Do not include the docinfo section.',
+          ['--no-docinfo'], {'action': 'store_false', 'dest': 'docinfo'}),
          ('Enable backlinks from section headers to table of contents '
           'entries.  This is the default.',
           ['--toc-entry-backlinks'],

diff -u -r1.4 frontmatter.py
--- transforms/frontmatter.py	11 Jul 2002 01:50:40 -0000	1.4
+++ transforms/frontmatter.py	26 Jul 2002 10:41:06 -0000
@@ -239,7 +239,8 @@
                 document[index] = remainder
             else:
                 del document[index]
-            document[biblioindex:biblioindex] = nodelist
+            if document.options.docinfo:
+                document[biblioindex:biblioindex] = nodelist
         return
 
     def extract_bibliographic(self, field_list):


---
Adam Chodorowski <ad...@ch...>

Unseen University had never admitted women, muttering something about
problems with the plumbing, but the real reason was an unspoken dread that
if women were allowed to mess around with magic they would probably be
embarrassingly good at it ...
    -- Terry Pratchett, "The Light Fantastic"