Date: Mon, 2 Mar 1998 11:02:40 +0000 From: nik@iii.co.uk To: John Fieber <jfieber@indiana.edu> Cc: Nik Clayton <nik@nothing-going-on.demon.co.uk>, doc@FreeBSD.ORG Subject: Re: Handbook/FAQ -> DocBook migration Message-ID: <19980302110240.40444@iii.co.uk> In-Reply-To: <Pine.BSF.3.96.980301182525.15482I-100000@fallout.campusview.indiana.edu>; from John Fieber on Sun, Mar 01, 1998 at 07:32:47PM -0500 References: <19980301204519.07839@nothing-going-on.org> <Pine.BSF.3.96.980301182525.15482I-100000@fallout.campusview.indiana.edu>
next in thread | previous in thread | raw e-mail | index | archive | help
On Sun, Mar 01, 1998 at 07:32:47PM -0500, John Fieber wrote:
> [cc'd to doc, I hope you don't mind]
Not at all. I meant to suggest it in my message :-)
> 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.
That's fine. But if I read your previous message correctly, there are
still issues with the conversion process itself (both conversion from
LinuxDoc to DocBook, and conversion from DocBook to HTML). And it's
these issues that are holding up the migration, because until they're
fixed they'll probably cause problems for most people trying to use
the handbook.
Hence the branch suggestion. The DocBook conversion process can go ahead,
without worrying about inadvertantly breaking the 'live' handbook.
> > 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.
Is now a good time to start a seperate discussion about the design and
structure of the handbook?
> > 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.
I'm in two minds about this. I think there's a need for a section in the
handbook that covers "Everything you need to know about PPP on FreeBSD",
and a tutorial that says "Do this, then do this, then do this. If you
want to understand why you're doing it, read this, this and this in the
main body of the handbook."
> > 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.
OK. What are the steps in the conversion process (assuming you will want
to do it 'live' and not on a separate branch)?
> > 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:
Good idea. Hadn't occured to me.
> > 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 hasn't been a great deal recently.
> 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.
Interesting approach. Wouldn't marked sections give more flexibility
though (on the assumption that inline images are not the only things
we might want to differentiate between different output formats) ?
> > 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."
"This OS is called NT. It's not new, and it's not really technology,
that's just the name of the OS."
N
--
Work: nik@iii.co.uk | FreeBSD + Perl + Apache
Rest: nik@nothing-going-on.demon.co.uk | Remind me again why we need
Play: nik@freebsd.org | Microsoft?
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?19980302110240.40444>