Hi folks, Has any work been done to create DocBook output from reST input? If not, where would I begin if I wanted to tackle such a thing? I'm actually interested in three output formats (in addition to XHTML and PDF, which appear to be well in hand): * DocBook * Simplified DocBook * XMLspec (the format W3C docs are written in) If there's anyone working on this already, how can I help? Please cc any reply, as I'm not (yet?) a subscriber to the list. TIA -Dethe
On Fri, Jun 14, 2002 at 10:19:12AM -0700, Dethe Elza wrote:
Hi folks,
Has any work been done to create DocBook output from reST input? If not, where would I begin if I wanted to tackle such a thing?
Hi, I just started on a docbook writer yesterday evening. It's probably about 1/4 done (but I started with all the easy elements ;-). I've never really used DocBook before, so I'm not very familiar with it, but I'm just trying to use the html writer as an example, and going from there. One question I had was what type of document(s) to generate? - book - chapter - article It would be nice if all 3 could be generated based on a parameter given to the writer, but given my lack of experience w/DocBook I don't know if this is feasible. Anyway, if I don't stall out or hit any big roadblocks, I'll try to make something available later this weekend. -Ollie
I'm actually interested in three output formats (in addition to XHTML and PDF, which appear to be well in hand):
* DocBook * Simplified DocBook * XMLspec (the format W3C docs are written in)
If there's anyone working on this already, how can I help?
Please cc any reply, as I'm not (yet?) a subscriber to the list.
TIA
-Dethe
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
Dethe Elza wrote:
Has any work been done to create DocBook output from reST input?
I don't think so. Welcome!
If not, where would I begin if I wanted to tackle such a thing?
First, make sure you're using the latest Docutils from CVS. Either get the files directly from CVS (instructions here: http://sourceforge.net/cvs/?group_id=38414), or get the latest snapshot (http://docutils.sourceforge.net/docutils-snapshot.tgz). Second, take a look at docutils/writers/html4css1.py, which is the only complete output writer so far. It uses the "Visitor" design pattern to do walk the document tree. Third, join the Docutils-specific mailing lists: - docutils-develop, for implementation discussions: http://lists.sf.net/lists/listinfo/docutils-develop/ - docutils-checkins, for CVS checkin messages (normally read-only): http://lists.sf.net/lists/listinfo/docutils-checkins/ (Join Doc-SIG too; high-level discussions take place here.) Finally, ask lots of questions. The internals are not well documented yet; your questions will help to fill the gaps.
I'm actually interested in three output formats ... :
* DocBook * Simplified DocBook * XMLspec (the format W3C docs are written in)
Great! I know DocBook quite well (as do many others, I'm sure), so we will be able to help conceptually map Docutils nodes to DocBook elements. It should be easy. I don't know anything about XMLspec.
(in addition to XHTML and PDF, which appear to be well in hand)
Englebert Gruber began work on PDF (via ReportLabs), but it still needs a lot of work. Englebert, what are your plans? Oliver Rutherfurd wrote:
I just started on a docbook writer yesterday evening. ... Anyway, if I don't stall out or hit any big roadblocks, I'll try to make something available later this weekend.
That's great! I look forward to seeing it. Let us know if you run into any trouble. I'll be checking mail over the weekend. And welcome!
One question I had was what type of document(s) to generate?
- book - chapter - article
It would be nice if all 3 could be generated based on a parameter given to the writer, but given my lack of experience w/DocBook I don't know if this is feasible.
You could add command-line options to choose the top-level element of the DocBook output. Articles and chapters contain sections, and books contain chapters. But I wouldn't worry about it for now. Choose one (article seems best); we can add bells & whistles later. -- David Goodger <goodger@users.sourceforge.net> 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/
... where would I begin if I wanted to tackle such a thing?
I forgot to mention was that you should also look at: - spec/docutils.dtd: This is the authority on the standard Docutils elements and their relationships. It may give you some clues about the semantics of Docutils document tree nodes. - "Project Policies" in spec/notes.txt: This is an overview of how the Docutils project is set up, and some guidelines that will help make development go smoothly. (Also online at http://docutils.sf.net/spec/notes.html#project-policies) As always, feedback is welcome. -- David Goodger <goodger@users.sourceforge.net> 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/
OK, thanks for the feedback. For reference, Simplified Docbook (current draft) is at: http://www.oasis-open.org/docbook/xml/simple/1.0CR1/index.shtml The DTD is specifically aimed at documents with root <Article>. And the XMLspec info is at: http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm I've done a bit more of my homework and read through the HTML writer, which looks clear enough. Sometimes I forget how easy it is to read the source in Python. Of course, it helps when the project is well-organized. Kudos to you. I've also joined the mailing lists, will load from CVS later. Thanks and I hope to be of some help. --Dethe -- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/
I've been lurking here for quite a while, but thought I would weigh in quickly on the issue of DocBook output, since I spent a good portion of the last year working with about a dozen developers creating a DocBook-based documentation system for a research programming and specification language. We experimented with "custom" markup syntaxes, automatic DocBook generation from source code, etc., and the experience was not as pleasant or fruitful as I had initially hoped. Basically, DocBook is the 400-lb. gorilla of markup formats. Most of our developers never used more than a 12-25 of the several hundred available element types, simply because there were too many to remember the proper nesting and attribute declaration policies for. The semantic richness of fully "DocBook-ized" documentation is impressive, but the time involved in actually placing more than basic structural and keyword markup around the text proved prohibitive in most cases. WRT to the choice of top-level element ('book', 'chapter', 'article', et. al.), I would have to recommend starting with the Simplified DTD, unless you're going to allow some sort of inline directive in the source to make the chapter, section, and appendix blocks explicit. Of course, you could just create one "default" template which included a "global" foreword, and then had chapters assigned to each source file in the original document, but it seems like an awful lot of work just for something that's usually intended to be an precursor format for HTML, PDF, or LaTeX final output. If you're seriously committed to DocBook output, though, might it not be easier to simply use an XSLT stylesheet to convert the DocUtils "native" XML format (basically just a dump of the internal document node structure, IIRC) into DocBook, rather than a seperate Python implementation? I'm a die-hard Python user, as well, but XSLT really is a great tool for this kind of deep tree walking and transformation task, esp. when your input and output are already both going to be XML documents. One specific "gotcha" to keep an eye out for: DocBook tables are painful, compared to HTML. Web browsers, and even other document publishing tools, are pretty good about making a "best guess" attempt at laying out simple tables according to their contents, with little or no explicit size information from the author, but most of the DocBook rendering tools I've used tend to mangle any table that doesn't include explicit column widths. In short, personally, I don't see any real use to DocBook output if HTML and PDF are already available with any degree of customizable formatting. Of course, that doesn't exclude the possibility that you might really want/need DocBook and XMLspec. So, now that I've done my soapboxing for the day, it's time for some breakfast. Good luck, either way. Lennon Day-Reynolds P.S.: To everyone who's contributed to the Doc-SIG, reST, etc., I say, "Good work!" Things are starting to look really good, guys and gals. On Saturday, June 15, 2002, at 09:56 PM, Dethe Elza wrote:
OK, thanks for the feedback.
For reference, Simplified Docbook (current draft) is at: http://www.oasis-open.org/docbook/xml/simple/1.0CR1/index.shtml The DTD is specifically aimed at documents with root <Article>.
And the XMLspec info is at: http://www.w3.org/XML/1998/06/xmlspec-report-v21.htm
I've done a bit more of my homework and read through the HTML writer, which looks clear enough. Sometimes I forget how easy it is to read the source in Python. Of course, it helps when the project is well-organized. Kudos to you.
I've also joined the mailing lists, will load from CVS later.
Thanks and I hope to be of some help.
--Dethe
-- "Melting down holy grails to make silver bullets for my .357 Panacea" Dethe Elza (delza@burningtiger.com) Chief Mad Scientist Enfolding Systems (http://enfoldingsystems.com) Weblog: http://livingcode.ca/
_______________________________________________ Doc-SIG maillist - Doc-SIG@python.org http://mail.python.org/mailman/listinfo/doc-sig
Lennon Day-Reynolds mail: lennon@day-reynolds.com www: http://day-reynolds.com/lennon/
Hi folks,
Has any work been done to create DocBook output from reST input? If not, where would I begin if I wanted to tackle such a thing?
I'm actually interested in three output formats (in addition to XHTML and PDF, which appear to be well in hand): you nearly got the point it is not my hand it is the elbow
On 14 Jun 2002, Dethe Elza wrote: that is broken, similar to my pdf-writer :-)
-- BINGO: change the basis of competition --- Engelbert Gruber -------+ SSG Fintl,Gruber,Lassnig / A6410 Telfs Untermarkt 9 / Tel. ++43-5262-64727 ----+
participants (5)
-
David Goodger -
Dethe Elza -
grubert@users.sourceforge.net -
Lennon Day-Reynolds -
Oliver Rutherfurd