Date: Fri, 27 Aug 1999 13:22:42 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: Supporting non-DocBook documents in the tree Message-ID: <19990827132242.A26830@kilt.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
-doc,
Just an idea I'm kicking around at the moment, and feedback would be useful.
Please note that I'm not talking about doing any of this yet, but I'd like
to know people's opinions.
I think it's probably a bad idea if we insist that documentation that's
stored under doc/ be in DocBook format. DocBook's a great format, and
it should certainly be the 'official' DTD of the project, but there
are certainly going to be some authors who can't use it for some reason.
Specifically, I'm thinking of the sort of author who's just made a bit
of a breakthrough on something ("How I got my mumblefrozz card working
under FreeBSD") and wants to contribute that to the project. They've
written it up in either plain text, or HTML, and that's what they send
us. Their point of view is that they're doing us a favour, and that
they shouldn't have to spend more of their time learning DocBook before
we'll take their article. I think this is a wholly understandable point
of view.
I get the impression that we're currently viewed as being a bit
inflexible about the formats that we accept documentation in, and that
even when we do accept submissions, it takes us a while to get around
to converting them to DocBook. This is mostly due to lack of manpower.
So, how would we work around this, given that the current tree is geared
up to accept DocBook text[1], and convert that to the appropriate output
formats?
Each piece of documentation in the tree has to have a Makefile associated
with it, right? So there's no reason why we couldn't create a new make(1)
variable (SOURCE_FORMAT ?) that describes what the document's source format
is, and then the various make(1) rules that do the conversion from
$SOURCE_FORMAT to html, plain text, Postscript, and PDF all look at
$SOURCE_FORMAT to decide how to do the conversion.
For example, if $SOURCE_FORMAT == docbook then things stay pretty much
as they are. If $SOURCE_FORMAT == ascii (or perhaps, us-iso-8859-1, or
whatever) then we do conversion to HTML by pre/ap-pending "<pre>" and
"</pre>", conversion to Postscript with txt2ps (or maybe pre/ap-pending
some boilerplate TeX, and then running it through TeX), and so on.
We still wouldn't accept raw LinuxDoc though, that would be converted to
DocBook before being imported in to the tree.
The overall effect is that this would get more documentation in to the
tree, where it can be seen by more pairs of eyes, more people can practice
converting other formats to DocBook, and, through the CVS logs, more
people can see how you go about converting something from plain text
or HTML to DocBook, helping to demystify the process.
We live or die by the quality and quantity of documentation that we make
available, and I don't ever want to see us in a position where someone's
perfectly good article or book isn't accepted in to the tree because it's
in the wrong format, and we don't have the manpower to spare to convert
it to DocBook.
One obvious consequence of this is the FreeBSD 'house style'. As you
can see when you look at the books and articles that are already in the
tree, they've adopted a 'house style', because the HTML and other formats
that are generated are run through the same stylesheets. Obviously,
J. Random submissions from other people that weren't in DocBook wouldn't
be in the house style. But I think that's a small price to pay in order
to get the documentation in to the tree in the first place, where it's
as useful as possible to the maximum number of people.
Over time, the documents will migrate to the house style as they are
converted to DocBook.
I can see the question that's going to be immediately asked: "Why, then,
did we just go through all the pain of moving from LinuxDoc to DocBook?"
There are a couple of reasons for this. The 'flagship' documentation for
FreeBSD should certainly be in our flagship format, specifically, DocBook.
DocBook is far more suited to this type of documentation than LinuxDoc is.
LinuxDoc can also be mechanically translated to DocBook with the minimum
of fuss. This is not the case for other formats, such as plain text, or
HTML.
N
[1] That's not strictly true -- the Japanese subdirectory has contents
marked up in *roff. I refer, of course, to the manual pages.
--
[intentional self-reference] can be easily accommodated using a blessed,
non-self-referential dummy head-node whose own object destructor severs
the links.
-- Tom Christiansen in <375143b5@cs.colorado.edu>
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?19990827132242.A26830>