[ Once more, but this time, with feeling. Oh, "Hello Paul" :-) ]

os/doc

Welcome to the porter's handbook, based on section 4.4 from the Handbook.

To do this for your language, checkout a copy of the docs, and:

    cd doc/<lang>/books/
    mkdir porter-handbook
    cd porter-handbook
    cp ../handbook/ports/chapter.sgml book.sgml

Now edit book.sgml.  Add the following just after the comment at the top
of the file (and before the <chapter> element (everything between the
two '===')

===
<!DOCTYPE BOOK PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" [
<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
%man;

<!ENTITY % bookinfo PUBLIC "-//FreeBSD//ENTITIES DocBook BookInfo Entities//EN">
%bookinfo;

<!ENTITY % authors SYSTEM "../handbook/authors.ent"> %authors;
<!ENTITY % mailing-lists SYSTEM "../handbook/mailing-lists.ent">
%mailing-lists;
]>

<book>
  <bookinfo>
    <title>FreeBSD Porter's Handbook</title>

    <authorgroup>
      <author>
        <surname>The FreeBSD Documentation Project</surname>
        <affiliation>
          <address>
            <email>doc@@FreeBSD.org</email>
          </address>
        </affiliation>
      </author>
    </authorgroup>

    <pubdate>April 2000</pubdate>

    <copyright>
      <year>2000</year>
    </copyright>

    &bookinfo.legalnotice;
  </bookinfo>
==

Delete all the text from

    <chapter id="ports">

to

    <sect1 id="porting">

*and* the <title> for that section.  You should be left with

    <sect2>
      <title>Making a port yourself</title>

      ...

(obviously, translated to your language).

Next, do a search and replace of the various sectional elements, replacing
them with the element two-up in the hierarchy.

In other words,

    sect2    becomes    chapter
    sect3    becomes    sect1
    sect4    becomes    sect2

There's nothing below <sect4> in that document.

Go to the bottom of the file, you'll see

    </chapter>
  </sect1>
</chapter>

Delete the last two lines, and add a "</book>" to close off the content
properly.

Finally, in the comment section at the end delete the

    sgml-declaration: "../chapter.decl"

and

    sgml-parent-document: ("../book.sgml" "part" "chapter")

lines.

Finally, copy over the "Makefile" and "freebsd.dsl" file from the English
directory.  You will need to translate the two lines of text in freebsd.dsl

Once you've done that your copy of the file will be the same as the one
I committed as version 1.1 in the English directory.

This file won't build cleanly.  This is because there are still some
<xref>s and <link>s which point back to chapters in the Handbook.  We'll
clean those up shortly.  When that's done, and the doc is linked in to
the website we can remove the text from the main Handbook.

We're also sharing some entity files with the Handbook as well.  At the
moment those are SYSTEM entities pointing back to the Handbook copies.
I'm going to shift them in to doc/share/sgml/, with the other language
independent entities.

Oh, and the structure needs looking at.  Some of the things that are
chapters now could probably be sections inside another chapter.  This is
why I haven't changed the indentation yet, as it'll only change as we sort
out the structure.

This commit is contained in: