Date: Mon, 23 Apr 2012 16:14:34 GMT From: Rene Ladan <rene@FreeBSD.org> To: Perforce Change Reviews <perforce@FreeBSD.org> Subject: PERFORCE change 210076 for review Message-ID: <201204231614.q3NGEYe4048702@skunkworks.freebsd.org>
next in thread | raw e-mail | index | archive | help
http://p4web.freebsd.org/@@210076?ac=10 Change 210076 by rene@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@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@tuxproject.de</email></para> + </listitem> + + <listitem> <para>Jens Rehsack <email>rehsack@liwing.de</email></para> </listitem> @@ -9513,6 +9518,11 @@ </listitem> <listitem> + <para>Stephon Chen + <email>stephon@gmail.com</email></para> + </listitem> + + <listitem> <para>Steve Ames <email>steve@energistic.com</email></para> </listitem> @@ -9681,6 +9691,11 @@ </listitem> <listitem> + <para>Svyatoslav Lempert + <email>svyatoslav.lempert@gmail.com</email></para> + </listitem> + + <listitem> <para>Sybolt de Boer <email>bolt@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@FreeBSD.org To: freebsd-doc@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) <<<
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201204231614.q3NGEYe4048702>