It's not technically required, but it keeps things looking nice, and much
easier to understand. This is important if people are going to be able
to learn DocBook by looking at the Handbook. It also makes it easier
to follow the structure if you don't have an SGML savvy editor.
I'm going to be *at least* as anal about this as bde is about style(9).
Sorry folks :-)
tar'ed and installed. Prompted by JKH.
Turn 'distribute' in to a NOP, so that the LinuxDoc Handbook is not
smashed by this one during "make release". We're almost ready to do
the switch. . .
me to *not* copy over his "BEER-WARE LICENSE" from doc/handbook/ctm.sgml
(which has been subsumed in to this file as part of the DocBook conversion).
Thanks Poul.
most of the other spurious comments.
Two comments relating to copyright have *not* been merged in from the
LinuxDoc version yet -- I've contacted the original authors to ask if
they would be willing to assign the copyright to the project. When I
get their response the copyright comments will either be merged in, or
left out, as necessary.
Rationale: All the changes to the DocBook handbook so far have been
careful to keep whitespace changes to a minimum. This is so the
translators have as easy a job as possible in identifying exactly what's
changed.
This has meant the English version has become more and more 'ugly'. Lines
indented by the wrong amount, some lines longer than 130 characters,
others shorter than 20, gaps of 3 or 4 lines between paragraphs (and
sometimes within paragraphs). This makes it difficult to follow the
structure of the document, and needlessly complicates fixing SGML
problems.
It also makes the source practically useless as a teaching aid; the
more baroque the source looks, the less likely people are to dive in and
contribute.
This commit fixes all that -- and boy was it tedious. The snag is, it's
touched almost every line in every file in the Handbook.
Technically, the changes were made by running (in Emacs)
sgml-indent-or-tab (bound to the TAB key) on almost each line (except
those in <programlisting>, <screen>, <literallayout>, and other
verbatim sections), and then running sgml-fill-element (bound to
C-c C-q) on most paragraphs.
FWIW, this is the first, only, and last change of this type contemplated.
The construct:
<citerefentry>
<refentrytitle>foobar</refentrytitle>
<manvolnum>1</manvolnum>
</citerefentry>
is a pain to type, and messes up the pretty-printing of the source code.
Replace every occurence of a entry like that with:
&man.foobar.1;
Adjusting the manual page name and section number appropriately.
The definitions for these entities are stored in man-refs.ent. This
file is in doc/share/sgml because it is not just specific to the Handbook.
I expect the DocBook'd FAQ and Tutorials (coming RSN) to use them as
well.
A new PUBLIC identifier has been created for these entities, and added to
the catalog file.
from doc/handbook.
File From -> To Merged to files...
---------------------------------------------------------------
authors.sgml 1.135 -> 1.139 authors.ent
bibliography.sgml 1.38 -> 1.39 bibliography/chapter.sgml
contrib.sgml 1.338 -> 1.341 staff/chapter.sgml
current.sgml 1.25 -> 1.26 cutting-edge/chapter.sgml
cvsup.sgml 1.41 -> 1.45 cutting-edge/chapter.sgml
eresources.sgml 1.53 -> 1.54 eresources/chapter.sgml
handbook.sgml 1.96 -> 1.101 handbook.sgml
install.sgml 1.67 -> 1.72 install/chapter.sgml
lists.sgml 1.8 -> 1.12 mailing-lists.ent
mirrors.sgml 1.101 -> 1.111 mirrors/chapter.sgml
porting.sgml 1.124 -> 1.130 ports/chapter.sgml
stable.sgml 1.19 -> 1.22 cutting-edge/chapter.sgml
submitters.sgml 1.277 -> 1.299 contrib/chapter.sgml[1]
vm.sgml -> 1.3 internals/chapter.sgml
Added
-----
newsgroups.ent
[1] For translators: Due to Eivind's massive update to the "Additional
Contributors" section, I refrained from merging in the changes by
hand. Instead, I took the list of names from submitters.sgml and
did various search/replaces on them.
I strongly suggest you just lift the complete list of names from
contrib/chapter.sgml and paste it in to your translation, since
there shouldn't be any actual translation required.
to resort the non-sorted entry of my "neighborhood", as well as myself.
I still have lingering doubts about the wiseness of moving David Greenman
around, though...
Also, changed other files to include myself as well. And that ends the
Committers 101. I hope I passed. :-) Now, to break the world. Err, "conquer"
the world. :-)
to resort the non-sorted entry of my "neighborhood", as well as myself.
I still have lingering doubts about the wiseness of moving David Greenman
around, though...
Committers 101. I hope I passed. :-) Now, to break the world. Err, "conquer"
the world. :-)
<informalexample>
<screen>
...
</screen>
</informalexample>
need the <informalexample> element. So remove it. Simple search and
replace does the trick.
${DOC}.tar. This honours the compression flags, so you can have it
generate .gz, .zip, etc.
* Instead of only building compressed versions when running the "install"
target they are now built for the "all" target as well.
generated for this target, and not the generic .html target as well.
Additional "-" before TeX and PDFTeX calls, which also return non-zero
status codes (almost called them errorlevels, how long since I last wrote
a .bat file?)
Doc. Proj. related ports under $PREFIX/share. Update en/handbook/Makefile
with the new paths.
Didn't seem worthwhile to do a repository copy for only three files moved.
Rather than delay any longer for a fix from Sebastien Rahtz (my TeX is not
up to fixing it, natch) replace footnotes in tables with <note>...</note>
after the table.
When the JadeTeX macros DTRT, this change can be reverted.
versions (modulo bugs in JadeTex). "make install" and "make clean" now also
seem to do the right thing.
Extensive documentation included, comments welcomed.
Default to "IGNORE", you should set them to "INCLUDE" by whatever
mechanism your SGML parser supports as necessary (i.e., Jade's -i
flag).
Added redefinitions for some ISO entities that aren't understood by
most web browsers. Since this is for HTML output only, wrap it in a
%output.html; marked section.
Use these marked sections to put both print and HTML stylesheets in one
.dsl file (freebsd.dsl). The print stylesheet now understands about the
elements that have been added to DocBook (and won't try and render them
in red).
Updated Makefile to use output.html and output.print on the command
line to Jade, instead of the earlier "html" and "print.
Note: producing .tex (and thence .ps and .pdf) versions of the Handbook
is broken. The Handbook tickles several bugs in the JadeTeX macros.
Sebastian Rahz, the JadeTeX author, knows about this, and is working on
fixing them.
* Merged in changes between tags LINUXDOC_2_DOCBOOK and
LINUXDOC_2_DOCBOOK_2. The merges are as follows (if a file isn't listed
here it's because there are no changes to merge since the
LINUXDOC_2_DOCBOOK tag was put down).
File From -> To Merged to files...
---------------------------------------------------------------
authors.sgml 1.118 -> 1.128 authors.ent
boothelp.sgml Added
contrib.sgml 1.312 -> 1.329 staff/chapter.sgml
eresources.sgml 1.50 -> 1.51 eresources/chapter.sgml
handbook.sgml 1.91 -> 1.95 handbook.sgml
mirrors.sgml 1.92 -> 1.99 mirrors/chapter.sgml
porting.sgml 1.112 -> 1.118 [1]
ports.sgml 1.31 -> 1.33 ports/chapter.sgml
printing.sgml 1.22 -> 1.23 printing/chapter.sgml
stable.sgml 1.17 -> 1.18 cutting-edge/chapter.sgml [2]
submitters.sgml 1.246 -> 1.261 contrib/chapter.sgml
[1] Merged changes. Part of these changes are the migration of the
"Making a port" section from contrib/chapter.sgml to
ports/chapter.sgml
[2] Merged some changes. 1.18 demotes some of the section headings so
that the -stable section will appear on one HTML page. This is not
the case with the DocBook stylesheets we're using, so wasn't
necessary. For the time being, the -stable headings will follow
the -current headings. This can be revisited after the migration
is complete.
There will be one more merge pass once the Handbook in doc/handbook/ is
frozen, and then a pass to reformat (refill) most of the lines in the
Handbook so it's more aesthetically pleasing. The SGML parsers don't
care, but it makes it easier to follow the structure when editing the
documents.
* Removed
sgml-shorttag: nil
sgml-minimize-attributes: max
from the Emacs local variables at the bottom of each file. It didn't
do quite what I was expecting.
tags LINUXDOC_2_DOCBOOK_START and LINUXDOC_2_DOCBOOK from doc/handbook/.
Note that the LINUXDOC_2_DOCBOOK tag is not necessarily at the HEAD of
the file. So some files won't show changes because changes were applied
after I laid down the LINUXDOC_2_DOCBOOK tag.
Not everything was merged. In some cases, URLs had been shortened;
http://www.freebsd.org/docproj/
becomes
../docproj/
This is a mistake, since users browsing the Handbook on their own machine
can't be expected to have links like this work. Of course, for mirrors,
they'll end up pointing back to the main site. For the mean time, do
nothing -- this will need an entity defined to reference the base URL
of the FreeBSD site, individual mirrors can set this as necessary.
Notice how some files (on the left) are merged to the same file (on
the right). This is because the new Handbook file structure is organised
on DocBook chapter lines.
Files with no revision number in the "From" column didn't exist when I
started the conversion.
File From -> To Merged to files...
---------------------------------------------------------------
anoncvs.sgml -> 1.1 cutting-edge/chapter.sgml
authors.sgml 1.93 -> 1.118 authors.ent
backups.sgml -> 1.4 backups/chapter.sgml
bibliography.sgml 1.33 -> 1.37 bibliography/chapter.sgml
contrib.sgml 1.274 -> 1.312 staff/chapter.sgml
ctm.sgml 1.22 -> 1.23 cutting-edge/chapter.sgml
cvsup.sgml 1.36 -> 1.40 cutting-edge/chapter.sgml
disks.sgml -> 1.3 disks/chapter.sgml
eresources.sgml 1.39 -> 1.50 eresources/chapter.sgml
firewalls.sgml 1.19 -> 1.20 security/chapter.sgml
handbook.sgml 1.83 -> 1.91 handbook.sgml
history.sgml 1.24 -> 1.25 introduction/chapter.sgml
install.sgml 1.65 -> 1.67 install/chapter.sgml
isdn.sgml 1.12 -> 1.15 advanced-networking/chapter.sgml
kerberos.sgml 1.12 -> 1.13 security/chapter.sgml
kernelconfig.sgml 1.31 -> 1.32 kernelconfig/chapter.sgml
kerneldebug.sgml 1.17 -> 1.19 kerneldebug/chapter.sgml
linuxemu.sgml 1.22 -> 1.24 linuxemu/chapter.sgml
memoryuse.sgml 1.11 -> 1.12 internals/chapter.sgml
mirrors.sgml 1.80 -> 1.92 mirrors/chapter.sgml
nutshell.sgml 1.14 -> 1.15 introduction/chapter.sgml
pgpkeys.sgml 1.25 -> 1.28 pgpkeys/chapter.sgml
policies.sgml 1.16 -> 1.18 policies/chapter.sgml
porting.sgml 1.93 -> 1.112 contrib/chapter.sgml
ports.sgml 1.29 -> 1.31 ports/chapter.sgml
printing.sgml 1.21 -> 1.22 printing/chapter.sgml
relnotes.sgml 1.24 -> 1.28 introduction/chapter.sgml [1]
submitters.sgml 1.161 -> 1.246 contrib/chapter.sgml
synching.sgml 1.12 -> 1.13 cutting-edge/chapter.sgml
userppp.sgml 1.28 -> 1.30 ppp-and-slip/chapter.sgml
[1] A chunk of relnotes.sgml is in an IGNORED marked section. Why?
Submitted by: A bunch (~ 50%) of merging done by Charles A. Wimmer
(cawimm@FreeBSD.ORG), rest by Nik.
- Remove the <bookbiblio> element, it's not needed
- Added a <copyright> element and sub-elements. Based on the CVS logs
the Handbook dates back to 1995.
- Changed the <xref> to a <link> in the abstract.
- Reformatted abstract to be neater (sorry translators, but it's only
one paragraph).
This lets the stylesheets generate a nice front page.
these changes;
1. Remove '<tt>' and '</tt>'.
2. Search/replace
\s-+<htmlurl url='mailto:\([^']+\)'\s-+name='[^']+'>
with
<email>\1</email>
(there's a leading space before <email>)
Added an ENTITY line to handbook.sgml to use the new entities.
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-shorttag: nil
sgml-always-quote-attributes: t
sgml-minimize-attributes: max
End:
-->
to handbook.sgml
Added
<!--
Local Variables:
mode: sgml
sgml-declaration: "../chapter.decl"
sgml-indent-data: t
sgml-omittag: nil
sgml-shorttag: nil
sgml-always-quote-attributes: t
sgml-minimize-attributes: max
sgml-parent-document: ("../handbook.sgml" "part" "chapter")
End:
-->
to the bottom of each chapter.sgml file so that Emacs can do the right
thing.
chapter.sgml in a directory named according to the value the id
attribute on that chapter.
Added chapters.ent, which lists the entities for each chapter.
Updated handbook.sgml to use these entities.
* Fixup use of <symbol> with more appropriate element
* Fixup wrong occurence of $Id$
* Fixup references to 'make' variables, and strim off the surrounding
${...}, it can be added back by the stylesheet at presentation time.
* More insertions or deletions of <para>...</para> as appropriate.
And with this commit, ladies and gentlemen, we're almost there as far as
the DocBook conversion goes. I still need to:
- Split the big handbook.sgml into its constituent files and directories.
- Sort out the files that will contain entities, and put in the correct
SGML to use them.
- Merge in the changes that have happened to doc/handbook over the past
7 or so months.
- Build the Makefile framework and supporting apps to do .txt, .ps, .rtf
and .pdf conversions.
But the mind numbingly tedious stuff is over. Of course, there's
always more to do (like the whole bibliography section should be marked
up as a bibliography) and I'm putting together the "This is how the
handbook should be marked up" document as well. Oh, and organising my
notes on how the Handbook could be re-arranged. But apart from that,
it's done :-)
id="bar">
...
changed to
<foo id="bar">
...
Before people complain that "Hang on, now you can't find out what the
allocated ID values are with a simple 'grep'" I'll say that's not a
problem. I plan to introduce a target in the Makefile (probably
something like 'handbook.id' which will automatically generate this
list doing a proper SGML parse.
to <email>.
Can't do this globally. Some of the links are odd (i.e,. the link
is not their e-mail address but is their name, eg
<ulink url="mailto:nik@freebsd.org">Nik Clayton</ulink>
which would turn to
<email>Nik Clayton</email>
which isn't very useful. Ignore these ones, and do the others.
(i.e., the ones that look like
<ulink url="mailto:nik@freebsd.org">nik@freebsd.org</ulink>
)
This Emacs regexp does the job.
Search for: <ulink\s-+url="mailto[^>]+>\([^<]+\)</ulink>
Replace with: <email>\1</email>
Step 2. A lot of the <email>...</email> sets will have '<' and '>' embedded
in them (as entities). These can be removed, since the stylesheet
will add them;
Search for: <email><\([^&]+\)></email>
Replace with: <email>\1</email>
Step 3. The trick now is to turn
<ulink url="mailto:nik@freebsd.org">Nik Clayton</ulink>
into
Nik Clayton <email>nik@freebsd.org</email>
This step could (possibly) have been done first, and then steps
1 and 2 could be done globally. I haven't done this because of
concerns about the ordering of names within languages. This
transformation is fairly simple in English, I've no idea what
it's like in Japanese.
Search for: <ulink\s-+url="mailto:\([^"]+\)">\([^<]+\)</ulink>
Replace with: \2 <email>\1</email>
Step 4. Remove leading and trailing spaces that may have slipped in
Search for: <email>\s-+
Replace with: <email>
Search for: \s-+</email>
Replace with: </email>
<literal remap=..> -> <literal>
<command remap=..> -> <command>
Or deleted <emphasis ..> altogether in some cases.
More redundant <para>..</para>'s removed.
things.
I'm now working through from the beginning of the handbook to end,
correcting as I go. I'll commit in chunks of 5,000 lines (or
thereabouts).
Most of the changes fall into the following categories.
* <emphasis remap=bf> --> <emphasis>
* Spurious <para>s around <*list>s deleted (but not reformatted)
"C-c -" in Emacs SGML mode (when the point is on an element starting
or end tags) will delete that element's starting or end tags.
* Marked smileys with <!-- smiley --> for possible future deletion
* Deleting <emphasis>, around
<term><emphasis>...</emphasis></term> -> <term>...</term>
* Fine tuning markup choices in some cases
- <filename>C:</filename> -> <devicename>C:</devicename>
* Extra <note>s here and there.
* Some <*list>s to <procedure> (and <listitem>s to <step>)
* ASCII emphasis converted to <emphasis>
i.e., do it like *this* -> do it like <emphasis>this</emphasis>
* <symbol> -> <replaceable>
There are very few whitespace changes, although a few have probably
cropped up. The vast majority of the whitespace changes will happen in
one megacommit, hopefully some time next week.
This does the first 5,000 lines or so.
this (in Emacs) by searching for
\s-+</para>
and replacing with
</para>
Do this for all occurences *except* where the element immediately before
the </para> is one of <itemizedlist>, <orderedlist>, <variablelist>,
<procedure>. The <para>...</para> wrapping these elements is mostly
redundant, and will be removed later.
<para> There is some leading space here.</para>
Get rid of it, doing an emacs search/replace for
<para> +\([^ ]\)
and replacing with
<para>\1
This can be done globally.
Some parts of the handbook had single spaces after stops, some had double
or triple. While the typographical convention for monospaced fonts may
be to use double spaces after them, that doesn't apply here. TeX will
ignore them, as will HTML. If we need them for a plain text version of the
Handbook then the stylesheet / conversion mechanism can insert them
as necessary.
Searching for
_\([;:!\.\?,]\) +_
in Emacs and replacing with
_\1 _
(ignore the '_', they're just to delineate the regexps) does the job
quite nicely. However, you can't do this everywhere, since some of the
double spaces might be in program listings or other literal sections
(e.g., the BSD Copyright), so you need to sit and bounce on the 'y' or
'n' key as appropriate for each occurance of a stop.
In some cases <informalexample> wasn't appropriate, and the markup was
changed to <programlisting> or other.
In some cases there were spurious <para> elements before and after the
<informalexample>. These were removed.
Reformatted text within <screen> elements because the whitespace *is*
significant.
Added <prompt> and <userinput> elements within <screen> where necessary.
If I spotted inappropriate use of markup within the immediate vicinity
of the <informalexample> elements then I fixed that (mostly the use of
<emphasis remap="...">).
This is part one of these changes -- there's a load of them, and this
goes up to line 11,284 or thereabouts, roughly one third of the way
through.
contract, start contract, work too many hours per day) I'm back working
on the DocBook conversion :-)
Create two new entities, prompt.root and prompt.user. Use these where the
user is shown an OS prompt, to indicate whether they should be a normal
user or do it as root.
Everything else that looks like a prompt (e.g., C:\> which occurs here
and there) is also marked up as <prompt>.
and near it. Most of the time this consisted of replacing the <emphasis>
with <replaceable> or <userinput>. Sometimes <screen> is the wrong element
to use, and will need replacing with something like <programlisting> or
<literallayout>.
command(number)) from the variety of different existing markup
(which included <command>, <emphasis>, and <ulink>s to man2html
CGI scripts) to a common format, which is
<citerefentry>
<refentrytitle>command</refentrytitle>
<manvolnum>number</manvolnum>
</citerefentry>
although in the interests of keeping the changes as simple as possible
for the translators, the above was flattened on to one line.
to link to it any more, and the version on my website is currently more
up to date. An AltaVista search to see if any one else had linked to it
didn't turn up anything, so I think this is pretty safe. I'll 'cvs remove'
the directory and its files shortly.
them with the correct markup.
The only quotes left now are either around items for which I'm not 100%
sure which element to use, or in literal blocks as part of commands the
user types in.
so I can check my progress, partly so that others can offer comments on
the result of the conversion.
See <URL:http://www.freebsd.org/~nik/handbook/book01.htm> for the first
results. Keep in mind that the conversion has not been fine tuned in any
way. That said, comments are welcome.
The file:/usr/src/sys/i386/boot/biosboot/README.386BSD is probably false,
but I don't have a checked out tree at hand, and I'd rather would let that
point to some http or ftp source (at least alternatively). Will check later
today.
Submitted by: "SSC Webmaster" <wwwadmin@ssc.com>
markup something that looks like a filename as <filename>...</filename>,
rather than <emphasis role="tt">...</emphasis> or whatever.
These changes can not be automated, the Japanese team will need to go
through the diffs to see which bits of markup have changed.
I'm halfway through (line 16704). It's been quite instructive, and I'm
learning lots about printing with FreeBSD :-)
Join me tomorrow, when I'll be doing the same thing to the other half of
the Handbook -- same Bat time, same Bat channel.
in English, to be consistent with the doc/ja/ hierarchy.
Rather than moving the existing FAQ and Handbook over to this directory,
they will be converted to the DocBook DTD, and the results of the conversion
will be committed to this new hierarchy. The existing doc/faq and
doc/handbook can then be removed.
The README file will be used to explain the current state of the DocBook
conversion process for the Handbook, so that people without easy access
to the CVS logs can keep track of what's going on, and lend a hand where
appropriate.
I plan to start converting the Handbook around 1830 BST.
clean up the build process a wee bit.
The basic change: instead of cheacking out bits and pieces of the
doc tree into the web build tree, check out the doc tree somewhere
else and put in a few symlinks from the web tree to the doc tree.
On catfish (soon to be hub) for example:
/usr/local/www/build/doc/...
/usr/local/www/build/www/...
where
/usr/local/www/build/www/data/handbook -> ../../doc/handbook
You have to manually put in the symlinks at the moment, but it
works better than the evil CVS hackery.
Also, install with -C to help avoid gratuitous cache-busting due to
gratuitous timestamp twiddling.
. Removed references that dangerously dedicated disks won't boot. Several
people on -questions have proved me wrong.
. Add credit to Greg Lemis for the above note.
Submitted by: Doug White <dwhite@gdi.uoregon.edu>
I have not personally done a "make world" since the 386BSD + patchkit days
so additional reviews from people who have would be good.
Submitted by: Nik Clayton <nik@blueberry.co.uk>
<code> seems to be not-liked by our HTML conversion right now, so I've
switched over to <tscreen><verb> sections which should accomplish the
same effect (and also look consistent with other examples).
that were revealed. Note: I didn't go through all of
the tutorials, so there is still some work to be
done here.
Made mailing addresses consistent with the handbook.
E.g:
freebsd-questions@FreeBSD.ORG
instead of:
questions@freebsd.org
Yes, this is supposed to be a new top level in the repository.
For the moment any changes to this area must be cleared by myself
or Jordan. Once the kinks are worked out, the policy will probably
be relaxed.
