head	1.66;
access;
symbols;
locks; strict;
comment	@# @;


1.66
date	99.05.05.20.32.51;	author nik;	state dead;
branches;
next	1.65;

1.65
date	98.11.03.23.49.34;	author nik;	state Exp;
branches;
next	1.64;

1.64
date	98.11.03.23.48.02;	author nik;	state Exp;
branches;
next	1.63;

1.63
date	98.11.03.23.46.32;	author nik;	state Exp;
branches;
next	1.62;

1.62
date	98.11.03.23.40.13;	author nik;	state Exp;
branches;
next	1.61;

1.61
date	98.11.03.23.35.40;	author nik;	state Exp;
branches;
next	1.60;

1.60
date	98.11.03.23.31.20;	author nik;	state Exp;
branches;
next	1.59;

1.59
date	98.11.03.23.28.11;	author nik;	state Exp;
branches;
next	1.58;

1.58
date	98.11.03.23.16.38;	author nik;	state Exp;
branches;
next	1.57;

1.57
date	98.11.03.23.07.57;	author nik;	state Exp;
branches;
next	1.56;

1.56
date	98.10.28.23.42.39;	author nik;	state Exp;
branches;
next	1.55;

1.55
date	98.10.26.23.54.18;	author nik;	state Exp;
branches;
next	1.54;

1.54
date	98.10.26.23.53.48;	author nik;	state Exp;
branches;
next	1.53;

1.53
date	98.10.26.23.53.22;	author nik;	state Exp;
branches;
next	1.52;

1.52
date	98.10.26.23.52.48;	author nik;	state Exp;
branches;
next	1.51;

1.51
date	98.10.26.23.52.05;	author nik;	state Exp;
branches;
next	1.50;

1.50
date	98.10.26.23.51.34;	author nik;	state Exp;
branches;
next	1.49;

1.49
date	98.10.26.23.51.03;	author nik;	state Exp;
branches;
next	1.48;

1.48
date	98.10.26.23.50.34;	author nik;	state Exp;
branches;
next	1.47;

1.47
date	98.10.26.23.49.59;	author nik;	state Exp;
branches;
next	1.46;

1.46
date	98.10.26.23.49.18;	author nik;	state Exp;
branches;
next	1.45;

1.45
date	98.10.22.23.07.02;	author nik;	state Exp;
branches;
next	1.44;

1.44
date	98.10.22.23.06.05;	author nik;	state Exp;
branches;
next	1.43;

1.43
date	98.10.22.23.03.53;	author nik;	state Exp;
branches;
next	1.42;

1.42
date	98.10.22.23.03.04;	author nik;	state Exp;
branches;
next	1.41;

1.41
date	98.10.21.22.05.23;	author nik;	state Exp;
branches;
next	1.40;

1.40
date	98.10.21.22.02.39;	author nik;	state Exp;
branches;
next	1.39;

1.39
date	98.10.21.22.00.19;	author nik;	state Exp;
branches;
next	1.38;

1.38
date	98.10.21.21.58.40;	author nik;	state Exp;
branches;
next	1.37;

1.37
date	98.10.21.21.53.36;	author nik;	state Exp;
branches;
next	1.36;

1.36
date	98.10.21.21.52.28;	author nik;	state Exp;
branches;
next	1.35;

1.35
date	98.10.21.21.51.11;	author nik;	state Exp;
branches;
next	1.34;

1.34
date	98.10.21.21.48.30;	author nik;	state Exp;
branches;
next	1.33;

1.33
date	98.10.16.23.58.33;	author nik;	state Exp;
branches;
next	1.32;

1.32
date	98.10.12.21.56.14;	author nik;	state Exp;
branches;
next	1.31;

1.31
date	98.10.01.06.11.44;	author nik;	state Exp;
branches;
next	1.30;

1.30
date	98.08.25.09.06.27;	author nik;	state Exp;
branches;
next	1.29;

1.29
date	98.08.25.09.01.24;	author nik;	state Exp;
branches;
next	1.28;

1.28
date	98.08.11.08.30.38;	author nik;	state Exp;
branches;
next	1.27;

1.27
date	98.08.11.08.29.39;	author nik;	state Exp;
branches;
next	1.26;

1.26
date	98.08.11.08.28.42;	author nik;	state Exp;
branches;
next	1.25;

1.25
date	98.08.03.08.53.53;	author nik;	state Exp;
branches;
next	1.24;

1.24
date	98.07.14.13.17.29;	author nik;	state Exp;
branches;
next	1.23;

1.23
date	98.06.30.08.43.42;	author nik;	state Exp;
branches;
next	1.22;

1.22
date	98.06.29.09.48.31;	author nik;	state Exp;
branches;
next	1.21;

1.21
date	98.06.29.09.46.43;	author nik;	state Exp;
branches;
next	1.20;

1.20
date	98.06.29.09.43.52;	author nik;	state Exp;
branches;
next	1.19;

1.19
date	98.06.29.09.38.56;	author nik;	state Exp;
branches;
next	1.18;

1.18
date	98.06.29.08.23.33;	author nik;	state Exp;
branches;
next	1.17;

1.17
date	98.06.26.11.37.35;	author nik;	state Exp;
branches;
next	1.16;

1.16
date	98.06.26.11.33.58;	author nik;	state Exp;
branches;
next	1.15;

1.15
date	98.06.19.08.48.36;	author nik;	state Exp;
branches;
next	1.14;

1.14
date	98.06.19.08.39.18;	author nik;	state Exp;
branches;
next	1.13;

1.13
date	98.06.18.08.42.02;	author nik;	state Exp;
branches;
next	1.12;

1.12
date	98.06.11.08.28.38;	author nik;	state Exp;
branches;
next	1.11;

1.11
date	98.06.11.08.24.06;	author nik;	state Exp;
branches;
next	1.10;

1.10
date	98.06.09.08.30.31;	author nik;	state Exp;
branches;
next	1.9;

1.9
date	98.06.09.08.28.03;	author nik;	state Exp;
branches;
next	1.8;

1.8
date	98.06.09.08.25.59;	author nik;	state Exp;
branches;
next	1.7;

1.7
date	98.04.03.21.21.47;	author nik;	state Exp;
branches;
next	1.6;

1.6
date	98.04.02.21.35.05;	author nik;	state Exp;
branches;
next	1.5;

1.5
date	98.04.02.19.22.01;	author nik;	state Exp;
branches;
next	1.4;

1.4
date	98.04.01.19.24.43;	author nik;	state Exp;
branches;
next	1.3;

1.3
date	98.04.01.19.12.41;	author nik;	state Exp;
branches;
next	1.2;

1.2
date	98.04.01.18.25.30;	author nik;	state Exp;
branches;
next	1.1;

1.1
date	98.04.01.10.24.11;	author nik;	state Exp;
branches;
next	;


desc
@@


1.66
log
@Nuke this, it's served its purpose.
@
text
@This will be the location of the DocBook version of the FreeBSD Handbook,
which will eventually obsolete the version currently in doc/handbook/.

Interested parties should examine

  <URL:http://www.nothing-going-on.demon.co.uk/FreeBSD/docbook-migration.html>

and get in touch with Nik Clayton (either to nik@@FreeBSD.ORG or via the
FreeBSD-doc mailing list) if they have specific questions.

All the scripts mentioned here can also be downloaded by doing to

  <URL:http://www.freebsd.org/~nik/script_name>

