This update has been bounced around, revised, rewritten, and audited
by darn near every member of the -doc team.
Submitted by: Tom Rhodes
PR: docs/35098
Content chainsawed from various FAQs.
This is a short chapter, and I'm not certain just how "advanced" it
is, but it doesn't fit in any other section of the FAQ.
Example domain names that are used inline should be kept as short as
possible. Domain names can not be broken up with hyphenation at
syllable boundaries for obvious reasons, and using 12 unbreakable
characters is bound to cause an hbox overflow when creating justified
output with TeX (the print backend).
* After reading this chapter you will know:
-> After reading this chapter, you will know:
* Before reading this chapter you should:
-> Before reading this chapter, you should:
some of the more conventional filesystems, but pseudo-filesystems are
more unusual (at least NFS stores data), and all filesystems are
"unique" by definition.
PR: 29503
Approved by: jim
* Two spaces after a period.
* Fix up the spacing in the listitems.
<itemizedlist>
<listitem>
<para></para>
</listitem>
<listitem>
<para></para>
</listitem>
</itemizedlist>
This is covered in the fdp-primer. Please read it.
* First and last word uppercase
* Prepositions, articles, and short conjunctions lowercase
* The word 'to' lowercase
* Preserved capitalization for program/command names
Reviewed by: murray
* OSs -> Operating Systems
* commmunications -> communications
* realise -> realize
* customising -> customizing
* customise -> customize
* realise -> realize
* behaviour -> behavior
British to American spelling for some of the above words only in the
Handbook as discussed on -doc.
Reviewed by: murray
Place some terms in <varname>
Change <emphasis> -> <varname> in some intstances
Place commands in <command> or man entitiy
Place applications in <application>
Place filenames in <filename>
Place hostnames in <hostid>
One instance of <quote> -> <errorname>
Spelling/Terminology Fixes:
ip -> IP address
IPs/ips -> IP addresses
cfg -> config
Unice -> Unix systems
Reviewed by: murray
internet -> Internet
can not -> cannot
CD-ROM -> CDROM
cdrom -> CDROM
UNIX -> Unix
To be standardized with the rest of the doc tree.
Approved by: murray
O'Reilly has standardized on 'CD-ROM' as have several other
publishers, however 'CDROM' outnumbers 'CD-ROM' 2 to 1 in our
documentation and it has always appeared this way on FreeBSD CDs from
Walnut Creek/BSDi/WRS. I don't have a preference either way as long
as it stays consistent.
<indexterm> tags outside of <para>s since this can add extra
whitespace characters to the output (for print stylesheets).
Pointed out by: Chris Costello
used to describe network topology. Change instances of '10 base T' to
'10 base 2' and adjust sentence structure when describing a bus-based
topology.
While I'm here, consistently use 'LAN' instead of 'lan' for local area
networks.
when the output format supports it.
The PNG driver for Ghostscript doesn't support anti-aliasing on
FreeBSD, so the PNG file was created on another platform and should
not be automatically generated from the eps file.
Submitted by: G. Adam Stanislav (created the EPS file with a text editor)
along with realtime examples as in the other parts.
Submitted by: Udo Erdelhoff <ue@nathan.ruhr.de>
Reviewed by: Neil Bliss <yoda@integratus.com> and myself
users (and more changes).
The original patch was
Submitted by: Eric Ogren <eogren@earthlink.net>
PR: 18926
but I received a big
Comment email by: Udo Erdelhoff <ue@nathan.ruhr.de>
where he addressed many nits in Eric's changes and/or suggested how to
rewrite parts in a correct/better way and gave me some further content.
Eric's patches removed some of Bill Swingle's old work. I decided
to keep these but to merge Eric's changes into the existing content.
The result is a very fine NIS tutorial, which is supposed to be extended
by NIS Netgroups content written by Udo Erdelhoff soon (at least he
promised that :-])
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.
<informalexample>
<screen>
...
</screen>
</informalexample>
need the <informalexample> element. So remove it. Simple search and
replace does the trick.
* 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.
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.
