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>