PERFORCE change 210076 for review
Rene Ladan
rene at FreeBSD.org
Mon Apr 23 16:14:36 UTC 2012
http://p4web.freebsd.org/@@210076?ac=10
Change 210076 by rene at rene_acer on 2012/04/23 16:14:07
IFC
Affected files ...
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/committers-guide/article.sgml#54 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#137 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml#82 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/releng/Makefile#4 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/articles/releng/article.sgml#11 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml#3 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml#7 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/handbook/mirrors/chapter.sgml#45 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/books/porters-handbook/book.sgml#138 integrate
.. //depot/projects/docproj_nl/en_US.ISO8859-1/share/sgml/authors.ent#75 integrate
.. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/config/chapter.sgml#42 integrate
.. //depot/projects/docproj_nl/nl_NL.ISO8859-1/books/handbook/introduction/chapter.sgml#37 integrate
.. //depot/projects/docproj_nl/share/images/articles/releng/branches-head.pic#2 integrate
.. //depot/projects/docproj_nl/share/images/articles/releng/branches-releng8.pic#3 integrate
.. //depot/projects/docproj_nl/share/images/articles/releng/branches-releng9.pic#1 branch
.. //depot/projects/docproj_nl/share/pgpkeys/jlh.key#1 branch
.. //depot/projects/docproj_nl/share/pgpkeys/pgpkeys-developers.sgml#75 integrate
.. //depot/projects/docproj_nl/share/pgpkeys/pgpkeys.ent#72 integrate
.. //depot/projects/docproj_nl/share/sgml/freebsd.ent#28 integrate
.. //depot/projects/docproj_nl/www/en/advocacy/index.sgml#5 integrate
.. //depot/projects/docproj_nl/www/en/cgi/man.cgi#28 integrate
.. //depot/projects/docproj_nl/www/en/community/social.xsl#6 integrate
.. //depot/projects/docproj_nl/www/en/developers.sgml#75 integrate
.. //depot/projects/docproj_nl/www/en/platforms/index.sgml#2 integrate
.. //depot/projects/docproj_nl/www/en/projects/newbies.sgml#7 integrate
.. //depot/projects/docproj_nl/www/en/releases/8.3R/Makefile#3 integrate
.. //depot/projects/docproj_nl/www/en/releases/8.3R/announce.sgml#1 branch
.. //depot/projects/docproj_nl/www/en/releases/8.3R/installation.html#1 branch
.. //depot/projects/docproj_nl/www/en/releases/8.3R/relnotes.sgml#1 branch
.. //depot/projects/docproj_nl/www/en/releases/index.sgml#16 integrate
.. //depot/projects/docproj_nl/www/en/search/web.atoz#10 integrate
.. //depot/projects/docproj_nl/www/en/security/security.sgml#22 integrate
.. //depot/projects/docproj_nl/www/share/sgml/news.xml#140 integrate
.. //depot/projects/docproj_nl/www/share/sgml/press.xml#23 integrate
.. //depot/projects/docproj_nl/www/share/sgml/release.ent#46 integrate
Differences ...
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/committers-guide/article.sgml#54 (text+ko) ====
@@ -9,7 +9,7 @@
<corpauthor>The &os; Documentation Project</corpauthor>
- <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v 1.317 2012/04/03 12:07:47 gavin Exp $</pubdate>
+ <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/committers-guide/article.sgml,v 1.318 2012/04/18 19:23:55 bcr Exp $</pubdate>
<copyright>
<year>1999</year>
@@ -2143,6 +2143,267 @@
</sect3>
<sect3>
+ <title>Vendor imports with <acronym>SVN</acronym></title>
+
+ <important>
+ <para>Please read this entire section before starting a vendor
+ import.</para>
+ </important>
+
+ <note>
+ <para>Patches to vendor code fall into two categories:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Vendor patches: these are patches that have been
+ issued by the vendor, or that have been extracted from
+ the vendor's version control system, which address
+ issues which in your opinion can't wait until the next
+ vendor release.</para>
+ </listitem>
+ <listitem>
+ <para>&os; patches: these are patches that modify the
+ vendor code to address &os;-specific issues.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The nature of a patch dictates where it should be
+ committed:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Vendor patches should be committed to the vendor
+ branch, and merged from there to head. If the patch
+ addresses an issue in a new release that is currently
+ being imported, it <emphasis>must not</emphasis> be
+ committed along with the new release: the release must
+ be imported and tagged first, then the patch can be
+ applied and committed. There is no need to re-tag the
+ vendor sources after committing the patch.</para>
+ </listitem>
+ <listitem>
+ <para>&os; patches should be committed directly to
+ head.</para>
+ </listitem>
+ </itemizedlist>
+ </note>
+
+ <sect4>
+ <title>Preparing the tree</title>
+
+ <para>If importing for the first time after the switch to
+ Subversion, flattening and cleaning up the vendor tree is
+ necessary, as well as bootstrapping the merge history in
+ the main tree.</para>
+
+ <sect5>
+ <title>Flattening</title>
+
+ <para>During the conversion from <acronym>CVS</acronym> to
+ Subversion, vendor branches were imported with the same
+ layout as the main tree. This means that the
+ <literal>pf</literal> vendor sources ended up in
+ <filename>vendor/pf/dist/contrib/pf</filename>. The
+ vendor source is best directly in
+ <filename>vendor/pf/dist</filename>.</para>
+
+ <para>To flatten the <literal>pf</literal> tree:</para>
+
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist/contrib/pf</replaceable></userinput>
+&prompt.user; <userinput>svn mv $(svn list) ../..</userinput>
+&prompt.user; <userinput>cd ../..</userinput>
+&prompt.user; <userinput>svn rm contrib</userinput>
+&prompt.user; <userinput>svn propdel -R svn:mergeinfo .</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
+
+ <para>The <literal>propdel</literal> bit is necessary
+ because starting with 1.5, Subversion will automatically
+ add <literal>svn:mergeinfo</literal> to any directory
+ that is copied or moved. In this case, as nothing is
+ being merged from the deleted tree, they just get in the
+ way.</para>
+
+ <para>Tags may be flattened as well (3, 4, 3.5 etc.); the
+ procedure is exactly the same, only changing
+ <literal>dist</literal> to <literal>3.5</literal> or
+ similar, and putting the <command>svn commit</command>
+ off until the end of the process.</para>
+ </sect5>
+ <sect5>
+ <title>Cleaning up</title>
+
+ <para>The <literal>dist</literal> tree can be cleaned up
+ as necessary. Disabling keyword expansion is
+ recommended, as it makes no sense on unmodified vendor
+ code and in some cases it can even be harmful.
+ <application>OpenSSH</application>, for example, includes
+ two files that originated with &os; and still contain the
+ original version tags. To do this:</para>
+
+ <screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput>
+&prompt.root; <userinput>svn commit</userinput></screen>
+ </sect5>
+ <sect5>
+ <title>Bootstrapping merge history</title>
+
+ <para>If importing for the first time after the switch to
+ Subversion, bootstrapping
+ <literal>svn:mergeinfo</literal> on the target directory
+ in the main tree to the to the revision that corresponds
+ to the last related change to the vendor tree, prior to
+ importing new sources:</para>
+
+ <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
+&prompt.user; <userinput>svn merge --record-only svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist at 180876</replaceable> .</userinput>
+&prompt.user; <userinput>svn commit</userinput></screen>
+ </sect5>
+ </sect4>
+
+ <sect4>
+ <title>Importing new sources</title>
+
+ <para>With two commits—one for the import itself and
+ one for the tag—this step can optionally be repeated
+ for every upstream release between the last import and the
+ current import.</para>
+
+ <sect5>
+ <title>Preparing the vendor sources</title>
+
+ <para>Unlike in <acronym>CVS</acronym> where only the needed
+ parts were imported into the vendor tree to avoid bloating
+ the main tree, Subversion is able to store a full
+ distribution in the vendor tree. So, import everything,
+ but merge only what is required.</para>
+
+ <para>A <command>svn add</command> is required to add any
+ files that were added since the last vendor import, and
+ <command>svn rm</command> is required to remove any that
+ were removed since. Preparing sorted lists of the
+ contents of the vendor tree and of the sources that are
+ about to be imported is recommended, to facilitate the
+ process.</para>
+
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist</replaceable></userinput>
+&prompt.user; <userinput>svn list -R | grep -v '/$' | sort >../old</userinput>
+&prompt.user; <userinput>cd <replaceable>../pf-4.3</replaceable></userinput>
+&prompt.user; <userinput>find . -type f | cut -c 3- | sort >../new</userinput></screen>
+
+ <para>With these two files,
+ <command>comm -23 ../old ../new</command>
+ will list removed files (files only in
+ <filename>old</filename>), while
+ <command>comm -13 ../old ../new</command>
+ will list added files only in <filename>new</filename>.</para>
+ </sect5>
+ <sect5>
+ <title>Importing into the vendor tree</title>
+
+ <para>Now, the sources must be copied into
+ <filename><replaceable>dist</replaceable></filename> and
+ the <command>svn add</command> and
+ <command>svn rm</command> commands should be used as
+ needed:</para>
+
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/pf-4.3</replaceable></userinput>
+&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput>
+&prompt.user; <userinput>cd <replaceable>../dist</replaceable></userinput>
+&prompt.user; <userinput>comm -23 ../old ../new | xargs svn rm</userinput>
+&prompt.user; <userinput>comm -13 ../old ../new | xargs svn --parents add</userinput></screen>
+
+ <para>If any directories were removed, they will have to be
+ <command>svn rm</command>ed manually. Nothing will break
+ if they are not, but they will remain in the tree.</para>
+
+ <para>Check properties on any new files. All text files
+ should have <literal>svn:eol-style</literal> set to
+ <literal>native</literal>. All binary files should have
+ <literal>svn:mime-type</literal> set to
+ <literal>application/octet-stream</literal> unless there
+ is a more appropriate media type. Executable files should
+ have <literal>svn:executable</literal> set to
+ <literal>*</literal>. No other properties should exist
+ on any file in the tree.</para>
+
+ <para>Committing is now possible, however it is good
+ practice to make sure that everything is OK by using the
+ <command>svn stat</command> and
+ <command>svn diff</command> commands.</para>
+ </sect5>
+ <sect5>
+ <title>Tagging</title>
+
+ <para>Once committed, vendor releases should be tagged for
+ future reference. The best and quickest way to do this
+ is directly in the repository:</para>
+
+ <screen>&prompt.user; <userinput>svn cp svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/4.3</replaceable></userinput></screen>
+
+ <para>Once that is complete, <command>svn up</command> the
+ working copy of
+ <filename><replaceable>vendor/pf</replaceable></filename>
+ to get the new tag, although this is rarely
+ needed.</para>
+
+ <para>If creating the tag in the working copy of the tree,
+ <command>svn:mergeinfo</command> results must be removed:</para>
+
+ <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput>
+&prompt.user; <userinput>svn cp dist 4.3</userinput>
+&prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen>
+ </sect5>
+ </sect4>
+ <sect4>
+ <title>Merging to head</title>
+
+ <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput>
+&prompt.user; <userinput>svn up</userinput>
+&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> .</userinput></screen>
+
+ <para>The <literal>--accept=postpone</literal> tells
+ Subversion that it shouldn't complain because merge conflicts
+ will be taken care of manually.</para>
+
+ <para>It is necessary to resolve any merge conflicts.
+ This process is the same in <acronym>SVN</acronym> as in
+ <acronym>CVS</acronym>.</para>
+
+ <para>Make sure that any files that were added or removed in
+ the vendor tree have been properly added or removed in the
+ main tree. To check diffs against the vendor branch:</para>
+
+ <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/<replaceable>vendor/pf/dist</replaceable> --new=.</userinput></screen>
+
+ <para>The <literal>--no-diff-deleted</literal> tells
+ Subversion not to complain about files that are in the
+ vendor tree but not in the main tree, i.e. things that
+ would have previously been removed before the vendor
+ import, like for example the like the vendor's makefiles
+ and configure scripts.</para>
+
+ <para>Using <acronym>CVS</acronym>, once a file was off the
+ vendor branch, it was not able to be put back. With
+ Subversion, there is no concept of on or off the vendor
+ branch. If a file that previously had local
+ modifications, to make it not show up in diffs in the
+ vendor tree, all that has to be done is remove any left-over
+ cruft like &os; version tags, which is much easier.</para>
+
+ <para>If any changes are required for the world to build
+ with the new sources, make them now, and keep testing
+ until everything builds and runs perfectly.</para>
+ </sect4>
+ <sect4>
+ <title>Committing the vendor import</title>
+
+ <para>Committing is now possible! Everything must be
+ committed in one go. If done properly, the tree will move
+ from a consistent state with old code, to a consistent
+ state with new code.</para>
+ </sect4>
+ </sect3>
+
+ <sect3>
<title>Reverting a Commit</title>
<para>Reverting a commit to a previous version is fairly
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml#137 (text+ko) ====
@@ -1,4 +1,4 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml,v 1.1081 2012/04/17 16:27:03 jgh Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.additional.sgml,v 1.1084 2012/04/22 09:30:16 netchild Exp $ -->
<!--
NOTE TO COMMITTERS: Contributors lists are sorted in alphabetical
order by first name.
@@ -4496,6 +4496,11 @@
</listitem>
<listitem>
+ <para>Jens K. Loewe
+ <email>bsd at tuxproject.de</email></para>
+ </listitem>
+
+ <listitem>
<para>Jens Rehsack
<email>rehsack at liwing.de</email></para>
</listitem>
@@ -9513,6 +9518,11 @@
</listitem>
<listitem>
+ <para>Stephon Chen
+ <email>stephon at gmail.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Steve Ames
<email>steve at energistic.com</email></para>
</listitem>
@@ -9681,6 +9691,11 @@
</listitem>
<listitem>
+ <para>Svyatoslav Lempert
+ <email>svyatoslav.lempert at gmail.com</email></para>
+ </listitem>
+
+ <listitem>
<para>Sybolt de Boer
<email>bolt at xs4all.nl</email></para>
</listitem>
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml#82 (text+ko) ====
@@ -1,4 +1,4 @@
-<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml,v 1.357 2012/04/15 15:42:23 sperber Exp $ -->
+<!-- $FreeBSD: doc/en_US.ISO8859-1/articles/contributors/contrib.committers.sgml,v 1.359 2012/04/22 17:04:31 jlh Exp $ -->
<!--
NOTE TO NEW COMMITTERS: Core and committers lists are sorted in
alphabetical order by last name. Please keep in mind that fact while
@@ -739,6 +739,10 @@
</listitem>
<listitem>
+ <para>&a.jlh;</para>
+ </listitem>
+
+ <listitem>
<para>&a.leeym;</para>
</listitem>
@@ -1415,6 +1419,10 @@
</listitem>
<listitem>
+ <para>&a.dteske;</para>
+ </listitem>
+
+ <listitem>
<para>&a.itetcu;</para>
</listitem>
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/releng/Makefile#4 (text+ko) ====
@@ -1,5 +1,5 @@
#
-# $FreeBSD: doc/en_US.ISO8859-1/articles/releng/Makefile,v 1.20 2009/11/28 19:55:51 hrs Exp $
+# $FreeBSD: doc/en_US.ISO8859-1/articles/releng/Makefile,v 1.21 2012/04/18 14:05:43 hrs Exp $
#
# Article: FreeBSD Release Engineering
@@ -19,6 +19,7 @@
IMAGES_EN+= branches-releng6.pic
IMAGES_EN+= branches-releng7.pic
IMAGES_EN+= branches-releng8.pic
+IMAGES_EN+= branches-releng9.pic
CSS_SHEET_ADDITIONS= extra.css
==== //depot/projects/docproj_nl/en_US.ISO8859-1/articles/releng/article.sgml#11 (text+ko) ====
@@ -37,7 +37,7 @@
</author>
</authorgroup>
- <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/releng/article.sgml,v 1.89 2012/02/11 04:28:17 eadler Exp $</pubdate>
+ <pubdate>$FreeBSD: doc/en_US.ISO8859-1/articles/releng/article.sgml,v 1.90 2012/04/18 14:05:43 hrs Exp $</pubdate>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
@@ -359,6 +359,16 @@
<phrase>&os; 8.x STABLE Branch</phrase>
</textobject>
</mediaobject>
+
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="branches-releng9" align="center">
+ </imageobject>
+
+ <textobject>
+ <phrase>&os; 9.x STABLE Branch</phrase>
+ </textobject>
+ </mediaobject>
</sect3>
<sect3 id="versionbump">
==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml#3 (text+ko) ====
@@ -27,16 +27,16 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml,v 1.15 2009/01/22 12:08:03 pgj Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.sgml,v 1.16 2012/04/21 02:49:44 wblock Exp $
-->
<chapter id="see-also">
<title>See Also</title>
- <para>This document is deliberately not an exhaustive discussion of SGML,
- the DTDs listed, and the FreeBSD Documentation Project. For more
- information about these, you are encouraged to see the following web
- sites.</para>
+ <para>This document is deliberately not an exhaustive discussion of
+ SGML, the DTDs listed, and the FreeBSD Documentation Project. For
+ more information about these, you are encouraged to see the
+ following web sites.</para>
<sect1 id="see-also-fdp">
<title>The FreeBSD Documentation Project</title>
@@ -48,7 +48,8 @@
</listitem>
<listitem>
- <para><ulink url="&url.books.handbook;/index.html">The FreeBSD Handbook</ulink></para>
+ <para><ulink url="&url.books.handbook;/index.html">The FreeBSD
+ Handbook</ulink></para>
</listitem>
</itemizedlist>
</sect1>
@@ -58,13 +59,15 @@
<itemizedlist>
<listitem>
- <para><ulink url="http://www.oasis-open.org/cover/">The SGML/XML web
- page</ulink>, a comprehensive SGML resource</para>
+ <para><ulink url="http://www.oasis-open.org/cover/">The
+ SGML/XML web page</ulink>, a comprehensive SGML
+ resource</para>
</listitem>
-
+
<listitem>
<para><ulink
- url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">Gentle introduction to SGML</ulink></para>
+ url="http://www-sul.stanford.edu/tools/tutorials/html2.0/gentle.html">Gentle
+ introduction to SGML</ulink></para>
</listitem>
</itemizedlist>
</sect1>
@@ -79,8 +82,8 @@
</listitem>
<listitem>
- <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML 4.0
- specification</ulink></para>
+ <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML
+ 4.0 specification</ulink></para>
</listitem>
</itemizedlist>
</sect1>
@@ -90,21 +93,21 @@
<itemizedlist>
<listitem>
- <para><ulink url="http://www.oasis-open.org/docbook/">The DocBook
- Technical Committee</ulink>, maintainers of the DocBook DTD</para>
+ <para><ulink url="http://www.oasis-open.org/docbook/">The
+ DocBook Technical Committee</ulink>, maintainers of the
+ DocBook DTD</para>
</listitem>
<listitem>
- <para><ulink url="http://www.docbook.org/">DocBook: The Definitive
- Guide</ulink>, the online documentation for the DocBook
- DTD</para>
-
+ <para><ulink url="http://www.docbook.org/">DocBook: The
+ Definitive Guide</ulink>, the online documentation for the
+ DocBook DTD</para>
</listitem>
<listitem>
- <para><ulink url="http://docbook.sourceforge.net/">The DocBook Open
- Repository</ulink> contains DSSSL stylesheets and other resources
- for people using DocBook</para>
+ <para><ulink url="http://docbook.sourceforge.net/">The DocBook
+ Open Repository</ulink> contains DSSSL stylesheets and
+ other resources for people using DocBook</para>
</listitem>
</itemizedlist>
</sect1>
@@ -114,8 +117,8 @@
<itemizedlist>
<listitem>
- <para><ulink url="http://www.tldp.org/">The Linux Documentation
- Project web pages</ulink></para>
+ <para><ulink url="http://www.tldp.org/">The Linux
+ Documentation Project web pages</ulink></para>
</listitem>
</itemizedlist>
</sect1>
==== //depot/projects/docproj_nl/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml#7 (text+ko) ====
@@ -27,70 +27,73 @@
ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.
- $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.80 2010/08/08 13:54:36 jkois Exp $
+ $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.sgml,v 1.81 2012/04/21 04:52:03 wblock Exp $
-->
<chapter id="sgml-markup">
<title>SGML Markup</title>
- <para>This chapter describes the two markup languages you will encounter
- when you contribute to the FreeBSD documentation project. Each section
- describes the markup language, and details the markup that you are likely
- to want to use, or that is already in use.</para>
+ <para>This chapter describes the two markup languages you will
+ encounter when you contribute to the FreeBSD documentation
+ project. Each section describes the markup language, and details
+ the markup that you are likely to want to use, or that is already
+ in use.</para>
+
+ <para>These markup languages contain a large number of elements, and
+ it can be confusing sometimes to know which element to use for a
+ particular situation. This section goes through the elements you
+ are most likely to need, and gives examples of how you would use
+ them.</para>
- <para>These markup languages contain a large number of elements, and it can
- be confusing sometimes to know which element to use for a particular
- situation. This section goes through the elements you are most likely to
- need, and gives examples of how you would use them.</para>
-
- <para>This is <emphasis>not</emphasis> an exhaustive list of elements, since
- that would just reiterate the documentation for each language. The aim of
- this section is to list those elements more likely to be useful to you.
- If you have a question about how best to markup a particular piece of
- content, please post it to the &a.doc;.</para>
+ <para>This is <emphasis>not</emphasis> an exhaustive list of
+ elements, since that would just reiterate the documentation for
+ each language. The aim of this section is to list those elements
+ more likely to be useful to you. If you have a question about how
+ best to markup a particular piece of content, please post it to
+ the &a.doc;.</para>
<note>
<title>Inline vs. Block</title>
-
+
<para>In the remainder of this document, when describing elements,
- <emphasis>inline</emphasis> means that the element can occur within a
- block element, and does not cause a line break. A
- <emphasis>block</emphasis> element, by comparison, will cause a line
- break (and other processing) when it is encountered.</para>
+ <emphasis>inline</emphasis> means that the element can occur
+ within a block element, and does not cause a line break. A
+ <emphasis>block</emphasis> element, by comparison, will cause a
+ line break (and other processing) when it is encountered.</para>
</note>
-
+
<sect1 id="sgml-markup-html">
<title>HTML</title>
-
- <para>HTML, the HyperText Markup Language, is the markup language of
- choice on the World Wide Web. More information can be found at
- <ulink url="http://www.w3.org/"></ulink>.</para>
+
+ <para>HTML, the HyperText Markup Language, is the markup language
+ of choice on the World Wide Web. More information can be found
+ at <ulink url="http://www.w3.org/"></ulink>.</para>
+
+ <para>HTML is used to markup pages on the FreeBSD web site. It
+ should not (generally) be used to mark up other documentation,
+ since DocBook offers a far richer set of elements to choose
+ from. Consequently, you will normally only encounter HTML pages
+ if you are writing for the web site.</para>
- <para>HTML is used to markup pages on the FreeBSD web site. It should not
- (generally) be used to mark up other documentation,
- since DocBook offers a
- far richer set of elements to choose from. Consequently, you will
- normally only encounter HTML pages if you are writing for the web
- site.</para>
+ <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
+ and the latest, 4.0 (available in both
+ <emphasis>strict</emphasis> and <emphasis>loose</emphasis>
+ variants).</para>
- <para>HTML has gone through a number of versions, 1, 2, 3.0, 3.2, and the
- latest, 4.0 (available in both <emphasis>strict</emphasis> and
- <emphasis>loose</emphasis> variants).</para>
-
- <para>The HTML DTDs are available from the Ports Collection in the
- <filename role="package">textproc/html</filename> port. They are automatically
- installed as part of the <filename role="package">textproc/docproj</filename>
- port.</para>
+ <para>The HTML DTDs are available from the Ports Collection
+ in the <filename role="package">textproc/html</filename> port.
+ They are automatically installed as part of the <filename
+ role="package">textproc/docproj</filename> port.</para>
<sect2>
<title>Formal Public Identifier (FPI)</title>
- <para>There are a number of HTML FPIs, depending upon the version (also
- known as the level) of HTML that you want to declare your document to
- be compliant with.</para>
+ <para>There are a number of HTML FPIs, depending upon the
+ version (also known as the level) of HTML that you want to
+ declare your document to be compliant with.</para>
- <para>The majority of HTML documents on the FreeBSD web site comply with
- the loose version of HTML 4.0.</para>
+ <para>The majority of HTML documents on the FreeBSD web site
+ comply with the loose version of HTML 4.0.</para>
<programlisting>PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"</programlisting>
</sect2>
@@ -98,16 +101,17 @@
<sect2>
<title>Sectional Elements</title>
- <para>An HTML document is normally split into two sections. The first
- section, called the <emphasis>head</emphasis>, contains
- meta-information about the document, such as its title, the name of
- the author, the parent document, and so on. The second section, the
- <emphasis>body</emphasis>, contains the content that will be displayed
- to the user.</para>
+ <para>An HTML document is normally split into two sections. The
+ first section, called the <emphasis>head</emphasis>, contains
+ meta-information about the document, such as its title, the
+ name of the author, the parent document, and so on. The
+ second section, the <emphasis>body</emphasis>, contains the
+ content that will be displayed to the user.</para>
- <para>These sections are indicated with <sgmltag>head</sgmltag> and
- <sgmltag>body</sgmltag> elements respectively. These elements are
- contained within the top-level <sgmltag>html</sgmltag> element.</para>
+ <para>These sections are indicated with <sgmltag>head</sgmltag>
+ and <sgmltag>body</sgmltag> elements respectively. These
+ elements are contained within the top-level
+ <sgmltag>html</sgmltag> element.</para>
<example>
<title>Normal HTML Document Structure</title>
@@ -125,24 +129,25 @@
</html></programlisting>
</example>
</sect2>
-
+
<sect2>
<title>Block Elements</title>
<sect3>
<title>Headings</title>
- <para>HTML allows you to denote headings in your document, at up to
- six different levels.</para>
+ <para>HTML allows you to denote headings in your document, at
+ up to six different levels.</para>
- <para>The largest and most prominent heading is <sgmltag>h1</sgmltag>,
- then <sgmltag>h2</sgmltag>, continuing down to
- <sgmltag>h6</sgmltag>.</para>
+ <para>The largest and most prominent heading is
+ <sgmltag>h1</sgmltag>, then <sgmltag>h2</sgmltag>,
+ continuing down to <sgmltag>h6</sgmltag>.</para>
<para>The element's content is the text of the heading.</para>
<example>
- <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, etc.</title>
+ <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>,
+ etc.</title>
<para>Use:</para>
@@ -160,20 +165,22 @@
<h2>This is the heading for the second section</h2>
-<!-- Content for the second section goes here -->]]></programlisting>
+<!-- Content for the second section goes here -->]]></programlisting>
</example>
-
- <para>Generally, an HTML page should have one first level heading
- (<sgmltag>h1</sgmltag>). This can contain many second level
- headings (<sgmltag>h2</sgmltag>), which can in turn contain many
- third level headings. Each
- <sgmltag>h<replaceable>n</replaceable></sgmltag> element should have
- the same element, but one further up the hierarchy, preceding it.
- Leaving gaps in the numbering is to be avoided.</para>
+
+ <para>Generally, an HTML page should have one first level
+ heading (<sgmltag>h1</sgmltag>). This can contain many
+ second level headings (<sgmltag>h2</sgmltag>), which can in
+ turn contain many third level headings. Each
+ <sgmltag>h<replaceable>n</replaceable></sgmltag> element
+ should have the same element, but one further up the
+ hierarchy, preceding it. Leaving gaps in the numbering is
+ to be avoided.</para>
<example>
<title>Bad Ordering of
- <sgmltag>h<replaceable>n</replaceable></sgmltag> Elements</title>
+ <sgmltag>h<replaceable>n</replaceable></sgmltag>
+ Elements</title>
<para>Use:</para>
@@ -186,7 +193,7 @@
<!-- This is bad, <h2> has been left out -->]]></programlisting>
</example>
</sect3>
-
+
<sect3>
<title>Paragraphs</title>
@@ -206,8 +213,9 @@
<sect3>
<title>Block Quotations</title>
- <para>A block quotation is an extended quotation from another document
- that should not appear within the current paragraph.</para>
+ <para>A block quotation is an extended quotation from another
+ document that should not appear within the current
+ paragraph.</para>
<example>
<title><sgmltag>blockquote</sgmltag></title>
@@ -228,32 +236,35 @@
<sect3>
<title>Lists</title>
- <para>You can present the user with three types of lists, ordered,
- unordered, and definition.</para>
+ <para>You can present the user with three types of lists,
+ ordered, unordered, and definition.</para>
- <para>Typically, each entry in an ordered list will be numbered, while
- each entry in an unordered list will be preceded by a bullet point.
- Definition lists are composed of two sections for each entry. The
- first section is the term being defined, and the second section is
- the definition of the term.</para>
+ <para>Typically, each entry in an ordered list will be
+ numbered, while each entry in an unordered list will be
+ preceded by a bullet point. Definition lists are composed
+ of two sections for each entry. The first section is the
+ term being defined, and the second section is the definition
+ of the term.</para>
<para>Ordered lists are indicated by the <sgmltag>ol</sgmltag>
- element, unordered lists by the <sgmltag>ul</sgmltag> element, and
- definition lists by the <sgmltag>dl</sgmltag> element.</para>
+ element, unordered lists by the <sgmltag>ul</sgmltag>
+ element, and definition lists by the <sgmltag>dl</sgmltag>
+ element.</para>
- <para>Ordered and unordered lists contain listitems, indicated by the
- <sgmltag>li</sgmltag> element. A listitem can contain textual
- content, or it may be further wrapped in one or more
- <sgmltag>p</sgmltag> elements.</para>
+ <para>Ordered and unordered lists contain listitems, indicated
+ by the <sgmltag>li</sgmltag> element. A listitem can
+ contain textual content, or it may be further wrapped in one
+ or more <sgmltag>p</sgmltag> elements.</para>
<para>Definition lists contain definition terms
(<sgmltag>dt</sgmltag>) and definition descriptions
- (<sgmltag>dd</sgmltag>). A definition term can only contain inline
- elements. A definition description can contain other block
- elements.</para>
+ (<sgmltag>dd</sgmltag>). A definition term can only contain
+ inline elements. A definition description can contain other
+ block elements.</para>
<example>
- <title><sgmltag>ul</sgmltag> and <sgmltag>ol</sgmltag></title>
+ <title><sgmltag>ul</sgmltag> and
+ <sgmltag>ol</sgmltag></title>
<para>Use:</para>
@@ -310,10 +321,11 @@
<sect3>
<title>Pre-formatted Text</title>
- <para>You can indicate that text should be shown to the user exactly
- as it is in the file. Typically, this means that the text is shown
- in a fixed font, multiple spaces are not merged into one, and line
- breaks in the text are significant.</para>
+ <para>You can indicate that text should be shown to the user
+ exactly as it is in the file. Typically, this means that
+ the text is shown in a fixed font, multiple spaces are not
+ merged into one, and line breaks in the text are
+ significant.</para>
<para>In order to do this, wrap the content in the
<sgmltag>pre</sgmltag> element.</para>
@@ -321,8 +333,8 @@
<example>
<title><sgmltag>pre</sgmltag></title>
- <para>You could use <sgmltag>pre</sgmltag> to mark up an email
- message:</para>
+ <para>You could use <sgmltag>pre</sgmltag> to mark up an
+ email message:</para>
<programlisting><![ CDATA [<pre> From: nik at FreeBSD.org
To: freebsd-doc at FreeBSD.org
@@ -343,10 +355,10 @@
shown had to use <literal>&lt;</literal> instead of
<literal><</literal>. For consistency,
<literal>&gt;</literal> was used in place of
- <literal>></literal>, too. Watch out for the special characters
- that may appear in text copied from a plain-text source,
- e.g., an email message or program code.</para>
-
+ <literal>></literal>, too. Watch out for the special
+ characters that may appear in text copied from a
+ plain-text source, e.g., an email message or program
+ code.</para>
</example>
</sect3>
@@ -354,18 +366,19 @@
<title>Tables</title>
<note>
- <para>Most text-mode browsers (such as Lynx) do not render tables
- particularly effectively. If you are relying on the tabular
- display of your content, you should consider using alternative
- markup to prevent confusion.</para>
+ <para>Most text-mode browsers (such as Lynx) do not render
+ tables particularly effectively. If you are relying on
+ the tabular display of your content, you should consider
+ using alternative markup to prevent confusion.</para>
</note>
- <para>Mark up tabular information using the <sgmltag>table</sgmltag>
- element. A table consists of one or more table rows
- (<sgmltag>tr</sgmltag>), each containing one or more cells of table
- data (<sgmltag>td</sgmltag>). Each cell can contain other block
- elements, such as paragraphs or lists. It can also contain another
- table (this nesting can repeat indefinitely). If the cell only
+ <para>Mark up tabular information using the
+ <sgmltag>table</sgmltag> element. A table consists of one
+ or more table rows (<sgmltag>tr</sgmltag>), each containing
+ one or more cells of table data (<sgmltag>td</sgmltag>).
+ Each cell can contain other block elements, such as
+ paragraphs or lists. It can also contain another table
+ (this nesting can repeat indefinitely). If the cell only
contains one paragraph then you do not need to include the
<sgmltag>p</sgmltag> element.</para>
@@ -390,10 +403,11 @@
</tr>
</table>]]></programlisting></example>
- <para>A cell can span multiple rows and columns. To indicate this,
- add the <literal>rowspan</literal> and/or <literal>colspan</literal>
- attributes, with values indicating the number of rows or columns
- that should be spanned.</para>
+ <para>A cell can span multiple rows and columns. To indicate
+ this, add the <literal>rowspan</literal> and/or
+ <literal>colspan</literal> attributes, with values
+ indicating the number of rows or columns that should be
+ spanned.</para>
<example>
<title>Using <literal>rowspan</literal></title>
@@ -481,14 +495,17 @@
<para>You have two levels of emphasis available in HTML,
<sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag>.
<sgmltag>em</sgmltag> is for a normal level of emphasis and
- <sgmltag>strong</sgmltag> indicates stronger emphasis.</para>
+ <sgmltag>strong</sgmltag> indicates stronger
+ emphasis.</para>
- <para>Typically, <sgmltag>em</sgmltag> is rendered in italic and
- <sgmltag>strong</sgmltag> is rendered in bold. This is not always
- the case, however, and you should not rely on it.</para>
+ <para>Typically, <sgmltag>em</sgmltag> is rendered in italic
+ and <sgmltag>strong</sgmltag> is rendered in bold. This is
+ not always the case, however, and you should not rely on
+ it.</para>
<example>
- <title><sgmltag>em</sgmltag> and <sgmltag>strong</sgmltag></title>
+ <title><sgmltag>em</sgmltag> and
+ <sgmltag>strong</sgmltag></title>
<para>Use:</para>
@@ -500,9 +517,9 @@
<sect3>
<title>Bold and Italics</title>
- <para>Because HTML includes presentational markup, you can also
- indicate that particular content should be rendered in bold or
- italic. The elements are <sgmltag>b</sgmltag> and
+ <para>Because HTML includes presentational markup, you can
+ also indicate that particular content should be rendered in
+ bold or italic. The elements are <sgmltag>b</sgmltag> and
<sgmltag>i</sgmltag> respectively.</para>
<example>
@@ -516,8 +533,8 @@
<sect3>
<title>Indicating Fixed-Pitch Text</title>
- <para>If you have content that should be rendered in a fixed pitch
- (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
+ <para>If you have content that should be rendered in a fixed
+ pitch (typewriter) typeface, use <sgmltag>tt</sgmltag> (for
<quote>teletype</quote>).</para>
<example>
@@ -534,29 +551,35 @@
<sect3>
<title>Content Size</title>
- <para>You can indicate that content should be shown in a larger or
- smaller font. There are three ways of doing this.</para>
+ <para>You can indicate that content should be shown in a
+ larger or smaller font. There are three ways of doing
+ this.</para>
<orderedlist>
<listitem>
- <para>Use <sgmltag>big</sgmltag> and <sgmltag>small</sgmltag>
- around the content you wish to change size. These tags can be
- nested, so <literal><big><big>This is much
- bigger</big></big></literal> is possible.</para>
+ <para>Use <sgmltag>big</sgmltag> and
+ <sgmltag>small</sgmltag> around the content you wish to
+ change size. These tags can be nested, so
+ <literal><big><big>This is much
+ bigger</big></big></literal> is
+ possible.</para>
</listitem>
>>> TRUNCATED FOR MAIL (1000 lines) <<<
More information about the p4-projects
mailing list