Date: Sun, 1 Mar 1998 19:32:47 -0500 (EST) From: John Fieber <jfieber@indiana.edu> To: Nik Clayton <nik@nothing-going-on.demon.co.uk> Cc: doc@FreeBSD.ORG Subject: Re: Handbook/FAQ -> DocBook migration Message-ID: <Pine.BSF.3.96.980301182525.15482I-100000@fallout.campusview.indiana.edu> In-Reply-To: <19980301204519.07839@nothing-going-on.org>
next in thread | previous in thread | raw e-mail | index | archive | help
[cc'd to doc, I hope you don't mind] On Sun, 1 Mar 1998, Nik Clayton wrote: > Right. However, couldn't the conversion project start now? I was > thinking something along the lines of: > > - Branch the CVS tree, and start doing the conversion on the branch. > > - Peridoically merge in changes from HEAD on to the branch. Every > time a merge is performed, tag the HEAD with a specific tag to > indicate that the merge was performed. As it stands, the semi-automated part of the linuxdoc to docbook conversion of the handbook is probably a couple hours of work at the most. The result is a parsable docbook version whose rendering basically matches that of the former linuxdoc version. The tedious manual part is cleaning up some of things that were mis-tagged by the automatic conversion and adding "enhanced" tagging that the docbook DTD allows. Since the result of the quick-and-dirty semi-automatic conversion is no *worse* than the existing linuxdoc markup, I don't feel that taking a CVS branch is really worthwhile. The tedious manual cleanup can happen on the "live" copy without difficulty. > Also, is there anything about the layout (within the > filesystem) of the component files that make up the handbook > that you'd like to change? For example, when I'm working on my > own documentation, I do things like name all the .sgml files > that are only intended to be included in other documents with a > leading '_'. I personally find leading underscores æthetically less than pleasing, but naming conventions are certainly open to change--SGML doesn't care a bit what things are called. > Also, one of my pet hates when working with the source to the existing > handbook is that the SGML files are all in one directory. It might be nice > if 'Handbook Mk II' organised them into directories, perhaps by chapter. For a book that was "designed" this would work, but the handbook, contrary to good design principles, has more or less just evolved. Since CVS doesn't handle moving files that well, I think a flat directory provides some needed flexibility. > > * Make sure it will all work for the Japanese version which uses > > EUC encoding for the source files. We will need to consult with ... > That's an interesting problem. Has anyone with sufficient Japanese > fluency/technical ability come forward to advise on this? The Japanese doc team is really on the ball; I'm not too worried about it actually. I just want to be sure we don't head down a path that will make things difficult for them in the long run. Basically, the semi-automatic part of the conversion needs to be carefully document so the Japanese team can duplicate it. The tedious manual markup cleanup can be done by tracking the CVS commits on the English version. (Taking great care to NOT mix actual markup changes with gratuitous re-formatting in the same commit!) > It occurs to me that having the FAQ, the Handbook and the tutorials as > 3 distinct entities spreads the information out a little too much. And generates unnecessary duplication, for example the PPP tutorial and the PPP stuff in the handbook. These really should be merged. Most of the tutorials should be merged for that matter. Two historical reasons for the tutorials existance are (1) to serve as a holding place for good documentation that needs to be integrated into the handbook and (2) for documents that should be processable as complete documents by themselves. > The existing handbook would be split into several DocBook 'parts'. Each > part would contain (probably) several chapters, one of which would be > 'Frequently Asked Questions'. Each of these might also contain one or > more tutorials (marked up as 'articles'). The FAQ chapter and tutorials > chapter would only contain FAQs and tutorials relative to that 'part'. This is a fairly radical reorganization...it sounds like it could work...let's just get the stuff translated into the infinately more flexible docbook framework, then think more about the (desparately needed) content examination/reorganization. > I'm also thinking about a slight amendment to the DTD. Specifically, > for marking up a FAQ it would be nice to have 'question' and 'answer' > elements, possibly with a containing 'faq' element. So the source > might look something like: I've been thinking about this for quite some time. For the moment, I think the simple approach would be to use the role attribute (common to all elements) to mark a section as being an FAQ: <chapter> <title>Installing FreeBSD</title> <sect1 role="FAQ"> <title>Which file do I download to get FreeBSD?</title> <para>[the answer]</para> </sect1> The stylesheet can do the appropriate rendering, yet the document remains processable by tools expecting a standard DocBook DTD. If we customize the DTD later, it will be trivial to change the document to use it. > On a related issue, what's your current thinking on using inline graphics > within the handbook (and potentially, the FAQ). I posted a message to -doc > on Friday in reponse to someone else's query about this that showed how > it could be done using marked sections, and at least four different > entity names. Hmph. I thought things were a little quiet, so I checked and I was dropped from the doc mailing list! Re-subscribed now. (gee, what else did I miss?) There are proverbial 101 ways to do graphics in SGML. The way I'm currently leaning toward is like this: <figure> <title>My Figure</title> <graphic entityref="myFigure"></graphic> </figure> The definition of the myFigure entity is in a catalog file. You have three catalog files for: HTML with graphics, HTML without and print. The HTML with graphics would reference a GIF (or JPEG) image, HTML without graphics would reference an ASCII-art image (or appropriate text description), print would reference a postscript image. Specify the correct catalog file when parsing with jade and the stylesheet will automagically get it right. > Remind me again why we need > Microsoft? Reminds me of a little quote from Arlo Guthrie: "You can't have, like, a light, without a dark to stick it in." -john To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?Pine.BSF.3.96.980301182525.15482I-100000>