Re: [Docutils-develop] [PATCH] Optionally disable docinfo section

[David G. <go...@us...>]

[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/