* First and last word uppercase
* Prepositions, articles, and short conjunctions lowercase
* The word 'to' lowercase
* Preserved capitalization for program/command names
Reviewed by: murray
instead of creating a new subsection for each field. The output is
much more succinct and legible.
- Add a note about FreeBSD 5.0 and devfs that obviates the 'Making
Device Special Files' section.
- Remove reference to a book that we don't have any bibliographical
information for and that is a bit tangential to the subject at hand
(RS-232 Bible).
- Add missing words to make complete sentences.
- Simplify discussion of null-modem and "straight" serial cables.
- Consistently use a replaceable 'N' for the last character of
terminal devices instead of interspersing ? and X.
- Remove duplicate 'See the sio(4) manual page for more information.'
lines. One of these is quite sufficient per section.
- Remove more duplicate information that is unnecessary since this
chapter has been reorganized.
- Enclose a hint in the <tip> tag.
This chapter still needs work.
* 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
Many of the sections in this chapter contained duplicate information
(about FreeBSD 1.1.5.1, mind you).
This commit adds a more substantial introduction section with
information about terminology, cables and ports, kernel configuration
of serial devices, and using stty for serial configuration. The
remaining sections ("terminals", "dial-in service", "dial-out
service", and "setting up a serial console") can then refer to this
earlier section instead of duplicating how to setup /etc/ttys and HUP
init, etc. in each one.
Also contains a couple more markup fixes for <keycode>s.
PR: 19481
commits to make it slightly easier on the translation teams.
* Add a standard synopsis
* Remove references to FreeBSD 1.1.5.1 and FreeBSD 1.1. Document
the behavior of 4.x / 5.x and ignore the paleontology.
* Move <indexterm>s around so that printed output looks better.
* Reference other chapters in the Handbook instead of duplicating
information.
* Rephrase many sentences to be more concise.
* <filename> -> <command>
* Refer to the text as "this chapter" instead of "this document"
* Refer to manual pages consistently.
* Turns a couple of question and answer entries into more formal
paragraphs.
* Don't intersperse example commands inside paragraphs as often.
Instead, talk about something and then provide an example.
* Mark up contributors in <sectNinfo>.
* Remove synopsis-like information from one of the individual
sections, since this has been expanded at the front of the
chapter.
* Mark up keys in <keycode>
* Remove acknowledgments section. This is inappropriate for a book
chapter and the acknowledged person has been moved to the
<sectNinfo> as an additional contributor.
* Remove "information integrated from FAQ", that describes much of
our documentation.
* Remove troubleshooting entry about needing to be in a specific
group to run tip or cu, since this is no longer the case.
PR: 19481
it slightly from the submission just to clean up some of the English,
but Kazutaka YOKOTA should get all the kudos for this.
Submitted by: Kazutaka YOKOTA <yokota@zodiac.mech.utsunomiya-u.ac.jp>
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.
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.
* 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.
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.
