Conversion of README's to DocBook Format
Greetings, I have been laboring in the background for about 18 months converting the README files from linuxdoc format to DocBook format. I believe I have nearly completed that effort. My efforts are currently stored in a separate cvs instance at XFree86.Org. During that time, some bit-rot of the documentation has occurred, but it should be a very small task to bring the DocBook versions to currency. It is time to begin submitting the infrastructure necessary to support the conversion (tools, DTD, stylesheets, etc) to XFree86 for inclusion into the main cvs instance. Since this involves over 1800 files, submitting them via Bugzilla or mailing lists as individual files is quite impractical (I have a gift for seeing the obvious) :-] I would like group the files into logical components and submit them as tar files. David Dawes and I have exchanged emails on the doc list and have come to an agreement as to placement of the logical groups in cvs. To whom or to where should I submit the tar files? After the infrastructure is completely in place, I will begin submitting the converted README files. Since there will be some stylistic changes in the output, I plan to start by submitting the converted XFree86 4.4 Release Notes, the New Design document, and the README.ati document. I chose these because they represent different styles of documents and will present good examples for discussion of any requested changes to style. Questions and comments are encouraged. John ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
Re: Conversion of README's to DocBook Format
On Fri, 21 Nov 2003 18:33:49 -0600, John Himpel [EMAIL PROTECTED] wrote: Greetings, I have been laboring in the background for about 18 months converting the README files from linuxdoc format to DocBook format. I believe I have nearly completed that effort. My efforts are currently stored in a separate cvs instance at XFree86.Org. Yes that's xml-work, right? Couldn't we just move it over to the public CVS? Since this involves over 1800 files, submitting them via Bugzilla or mailing lists as individual files is quite impractical (I have a gift for seeing the obvious) :-] I would like group the files into logical components and submit them as tar files. David Dawes and I have exchanged emails on the doc list and have come to an agreement as to placement of the logical groups in cvs. To whom or to where should I submit the tar files? Couldn't you just send them here? I think that would work. Questions and comments are encouraged. Do you have any documentation on how to read this docbook stuff? Are special utiliites required? How do they become HTML for Web browsing or is that a separate issue? I'm glad to hear that the Doc Team Leader finally finished his magnus opus. Could a sample page be sent here so we could start discussing it and seeing what this is all about? Best Regards, Georgina ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
Re: Conversion of README's to DocBook Format
On Fri, Nov 21, 2003 at 10:31:42PM -0500, Georgina Economou wrote: On Fri, 21 Nov 2003 18:33:49 -0600, John Himpel [EMAIL PROTECTED] wrote: Questions and comments are encouraged. Do you have any documentation on how to read this docbook stuff? While not directed at me, I do have some experience in converting a large scale documentation project to docbook. I'm glad this is being done -- DocBook is, IMHO, the best of the currently available markup formats for large amounts of information. It can render the input documents into a variety of formats... Are special utiliites required? For viewing and editting the docbook source files, all you need are a text editor, like vi (or emacs). There are certainly tools available that make doing the markup more automatic, but it certainly can be done in something as simple as a text editor. How do they become HTML for Web browsing or is that a separate issue? Typically, this is done with either something like XSLT (I think that's the right one -- I've not used this one), or something like a pipeline with OpenJade, and a bunch of other tools. When I did it last, it was involved to get the entire documentation tool-chain up and running, but once that was done, rendering the same document source into HTML, PDF and PostScript was just a matter of typing make. In many ways, if you're good at doing HTML, you're going to have no problems with doing DocBook markup. Some of the shortcuts that people often take in HTML (and most browsers are happy enough to display) don't work in SGML. -Kurt ___ Devel mailing list [EMAIL PROTECTED] http://XFree86.Org/mailman/listinfo/devel
