Date: Tue, 17 Aug 1999 22:49:25 +0100 From: Nik Clayton <nik@freebsd.org> To: doc@freebsd.org Subject: HEADS UP: DocBook FAQ translations required ASAP Message-ID: <19990817224925.A89707@catkin.nothing-going-on.org>
next in thread | raw e-mail | index | archive | help
Converting the FAQ to DocBook
IMPORTANT: The doc/ tree is *still* frozen. The only commits allowed
in doc/ at the moment are from (a) me, (b) a nominated member of one of
the translation teams, carrying out the instructions below. The tree
will be thawed as soon as possible, which basically means when this
work is carried out.
Translators -- with the repo-change almost complete, it's imperative that
we migrate the FAQs in the repository to DocBook, and to their correct
place in the repository, as soon as possible.
First, let me emphasise that this task is (a) not too difficult, and (b) not
too time consuming. I did it today in about 3 hours, which includes the
time spent to write this documentation. If you're familiar with Emacs
you should be able to do this in under two hours.
The steps to do the conversion are as follows (ignore the "book.sgml.nn"
comments -- those are the points when I copied "book.sgml" to a new filename
to keep a copy of my work so far, just in case I made mistakes -- although
feel free to use them to indicate convenient places to checkpoint your work
as well, or as convenient places to commit your changes -- note that the
filename is *always* book.sgml, and not book.sgml.2 or similar).
* You need to convert the LinuxDoc FAQ to DocBook, and place it in the
correct place in your repository tree.
Your FAQ is in doc/<your dir>/FAQ/*, and it should be stored in
doc/<your dir>/books/faq/. If at all in doubt, use the English FAQ as
a guide.
[ <your dir> is one of the new repo-directories, such as es_ES.ISO_8859-1
or ja_JP.eucJP, *not* the 'es' or 'ja' directories ]
In order to do the conversion you need instant(1) installed. This is
part of sgmlfmt(1), which you should have installed anyway for the
legacy Doc. Proj. stuff, so there should be no problems. The commands
to run are
% cvs checkout doc
% cd doc/<your dir>/books
% mkdir faq
% cvs add faq
% cd FAQ
% nsgmls -c /usr/local/share/sgml/linuxdoc/catalog FAQ.sgml | \
instant -t /usr/local/share/sgml/transpex/linuxdoc-docbook.ts > \
../books/faq/book.sgml
That gives you a "book.sgml" in the right place that you can commit to
the tree.
* Alter the DOCTYPE, so that is now using the FreeBSD exensions to DocBook
(book.sgml.2)
* Put in a Makefile to allow you to build other versions of the FAQ. You
can copy the English Makefile (making suitable modifications to the
MAINTAINER line as necessary) with no ill effects.
* Adding a QAndASet framework.
DocBook 3.1 has the <QAndASet> elements. The conversion will have marked
up each question in its own <sect1>, where the text of the question is the
<title>, and the answers are the different <para>s.
E.g.,
<sect1>
<title>What are the goals of FreeBSD?</title>
<para>...</para>
Groups of questions are chunked into <chapter>s.
What we want is a chapter bracketing a <qandaset> element.
Each question is indicated by a <qandaentry> element, which can in
turn contain <question> and <answer> elements (which can then contain
<para>s, and so on). In other words, we want to end up with this
(ignore the indentation for a moment).
<chapter>
<title>Networking and foo</title>
<qandaset>
<qandaentry>
<question>
<para>How do I do foo?</para>
</question>
<answer>
<para>You do foo by doing bar, followed by baz.</para>
</answer>
</qandaentry>
<qandaentry>
...
</qandaentry>
...
</qandaset>
</chapter>
To change this, do the following: ("S/R" == search and replace)
1. Just before (and after) each <chapter> element starts and ends,
include "<qandaset>" and "</qandaset>"
S/R "<sect1" -> "<qandaset><sect1"
"</sect1>" -> "</sect1></qandaset>"
This will leave some bogus <qandaset> elements in place, don't
worry, they get removed at a later stage.
book.sgml.3
2. Convert each "<sect1>" to a "<qandaentry><question>" pair. Leave
the trailing ">" off when you do the S/R, so that things like
<sect1
id="serial">
get turned in to
<qandaentry><question
id="serial">
S/R "<sect1" -> "<qandaentry><question"
book.sgml.4
3. Convert each <title> (except for those in the preamble, and
attached to <chapter>) to a <para>.
S/R "<title" -> "<para"
book.sgml.5
4. Convert each </title> (except for those in the preamble, and
attached to <chapter>) to a "</para></question><answer>"
triple.
S/R "</title>" -> "</para></question><answer>"
book.sgml.6
5. Convert each </sect1> to a </answer></qandaentry> pair.
S/R "</sect1>" -> "</answer></qandaentry>"
book.sgml.7
6. Remove the extra <qandaset>s that been added. If you're
using Emacs then do a regexp search for
</qandaset>\s-+<qandaset>
and replace it with
\n\n
to retain the newlines.
book.sgml.8
Commit at this point.
Now start fixing up the SGML validation errors. Most of these are because
the original FAQ didn't stick to the Q/A format it should have.
There are three problems you will need to fix before this is ready to go
live.
1. "Micron systems hang at boot time" is marked as <sect2>. This section
should be redesignated.
In the English version, this looks like
===
<qandaentry><question>
<para>Workarounds for specific hardware problems</para></question><answer>
<para>This section contains workarounds for specific hardware
problems encountered by our users.</para>
<sect2>
<para>Micron systems hang at boot time</para></question><answer>
<para>Certain Micron motherboards have a non-conforming PCI BIOS
implementation that causes grief when FreeBSD boots because
PCI devices don't get configured at their reported addresses.</para>
<para>Disable the "Plug and Play Operating System" flag in the BIOS
to work around this problem. More information can be found at
<ulink URL="http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron">http://cesdis.gsfc.nasa.gov/linux/drivers/vortex.html#micron</ulink></para>;
</sect2>
</answer></qandaentry>
===
Which is very strange. Remove the sentance starting at "Workarounds...",
and all the text (including markup) up to "Micron systems...". Then reword
the question to "My Micron system hangs..."
Remove the trailing </sect2>, and now it makes sense as a question. If in
doubt, use the CVS logs to see the differences in the English version.
book.sgml.9
Commit at this point.
2. Embedded in the "Networking" chapter is a large section about PPP, that
has appeared as a collection of <sect2> (and <sect3>) marked up sections.
This is a pain to deal with, so I've taken a somewhat simpler route.
All the contiguous PPP questions in this section have been taken out
en masse, and put in their own chapter, that comes between chapter
10 ("Networking") and the old chapter 11 ("Serial Communications").
This is quite handy, because (a) PPP is part way between these two topics
anyway, and (b) there is a wealth of PPP information hidden in the FAQ,
but the old organisation stuck it all behind one question ("I can't make
PPP work, what am I doing wrong?"). This new approach is easy to manage,
a little more consistent, and makes the PPP information much more visible
to the average user idly scanning the FAQ.
So, to duplicate what I did in your translations of the FAQ.
1. Find the '<qandentry><question id="userppp">' line (it's two lines
in the converted doc. This marks the start of the PPP section.
2. Find the end, which is the '</answer></qandaentry>' line just
before the "I can't create a /dev/ed0 device!" question.
3. Select all this text in your editor, and cut it out of that section.
4. Move to the beginning of the "Serial Communications" chapter,
and paste this text in between the two chapters.
5. Add a "<chapter id="ppp"><title>PPP</title><qandaset>" and
"</qandaset></chapter>"
line to the top and bottom of the newly pasted section,
respectively.
book.sgml.10
6. Go back to the search and replaces you did earlier, (but from the
2nd entry, not the first). Redo them, but looking for <sect2>
where previously you looked for <sect1>.
7. As the last step, but look for <sect3> instead.
This almost fixes things up adequately. The old <sect3> entries should
probably be itemised lists in the final output, but we can fix that up
later. The important thing to do at the moment is get something that
builds sufficiently well that it can be put up on the website.
At this point, you should be able to type "make" and get a formatted
version of the FAQ out. There should be no validation errors, but there
will be some XREF errors -- these are fairly harmless, and can be ignored
for the time being.
If there are validation errors it probably means you've ommitted an
element. Use "make validate" to get a list of just the errors, and
you can use "C-c C-o" in Emacs to move to the areas of the document
that have problems.
If you've still got problems, drop me a line, and I'll take a look at
it.
book.sgml.12
3. The Biblio information at the start of the FAQ is wrong, which means
that it doesn't appear properly on the generated files. Specifically,
you can just remove the "<bookbiblio>" and "</bookbiblio>" lines at
the top of the file.
book.sgml.13
That's it!
OK, there's still a lot of work to do, particularly in changing the markup
choices to something more useful. But the work you've just done is enough
to get the DocBook'd FAQ in a state where it's ready (IMHO) to go on the
Web, and replace the LinuxDoc version (and the crowd goes wild :-) ).
When you've done the above, and you're happy with it, please do one of
the following;
- If you're a translation team with commit privs, commit to the correct
place in the tree.
The only two files you should be committing are
doc/<your dir>/books/faq/book.sgml
doc/<your dir>/books/faq/Makefile
do not commit anything else. In particular (and no offense) please
wait for me to test it before you remove the LinuxDoc FAQ from your
tree, or turn on the books/faq directory in the Makefiles, thanks.
- If you're a translation team that hasn't got commit privs yet (and
if you are, fixing that is one of my priorities when all this hassle
is over) then e-mail me the book.sgml you've generated (run it through
gzip(1) or bzip(1) first though please) and I'll commit it ASAP.
If you're going to be doing the conversion of a translated FAQ, please let
me know, so I can keep track of who's doing what. Thanks.
N
--
[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?19990817224925.A89707>