docutils-develop

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

[Adam C. <ad...@ch...>]

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"

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

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

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/

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

[Adam C. <ad...@ch...>]

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

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/

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

[Adam C. <ad...@ch...>]

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

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

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

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/

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

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

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