From: Ollie R. <ol...@ru...> - 2002-06-24 05:04:57
|
Hi, I just checked in an initial version of a DocBook writer for docutils into the sandbox (in "oliverr"). It still needs some work as well as general polish and testing, but I've been able to use it to generate html documents that were fairly similar to what's generated by the docutils html writer. I was generating html because I've not used docbook much, and it was easier to figure out how to generate html than pdf. To get html I generated DocBook output then used xsltproc and docbook-xslstylesheets to generate the html output. The main missing pieces are footnotes, citations, and all bibliography elements. Some footnode elements are generated, but don't work at all. Aside from that, most pieces should be in place -- whether they work correctly is another issue ;-). If anybody plays around with it, I'd appreciate any feedback or suggestions. Thanks to David for all his help and patience in answering all of my reST and DocBook questions. -Ollie |
From: Aahz <aa...@py...> - 2002-06-24 16:51:37
|
On Mon, Jun 24, 2002, Ollie Rutherfurd wrote: > > The main missing pieces are footnotes, citations, and all bibliography > elements. Some footnode elements are generated, but don't work > at all. Aside from that, most pieces should be in place -- whether > they work correctly is another issue ;-). Do you have a mechanism for generating index entries? -- Aahz (aa...@py...) <*> http://www.pythoncraft.com/ Project Vote Smart: http://www.vote-smart.org/ |
From: David G. <go...@us...> - 2002-06-25 00:43:55
|
Aahz wrote: > Do you have a mechanism for generating index entries? I doubt Oliver's DocBook writer does, because reStructuredText and the rest of DocBook doesn't, yet. You'll be needing these? The reStructuredText mechanism most suited to index entries would be "interpreted text". From the markup spec: Text enclosed by single backquote characters is interpreted:: This is `interpreted text`. Interpreted text is text that is meant to be related, indexed, linked, summarized, or otherwise processed, but the text itself is left alone. The text is "tagged" directly, in-place. The semantics of interpreted text are domain-dependent. It can be used as implicit or explicit descriptive markup (such as for program identifiers, as in the `Python Source Reader`_), for cross-reference interpretation (such as index entries), or for other applications where context can be inferred. The role of the interpreted text determines how the text is interpreted. It is normally inferred implicitly. The role of the interpreted text may also be indicated explicitly, using a role marker, either as a prefix or as a suffix to the interpreted text, depending on which reads better:: :role:`interpreted text` `interpreted text`:role: Roles are simply extensions of the available inline constructs; to emphasis_, `strong emphasis`_, `inline literals`_, and `hyperlink references`_, we can add "index entry", "acronym", "class", "red", "blinking" or anything else we want. A role marker consists of a colon, the role name, and another colon. A role name is a single word consisting of alphanumerics plus internal hypens, underscores, and periods; no whitespace or other characters are allowed. From the Docutils notes: Alan Jaffray suggested (and I agree) that it would be sensible to: - have a directive to specify a default role for interpreted text - allow the reST processor to take an argument for the default role - issue a warning when processing documents with no default role which contain interpreted text with no explicitly specified role For your purposes, setting a default role of "index" may do the trick. If all of your index entries will appear verbatim in the text, this should be sufficient. If not (e.g., if you want "Van Rossum, Guido" in the index but "Guido van Rossum" in the text), we'll have to figure out a supplemental mechanism, perhaps using substitutions. Either way, no support for any of this is implemented yet. Can you spell out your requirements? -- 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/ |
From: Richard J. <rj...@ek...> - 2002-06-25 01:12:20
|
On Tue, 25 Jun 2002 10:44, David Goodger wrote: > Aahz wrote: > > Do you have a mechanism for generating index entries? > > I doubt Oliver's DocBook writer does, because reStructuredText and the > rest of DocBook doesn't, yet. You'll be needing these? > > The reStructuredText mechanism most suited to index entries would be > "interpreted text". From the markup spec: > > Text enclosed by single backquote characters is interpreted:: > > This is `interpreted text`. An alternative to the "role" concept, where all text marked up in `backquotes` is assigned a particular role, would be to extend the parser to handle `index me`i or similar, to make the index tagging explicit. Just thinking out loud here... Richard |
From: David G. <go...@us...> - 2002-06-25 03:07:16
|
Richard Jones wrote: > An alternative to the "role" concept, where all text marked up in > `backquotes` is assigned a particular role, would be to extend the > parser to handle `index me`i or similar, to make the index tagging > explicit. That's what `index me`:i: does (could do). There's more syntax, but it's there on purpose, to emphasize the role. Without any extra syntax it looks like a typo, and may be too subtle to notice. The implicit role idea is that in any particular application, there's going to be one interpreted text role that is used more than any other. For that one role, no explicit :role: markup is required, just the `interpreted text` alone. A convenience feature, but significant. Any other roles used will need explicit markup. For docstrings in Python source, the implicit role will be "look up this text as a Python identifier in the current namespace, and automatically link to the definition of that identifier; the role itself is determined from context: the type of the identifier." For Aahz's book, it might be "mark this text as an index entry". The syntax for explicit interpreted text roles has yet to be tested in the real world; it's still just an idea that I'm not dead-set on. I'm open to alternatives. There's no real difference between `this`:role: and `this`<role> and `this`{role}; I chose :colons: because they're also used for field lists, <angle> brackets are too strongly associated with XML/SGML/HTML tags (and we'll probably see a lot of documents *featuring* such tags as subject matter), and {braces} are used in TeX and in ordinary text (especially technical text). For details of these and other alternatives considered, see http://docutils.sf.net/spec/rst/alternatives.html#interpreted-text-roles. -- 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/ |
From: David G. <go...@us...> - 2002-06-25 03:18:57
|
David Goodger wrote: > If all of your index entries will appear verbatim in the text, this > should be sufficient. If not (e.g., if you want "Van Rossum, Guido" > in the index but "Guido van Rossum" in the text), we'll have to > figure out a supplemental mechanism, perhaps using substitutions. I've thought a bit more on this, and I came up with two possibilities: 1. Using interpreted text, embed the index entry text within the interpreted text:: ... by `Guido van Rossum [Van Rossum, Guido]` ... The problem with this is obvious: the text becomes cluttered and hard to read. The processed output would drop the text in brackets, which goes against the spirit of interpreted text. 2. Use substitutions:: ... by |Guido van Rossum| ... .. |Guido van Rossum| index:: Van Rossum, Guido A problem with this is that each substitution definition must have a unique name. A subsequent ``.. |Guido van Rossum| index:: BDFL`` would be illegal. Some kind of anonymous substitution definition mechanism would be required, but I think that's going too far. Both of these alternatives are flawed. Any other ideas? -- 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/ |