for example,

  <URL:http://www.freebsd.org/~nik/entity-cdata.pl>

  
   ------------------------------------------------------------------------
    The Handbook is midway through the conversion process. It will almost
		certainly not convert to other formats cleanly
   ------------------------------------------------------------------------


				   Actions

  This list explains what's been done so far, so the Japanese team can
  track my changes. All actions took place on freefall.

  1. Initial conversion to DocBook

     Checked out a copy of the doc repository to ~/cvs/. Then used 2 scripts
     to convert the handbook to its initial DocBook format. The 2 scripts are
     2docbook.sh and entity-cdata.pl, both of which can be found in ~nik/bin/.

     2docbook.sh calls entity-cdata.pl as necessary.

         % cd ~/cvs/doc/handbook
	 % 2docbook.sh

     This created handbook-db.sgml in ~/cvs/doc/handbook. This file contains
     syntactically valid (but quite ugly) SGML. This file was then moved to
     the doc/en/handbook directory and renamed to handbook.sgml. The
     conversion process left a few spurious changes in the old handbook files
     which I don't want to commit, so I removed them and updated the
     repository.

     The new file was then committed.

         % mv handbook-db.sgml ~/cvs/doc/en/handbook/handbook.sgml
	 % rm *.sgml
	 % cvs update
	 % cd ~/cvs/doc/en/handbook
	 % cvs add handbook.sgml
	 % cvs commit

  2. handbook.sgml was loaded into XEmacs 20.30 (straight from the ports
     collection) and sgml-mode was turned on. My .emacs file contains the
     following hook:

         (add-hook 'sgml-mode-hook
              (function
               (lambda()
                 (setq sgml-omittag nil)
                 (setq sgml-indent-data t))))

     This configures psgml to not omit any tags that the DTD lists as
     omittable, and to indent data in the same way that markup is indented.

     The following function was pasted into the *scratch* buffer, and then
     "M-x eval-current-buffer" was run.

         (defun sgml-indent-buffer
            "Indents the current buffer, one line at a time"
            (interactive "*")
            (save-excursion
              (goto-char (point-min))
              (while (= (forward-line 1) 0)
                (sgml-indent-or-tab))))

     In the handbook.sgml buffer, the point was placed on the first character
     of the first line, and "M-x sgml-indent-buffer" was run.

     The changes were then committed.

  3. Refilled the Handbook -- this rewraps the lines as necessary. This was
     done by placing the point on the first <book> tag, and running
     "M-x sgml-fill-element".

     This takes about 10 minutes to run.

     It also reformats some sections that should not be reformatted, including
     examples of text on the screen, PGP key blocks and so on. They will be
     fixed in a later commit.

  4. Removed spurious markup. The conversion process has left a lot of

         <para></para>

     entries in the handbook, and they need to be removed. There are a
     number of places this happens, and the rules are slightly different
     each time.

     For example,

     ====================================================================
       Original markup                      Changed markup
       --------------------------------------------------------------

       <listitem>                            <listitem>
         <para></para>                         <para>A real paragraph</para>

	 <para>A real paragraph</para>

       --------------------------------------------------------------

         <para>A real paragraph</para>         <para>A real paragraph</para>
	                                     </listitem>
         <para></para> 
	 
       </listitem>       

       --------------------------------------------------------------

         <para>A real paragraph</para>       <para>A real paragraph</para>

	 <para></para>                       <para>Another paragraph</para>

	 <para>Another paragraph</para>
     ====================================================================

     Notice the last example. It's not enough to simply put together a
     regexp that matches (all whitespace)<para></para>(allwhitespace)
     and removes it, since that would leave you with

       <para>A realparagraph</para>
       <para>Another paragraph</para>

     In the end I got bored of trying to write this using Emacs regexps,
     and knocked together a quick Perl script to do it. It's ~nik/bin/para.pl
     on freefall.

  5. Got halfway through looking for filenames, and marking them up as such.

     There are a lot ( :-( ) of filenames in the Handbook. The conversion
     process did a pretty good job of marking them as <filename>...</filename>
     but it wasn't perfect.

     I'm halfway through (line 16704) going through the Handbook, eyeballing
     each line and changing things like <emphasis remap="tt">...</emphasis>
     to <filename>...</filename> where appropriate.

     The remainder will follow tomorrow evening.

  6. Finished the first sweep marking up filenames.

     If it looked like a filename (but wasn't a command for the user to type
     in) it's been marked up with <filename>...</filename>.

     If it had already been marked up as <filename>...</filename> but wasn't
     a filename, the markup was changed to <emphasis remap="tt">...</emphasis>

     PSGML and Xemacs are very useful for this, using "C-c =" to change
     existing markup.
     
     Synchronising with changes 5 and 6 will involve examining the diffs
     and changing by hand I'm afraid. It could not be automated.

  7. Start replacing `` and '' with <quote> and </quote>. Don't change        
     things indiscriminately, but look at the context to see if the change is
     appropriate. There are still many `` and '' occurences which should be
     changed to some other element.

     This was done using a regexp search/replace, looking for the regexp

	 ``\([^']\)''

     and replacing with 

	 <quote>\1</quote>

     Not all the `` '' pairs were changed, since in some cases they delimit
     filenames, options and so on.

  8. As with change 7, but replace with <command> ... </command> as
     necessary.

  9. Remove the `` and '' from options. 

     ``<option>...</option>'' becomes <option>...</option>

 10. Converted appropriate occurences of 

         <emphasis remap=tt>...</emphasis>

     to
   
         <filename>...</filename>

 11. As above, but changing to <command>...</command>. Modified the Emacs
     regexp slightly to search for 

         <emphasis[ \n\t]+remap=tt>\([^<]+\)</emphasis>

     which matches elements spread over two lines.

 12. Looked for explanatory notes in the text (typically prefixed by "note",
     "Note:" or "<para><blockquote><para><emphasis role=bf>Note:</emphasis>"
     and marked them up as 'note' elements.

     This change involves markup changes *and* text changes. This is because
     text like

         <para>Note: The foo file is only used once, and can be deleted.</para>

     became

         <note>
           <para>The foo file is only used once, and can be deleted.</para>
         </note>
 
 13. Look for text marked up as an acronym and alter as necessary. The
     automatic conversion tended to mark any string of upper case letters
     as acronyms, which is not always right.

     The difference between an <acronym> and <abbrev> is subtle -- in a 
     nutshell, an acronym is pronounceble, an abbreviation isn't.

 14. Another sweep for "`" and "``" (and their closing equivalents), 
     replacing them with the right markup (since most of the time they're
     used to 'delimit' filenames or options from the surrounding text.

     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.

 15. Look for double quotes not used in attributes and alter to the 
     appropriate markup (or remove as necessary). A useful Emacs regexp
     when doing the search replace is

         \([^=]\)"\([^ \t\n]+[^"]+\)"\([^>]\)

     and replace with

         \1<quote>\2</quote>\3

     or whatever the replacement element is.

     Converted '"' into <quote>, <literal>, <command>, <application>,
     <filename>, <emphasis>, <option> or removed it as neccessary.

 16. A general cleanup to get it to validate. The original conversion 
     process left some <sect?>'s with just a title, which is invalid,
     they must contain a <para> or similar element.

     Also fixed a couple of typos in the tags. The document should now 
     validate, save for the undefined external entitites.

 17. Created a new FreeBSD Doc. Project DTD in the ../../sgml directory.
     Changed the declaration at the top of the handbook to use this new
     DTD.

 18. Yet more things that should be filenames marked up as such.

 19. Use the new <hostid> element to mark up hostnames, IP addresses and
     such. The markup choice is as follows.

        <hostid>...</hostid> is a simple hostname.
        <hostid role="ipaddr">...</hostid> is an IP address.
	<hostid role="domainname">...</hostid> is a domain name.
	<hostid role="fqdn">...</hostid> is a fully qualified domain name.
	<hostid role="netmask">...</hostid> is a netmask.
        <hostid role="mac">...</hostid> is a network card MAC address.

     These might migrate to being separate elements in the future. However,
     if they do then changing the markup can be done automatically.

 20. Convert <emphasis remap=it>...</emphasis> to plain <emphasis> in some
     cases. I'm pretty certain that all the <emphasis>...</emphasis>
     markup is correct now, which makes searching for markup that does
     need changing much easier. 

 21. Replace the last few occurences of curly quoted items (`` and '') 
     with the right markup.

 22. Almost the last lot. I missed a diff I'd done at home. There's a
     section in the handbook that talks about kernel options, where the
     quoted options are quoted with `` and ''. Fix them so that standard
     double quotes are used (so they can cut-n-pasted).
 
 23. Start working on <emphasis remap=bf>...</emphasis>

     Convert the first lot to <command>...</command>

 24. Fixed manual page references to use the right markup, which is

       <citerefentry>
         <refentrytitle>page_name</refentrytitle>
         <manvolnum>number</manvolnum>
       </citerefentry>

     Did this with a regexp search for

       \([a-z-_\.]+\)(\([1-9]\))

     and replacing with

       <citerefentry><refentrytitle>\1</refentrytitle><manvolnum>\2</manvolnum>

     Since most of the page references had <command>, <emphasis>, or
     <ulink> elements wrapped around them, you then have to sweep through the
     file looking for "><cite" and using C-c C-k to kill the markup 
     immediately before and after.

 25. <emphasis remap=..>...</emphasis> -> <literal>...</literal>

 26. <emphasis remap=..>...</emphasis> -> <makevar>...</makevar>

 27. <emphasis remap=..>...</emphasis> -> <maketarget>...</maketarget>
 
 28. Fix up some uses of <screen> and the use of <emphasis> elements within
     and near it. Most of the time this consisted of replacing the <emphasis>
     with <replaceable> or <userinput>.

 29. Fixed up more references to manpages that used <ulink> to use 
     <citerefentry>. These were missed at step 24 because they didn't 
     include a section number. No references to man.cgi now exist in  
     handbook.sgml.

 30. Create two entities, prompt.root and prompt.user. Use these anywhere
     the OS prompt is displayed, depending on whether the user should be
     a normal user or root.

     Also markup other prompts (e.g., the DOS prompt C:\> that occurs in
     some places) as <prompt>s.

 31. Reviewing the use of <informalexample> and <screen>.

     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.

 32. Continuing the work from the previous commit. This takes us up to
     the beginning of Chapter 16, "The Cutting Edge".

 33. Finished sweep. If it's white space sensitive (examples, program 
     listings, PGP signatures...) the white space is now correct. I may
     have missed one or two on the way, I'll catch them later.

 34. Removed repeated spaces from the end of stops,  . , ! ? : ;

     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 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 occurence of a stop.

 35. Some paragraphs have leading space(s). E.g.,

        <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.

 36. A lot of </para> tags have leading whitespace before them. Remove it. Do
     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.

 37. With the agreement of the Japanese team, a change in the way I'm doing
     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. 

 38. As above, to line 11490.

 39. . . . to line 15126 . . . 

 40. . . . to line 20370 . . .

 41. . . . to line 24997 . . .

 42. Brief interruption, small changes to keep it validating.

 43. . . . to line 30118 . . .

 44. . . . to line 35973 . . .

 45. . . . to end of file!

 46. <emphasis remap=..> -> <emphasis>
     <literal remap=..>  -> <literal>
     <command remap=..>  -> <command>

     Or deleted <emphasis ..> altogether in some cases.

     More redundant <para>..</para>'s removed.

 47. Removed white space after <title> and before </title>. Use two search and
     replaces

         \s-+</title>  ->  </title>
         <title>\s-+   ->  <title>

 48. Use the correct ISO entities for dashes. According to a TeX manual I have
     kicking around here,

      daughter-in-law, X-rated    = hyphen      =  -
      pages 13--67                = en-dash     = &ndash;
      yes---or no?                = em-dash     = &mdash;
      0, 1, and -1                = minus sign  = &minus;

 49. Step 1. Find <ulink url="mailto:...">...</ulink>  and change the <ulink>
     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>&lt;\([^&]+\)&gt;</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>

 50. <abbrev> -> <acronym> in some cases.

 51. Fixup erroneous or extraneous <para>...</para> elements.

 52. <foo
       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.

 53. Where kernel options ("options INET" for example) are listed, wrap them
     in <literal>...</literal>.

 54. <quote>  -> &rdquo;
     </quote> -> &ldquo;

 55. * \s-+</programlisting> replaced with </programlisting> globally.

     * Fixup use of <symbol> with more appropriate element

     * Fixup wrong occurence of 'dollar'Id'dollar'

     * Fixup references to 'make' variables, and strim off the surrounding
       &#36;{...}, it can be added back by the stylesheet at presentation 
       time.

     * More insertions or deletions of <para>...</para> as appropriate.

 56. Add values for the 'id' attribute for those <chapters> that don't
     have them.

 57. Split the Handbook into individual files, called chapter.sgml, stored
     in directories named after the value of the id attribute on the
     chapter.

     Added chapters.ent, which lists the entities used to refer to the
     chapters. Update handbook.sgml to refer to this file and use entity
     references to pull everything in.

 58. Added chapter.decl, which contains a declaration for a DocBook
     chapter.

     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 Emacs can do something
     useful with it. This uses the new chapter.decl file.

 59. Add similar local variables (but not sgml-declaration or
     sgml-parent-document to handbook.sgml.

 60. Added authors.ent. This is v1.93 of doc/handbook/authors.sgml, with
     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.

 61. Removed the prompt.* entities from handbook.sgml and added them to
     freebsd.dtd.

 62. Do step 60, but for version 1.8 of doc/handbook/lists.sgml. Call
     the transformed file mailing-lists.ent, and add an ENTITY line for
     it to handbook.sgml

 63. Add <!ENTITY rel.current CDATA "2.2.6"> to handbook.sgml, from
     r1.83 of doc/handbook/handbook.sgml.

 64. Fix line 125 of kerneldebug/chapter.sgml, & -> &amp;

@


1.65
log
@Fix line 125 of kerneldebug/chapter.sgml, & -> &amp;
@
text
@@


1.64
log
@Add <!ENTITY rel.current CDATA "2.2.6"> to handbook.sgml, from
r1.83 of doc/handbook/handbook.sgml
@
text
@d648 2
@


1.63
log
@Take version 1.8 of doc/handbook/lists.sgml, apply the same search/replace
as to authors.ent, and add an ENTITY line to handbook.sgml.
@
text
@d644 4
@


1.62
log
@Removed the prompt.* entities from handbook.sgml and added them to
freebsd.dtd.
@
text
@d640 4
@


1.61
log
@Added authors.ent. This is v1.93 of doc/handbook/authors.sgml, with
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.
@
text
@d638 2
@


1.60
log
@Added

<!--
     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
@
text
@d620 18
@


1.59
log
@Added chapter.decl, which contains a declaration for a DocBook chapter.
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.
@
text
@d618 2
@


1.58
log
@Split the handbook into individual files. Each chapter is in a file called
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.
@
text
@d597 21
@


1.57
log
@Added values to the 'id' attribute for <chapter>s which don't have them.
@
text
@d588 9
@


1.56
log
@  * \s-+</programlisting> replaced with </programlisting> globally.

  * Fixup use of <symbol> with more appropriate element

  * Fixup wrong occurence of $Id$

  * Fixup references to 'make' variables, and strim off the surrounding
    &#36;{...}, 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 :-)
@
text
@d585 3
@


1.55
log
@<quote>  -> &rdquo;
</quote> -> &ldquo;
@
text
@d574 11
@


1.54
log
@Where kernel options ("options INET" for example) are listed, wrap them
in <literal>...</literal>.
@
text
@d570 4
@


1.53
log
@    <foo
       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.
@
text
@d567 3
@


1.52
log
@Fixup erroneous or extraneous <para>...</para> elements.
@
text
@d552 15
@


1.51
log
@<abbrev> -> <acronym> in some cases.
@
text
@d550 2
@


1.50
log
@Step 1. Find <ulink url="mailto:...">...</ulink>  and change the <ulink>
        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>&lt;\([^&]+\)&gt;</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>
@
text
@d548 2
@


1.49
log
@Use the correct ISO entities for dashes. According to a TeX manual I have
kicking around here,

    daughter-in-law, X-rated    = hyphen      =  -
    pages 13--67                = en-dash     = &ndash;
    yes---or no?                = em-dash     = &mdash;
    0, 1, and -1                = minus sign  = &minus;
@
text
@d495 2
d498 50
@


1.48
log
@Removed white space after <title> and before </title>. Use two search and
replaces

    \s-+</title>  ->  </title>
    <title>\s-+   ->  <title>
@
text
@d487 9
@


1.47
log
@<emphasis remap=..> -> <emphasis>
<literal remap=..>  -> <literal>
<command remap=..>  -> <command>

Or deleted <emphasis ..> altogether in some cases.

More redundant <para>..</para>'s removed.
@
text
@d481 6
@


1.46
log
@As previous commits, to end of file.
@
text
@d473 8
@


1.45
log
@As previous commit, to line 35973.
@
text
@d471 2
@


1.44
log
@As earlier commits, to line 30118
@
text
@d468 3
@


1.43
log
@Small changes to keep it validating.
@
text
@d466 2
@


1.42
log
@As previous commit, to line 24997
@
text
@d464 2
@


1.41
log
@As previous commit, to line 20370.
@
text
@d463 1
@


1.40
log
@As previous commit, to line 15126
@
text
@d461 2
@


1.39
log
@As previous commit, now to up to line 11490.
@
text
@d453 3
a455 3
    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. 
d457 3
a459 1
38. As above, to line 11490.
@


1.38
log
@With the agreement of the Japanese team, a change in the way I'm doing
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.
@
text
@d456 3
@


1.37
log
@A lot of </para> tags have leading whitespace before them. Remove it. Do
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.
@
text
@d416 40
@


1.36
log
@Some paragraphs have leading space(s). E.g.,

   <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.
@
text
@d402 14
@


1.35
log
@Removed double whitespace from the end of stops -- . , ! ? : ;

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.
@
text
@d389 13
@


1.34
log
@Finished sweep. If it's white space sensitive (examples, program
listings, PGP signatures...) the white space is now correct. I may
have missed one or two on the way, I'll catch them later.
@
text
@d365 24
@


1.33
log
@Continuing on from the previous commit -- this takes it up to the beginning
of chapter 16. . .
@
text
@d361 4
@


1.32
log
@Reviewing the use of <informalexample> and <screen>.

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.
@
text
@d359 2
@


1.31
log
@After an extended absence (quit job, set up company, get girlfriend, get
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>.
@
text
@d338 21
@


1.30
log
@<ulink url="...man.cgi?...">...</ulink> -> <citerefentry>...</citerefentry>
@
text
@d331 7
@


1.29
log
@Fix up some uses of <screen> and the use of <emphasis> elements within
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>.
@
text
@d326 5
@


1.28
log
@<emphasis remap=..>...</emphasis> -> <maketarget>...</maketarget>
@
text
@d321 4
@


1.27
log
@<emphasis remap=..>...</emphasis> -> <makevar>...</makevar>
@
text
@d320 2
@


1.26
log
@<emphasis remap=..>...</emphasis> -> <literal>...</literal>
@
text
@d318 2
@


1.25
log
@Convert things that look like man page references (i.e.,
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.
@
text
@d316 2
@


1.24
log
@<emphasis remap=bf>...</emphasis> --> <command>...</command>
@
text
@d296 20
@


1.23
log
@Fix the use of `` and '' in the section that explains kernel options. Use
'"' to ease cut-n-paste.
@
text
@d291 4
@


1.22
log
@Replace the last few occurences of curly quoted items (`` and '')
with the right markup.
@
text
@d287 5
@


1.21
log
@<emphasis remapt=it> -> <emphasis> in some cases.
@
text
@d284 3
@


1.20
log
@Mark up domain names, hostnames, IP addresses, netmasks and MAC addresses
using the new <hostid> element (with appropriate roles).
@
text
@d279 4
@


1.19
log
@More things that should be filenames marked up as such.
@
text
@d266 14
@


1.18
log
@Use the new FreeBSD Doc. Project DTD.
@
text
@d264 1
@


1.17
log
@A cleanup to get it to validate. Fixed some invalid and missplet markup.
Lots of undefined entities still exist, but they will be fixed with a
later commit.
@
text
@d260 5
@


1.16
log
@Replaced double quotes with appropriate elements.
@
text
@d253 7
@


1.15
log
@Another sweep for "`" and "``" (and their closing equivalents), replacing
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.
@
text
@d238 15
@


1.14
log
@Examine text marked up as <acronym>, alter markup as appropriate.
@
text
@d181 1
a181 1
	 <query>\1</query>
d228 9
a236 1
     nutshell, an acronym is pronounceble, and abbreviation isn't.
@


1.13
log
@Swept through looking for explanatory notes and marking them up as 'note'
elements.
@
text
@d222 7
@


1.12
log
@<emphasis remap=tt>...</emphasis>  ->  <command>...</command> where
necessary.
@
text
@d208 15
@


1.11
log
@Converted appropriate occurences of <emphasis remap=tt>...</emphasis> to
<filename>...</filename>

As with most of these conversions, I won't have got all of them in this
first pass.
@
text
@d201 7
@


1.10
log
@Remove the quotes from constructs like ``<option>...</option>''
@
text
@d193 7
@


1.9
log
@Replace `` '' with <command> ... </command> where appropriate.
@
text
@d189 5
@


1.8
log
@Replace some (not all) occurences of `` and '' with <quote> and </quote>.
@
text
@d186 3
@


1.7
log
@Finished the first sweep for <filename>...</filename>.

My next commit opportunity will probably be this time next Monday. Stay
tuned. . .
@
text
@d169 17
@


1.6
log
@This is the first commit that starts changing the markup. All these changes
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.
@
text
@d11 9
d156 13
a168 1
       @


1.5
log
@Another automated change. Remove <para></para> from the generated
source, it's a legacy from the LinuxDoc formatting.
@
text
@d135 11
@


1.4
log
@Refilled the paragraphs. This is the last big change for a while, the
next batch are fairly small. And they'll have to wait until tomorrow,
as I'm off home.
@
text
@d88 49
@


1.3
log
@Re-indented the lines to be more aesthetically pleasing, using XEmacs,
PSGML and a little bit of Lisp. Full details in README.
@
text
@d77 11
@


1.2
log
@This is first step in the Handbook migration from the LinuxDoc DTD to
the DocBook DTD. Details on how this was carried out are in the README
file.
@
text
@d49 28
@


1.1
log
@As discussed in -doc, this jumpstarts the doc/en/ hierarchy for documentation
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.
@
text
@d4 1
a4 2
The conversion process will start at roughly GMT 1830, 1/4/1998. Interested
parties should examine
d9 40
a48 1
FreeBSD-doc mailing list).
@
