diff options
Diffstat (limited to 'en_US.ISO8859-1')
171 files changed, 20171 insertions, 16675 deletions
diff --git a/en_US.ISO8859-1/articles/bsdl-gpl/article.xml b/en_US.ISO8859-1/articles/bsdl-gpl/article.xml index f1043f3ed3..85db178021 100644 --- a/en_US.ISO8859-1/articles/bsdl-gpl/article.xml +++ b/en_US.ISO8859-1/articles/bsdl-gpl/article.xml @@ -1,24 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <title>Why you should use a BSD style license for your Open Source Project</title> - <articleinfo> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + + <info><title>Why you should use a BSD style license for your Open Source Project</title> <authorgroup> - <author> - <firstname>Bruce</firstname> -<!-- middle initial: R. --> - <surname>Montague</surname> - <affiliation> + <author><personname><firstname>Bruce</firstname><surname>Montague</surname></personname><affiliation> <address><email>brucem@alumni.cse.ucsc.edu</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.general; @@ -27,9 +21,9 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> -<sect1 id="intro"> +<sect1 xml:id="intro"> <title>Introduction</title> <para>This document makes a case for using a BSD style license for @@ -38,13 +32,13 @@ GPL Open Source License introduction and summary.</para> </sect1> -<sect1 id="history"> +<sect1 xml:id="history"> <title>Very Brief Open Source History</title> <para>Long before the term <quote>Open Source</quote> was used, software was developed by loose associations of programmers and freely exchanged. Starting in the early 1950's, organizations such as - <ulink url="http://www.share.org">SHARE</ulink> and <ulink url="http://www.decus.org">DECUS</ulink> developed much of the + <link xlink:href="http://www.share.org">SHARE</link> and <link xlink:href="http://www.decus.org">DECUS</link> developed much of the software that computer hardware companies bundled with their hardware offerings. At that time computer companies were in the hardware business; anything that reduced software cost and made @@ -74,7 +68,7 @@ the customer.</para> </sect1> -<sect1 id="unix-license"> +<sect1 xml:id="unix-license"> <title>Unix from a BSD Licensing Perspective</title> <para>AT&T, who owned the original Unix implementation, was a @@ -129,11 +123,11 @@ soon terminated its support for BSD.</para> </sect1> -<sect1 id="current-bsdl"> +<sect1 xml:id="current-bsdl"> <title>The Current State of FreeBSD and BSD Licenses</title> - <para>The so-called <ulink url="http://www.opensource.org/licenses/bsd-license.php"> new BSD - license</ulink> applied to FreeBSD within the last few years is + <para>The so-called <link xlink:href="http://www.opensource.org/licenses/bsd-license.php"> new BSD + license</link> applied to FreeBSD within the last few years is effectively a statement that you can do anything with the program or its source, but you do not have any warranty and none of the authors has any liability (basically, you cannot sue anybody). This @@ -148,7 +142,7 @@ </sect1> -<sect1 id="origins-gpl"> +<sect1 xml:id="origins-gpl"> <title>The origins of the GPL</title> <para>While the future of Unix had been so muddled in the late 1980s @@ -164,8 +158,8 @@ disagreement over access to the source code for this software). Stallman devised an alternative to the commercial software license and called it the GPL, or "GNU Public License". He also started a - non-profit foundation, the <ulink url="http://www.fsf.org">Free - Software Foundation</ulink> (FSF), which intended to develop an entire + non-profit foundation, the <link xlink:href="http://www.fsf.org">Free + Software Foundation</link> (FSF), which intended to develop an entire operating system, including all associated software, that would not be subject to proprietary licensing. This system was called GNU, for "GNU is Not Unix".</para> @@ -183,7 +177,7 @@ incorporating your program into proprietary programs.</quote>[1]</para> - <para>The <ulink url="http://www.opensource.org/licenses/gpl-license.php">GPL</ulink> + <para>The <link xlink:href="http://www.opensource.org/licenses/gpl-license.php">GPL</link> is a complex license so here are some rules of thumb when using the GPL:</para> @@ -226,7 +220,7 @@ </sect1> -<sect1 id="origins-lgpl"> +<sect1 xml:id="origins-lgpl"> <title>The origins of Linux and the LGPL</title> <para>While the commercial Unix wars raged, the Linux kernel was @@ -241,7 +235,7 @@ of the GPL. Pressure to put proprietary applications on Linux became overwhelming. Such applications often must link with system libraries. This resulted in a modified version of the GPL called - the <ulink url="http://www.opensource.org/licenses/lgpl-license.php">LGPL</ulink> + the <link xlink:href="http://www.opensource.org/licenses/lgpl-license.php">LGPL</link> ("Library", since renamed to "Lesser", GPL). The LGPL allows proprietary code to be linked to the GNU C library, glibc. You do not have to release the source to code which has been dynamically @@ -255,7 +249,7 @@ </sect1> -<sect1 id="orphaning"> +<sect1 xml:id="orphaning"> <title>Open Source licenses and the Orphaning Problem</title> <para>One of the serious problems associated with proprietary @@ -283,7 +277,7 @@ </sect1> -<sect1 id="license-cannot"> +<sect1 xml:id="license-cannot"> <title>What a license cannot do</title> <para>No license can guarantee future software @@ -315,7 +309,7 @@ </sect1> -<sect1 id="gpl-advantages"> +<sect1 xml:id="gpl-advantages"> <title>GPL Advantages and Disadvantages</title> <para>A common reason to use the GPL is when modifying or extending @@ -377,7 +371,7 @@ </sect1> -<sect1 id="bsd-advantages"> +<sect1 xml:id="bsd-advantages"> <title>BSD Advantages</title> <para>A BSD style license is a good choice for long duration @@ -446,7 +440,7 @@ </sect1> -<sect1 id="recommendations"> +<sect1 xml:id="recommendations"> <title>Specific Recommendations for using a BSD license</title> <itemizedlist> @@ -531,7 +525,7 @@ </sect1> -<sect1 id="conclusion"> +<sect1 xml:id="conclusion"> <title>Conclusion</title> <para>In contrast to the GPL, which is designed to prevent the @@ -549,7 +543,7 @@ </sect1> -<sect1 id="addenda"> +<sect1 xml:id="addenda"> <title>Addenda</title> <programlisting> diff --git a/en_US.ISO8859-1/articles/building-products/article.xml b/en_US.ISO8859-1/articles/building-products/article.xml index 86ae7b5600..6689e1a69b 100644 --- a/en_US.ISO8859-1/articles/building-products/article.xml +++ b/en_US.ISO8859-1/articles/building-products/article.xml @@ -1,22 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Building Products with FreeBSD</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Building Products with FreeBSD</title> + <authorgroup> - <author> - <firstname>Joseph</firstname> - <surname>Koshy</surname> - <affiliation> + <author><personname><firstname>Joseph</firstname><surname>Koshy</surname></personname><affiliation> <orgname>The FreeBSD Project</orgname> <address><email>jkoshy@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -44,9 +39,9 @@ few <quote>best practices</quote> for organizations collaborating with the FreeBSD project.</para> </abstract> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>FreeBSD today is well-known as a high-performance server @@ -58,8 +53,7 @@ commercial shrink-wrapped software (see <xref linkend="freebsd-intro"/>).</para> - <para>In this article we look at the <ulink - url="&url.base;/">FreeBSD project</ulink> as a software + <para>In this article we look at the <link xlink:href="&url.base;/">FreeBSD project</link> as a software engineering resource—as a collection of building blocks and processes which you can use to build products.</para> @@ -166,7 +160,7 @@ </sect2> </sect1> - <sect1 id="freebsd-intro"> + <sect1 xml:id="freebsd-intro"> <title>FreeBSD as a set of building blocks</title> <para>FreeBSD makes an excellent foundation on which to build @@ -254,9 +248,7 @@ <listitem> <simpara>As a development environment supporting - cross-development for embedded OSes like <ulink - url="http://www.rtems.com/">RTEMS</ulink> and <ulink - url="http://ecos.sourceware.org/">eCOS</ulink>.</simpara> + cross-development for embedded OSes like <link xlink:href="http://www.rtems.com/">RTEMS</link> and <link xlink:href="http://ecos.sourceware.org/">eCOS</link>.</simpara> <simpara>There are many full-fledged development environments in the &os.numports;-strong collection of applications ported and packaged with FreeBSD.</simpara> @@ -280,7 +272,7 @@ </itemizedlist> </sect2> - <sect2 id="freebsd-technologies"> + <sect2 xml:id="freebsd-technologies"> <title>Technologies</title> <para>There are a large number of technologies supported by the @@ -403,9 +395,8 @@ <para>FreeBSD does not have <quote>corporate</quote> committers. Individual committers are required to take responsibility for - the changes they introduce to the code. The <ulink - url="&url.articles.committers-guide;">FreeBSD Committer's - guide</ulink> <citation>ComGuide</citation> documents the + the changes they introduce to the code. The <link xlink:href="&url.articles.committers-guide;">FreeBSD Committer's + guide</link> <citation>ComGuide</citation> documents the rules and responsibilities for committers.</para> <para>FreeBSD's project model is examined in detail in @@ -441,7 +432,7 @@ </listitem> </itemizedlist> - <figure id="fig-freebsd-branches"> + <figure xml:id="fig-freebsd-branches"> <title>FreeBSD Release Branches</title> <mediaobject> <imageobject> @@ -459,13 +450,11 @@ engineering and security teams, <firstterm>Tier 2</firstterm> architectures are supported on a best effort basis, and experimental architectures comprise <firstterm>Tier - 3</firstterm>. The list of <ulink - url="&url.articles.committers-guide;/archs.html">supported - architectures</ulink> is part of the FreeBSD documentation + 3</firstterm>. The list of <link xlink:href="&url.articles.committers-guide;/archs.html">supported + architectures</link> is part of the FreeBSD documentation collection.</para> - <para>The release engineering team publishes a <ulink - url="&url.base;/releng/">road map</ulink> for future + <para>The release engineering team publishes a <link xlink:href="&url.base;/releng/">road map</link> for future releases of FreeBSD on the project's web site. The dates laid down in the road map are not deadlines; FreeBSD is released when its code and documentation are ready.</para> @@ -476,7 +465,7 @@ </sect2> </sect1> - <sect1 id="freebsd-collaboration"> + <sect1 xml:id="freebsd-collaboration"> <title>Collaborating with FreeBSD</title> <para>Open-source projects like FreeBSD offer finished code of a @@ -520,16 +509,15 @@ <listitem> <simpara>FreeBSD enjoys an open and transparent working culture. Nearly all discussion in the project happens by - email, on <ulink url="&a.mailman.listinfo;">public mailing - lists</ulink> that are also archived for posterity. The - project's policies are <ulink - url="&url.base;/internal/policies.html">documented</ulink> + email, on <link xlink:href="&a.mailman.listinfo;">public mailing + lists</link> that are also archived for posterity. The + project's policies are <link xlink:href="&url.base;/internal/policies.html">documented</link> and maintained under revision control. Participation in the project is open to all.</simpara> </listitem> </itemizedlist> - <sect2 id="freebsd-org"> + <sect2 xml:id="freebsd-org"> <title>Understanding FreeBSD culture</title> <para>To be able to work effectively with the FreeBSD project, @@ -559,12 +547,10 @@ <para>FreeBSD traces its roots back nearly twenty years to the work of the Computer Science Research Group at the University of California Berkeley.<footnote> - <simpara>FreeBSD's <ulink - url="http://cvsweb.freebsd.org/">source - repository</ulink> contains a history of the project - since its inception, and there are <ulink - url="http://www.mckusick.com/csrg/">CDROMs - available</ulink> that contain earlier code from the + <simpara>FreeBSD's <link xlink:href="http://cvsweb.freebsd.org/">source + repository</link> contains a history of the project + since its inception, and there are <link xlink:href="http://www.mckusick.com/csrg/">CDROMs + available</link> that contain earlier code from the CSRG.</simpara> </footnote> A number of the original CSRG developers remain associated with the project.</para> @@ -592,7 +578,7 @@ consensus and running code</quote> <citation>Carp1996</citation>.</para> - <figure id="fig-change-log"> + <figure xml:id="fig-change-log"> <title>A sample change log entry</title> <programlisting> bde 2005-10-29 16:34:50 UTC @@ -647,9 +633,8 @@ bde 2005-10-29 16:34:50 UTC <formalpara> <title>Track FreeBSD source code</title> <para>The project makes it easy to mirror its CVS - repository using <ulink - url="&url.articles.cvsup-advanced;"><!-- - --><application>CVSup</application></ulink>. Having + repository using <link xlink:href="&url.articles.cvsup-advanced;"><!-- + --><application>CVSup</application></link>. Having the complete history of the source is useful when debugging complex problems and offers valuable insight into the intentions of the original developers. Use a @@ -662,10 +647,9 @@ bde 2005-10-29 16:34:50 UTC change log in <xref linkend="fig-change-log"/>. The ancestry of each line of the source is clearly visible. Annotated listings showing the history of every file - that is part of FreeBSD are <ulink - url="http://cvsweb.freebsd.org/">available on the - web</ulink>.</para> - <figure id="fig-cvs-annotate"> + that is part of FreeBSD are <link xlink:href="http://cvsweb.freebsd.org/">available on the + web</link>.</para> + <figure xml:id="fig-cvs-annotate"> <title>An annotated source listing generated using <command>cvs annotate</command></title> <programlisting> <![CDATA[ @@ -709,8 +693,8 @@ bde 2005-10-29 16:34:50 UTC <formalpara> <title>Report bugs upstream</title> <para>If you notice bug in the FreeBSD code that you are - using, file a <ulink url="&url.base;/send-pr.html">bug - report</ulink>. This step helps ensure that you do + using, file a <link xlink:href="&url.base;/send-pr.html">bug + report</link>. This step helps ensure that you do not have to fix the bug the next time you take a code drop from upstream.</para> </formalpara> @@ -750,18 +734,15 @@ bde 2005-10-29 16:34:50 UTC agreement with a developer or firm with FreeBSD experience. The &a.jobs; is a useful communication channel to find talent. The FreeBSD project maintains a - <ulink - url="&url.base;/commercial/consult_bycat.html">gallery - of consultants and consulting firms</ulink> - undertaking FreeBSD work. The <ulink - url="http://www.bsdcertification.org/">BSD - Certification Group</ulink> offers certification for + <link xlink:href="&url.base;/commercial/consult_bycat.html">gallery + of consultants and consulting firms</link> + undertaking FreeBSD work. The <link xlink:href="http://www.bsdcertification.org/">BSD + Certification Group</link> offers certification for all the major BSD derived OSes.</simpara> <simpara>For less critical needs, you can ask for help on - the <ulink - url="http://lists.FreeBSD.org/mailman/listinfo">project - mailing lists</ulink>. A useful guide to follow when + the <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">project + mailing lists</link>. A useful guide to follow when asking for help is given in <citation>Ray2004</citation>. </simpara> @@ -791,15 +772,12 @@ bde 2005-10-29 16:34:50 UTC already looking at a related problem. Help can range from hardware donations to direct financial assistance. In some countries, donations to the FreeBSD project - enjoy tax benefits. The project has a dedicated <ulink - url="&url.base;/donations/">donations liaison</ulink> + enjoy tax benefits. The project has a dedicated <link xlink:href="&url.base;/donations/">donations liaison</link> to assist donors. The project also maintains a web page - where developers <ulink - url="&url.base;/donations/wantlist.html">list their - needs</ulink>. + where developers <link xlink:href="&url.base;/donations/wantlist.html">list their + needs</link>. </simpara> - <simpara>As a policy the FreeBSD project <ulink - url="&url.articles.contributors;">acknowledges</ulink> + <simpara>As a policy the FreeBSD project <link xlink:href="&url.articles.contributors;">acknowledges</link> all contributions received on its web site.</simpara> </listitem> </varlistentry> @@ -807,7 +785,7 @@ bde 2005-10-29 16:34:50 UTC </sect2> </sect1> - <sect1 id="conclusion"> + <sect1 xml:id="conclusion"> <title>Conclusion</title> <para>The FreeBSD project's goals are to create and give away the source code for a high-quality operating system. By working @@ -826,36 +804,25 @@ bde 2005-10-29 16:34:50 UTC <bibliography> <biblioentry> <abbrev>Carp1996</abbrev> - <citetitle><ulink url="http://www.ietf.org/rfc/rfc1958.txt">The - Architectural Principles of the Internet</ulink></citetitle> - <author> - <firstname>B.</firstname> - <surname>Carpenter</surname> - <affiliation> + <citetitle><link xlink:href="http://www.ietf.org/rfc/rfc1958.txt">The + Architectural Principles of the Internet</link></citetitle> + <author><personname><firstname>B.</firstname><surname>Carpenter</surname></personname><affiliation> <orgname>The Internet Architecture Board</orgname> - </affiliation> - </author> + </affiliation></author> <copyright> <year>1996</year> </copyright> </biblioentry> <biblioentry xreflabel="Com2004"> <abbrev>Com2004</abbrev> - <citetitle><ulink - url="http://csdl.computer.org/comp/mags/so/2004/01/s1028.pdf">How + <citetitle><link xlink:href="http://csdl.computer.org/comp/mags/so/2004/01/s1028.pdf">How is Open-Source Affecting Software - Development?</ulink></citetitle> + Development?</link></citetitle> <authorgroup> - <author> - <firstname>Diomidis</firstname> - <surname>Spinellis</surname> - </author> - <author> - <firstname>Clemens</firstname> - <surname>Szyperski</surname> - </author> + <author><personname><firstname>Diomidis</firstname><surname>Spinellis</surname></personname></author> + <author><personname><firstname>Clemens</firstname><surname>Szyperski</surname></personname></author> </authorgroup> - <title>IEEE Computer</title> + <citetitle>IEEE Computer</citetitle> <copyright> <year>Jan/Feb 2004</year> </copyright> @@ -865,11 +832,10 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>ComGuide</abbrev> - <citetitle><ulink - url="&url.articles.committers-guide;">Committer's - Guide</ulink></citetitle> + <citetitle><link xlink:href="&url.articles.committers-guide;">Committer's + Guide</link></citetitle> <authorgroup> - <corpauthor>The FreeBSD Project</corpauthor> + <author><orgname>The FreeBSD Project</orgname></author> </authorgroup> <copyright> <year>2005</year> @@ -877,34 +843,26 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>Cov2005</abbrev> - <citetitle><ulink - url="http://www.coverity.com/news/nf_news_06_27_05_story_9.html">Coverity - study on kernel security holes in Linux and FreeBSD</ulink></citetitle> + <citetitle><link xlink:href="http://www.coverity.com/news/nf_news_06_27_05_story_9.html">Coverity + study on kernel security holes in Linux and FreeBSD</link></citetitle> <authorgroup> - <corpauthor>Coverity Inc.</corpauthor> + <author><orgname>Coverity Inc.</orgname></author> </authorgroup> <copyright> <year>2005</year> </copyright> </biblioentry> <biblioentry> - <abbrev>GoldGab2005</abbrev> <citetitle><ulink - url="http://dreamsongs.com/IHE/IHE.html">Innovation Happens - Elsewhere: Open Source as Business Strategy</ulink></citetitle> + <abbrev>GoldGab2005</abbrev> <citetitle><link xlink:href="http://dreamsongs.com/IHE/IHE.html">Innovation Happens + Elsewhere: Open Source as Business Strategy</link></citetitle> <authorgroup> - <author> - <firstname>Ron</firstname> - <surname>Goldman</surname> - </author> - <author> - <firstname>Richard</firstname> - <surname>Gabriel</surname> - </author> + <author><personname><firstname>Ron</firstname><surname>Goldman</surname></personname></author> + <author><personname><firstname>Richard</firstname><surname>Gabriel</surname></personname></author> </authorgroup> <copyright> <year>2005</year> </copyright> - <isbn>ISBN 1558608893</isbn> + <biblioid class="isbn">ISBN 1558608893</biblioid> <publisher> <publishername>Morgan-Kaufmann</publishername> </publisher> @@ -912,12 +870,9 @@ bde 2005-10-29 16:34:50 UTC <biblioentry xreflabel="Hub1994"> <!-- XXX Get the date of this article right --> <abbrev>Hub1994</abbrev> - <citetitle><ulink url="&url.articles.contributing;">Contributing - to the FreeBSD Project</ulink></citetitle> - <author> - <firstname>Jordan</firstname> - <surname>Hubbard</surname> - </author> + <citetitle><link xlink:href="&url.articles.contributing;">Contributing + to the FreeBSD Project</link></citetitle> + <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname></author> <copyright> <year>1994—2005</year> </copyright> @@ -927,19 +882,12 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>McKu1999</abbrev> - <citetitle><ulink - url="http://www.usenix.org/publications/library/proceedings/usenix99/mckusick.html">Soft + <citetitle><link xlink:href="http://www.usenix.org/publications/library/proceedings/usenix99/mckusick.html">Soft Updates: A Technique for Eliminating Most Synchronous Writes - in the Fast Filesystem</ulink></citetitle> + in the Fast Filesystem</link></citetitle> <authorgroup> - <author> - <firstname>Kirk</firstname> - <surname>McKusick</surname> - </author> - <author> - <firstname>Gregory</firstname> - <surname>Ganger</surname> - </author> + <author><personname><firstname>Kirk</firstname><surname>McKusick</surname></personname></author> + <author><personname><firstname>Gregory</firstname><surname>Ganger</surname></personname></author> </authorgroup> <confgroup> <conftitle>USENIX Annual Technical Conference</conftitle> @@ -950,21 +898,15 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>McKu1999-1</abbrev> - <citetitle><ulink - url="http://www.oreilly.com/catalog/opensources/book/kirkmck.html" - >Twenty Years of Berkeley Unix: From AT&T-Owned to - Freely Redistributable</ulink></citetitle> + <citetitle><link xlink:href="http://www.oreilly.com/catalog/opensources/book/kirkmck.html">Twenty Years of Berkeley Unix: From AT&T-Owned to + Freely Redistributable</link></citetitle> <authorgroup> - <author> - <firstname>Marshall Kirk</firstname> - <surname>McKusick</surname> - </author> + <author><personname><firstname>Marshall Kirk</firstname><surname>McKusick</surname></personname></author> </authorgroup> - <title><ulink - url="http://www.oreilly.com/catalog/opensources/book/toc.html">Open + <citetitle><link xlink:href="http://www.oreilly.com/catalog/opensources/book/toc.html">Open Sources: Voices from the Open Source - Revolution</ulink></title> - <isbn>ISBN 1-56592-582-3</isbn> + Revolution</link></citetitle> + <biblioid class="isbn">ISBN 1-56592-582-3</biblioid> <publisher> <publishername>O'Reilly Inc.</publishername> </publisher> @@ -974,13 +916,10 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>Mon2005</abbrev> - <citetitle><ulink url="&url.articles.bsdl-gpl;/article.html">Why you should + <citetitle><link xlink:href="&url.articles.bsdl-gpl;/article.html">Why you should use a BSD style license for your Open Source - Project</ulink></citetitle> - <author> - <firstname>Bruce</firstname> - <surname>Montague</surname> - </author> + Project</link></citetitle> + <author><personname><firstname>Bruce</firstname><surname>Montague</surname></personname></author> <publisher> <publishername>The FreeBSD Project</publishername> </publisher> @@ -990,12 +929,9 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry xreflabel="Nik2005"> <abbrev>Nik2005</abbrev> - <citetitle><ulink url="&url.books.dev-model;/book.html">A - project model for the FreeBSD Project</ulink></citetitle> - <author> - <firstname>Niklas</firstname> - <surname>Saers</surname> - </author> + <citetitle><link xlink:href="&url.books.dev-model;/book.html">A + project model for the FreeBSD Project</link></citetitle> + <author><personname><firstname>Niklas</firstname><surname>Saers</surname></personname></author> <copyright> <year>2005</year> </copyright> @@ -1005,18 +941,11 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry xreflabel="Nor1993"> <abbrev>Nor1993</abbrev> - <citetitle><ulink - url="http://www.norvig.com/luv-slides.ps">Tutorial - on Good Lisp Programming Style</ulink></citetitle> + <citetitle><link xlink:href="http://www.norvig.com/luv-slides.ps">Tutorial + on Good Lisp Programming Style</link></citetitle> <authorgroup> - <author> - <firstname>Peter</firstname> - <surname>Norvig</surname> - </author> - <author> - <firstname>Kent</firstname> - <surname>Pitman</surname> - </author> + <author><personname><firstname>Peter</firstname><surname>Norvig</surname></personname></author> + <author><personname><firstname>Kent</firstname><surname>Pitman</surname></personname></author> </authorgroup> <copyright> <year>1993</year> @@ -1024,26 +953,19 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>Nor2001</abbrev> - <citetitle><ulink url="http://www.norvig.com/21-days.html">Teach - Yourself Programming in Ten Years</ulink></citetitle> - <author> - <firstname>Peter</firstname> - <surname>Norvig</surname> - </author> + <citetitle><link xlink:href="http://www.norvig.com/21-days.html">Teach + Yourself Programming in Ten Years</link></citetitle> + <author><personname><firstname>Peter</firstname><surname>Norvig</surname></personname></author> <copyright> <year>2001</year> </copyright> </biblioentry> <biblioentry> <abbrev>Ray2004</abbrev> - <citetitle><ulink - url="http://www.catb.org/~esr/faqs/smart-questions.html">How - to ask questions the smart way</ulink></citetitle> + <citetitle><link xlink:href="http://www.catb.org/~esr/faqs/smart-questions.html">How + to ask questions the smart way</link></citetitle> <authorgroup> - <author> - <firstname>Eric Steven</firstname> - <surname>Raymond</surname> - </author> + <author><personname><firstname>Eric Steven</firstname><surname>Raymond</surname></personname></author> </authorgroup> <copyright> <year>2004</year> @@ -1051,12 +973,9 @@ bde 2005-10-29 16:34:50 UTC </biblioentry> <biblioentry> <abbrev>RelEngDoc</abbrev> - <citetitle><ulink url="&url.articles.releng;">FreeBSD Release - Engineering</ulink></citetitle> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - </author> + <citetitle><link xlink:href="&url.articles.releng;">FreeBSD Release + Engineering</link></citetitle> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> <copyright> <year>2001</year> </copyright> diff --git a/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml b/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml index 0e2156becd..051cc41148 100644 --- a/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml +++ b/en_US.ISO8859-1/articles/casestudy-argentina.com/article.xml @@ -1,23 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <title>Argentina.com : A Case Study</title> - <articleinfo> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + + <info><title>Argentina.com : A Case Study</title> <authorgroup> - <author> - <firstname>Carlos</firstname> - <surname>Horowicz</surname> - <affiliation> + <author><personname><firstname>Carlos</firstname><surname>Horowicz</surname></personname><affiliation> <address><email>ch@argentina.com</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.xfree86; @@ -27,9 +22,9 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> -<sect1 id="overview"> +<sect1 xml:id="overview"> <title>Overview</title> <para>Argentina.Com is an Argentine ISP with a small infrastructure @@ -69,7 +64,7 @@ business in the corporate and paid email arena.</para> </sect1> -<sect1 id="challenge"> +<sect1 xml:id="challenge"> <title>The Challenge</title> <para>The main challenge for Argentina.Com is to achieve a dialup @@ -133,10 +128,10 @@ </sect1> -<sect1 id="freebsd"> +<sect1 xml:id="freebsd"> <title>The FreeBSD solution</title> - <sect2 id="freebsd-intro"> + <sect2 xml:id="freebsd-intro"> <title>Introduction</title> <para>At the beginning of 2003 we had a CriticalPath mail system @@ -152,15 +147,14 @@ FreeBSD 4.8 with Linux emulation.</para> </sect2> - <sect2 id="freebsd-choice"> + <sect2 xml:id="freebsd-choice"> <title>The choice of FreeBSD</title> <para>The FreeBSD operating system is well-known for its great stability, plus its pragmatism and common sense to put - applications on-line thanks to its excellent <ulink - url="http://www.FreeBSD.org/ports">Ports System</ulink>. We - consider its <ulink url="http://www.FreeBSD.org/releng">release - engineering process</ulink> to be easily understandable, while + applications on-line thanks to its excellent <link xlink:href="http://www.FreeBSD.org/ports">Ports System</link>. We + consider its <link xlink:href="http://www.FreeBSD.org/releng">release + engineering process</link> to be easily understandable, while the users' community at the official mailing lists keeps a polite and civilized style when it comes to asking for support or reading other people's problems and solutions.</para> @@ -186,7 +180,7 @@ </sect2> - <sect2 id="freebsd-engineer"> + <sect2 xml:id="freebsd-engineer"> <title>Basic re-engineering</title> <para>The first re-engineering step was to put in place two @@ -209,7 +203,7 @@ </sect2> - <sect2 id="freebsd-email"> + <sect2 xml:id="freebsd-email"> <title>Email migration</title> <para>The email migration required careful planning due to the @@ -285,7 +279,7 @@ </sect2> - <sect2 id="freebsd-web"> + <sect2 xml:id="freebsd-web"> <title>Web migration</title> <para>With the adoption of FreeBSD, there was almost no additional @@ -300,7 +294,7 @@ </sect1> -<sect1 id="results"> +<sect1 xml:id="results"> <title>Results</title> <para>We managed to deploy a FreeBSD based email architecture that @@ -320,5 +314,3 @@ </sect1> </article> - - diff --git a/en_US.ISO8859-1/articles/committers-guide/article.xml b/en_US.ISO8859-1/articles/committers-guide/article.xml index 5f93df96ba..9b2b472a7f 100644 --- a/en_US.ISO8859-1/articles/committers-guide/article.xml +++ b/en_US.ISO8859-1/articles/committers-guide/article.xml @@ -1,14 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY ga "Google Analytics"> ]> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Committer's Guide</title> + -<article lang='en'> - <articleinfo> - <title>Committer's Guide</title> - - <corpauthor>The &os; Documentation Project</corpauthor> + <author><orgname>The &os; Documentation Project</orgname></author> <copyright> <year>1999</year> @@ -29,7 +28,7 @@ <holder>The &os; Documentation Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.coverity; &tm-attrib.ibm; @@ -52,16 +51,15 @@ more repositories. However, a few developers do not, and some of the information here applies to them as well. (For instance, some people only have rights to work with the - Problem Report database). Please see <xref - linkend="non-committers"/> for more information.</para> + Problem Report database). Please see <xref linkend="non-committers"/> for more information.</para> <para>This document may also be of interest to members of the &os; community who want to learn more about how the project works.</para> </abstract> - </articleinfo> + </info> - <sect1 id="admin"> + <sect1 xml:id="admin"> <title>Administrative Details</title> <informaltable frame="none" orient="port" pgwide="1"> @@ -76,35 +74,28 @@ <row> <entry><emphasis>Main Shell Host</emphasis></entry> - <entry><hostid - role="fqdn">freefall.FreeBSD.org</hostid></entry> + <entry><systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem></entry> </row> <row> <entry><emphasis><literal>src/</literal> Subversion Root</emphasis></entry> - <entry><literal>svn+ssh://</literal><hostid - role="fqdn">svn.FreeBSD.org</hostid><filename>/base</filename> - (see also <xref - linkend="svn-getting-started-base-layout"/>).</entry> + <entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/base</filename> + (see also <xref linkend="svn-getting-started-base-layout"/>).</entry> </row> <row> <entry><emphasis><literal>doc/</literal> Subversion Root</emphasis></entry> - <entry><literal>svn+ssh://</literal><hostid - role="fqdn">svn.FreeBSD.org</hostid><filename>/doc</filename> - (see also <xref - linkend="svn-getting-started-doc-layout"/>).</entry> + <entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/doc</filename> + (see also <xref linkend="svn-getting-started-doc-layout"/>).</entry> </row> <row> <entry><emphasis><literal>ports/</literal> Subversion Root</emphasis></entry> - <entry><literal>svn+ssh://</literal><hostid - role="fqdn">svn.FreeBSD.org</hostid><filename>/ports</filename> - (see also <xref - linkend="svn-getting-started-ports-layout"/>).</entry> + <entry><literal>svn+ssh://</literal><systemitem class="fqdomainname">svn.FreeBSD.org</systemitem><filename>/ports</filename> + (see also <xref linkend="svn-getting-started-ports-layout"/>).</entry> </row> <row> @@ -115,10 +106,10 @@ project repository has its own -developers and -committers mailing lists. Archives for these lists may be found in files - <filename>/home/mail/<replaceable>repository-name</replaceable>-developers-archive</filename> + <filename>/home/mail/repository-name-developers-archive</filename> and - <filename>/home/mail/<replaceable>repository-name</replaceable>-committers-archive</filename> - on the <hostid role="domainname">FreeBSD.org</hostid> + <filename>/home/mail/repository-name-committers-archive</filename> + on the <systemitem class="fqdomainname">FreeBSD.org</systemitem> cluster.)</entry> </row> @@ -127,7 +118,7 @@ <entry><emphasis>Core Team monthly reports</emphasis></entry> <entry><filename>/home/core/public/monthly-reports</filename> - on the <hostid role="domainname">FreeBSD.org</hostid> + on the <systemitem class="fqdomainname">FreeBSD.org</systemitem> cluster.</entry> </row> @@ -135,7 +126,7 @@ <entry><emphasis>Ports Management Team monthly reports</emphasis></entry> <entry><filename>/home/portmgr/public/monthly-reports</filename> - on the <hostid role="domainname">FreeBSD.org</hostid> + on the <systemitem class="fqdomainname">FreeBSD.org</systemitem> cluster.</entry> </row> @@ -159,25 +150,23 @@ <itemizedlist> <listitem> - <para><ulink url="&url.base;/internal/">&os; - Project Internal Pages</ulink></para> + <para><link xlink:href="&url.base;/internal/">&os; + Project Internal Pages</link></para> </listitem> <listitem> - <para><ulink - url="&url.base;/internal/machines.html">&os; Project - Hosts</ulink></para> + <para><link xlink:href="&url.base;/internal/machines.html">&os; Project + Hosts</link></para> </listitem> <listitem> - <para><ulink - url="&url.base;/administration.html">&os; Project - Administrative Groups</ulink></para> + <para><link xlink:href="&url.base;/administration.html">&os; Project + Administrative Groups</link></para> </listitem> </itemizedlist> </sect1> - <sect1 id="committer.types"> + <sect1 xml:id="committer.types"> <title>Commit Bit Types</title> <para>The &os; repository has a number of components which, @@ -274,7 +263,7 @@ </sect2> </sect1> - <sect1 id="subversion-primer"> + <sect1 xml:id="subversion-primer"> <title>Subversion Primer</title> <para>It is assumed that you are already familiar with the basic @@ -284,13 +273,12 @@ May 2012 and the <literal>ports</literal> tree as of July 2012.</para> - <para><ulink url="http://wiki.freebsd.org/SubversionMissing">There + <para><link xlink:href="http://wiki.freebsd.org/SubversionMissing">There is a list of things missing in Subversion when compared to - CVS</ulink>. The notes at <ulink - url="http://people.freebsd.org/~peter/svn_notes.txt"></ulink> + CVS</link>. The notes at <uri xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</uri> might also be useful.</para> - <sect2 id="svn-intro"> + <sect2 xml:id="svn-intro"> <title>Introduction</title> <para>The &os; source repository switched from @@ -310,8 +298,8 @@ The most notable change is the location of the &os; website <literal>www</literal> tree, which has been moved from - <literal>www/<replaceable>lang</replaceable>/</literal> to - <literal>head/<replaceable>lang</replaceable>/htdocs/</literal>.</para> + <literal>www/lang/</literal> to + <literal>head/lang/htdocs/</literal>.</para> </note> <para>The &os; <literal>ports</literal> repository switched @@ -386,13 +374,13 @@ &prompt.root; <userinput>make clean install</userinput></screen> </sect2> - <sect2 id="svn-getting-started"> + <sect2 xml:id="svn-getting-started"> <title>Getting Started</title> <para>There are a few ways to obtain a working copy of the tree from Subversion. This section will explain them.</para> - <sect3 id="svn-getting-started-direct-checkout"> + <sect3 xml:id="svn-getting-started-direct-checkout"> <title>Direct Checkout</title> <para>The first is to check out directly from the main @@ -421,8 +409,7 @@ </note> <para>The above command will check out a - <literal>CURRENT</literal> source tree as <filename - class="directory"><replaceable>/usr/src/</replaceable></filename>, + <literal>CURRENT</literal> source tree as <filename>/usr/src/</filename>, which can be any target directory on the local filesystem. Omitting the final argument of that command causes the working copy, in this case, to be named <quote>head</quote>, @@ -459,7 +446,7 @@ </note> </sect3> - <sect3 id="svn-getting-started-checkout-from-a-mirror"> + <sect3 xml:id="svn-getting-started-checkout-from-a-mirror"> <title>Checkout from a Mirror</title> <para>Check out a working copy from a mirror by @@ -486,7 +473,7 @@ information on how to set one up.</para> </sect3> - <sect3 id="svn-getting-started-base-layout"> + <sect3 xml:id="svn-getting-started-base-layout"> <title><literal>RELENG_*</literal> Branches and General Layout</title> @@ -512,19 +499,19 @@ <listitem> <para><emphasis>/stable/<replaceable>n</replaceable></emphasis> which corresponds to - <literal>RELENG_<replaceable>n</replaceable></literal>.</para> + <literal>RELENG_n</literal>.</para> </listitem> <listitem> <para><emphasis>/releng/<replaceable>n.n</replaceable></emphasis> which corresponds to - <literal>RELENG_<replaceable>n_n</replaceable></literal>.</para> + <literal>RELENG_n_n</literal>.</para> </listitem> <listitem> <para><emphasis>/release/<replaceable>n.n.n</replaceable></emphasis> which corresponds to - <literal>RELENG_<replaceable>n_n_n</replaceable>_RELEASE</literal>.</para> + <literal>RELENG_n_n_n_RELEASE</literal>.</para> </listitem> <listitem> @@ -546,7 +533,7 @@ </itemizedlist> </sect3> - <sect3 id="svn-getting-started-doc-layout"> + <sect3 xml:id="svn-getting-started-doc-layout"> <title>&os; Documentation Project Branches and Layout</title> @@ -587,7 +574,7 @@ </itemizedlist> </sect3> - <sect3 id="svn-getting-started-ports-layout"> + <sect3 xml:id="svn-getting-started-ports-layout"> <title>&os; Ports Tree Branches and Layout</title> <para>In <literal>svn+ssh://svn.freebsd.org/ports</literal>, @@ -603,7 +590,7 @@ <listitem> <para><emphasis>/branches/RELENG_<replaceable>n_n_n</replaceable></emphasis> which corresponds to - <literal>RELENG_<replaceable>n_n_n</replaceable></literal> + <literal>RELENG_n_n_n</literal> is used to merge back security updates in preparation for a release.</para> </listitem> @@ -611,7 +598,7 @@ <listitem> <para><emphasis>/tags/RELEASE_<replaceable>n_n_n</replaceable></emphasis> which corresponds to - <literal>RELEASE_<replaceable>n_n_n</replaceable></literal> + <literal>RELEASE_n_n_n</literal> represents a release tag of the ports tree.</para> </listitem> @@ -624,13 +611,13 @@ </sect3> </sect2> - <sect2 id="svn-daily-use"> + <sect2 xml:id="svn-daily-use"> <title>Daily Use</title> <para>This section will explain how to perform common day-to-day operations with Subversion.</para> - <sect3 id="svn-daily-use-help"> + <sect3 xml:id="svn-daily-use-help"> <title>Help</title> <para><acronym>SVN</acronym> has built in help documentation. @@ -639,11 +626,11 @@ <screen>&prompt.user; <userinput>svn help</userinput></screen> <para>Additional information can be found in the - <ulink url="http://svnbook.red-bean.com/">Subversion - Book</ulink>.</para> + <link xlink:href="http://svnbook.red-bean.com/">Subversion + Book</link>.</para> </sect3> - <sect3 id="svn-daily-use-checkout"> + <sect3 xml:id="svn-daily-use-checkout"> <title>Checkout</title> <para>As seen earlier, to check out the &os; head @@ -706,7 +693,7 @@ </note> </sect3> - <sect3 id="svn-daily-use-anonymous-checkout"> + <sect3 xml:id="svn-daily-use-anonymous-checkout"> <title>Anonymous Checkout</title> <para>It is possible to anonymously check out the &os; @@ -714,25 +701,24 @@ read-only tree that can be updated, but not committed back to the main repository. To do this, use the following command:</para> - <screen>&prompt.user; <userinput>svn co <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/base/head /usr/src</userinput></screen> + <screen>&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/base/head /usr/src</userinput></screen> <para>Select the closest mirror and verify the mirror server - certificate from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> + certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror sites</link>.</para> </sect3> - <sect3 id="svn-daily-use-updating-the-tree"> + <sect3 xml:id="svn-daily-use-updating-the-tree"> <title>Updating the Tree</title> <para>To update a working copy to either the latest revision, or a specific revision:</para> <screen>&prompt.user; <userinput>svn update</userinput> -&prompt.user; <userinput>svn update -<replaceable>r12345</replaceable></userinput></screen> +&prompt.user; <userinput>svn update -r12345</userinput></screen> </sect3> - <sect3 id="svn-daily-use-status"> + <sect3 xml:id="svn-daily-use-status"> <title>Status</title> <para>To view the local changes that have been made to the @@ -746,7 +732,7 @@ <screen>&prompt.user; <userinput>svn status --show-updates</userinput></screen> </sect3> - <sect3 id="svn-daily-use-editing-and-committing"> + <sect3 xml:id="svn-daily-use-editing-and-committing"> <title>Editing and Committing</title> <para>Unlike Perforce, <acronym>SVN</acronym> does not need to @@ -758,13 +744,11 @@ <screen>&prompt.user; <userinput>svn commit</userinput></screen> - <para>To commit all changes in, for example, <filename - class="directory"><replaceable>lib/libfetch/</replaceable></filename> - and <filename - class="directory"><replaceable>usr/bin/fetch/</replaceable></filename> + <para>To commit all changes in, for example, <filename>lib/libfetch/</filename> + and <filename>usr/bin/fetch/</filename> in a single operation:</para> - <screen>&prompt.user; <userinput>svn commit <replaceable>lib/libfetch</replaceable> <replaceable>usr/bin/fetch</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn commit lib/libfetch usr/bin/fetch</userinput></screen> <para>There is also a commit wrapper for the ports tree to handle the properties and sanity checking your @@ -774,15 +758,13 @@ </userinput></screen> </sect3> - <sect3 id="svn-daily-use-adding-and-removing"> + <sect3 xml:id="svn-daily-use-adding-and-removing"> <title>Adding and Removing Files</title> <note> - <para>Before adding files, get a copy of <ulink - url="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</ulink> - (there is also a <ulink - url="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt"> - ports tree specific version</ulink>) + <para>Before adding files, get a copy of <link xlink:href="http://people.freebsd.org/~peter/auto-props.txt">auto-props.txt</link> + (there is also a <link xlink:href="http://people.freebsd.org/~beat/cvs2svn/auto-props.txt"> + ports tree specific version</link>) and add it to <filename>~/.subversion/config</filename> according to the instructions in the file. If you added something before reading this, use @@ -798,7 +780,7 @@ add</command>. To add a file named <emphasis>foo</emphasis>, edit it, then:</para> - <screen>&prompt.user; <userinput>svn add <replaceable>foo</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn add foo</userinput></screen> <note> <para>Most new source files should include a @@ -814,7 +796,7 @@ <para>Files can be removed with <command>svn remove</command>:</para> - <screen>&prompt.user; <userinput>svn remove <replaceable>foo</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn remove foo</userinput></screen> <para>Subversion does not require deleting the file before using <command>svn rm</command>, and indeed complains if @@ -823,30 +805,30 @@ <para>It is possible to add directories with <command>svn add</command>:</para> - <screen>&prompt.user; <userinput>mkdir <replaceable>bar</replaceable></userinput> -&prompt.user; <userinput>svn add <replaceable>bar</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mkdir bar</userinput> +&prompt.user; <userinput>svn add bar</userinput></screen> <para>Although <command>svn mkdir</command> makes this easier by combining the creation of the directory and the adding of it:</para> - <screen>&prompt.user; <userinput>svn mkdir <replaceable>bar</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn mkdir bar</userinput></screen> <para>Like files, directories are removed with <command>svn rm</command>. There is no separate command specifically for removing directories.</para> - <screen>&prompt.user; <userinput>svn rm <replaceable>bar</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn rm bar</userinput></screen> </sect3> - <sect3 id="svn-daily-use-copying-and-moving"> + <sect3 xml:id="svn-daily-use-copying-and-moving"> <title>Copying and Moving Files</title> <para>This command creates a copy of <filename>foo.c</filename> named <filename>bar.c</filename>, with the new file also under version control:</para> - <screen>&prompt.user; <userinput>svn copy <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn copy foo.c bar.c</userinput></screen> <para>The example above is equivalent to:</para> @@ -855,10 +837,10 @@ <para>To move and rename a file:</para> - <screen>&prompt.user; <userinput>svn move <replaceable>foo.c</replaceable> <replaceable>bar.c</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn move foo.c bar.c</userinput></screen> </sect3> - <sect3 id="svn-daily-use-log-and-annotate"> + <sect3 xml:id="svn-daily-use-log-and-annotate"> <title>Log and Annotate</title> <para><command>svn log</command> shows revisions and commit @@ -872,7 +854,7 @@ revision for each line of a file.</para> </sect3> - <sect3 id="svn-daily-use-diffs"> + <sect3 xml:id="svn-daily-use-diffs"> <title>Diffs</title> <para><command>svn diff</command> displays changes to the @@ -893,7 +875,7 @@ <screen>&prompt.user; <userinput>svn diff -c179454 .</userinput></screen> </sect3> - <sect3 id="svn-daily-use-reverting"> + <sect3 xml:id="svn-daily-use-reverting"> <title>Reverting</title> <para>Local changes (including additions and deletions) can be @@ -902,7 +884,7 @@ pristine copies of the original version.</para> </sect3> - <sect3 id="svn-daily-use-conflicts"> + <sect3 xml:id="svn-daily-use-conflicts"> <title>Conflicts</title> <para>If an <command>svn update</command> resulted in a merge @@ -912,11 +894,11 @@ The simple, not yet deprecated procedure is the following:</para> - <screen>&prompt.user; <userinput>svn resolved <replaceable>foo</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn resolved foo</userinput></screen> <para>However, the preferred procedure is:</para> - <screen>&prompt.user; <userinput>svn resolve --accept=working <replaceable>foo</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn resolve --accept=working foo</userinput></screen> <para>The two examples are equivalent. Possible values for <literal>--accept</literal> are:</para> @@ -955,7 +937,7 @@ <sect2> <title>Advanced Use</title> - <sect3 id="svn-advanced-use-sparse-checkouts"> + <sect3 xml:id="svn-advanced-use-sparse-checkouts"> <title>Sparse Checkouts</title> <para><acronym>SVN</acronym> allows @@ -999,7 +981,7 @@ Thus, given the working copy produced by the previous example:</para> - <screen>&prompt.user; <userinput>cd <replaceable>~/freebsd</replaceable></userinput> + <screen>&prompt.user; <userinput>cd ~/freebsd</userinput> &prompt.user; <userinput>svn update --set-depth=immediates .</userinput></screen> <para>The above command will populate the working copy in @@ -1011,10 +993,10 @@ <replaceable>head</replaceable> (in this case) to infinity, and fully populate it:</para> - <screen>&prompt.user; <userinput>svn update --set-depth=infinity <replaceable>head</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn update --set-depth=infinity head</userinput></screen> </sect3> - <sect3 id="svn-advanced-use-direct-operation"> + <sect3 xml:id="svn-advanced-use-direct-operation"> <title>Direct Operation</title> <para>Certain operations can be performed directly on the @@ -1064,7 +1046,7 @@ &prompt.user; <userinput>svn commit stable/8</userinput></screen> </sect3> - <sect3 id="svn-advanced-use-merging"> + <sect3 xml:id="svn-advanced-use-merging"> <title>Merging with <acronym>SVN</acronym></title> <para>This section deals with merging code from one branch to @@ -1090,26 +1072,25 @@ <literal>svn:mergeinfo</literal>.</para> <para>It is <emphasis>not</emphasis> inherited. For - instance, <filename - class="directory">stable/6/contrib/openpam/</filename> + instance, <filename>stable/6/contrib/openpam/</filename> does not implicitly inherit mergeinfo from - <filename class="directory">stable/6/</filename>, or - <filename class="directory">stable/6/contrib/</filename>. + <filename>stable/6/</filename>, or + <filename>stable/6/contrib/</filename>. Doing so would make partial checkouts very hard to manage. Instead, mergeinfo is explicitly propagated down the tree. For merging something into - <filename class="directory">branch/foo/bar/</filename>, + <filename>branch/foo/bar/</filename>, the following rules apply:</para> <orderedlist> <listitem> <para>If - <filename class="directory">branch/foo/bar/</filename> + <filename>branch/foo/bar/</filename> does not already have a mergeinfo record, but a direct ancestor (for instance, - <filename class="directory">branch/foo/</filename>) + <filename>branch/foo/</filename>) does, then that record will be propagated down to - <filename class="directory">branch/foo/bar/</filename> + <filename>branch/foo/bar/</filename> before information about the current merge is recorded.</para> </listitem> @@ -1122,24 +1103,21 @@ <listitem> <para>If a direct descendant of - <filename class="directory">branch/foo/bar/</filename> - (for instance, <filename - class="directory">branch/foo/bar/baz/</filename>) + <filename>branch/foo/bar/</filename> + (for instance, <filename>branch/foo/bar/baz/</filename>) already has a mergeinfo record, information about the current merge will be propagated down to it.</para> </listitem> </orderedlist> <para>If you consider the case where a revision changes - several separate parts of the tree (for example, <filename - class="directory">branch/foo/bar/</filename> and - <filename class="directory">branch/foo/quux/</filename>), + several separate parts of the tree (for example, <filename>branch/foo/bar/</filename> and + <filename>branch/foo/quux/</filename>), but you only want to merge some of it (for example, - <filename class="directory">branch/foo/bar/</filename>), + <filename>branch/foo/bar/</filename>), you will see that these rules make sense. If mergeinfo was propagated up, it would seem like that revision had - also been merged to <filename - class="directory">branch/foo/quux/</filename>, when in + also been merged to <filename>branch/foo/quux/</filename>, when in fact it had not been.</para> </sect4> @@ -1170,35 +1148,32 @@ <listitem> <para>Changes to kernel code should be merged to - <filename class="directory">sys/</filename>. For + <filename>sys/</filename>. For instance, a change to the &man.ichwd.4; driver should be merged to - <filename class="directory">sys/</filename>, not - <filename class="directory">sys/dev/ichwd/</filename>. + <filename>sys/</filename>, not + <filename>sys/dev/ichwd/</filename>. Likewise, a change to the TCP/IP stack should be - merged to <filename class="directory">sys/</filename>, - not <filename - class="directory">sys/netinet/</filename>.</para> + merged to <filename>sys/</filename>, + not <filename>sys/netinet/</filename>.</para> </listitem> <listitem> <para>Changes to code under - <filename class="directory">etc/</filename> should be - merged at <filename class="directory">etc/</filename>, + <filename>etc/</filename> should be + merged at <filename>etc/</filename>, not below it.</para> </listitem> <listitem> <para>Changes to vendor code (code in - <filename class="directory">contrib/</filename>, - <filename class="directory">crypto/</filename> and so + <filename>contrib/</filename>, + <filename>crypto/</filename> and so on) should be merged to the directory where vendor - imports happen. For instance, a change to <filename - class="directory">crypto/openssl/util/</filename> - should be merged to <filename - class="directory">crypto/openssl/</filename>. This + imports happen. For instance, a change to <filename>crypto/openssl/util/</filename> + should be merged to <filename>crypto/openssl/</filename>. This is rarely an issue, however, since changes to vendor code are usually merged wholesale.</para> </listitem> @@ -1207,44 +1182,39 @@ <para>Changes to userland programs should as a general rule be merged to the directory that contains the Makefile for that program. For instance, a change to - <filename - class="directory">usr.bin/xlint/arch/i386/</filename> - should be merged to <filename - class="directory">usr.bin/xlint/</filename>.</para> + <filename>usr.bin/xlint/arch/i386/</filename> + should be merged to <filename>usr.bin/xlint/</filename>.</para> </listitem> <listitem> <para>Changes to userland libraries should as a general rule be merged to the directory that contains the Makefile for that library. For instance, a change to - <filename class="directory">lib/libc/gen/</filename> - should be merged to <filename - class="directory">lib/libc/</filename>.</para> + <filename>lib/libc/gen/</filename> + should be merged to <filename>lib/libc/</filename>.</para> </listitem> <listitem> <para>There may be cases where it makes sense to deviate from the rules for userland programs and libraries. - For instance, everything under <filename - class="directory">lib/libpam/</filename> is merged - to <filename class="directory">lib/libpam/</filename>, + For instance, everything under <filename>lib/libpam/</filename> is merged + to <filename>lib/libpam/</filename>, even though the library itself and all of the modules each have their own Makefile.</para> </listitem> <listitem> <para>Changes to manual pages should be merged to - <filename - class="directory">share/man/man<replaceable>N</replaceable>/</filename>, + <filename>share/man/manN/</filename>, for the appropriate value of <literal>N</literal>.</para> </listitem> <listitem> <para>Other changes to - <filename class="directory">share/</filename> should + <filename>share/</filename> should be merged to the appropriate subdirectory and not to - <filename class="directory">share/</filename> + <filename>share/</filename> directly.</para> </listitem> @@ -1275,15 +1245,13 @@ in one go.</para> <para>The source will almost invariably be the same as the - target. For instance, you will always merge <filename - class="directory">stable/7/lib/libc/</filename> from - <filename class="directory">head/lib/libc/</filename>. + target. For instance, you will always merge <filename>stable/7/lib/libc/</filename> from + <filename>head/lib/libc/</filename>. The only exception would be when merging changes to code that has moved in the source branch but not in the parent branch. For instance, a change to &man.pkill.1; would be - merged from <filename - class="directory">bin/pkill/</filename> in head to - <filename class="directory">usr.bin/pkill/</filename> in + merged from <filename>bin/pkill/</filename> in head to + <filename>usr.bin/pkill/</filename> in stable/7.</para> </sect4> @@ -1381,14 +1349,12 @@ $target - head/$source:$P,$Q,$R</screen> <para>As a practical example, consider the following scenario: The changes to <filename>netmap.4</filename> in r238987 is to be merged from CURRENT to 9-STABLE. - The file resides in <filename - class="directory">head/share/man/man4</filename> and + The file resides in <filename>head/share/man/man4</filename> and according to <xref linkend="svn-advanced-use-merging"/> this is also where to do the merge. Note that in this example all paths are relative to the top of the svn repository. For more information on the directory - layout, see <xref - linkend="svn-getting-started-base-layout"/>.</para> + layout, see <xref linkend="svn-getting-started-base-layout"/>.</para> <para>The first step is to inspect the existing mergeinfo.</para> @@ -1414,13 +1380,13 @@ U stable/9/share/man/man4/netmap.4 <sect5> <title>Merging into the Kernel - (<filename class="directory">sys/</filename>)</title> + (<filename>sys/</filename>)</title> <para>As stated above, merging into the kernel is different from merging in the rest of the tree. In many ways merging to the kernel is simpler because there is always the same merge target - (<filename class="directory">sys/</filename>).</para> + (<filename>sys/</filename>).</para> <para>Once <command>svn merge</command> has been executed, <command>svn diff</command> has to be run on the @@ -1465,7 +1431,7 @@ U stable/9/share/man/man4/netmap.4 </sect4> </sect3> - <sect3 id="svn-advanced-use-vendor-imports"> + <sect3 xml:id="svn-advanced-use-vendor-imports"> <title>Vendor Imports with <acronym>SVN</acronym></title> <important> @@ -1535,7 +1501,7 @@ U stable/9/share/man/man4/netmap.4 <para>To flatten the <literal>pf</literal> tree:</para> - <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf/dist/contrib/pf</replaceable></userinput> + <screen>&prompt.user; <userinput>cd vendor/pf/dist/contrib/pf</userinput> &prompt.user; <userinput>svn mv $(svn list) ../..</userinput> &prompt.user; <userinput>cd ../..</userinput> &prompt.user; <userinput>svn rm contrib</userinput> @@ -1580,8 +1546,8 @@ U stable/9/share/man/man4/netmap.4 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> + <screen>&prompt.user; <userinput>cd head/contrib/pf</userinput> +&prompt.user; <userinput>svn merge --record-only svn+ssh://svn.freebsd.org/base/vendor/pf/dist@180876 .</userinput> &prompt.user; <userinput>svn commit</userinput></screen> </sect5> </sect4> @@ -1611,10 +1577,10 @@ U stable/9/share/man/man4/netmap.4 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> + <screen>&prompt.user; <userinput>cd vendor/pf/dist</userinput> +&prompt.user; <userinput>svn list -R | grep -v '/$' | sort >../old</userinput> +&prompt.user; <userinput>cd ../pf-4.3</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 @@ -1628,14 +1594,14 @@ U stable/9/share/man/man4/netmap.4 <title>Importing into the Vendor Tree</title> <para>Now, the sources must be copied into - <filename><replaceable>dist</replaceable></filename> and + <filename>dist</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> + <screen>&prompt.user; <userinput>cd vendor/pf/pf-4.3</userinput> &prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput> -&prompt.user; <userinput>cd <replaceable>../dist</replaceable></userinput> +&prompt.user; <userinput>cd ../dist</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> @@ -1667,11 +1633,11 @@ U stable/9/share/man/man4/netmap.4 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> + <screen>&prompt.user; <userinput>svn cp svn+ssh://svn.freebsd.org/base/vendor/pf/dist svn+ssh://svn.freebsd.org/base/vendor/pf/4.3</userinput></screen> <para>Once that is complete, <command>svn up</command> the working copy of - <filename><replaceable>vendor/pf</replaceable></filename> + <filename>vendor/pf</filename> to get the new tag, although this is rarely needed.</para> @@ -1679,7 +1645,7 @@ U stable/9/share/man/man4/netmap.4 <command>svn:mergeinfo</command> results must be removed:</para> - <screen>&prompt.user; <userinput>cd <replaceable>vendor/pf</replaceable></userinput> + <screen>&prompt.user; <userinput>cd vendor/pf</userinput> &prompt.user; <userinput>svn cp dist 4.3</userinput> &prompt.user; <userinput>svn propdel svn:mergeinfo -R 4.3</userinput></screen> </sect5> @@ -1688,9 +1654,9 @@ U stable/9/share/man/man4/netmap.4 <sect4> <title>Merging to Head</title> - <screen>&prompt.user; <userinput>cd <replaceable>head/contrib/pf</replaceable></userinput> + <screen>&prompt.user; <userinput>cd head/contrib/pf</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> +&prompt.user; <userinput>svn merge --accept=postpone svn+ssh://svn.freebsd.org/base/vendor/pf/dist .</userinput></screen> <para>The <literal>--accept=postpone</literal> tells Subversion that it should not complain because merge @@ -1705,7 +1671,7 @@ U stable/9/share/man/man4/netmap.4 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> + <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn+ssh://svn.freebsd.org/base/vendor/pf/dist --new=.</userinput></screen> <para>The <literal>--no-diff-deleted</literal> tells Subversion not to complain about files that are in the @@ -1745,24 +1711,24 @@ U stable/9/share/man/man4/netmap.4 <para>This section is an example of importing and tagging <application>byacc</application> into - <filename class="directory">head</filename>.</para> + <filename>head</filename>.</para> <para>First, prepare the directory in - <filename class="directory">vendor</filename>:</para> + <filename>vendor</filename>:</para> - <screen>&prompt.user; <userinput>svn co --depth immediates <replaceable>$FSVN/vendor</replaceable></userinput> -&prompt.user; <userinput>cd <replaceable>vendor</replaceable></userinput> -&prompt.user; <userinput>svn mkdir <replaceable>byacc</replaceable></userinput> -&prompt.user; <userinput>svn mkdir <replaceable>byacc/dist</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn co --depth immediates $FSVN/vendor</userinput> +&prompt.user; <userinput>cd vendor</userinput> +&prompt.user; <userinput>svn mkdir byacc</userinput> +&prompt.user; <userinput>svn mkdir byacc/dist</userinput></screen> <para>Now, import the sources into the - <filename class="directory">dist</filename> directory. + <filename>dist</filename> directory. Once the files are in place, <command>svn add</command> the new ones, then <command>svn commit</command> and tag the imported version. To save time and bandwidth, direct remote committing and tagging is possible:</para> - <screen>&prompt.user; <userinput>svn cp -m <replaceable>"Tag byacc 20120115"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/vendor/byacc/20120115</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn cp -m "Tag byacc 20120115" $FSVN/vendor/byacc/dist $FSVN/vendor/byacc/20120115</userinput></screen> </sect5> <sect5> @@ -1771,7 +1737,7 @@ U stable/9/share/man/man4/netmap.4 <para>Due to this being a new file, copy it for the merge:</para> - <screen>&prompt.user; <userinput>svn cp -m <replaceable>"Import byacc to contrib"</replaceable> <replaceable>$FSVN/vendor/byacc/dist</replaceable> <replaceable>$FSVN/head/contrib/byacc</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn cp -m "Import byacc to contrib" $FSVN/vendor/byacc/dist $FSVN/head/contrib/byacc</userinput></screen> <para>Working normally on newly imported sources is still possible.</para> @@ -1779,7 +1745,7 @@ U stable/9/share/man/man4/netmap.4 </sect4> </sect3> - <sect3 id="svn-advanced-use-reverting-a-commit"> + <sect3 xml:id="svn-advanced-use-reverting-a-commit"> <title>Reverting a Commit</title> <para>Reverting a commit to a previous version is fairly @@ -1822,7 +1788,7 @@ U stable/9/share/man/man4/netmap.4 cause history to be lost.</para> </sect3> - <sect3 id="svn-advanced-use-fixing-mistakes"> + <sect3 xml:id="svn-advanced-use-fixing-mistakes"> <title>Fixing Mistakes</title> <para>While we can do surgery in an emergency, do not plan on @@ -1848,7 +1814,7 @@ U stable/9/share/man/man4/netmap.4 This is a waste.</para> </sect3> - <sect3 id="svn-advanced-use-setting-up-svnsync"> + <sect3 xml:id="svn-advanced-use-setting-up-svnsync"> <title>Setting up a <application>svnsync</application> Mirror</title> @@ -1872,7 +1838,7 @@ U stable/9/share/man/man4/netmap.4 <screen>&prompt.user; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/development/subversion/svnmirror-base-r221445.tar.xz</userinput></screen> <para>Once you have the file, extract it to somewhere like - <filename class="directory">home/svnmirror/base/</filename>. + <filename>home/svnmirror/base/</filename>. Then, update it, so that it fetches changes since the last revision in the archive:</para> @@ -1893,7 +1859,7 @@ U stable/9/share/man/man4/netmap.4 <para>Use <literal>propset</literal> to change things.</para> </sect3> - <sect3 id="svn-advanced-use-committing-high-ascii-data"> + <sect3 xml:id="svn-advanced-use-committing-high-ascii-data"> <title>Committing High-<acronym>ASCII</acronym> Data</title> <para>Files that have high-<acronym>ASCII</acronym> bits are @@ -1911,7 +1877,7 @@ U stable/9/share/man/man4/netmap.4 <screen>&prompt.user; <userinput>svn propset fbsd:notbinary yes foo.data</userinput></screen> </sect3> - <sect3 id="svn-advanced-use-maintaining-a-project-branch"> + <sect3 xml:id="svn-advanced-use-maintaining-a-project-branch"> <title>Maintaining a Project Branch</title> <para>A project branch is one that is synced to head (or @@ -1926,17 +1892,14 @@ U stable/9/share/man/man4/netmap.4 is dead (although you can have a new branch with the same name after you delete the branch if you want).</para> - <para>As per <ulink - url="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</ulink>, + <para>As per <link xlink:href="http://people.freebsd.org/~peter/svn_notes.txt">http://people.freebsd.org/~peter/svn_notes.txt</link>, work that is intended to be merged back into HEAD should be - in <filename class="directory">base/projects/</filename>. + in <filename>base/projects/</filename>. If you are doing work that is beneficial to the &os; community in some way but not intended to be merged directly - back into HEAD then the proper location is <filename - class="directory">base/user/<replaceable>your-name</replaceable>/</filename>. - <ulink - url="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This - page</ulink> contains further details.</para> + back into HEAD then the proper location is <filename>base/user/your-name/</filename>. + <link xlink:href="http://svnweb.freebsd.org/base/projects/GUIDELINES.txt">This + page</link> contains further details.</para> <para>To create a project branch:</para> @@ -1983,7 +1946,7 @@ ControlPersist yes</screen> <para>Checking out a working copy with a stock Subversion client without &os;-specific patches - (<makevar>OPTIONS_SET=FREEBSD_TEMPLATE</makevar>) will mean + (<varname>OPTIONS_SET=FREEBSD_TEMPLATE</varname>) will mean that <literal>$FreeBSD$</literal> tags will not be expanded. Once the correct version has been installed, trick Subversion into expanding them like so:</para> @@ -1995,7 +1958,7 @@ ControlPersist yes</screen> </sect2> </sect1> - <sect1 id="conventions"> + <sect1 xml:id="conventions"> <title>Conventions and Traditions</title> <para>As a new developer there are a number of things you should @@ -2003,14 +1966,14 @@ ControlPersist yes</screen> you are not a committer, e.g., have GNATS-only access, then your mentor needs to do these things for you.)</para> - <sect2 id="conventions-committers"> + <sect2 xml:id="conventions-committers"> <title>Guidelines for Committers</title> <note> <para>The <literal>.ent</literal>, <literal>.xml</literal>, and <literal>.xml</literal> files listed below exist in the &os; Documentation Project SVN repository at - <hostid role="fqdn">svn.FreeBSD.org/doc/</hostid>.</para> + <systemitem class="fqdomainname">svn.FreeBSD.org/doc/</systemitem>.</para> </note> <para>If you have been given commit rights to one or more of the @@ -2048,9 +2011,8 @@ ControlPersist yes</screen> <listitem> <para>Add yourself to the <quote>Developers</quote> section - of the <ulink - url="&url.articles.contributors;/index.html">Contributors - List</ulink> + of the <link xlink:href="&url.articles.contributors;/index.html">Contributors + List</link> (<filename>head/en_US.ISO8859-1/articles/contributors/contrib.committers.xml</filename>) and remove yourself from the <quote>Additional Contributors</quote> section @@ -2077,8 +2039,7 @@ ControlPersist yes</screen> <para>&a.des.email; has written a shell script (<filename>head/share/pgpkeys/addkey.sh</filename>) to - make this extremely simple. See the <ulink - url="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</ulink> + make this extremely simple. See the <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/pgpkeys/README">README</link> file for more information.</para> <note> @@ -2086,15 +2047,14 @@ ControlPersist yes</screen> in the Handbook, since the key may be required for positive identification of a committer, e.g., by the &a.admins; for account recovery. A complete keyring of - <hostid role="domainname">FreeBSD.org</hostid> users is - available for download from <ulink - url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para> + <systemitem class="fqdomainname">FreeBSD.org</systemitem> users is + available for download from <link xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para> </note> </listitem> <listitem> <para>Add an entry for yourself to - <filename>src/share/misc/committers-<replaceable>repository</replaceable>.dot</filename>, + <filename>src/share/misc/committers-repository.dot</filename>, where repository is either doc, ports or src, depending on the commit privileges you obtained.</para> </listitem> @@ -2111,12 +2071,10 @@ ControlPersist yes</screen> <listitem> <para>If you already have an account at the - <ulink url="http://wiki.freebsd.org">&os; wiki</ulink>, - make sure your mentor moves you from the <ulink - url="http://wiki.freebsd.org/ContributorsGroup">Contributors - group</ulink> to the <ulink - url="http://wiki.freebsd.org/DevelopersGroup">Developers - group</ulink>. Otherwise, consider signing up for an + <link xlink:href="http://wiki.freebsd.org">&os; wiki</link>, + make sure your mentor moves you from the <link xlink:href="http://wiki.freebsd.org/ContributorsGroup">Contributors + group</link> to the <link xlink:href="http://wiki.freebsd.org/DevelopersGroup">Developers + group</link>. Otherwise, consider signing up for an account so you can publish projects and ideas you are working on.</para> </listitem> @@ -2124,10 +2082,10 @@ ControlPersist yes</screen> <listitem> <para>Once you get access to the wiki, you may add yourself to the - <ulink url="http://wiki.freebsd.org/HowWeGotHere">How We - Got Here</ulink> and - <ulink url="http://wiki.freebsd.org/IrcNicks">Irc - Nicks</ulink> pages.</para> + <link xlink:href="http://wiki.freebsd.org/HowWeGotHere">How We + Got Here</link> and + <link xlink:href="http://wiki.freebsd.org/IrcNicks">Irc + Nicks</link> pages.</para> </listitem> <listitem> @@ -2146,7 +2104,7 @@ ControlPersist yes</screen> </note> </sect2> - <sect2 id="conventions-everyone"> + <sect2 xml:id="conventions-everyone"> <title>Guidelines for Everyone</title> <para>Whether or not you have commit rights:</para> @@ -2164,8 +2122,8 @@ ControlPersist yes</screen> </listitem> <listitem> - <para>Log into <hostid>hub.FreeBSD.org</hostid> and create a - <filename>/var/forward/<replaceable>user</replaceable></filename> + <para>Log into <systemitem>hub.FreeBSD.org</systemitem> and create a + <filename>/var/forward/user</filename> (where <replaceable>user</replaceable> is your username) file containing the e-mail address where you want mail addressed to @@ -2173,7 +2131,7 @@ ControlPersist yes</screen> forwarded. This includes all of the commit messages as well as any other mail addressed to the &a.committers; and the &a.developers;. Really large mailboxes which have - taken up permanent residence on <hostid>hub</hostid> often + taken up permanent residence on <systemitem>hub</systemitem> often get <quote>accidentally</quote> truncated without warning, so forward it or read it and you will not lose it.</para> @@ -2187,7 +2145,7 @@ ControlPersist yes</screen> checks turned off for your email you can place a file named <filename>.spam_lover</filename> in your home directory on - <hostid role="fqdn">freefall.FreeBSD.org</hostid> to + <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> to disable the checks for your email.</para> </listitem> </itemizedlist> @@ -2200,7 +2158,7 @@ ControlPersist yes</screen> </note> </sect2> - <sect2 id="mentors"> + <sect2 xml:id="mentors"> <title>Mentors</title> <para>All new developers also have a mentor assigned to them for @@ -2220,7 +2178,7 @@ ControlPersist yes</screen> </sect2> </sect1> - <sect1 id="pref-license"> + <sect1 xml:id="pref-license"> <title>Preferred License for New Files</title> <para>Currently the &os; Project suggests and uses the following @@ -2285,7 +2243,7 @@ ControlPersist yes</screen> brought to the attention of the core team.</para> </sect1> - <sect1 id="developer.relations"> + <sect1 xml:id="developer.relations"> <title>Developer Relations</title> <para>If you are working directly on your own code or on code @@ -2296,11 +2254,11 @@ ControlPersist yes</screen> areas, to our shame), the same applies. If, however, you are about to modify something which is clearly being actively maintained by someone else (and it is only by watching the - <literal><replaceable>repository</replaceable>-committers</literal> + <literal>repository-committers</literal> mailing list that you can really get a feel for just what is and is not) then consider sending the change to them instead, just as you would have before becoming a committer. For ports, you - should contact the listed <makevar>MAINTAINER</makevar> in the + should contact the listed <varname>MAINTAINER</varname> in the <filename>Makefile</filename>. For other parts of the repository, if you are unsure who the active maintainer might be, it may help to scan the revision history to see who has @@ -2308,7 +2266,7 @@ ControlPersist yes</screen> shell script that can help determine who the active maintainer might be. It lists each person who has committed to a given file along with the number of commits each person has made. It - can be found on <hostid>freefall</hostid> at + can be found on <systemitem>freefall</systemitem> at <filename>~fenner/bin/whodid</filename>. If your queries go unanswered or the committer otherwise indicates a lack of interest in the area affected, go ahead and commit it.</para> @@ -2347,7 +2305,7 @@ ControlPersist yes</screen> will review code.</para> </sect1> - <sect1 id="if-in-doubt"> + <sect1 xml:id="if-in-doubt"> <title>If in doubt...</title> <para>When you are not sure about something, whether it be a @@ -2386,15 +2344,15 @@ ControlPersist yes</screen> document it, as others will have the same question.</para> </sect1> - <sect1 id="gnats"> + <sect1 xml:id="gnats"> <title>GNATS</title> <para>The &os; Project utilizes <application>GNATS</application> for tracking bugs and change requests. Be sure that if you commit a fix or suggestion found in a <application>GNATS</application> PR, you use - <command>edit-pr <replaceable>pr-number</replaceable></command> - on <hostid>freefall</hostid> to close it. It is also considered + <command>edit-pr pr-number</command> + on <systemitem>freefall</systemitem> to close it. It is also considered nice if you take time to close any PRs associated with your commits, if appropriate. You can also make use of &man.send-pr.1; yourself for proposing any change which you feel @@ -2406,19 +2364,16 @@ ControlPersist yes</screen> <itemizedlist> <listitem> - <para><ulink - url="&url.articles.pr-guidelines;/index.html">&os; - Problem Report Handling Guidelines</ulink></para> + <para><link xlink:href="&url.articles.pr-guidelines;/index.html">&os; + Problem Report Handling Guidelines</link></para> </listitem> <listitem> - <para><ulink - url="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html"></ulink></para> + <para><uri xlink:href="http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html">http://www.cs.utah.edu/csinfo/texinfo/gnats/gnats.html</uri></para> </listitem> <listitem> - <para><ulink - url="&url.base;/support.html">http://www.FreeBSD.org/support.html</ulink></para> + <para><link xlink:href="&url.base;/support.html">http://www.FreeBSD.org/support.html</link></para> </listitem> <listitem> @@ -2436,18 +2391,18 @@ ControlPersist yes</screen> <title>Mirroring the GNATS Tree</title> <para>It is possible to mirror the GNATS database by installing - <filename role="package">net/rsync</filename>, and + <package>net/rsync</package>, and executing:</para> <screen>&prompt.user; <userinput>rsync -va rsync://bit0.us-west.freebsd.org/FreeBSD-bit/gnats .</userinput></screen> </sect2> - <sect2 id="gnatstools"> + <sect2 xml:id="gnatstools"> <title>Useful Tools</title> <para>Other than <command>edit-pr</command> there are a collection of tools in <filename>~gnats/tools/</filename> - on <hostid>freefall</hostid> which can make working with PRs + on <systemitem>freefall</systemitem> which can make working with PRs much easier.</para> <para><command>open-pr</command>, <command>close-pr</command>, @@ -2461,15 +2416,15 @@ ControlPersist yes</screen> command.</para> <para>For example, to assign PR 123456 to yourself type - <command>take-pr <replaceable>123456</replaceable></command>. + <command>take-pr 123456</command>. If you want to set the PR to patched awaiting an MFC at the same time use: <command>change-pr -t -p -m "awaiting MFC" - <replaceable>123456</replaceable></command></para> + 123456</command></para> </sect2> </sect1> - <sect1 id="people"> + <sect1 xml:id="people"> <title>Who's Who</title> <para>Besides the repository meisters, there are other &os; @@ -2489,12 +2444,10 @@ ControlPersist yes</screen> to the CVS tree. It is not a conflict resolution body. The vast majority of documentation related discussion takes place on the &a.doc;. More details regarding the - doceng team can be found in its <ulink - url="http://www.FreeBSD.org/internal/doceng.html">charter</ulink>. + doceng team can be found in its <link xlink:href="http://www.FreeBSD.org/internal/doceng.html">charter</link>. Committers interested in contributing to the documentation - should familiarize themselves with the <ulink - url="&url.books.fdp-primer;/index.html">Documentation - Project Primer</ulink>.</para> + should familiarize themselves with the <link xlink:href="&url.books.fdp-primer;/index.html">Documentation + Project Primer</link>.</para> </listitem> </varlistentry> @@ -2546,8 +2499,8 @@ ControlPersist yes</screen> <listitem> <para>Dag-Erling is the - <ulink url="&url.base;/security/">&os; Security - Officer</ulink> and oversees the + <link xlink:href="&url.base;/security/">&os; Security + Officer</link> and oversees the &a.security-officer;.</para> </listitem> </varlistentry> @@ -2621,7 +2574,7 @@ ControlPersist yes</screen> </variablelist> </sect1> - <sect1 id="ssh.guide"> + <sect1 xml:id="ssh.guide"> <title>SSH Quick-Start Guide</title> <procedure> @@ -2640,21 +2593,21 @@ ControlPersist yes</screen> <step> <para>Generate a key pair using &man.ssh-keygen.1;. The key pair will wind up in your - <filename><envar>$HOME</envar>/.ssh/</filename> + <filename>$HOME/.ssh/</filename> directory.</para> </step> <step> <para>Send your public key - (<filename><envar>$HOME</envar>/.ssh/id_dsa.pub</filename> + (<filename>$HOME/.ssh/id_dsa.pub</filename> or - <filename><envar>$HOME</envar>/.ssh/id_rsa.pub</filename>) + <filename>$HOME/.ssh/id_rsa.pub</filename>) to the person setting you up as a committer so it can be put into the - <filename><replaceable>yourlogin</replaceable></filename> + <filename>yourlogin</filename> file in - <filename class="directory">/etc/ssh-keys/</filename> on - <hostid>freefall</hostid>.</para> + <filename>/etc/ssh-keys/</filename> on + <systemitem>freefall</systemitem>.</para> </step> </procedure> @@ -2669,12 +2622,12 @@ ControlPersist yes</screen> freefall.FreeBSD.org ls /usr</command>.</para> <para>For more information, see - <filename role="package">security/openssh</filename>, + <package>security/openssh</package>, &man.ssh.1;, &man.ssh-add.1;, &man.ssh-agent.1;, &man.ssh-keygen.1;, and &man.scp.1;.</para> </sect1> - <sect1 id="coverity"> + <sect1 xml:id="coverity"> <title>&coverity.prevent; Availability for &os; Committers</title> <para>In January 2006, the &os; Foundation obtained a license @@ -2686,7 +2639,7 @@ ControlPersist yes</screen> <para>&os; developers who are interested in obtaining access to the analysis results of the automated <application>Coverity Prevent</application> runs, can find out - more by logging into <hostid>freefall</hostid> and reading the + more by logging into <systemitem>freefall</systemitem> and reading the relevant bits of the files:</para> <variablelist> @@ -2731,7 +2684,7 @@ ControlPersist yes</screen> <para>The &os; Wiki includes a mini-guide for developers who are interested in working with the &coverity.prevent; analysis reports: - <ulink url="http://wiki.freebsd.org/CoverityPrevent"></ulink>. + <uri xlink:href="http://wiki.freebsd.org/CoverityPrevent">http://wiki.freebsd.org/CoverityPrevent</uri>. Please note that this mini-guide is only readable by &os; developers, so if you cannot access this page, you will have to ask someone to add you to the appropriate Wiki access @@ -2743,7 +2696,7 @@ ControlPersist yes</screen> list of the &os; developers.</para> </sect1> - <sect1 id="rules"> + <sect1 xml:id="rules"> <title>The &os; Committers' Big List of Rules</title> <orderedlist> @@ -2762,7 +2715,7 @@ ControlPersist yes</screen> <listitem> <para>Respect existing maintainers (if listed in the - <makevar>MAINTAINER</makevar> field in + <varname>MAINTAINER</varname> field in <filename>Makefile</filename> or in the <filename>MAINTAINER</filename> file in the top-level directory).</para> @@ -2861,7 +2814,7 @@ ControlPersist yes</screen> <title>Details</title> <orderedlist> - <listitem id="respect"> + <listitem xml:id="respect"> <para>Respect other committers.</para> <para>This means that you need to treat other committers as @@ -2960,8 +2913,7 @@ ControlPersist yes</screen> is to put a maintainer line in the <filename>Makefile</filename> for any package or subtree which is being actively maintained by one or more people; - see <ulink - url="&url.books.developers-handbook;/policies.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</ulink> + see <link xlink:href="&url.books.developers-handbook;/policies.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/developers-handbook/policies.html</link> for documentation on this. Where sections of code have several maintainers, commits to affected areas by one maintainer need to be reviewed by at least one other @@ -2974,8 +2926,7 @@ ControlPersist yes</screen> <para>Other areas of &os; fall under the control of someone who manages an overall category of &os; evolution, such as internationalization or networking. - See <ulink - url="&url.base;/administration.html">http://www.FreeBSD.org/administration.html</ulink> + See <link xlink:href="&url.base;/administration.html">http://www.FreeBSD.org/administration.html</link> for more information on this.</para> </listitem> @@ -3120,8 +3071,8 @@ ControlPersist yes</screen> running that code. If you have a change which also may break another architecture, be sure and test on all supported architectures. Please refer to the - <ulink url="http://www.FreeBSD.org/internal/">&os; - Internal Page</ulink> for a list of available resources. + <link xlink:href="http://www.FreeBSD.org/internal/">&os; + Internal Page</link> for a list of available resources. As other architectures are added to the &os; supported platforms list, the appropriate shared testing resources will be made available.</para> @@ -3212,7 +3163,7 @@ ControlPersist yes</screen> <para>For all on-line manual pages, run <command>manck</command> (from ports) over the manual page to verify all of the cross references and file references are correct and that the man - page has all of the appropriate <makevar>MLINK</makevar>s + page has all of the appropriate <varname>MLINK</varname>s installed.</para> <para>Do not mix style fixes with new functionality. A style @@ -3257,7 +3208,7 @@ ControlPersist yes</screen> </sect2> </sect1> - <sect1 id="archs"> + <sect1 xml:id="archs"> <title>Support for Multiple Architectures</title> <para>&os; is a highly portable operating system intended to @@ -3454,7 +3405,7 @@ ControlPersist yes</screen> </sect2> </sect1> - <sect1 id="ports"> + <sect1 xml:id="ports"> <title>Ports Specific FAQ</title> <qandaset> @@ -3499,14 +3450,13 @@ ControlPersist yes</screen> <screen>&prompt.root; <userinput>make install</userinput> &prompt.root; <userinput>make package</userinput> &prompt.root; <userinput>make deinstall</userinput> -&prompt.root; <userinput>pkg_add <replaceable>package you built above</replaceable></userinput> +&prompt.root; <userinput>pkg_add package you built above</userinput> &prompt.root; <userinput>make deinstall</userinput> &prompt.root; <userinput>make reinstall</userinput> &prompt.root; <userinput>make package</userinput></screen> - <para>The <ulink - url="&url.books.porters-handbook;/index.html">Porters - Handbook</ulink> contains more detailed + <para>The <link xlink:href="&url.books.porters-handbook;/index.html">Porters + Handbook</link> contains more detailed instructions.</para> <para>Use &man.portlint.1; to check the syntax of the @@ -3516,15 +3466,14 @@ ControlPersist yes</screen> <para>If the port came from a submitter who has not contributed to the Project before, add that person's - name to the <ulink - url="&url.articles.contributors;/contrib-additional.html">Additional - Contributors</ulink> section of the &os; + name to the <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional + Contributors</link> section of the &os; Contributors List.</para> <para>Close the PR if the port came in as a PR. To close a PR, just do <userinput>edit-pr - <replaceable>PR#</replaceable></userinput> on - <hostid>freefall</hostid> and change the + PR#</userinput> on + <systemitem>freefall</systemitem> and change the <varname>state</varname> from <constant>open</constant> to <constant>closed</constant>. You will be asked to enter a log message and then you are done.</para> @@ -3574,7 +3523,7 @@ ControlPersist yes</screen> </step> <step> - <para>Remove the <makevar>SUBDIR</makevar> listing + <para>Remove the <varname>SUBDIR</varname> listing of the port in the parent directory <filename>Makefile</filename>.</para> </step> @@ -3594,8 +3543,7 @@ ControlPersist yes</screen> </itemizedlist> <para>Alternatively, you can use the - <command>rmport</command> script, from <filename - class="directory">ports/Tools/scripts</filename>. + <command>rmport</command> script, from <filename>ports/Tools/scripts</filename>. This script was written by &a.vd.email;. When sending questions about this script to the &a.ports;, please also CC &a.crees.email;, the current maintainer.</para> @@ -3618,13 +3566,12 @@ ControlPersist yes</screen> <procedure> <step> <para>Figure out when the port was removed. Use this - <ulink - url="http://people.freebsd.org/~crees/removed_ports/index.xml">list</ulink> + <link xlink:href="http://people.freebsd.org/~crees/removed_ports/index.xml">list</link> and then copy the last living revision of the port: - <screen>&prompt.user; <userinput>cd /usr/ports/<replaceable>category - </replaceable></userinput> -&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/<replaceable>category</replaceable>/<replaceable>portname</replaceable>/@{<replaceable>YYYY-MM-DD</replaceable>}' <replaceable>portname</replaceable> + <screen>&prompt.user; <userinput>cd /usr/ports/category + </userinput> +&prompt.user; <userinput>svn cp 'svn+ssh://svn.freebsd.org/ports/category/portname/@{YYYY-MM-DD}' portname </userinput></screen> Pick a date that is before the removal but after the @@ -3646,7 +3593,7 @@ ControlPersist yes</screen> </step> <step> - <para>Restore the <makevar>SUBDIR</makevar> listing of + <para>Restore the <varname>SUBDIR</varname> listing of the port in the parent directory <filename>Makefile</filename>, and delete the entry from <filename>ports/MOVED</filename>.</para> @@ -3729,11 +3676,11 @@ ControlPersist yes</screen> <step> <para>Upgrade the copied port to the new version. Remember to change the - <makevar>LATEST_LINK</makevar> so there are no + <varname>LATEST_LINK</varname> so there are no duplicate ports with the same name. In some rare cases it may be necessary to change the - <makevar>PORTNAME</makevar> instead of - <makevar>LATEST_LINK</makevar>, but this should + <varname>PORTNAME</varname> instead of + <varname>LATEST_LINK</varname>, but this should only be done when it is really needed — e.g., using an existing port as the base for a very similar program with a different name, or @@ -3742,13 +3689,13 @@ ControlPersist yes</screen> transition from <filename>textproc/libxml</filename> to <filename>textproc/libxml2</filename>. In most - cases, changing <makevar>LATEST_LINK</makevar> + cases, changing <varname>LATEST_LINK</varname> should suffice.</para> </step> <step> <para>Add the new subdirectory to the - <makevar>SUBDIR</makevar> listing in the parent + <varname>SUBDIR</varname> listing in the parent directory <filename>Makefile</filename>. You can run <command>make checksubdirs</command> in the parent directory to check this.</para> @@ -3756,7 +3703,7 @@ ControlPersist yes</screen> <step> <para>If the port changed categories, modify the - <makevar>CATEGORIES</makevar> line of the port's + <varname>CATEGORIES</varname> line of the port's <filename>Makefile</filename> accordingly</para> </step> @@ -3792,7 +3739,7 @@ ControlPersist yes</screen> <step> <para>Remove the old port and the - old <makevar>SUBDIR</makevar> entry.</para> + old <varname>SUBDIR</varname> entry.</para> </step> <step> @@ -3839,8 +3786,8 @@ ControlPersist yes</screen> <para>For more information on the background and policies surrounding a ports freeze, see the - <ulink url="&url.base;/portmgr/qa.html">Portmgr - Quality Assurance page</ulink>.</para> + <link xlink:href="&url.base;/portmgr/qa.html">Portmgr + Quality Assurance page</link>.</para> </answer> </qandaentry> @@ -3859,9 +3806,8 @@ ControlPersist yes</screen> <quote>sweeping changes</quote> are prohibited unless specifically permitted by portmgr. Complete details about what qualifies as a sweeping change can be found - on the <ulink - url="&url.base;/portmgr/implementation.html">Portmgr - Implementation page</ulink>.</para> + on the <link xlink:href="&url.base;/portmgr/implementation.html">Portmgr + Implementation page</link>.</para> <para>The benefit of a slush as opposed to a complete freeze is that it allows maintainers to continue adding @@ -3899,9 +3845,8 @@ ControlPersist yes</screen> saying, <quote>Go ahead and commit it.</quote></para> <para>Not everything is allowed to be committed during - a freeze. Please see the <ulink - url="&url.base;/portmgr/qa.html">Portmgr Quality - Assurance page</ulink> for more information.</para> + a freeze. Please see the <link xlink:href="&url.base;/portmgr/qa.html">Portmgr Quality + Assurance page</link> for more information.</para> <para>Note that you do not have implicit permission to fix a port during the freeze just because it is @@ -3964,9 +3909,8 @@ ControlPersist yes</screen> </question> <answer> - <para>Please see <ulink - url="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES"> - Proposing a New Category</ulink> in the Porter's + <para>Please see <link xlink:href="&url.books.porters-handbook;/makefile-categories.html#PROPOSING-CATEGORIES"> + Proposing a New Category</link> in the Porter's Handbook. Once that procedure has been followed and the PR has been assigned to &a.portmgr;, it is their decision whether or not to approve it. If they do, it @@ -3979,7 +3923,7 @@ ControlPersist yes</screen> </step> <step> - <para>Update the <makevar>VALID_CATEGORIES</makevar> + <para>Update the <varname>VALID_CATEGORIES</varname> definition in <filename>ports/Mk/bsd.port.mk</filename>.</para> </step> @@ -4009,11 +3953,11 @@ ControlPersist yes</screen> <procedure> <step> <para>Change the port's - <makevar>CATEGORIES</makevar> (this was the + <varname>CATEGORIES</varname> (this was the point of the exercise, remember?) The new category should be listed <emphasis>first</emphasis>. This will help to - ensure that the <makevar>PKGORIGIN</makevar> is + ensure that the <varname>PKGORIGIN</varname> is correct.</para> </step> @@ -4037,10 +3981,10 @@ ControlPersist yes</screen> </step> <step> - <para>Check that the <makevar>PKGORIGIN</makevar>s are + <para>Check that the <varname>PKGORIGIN</varname>s are correct. The ports system uses each port's - <makevar>CATEGORIES</makevar> entry to create its - <makevar>PKGORIGIN</makevar>, which is used to + <varname>CATEGORIES</varname> entry to create its + <varname>PKGORIGIN</varname>, which is used to connect installed packages to the port directory they were built from. If this entry is wrong, common port tools like &man.pkg.version.1; and @@ -4049,28 +3993,28 @@ ControlPersist yes</screen> <para>To do this, use the <filename>chkorigin.sh</filename> tool, as follows: <command>env - PORTSDIR=<replaceable>/path/to/ports</replaceable> + PORTSDIR=/path/to/ports sh -e - <replaceable>/path/to/ports</replaceable>/Tools/scripts/chkorigin.sh</command>. + /path/to/ports/Tools/scripts/chkorigin.sh</command>. This will check <emphasis>every</emphasis> port in the ports tree, even those not connected to the build, so you can run it directly after the move operation. Hint: do not forget to look at the - <makevar>PKGORIGIN</makevar>s of any slave ports of + <varname>PKGORIGIN</varname>s of any slave ports of the ports you just moved!</para> </step> <step> <para>On your own local system, test the proposed changes: first, comment out the - <makevar>SUBDIR</makevar> entries in the old ports' + <varname>SUBDIR</varname> entries in the old ports' categories' <filename>Makefile</filename>s; then enable building the new category in <filename>ports/Makefile</filename>. Run <command>make checksubdirs</command> in the affected category directories to check the - <makevar>SUBDIR</makevar> entries. Next, in the - <filename class="directory">ports/</filename> + <varname>SUBDIR</varname> entries. Next, in the + <filename>ports/</filename> directory, run <command>make index</command>. This can take over 40 minutes on even modern systems; however, it is a necessary step to prevent problems @@ -4096,9 +4040,8 @@ ControlPersist yes</screen> <itemizedlist> <listitem> - <para>the <ulink - url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list - of categories</ulink> in the Porter's + <para>the <link xlink:href="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list + of categories</link> in the Porter's Handbook</para> </listitem> @@ -4125,8 +4068,8 @@ ControlPersist yes</screen> </procedure> <para>It is not necessary to manually update the - <ulink url="&url.base;/ports/index.html">ports web - pages</ulink> to reflect the new category. This is + <link xlink:href="&url.base;/ports/index.html">ports web + pages</link> to reflect the new category. This is now done automatically via your change to <filename>www/en/ports/categories</filename> and the daily automated rebuild of @@ -4146,9 +4089,8 @@ ControlPersist yes</screen> <itemizedlist> <listitem> - <para>the <ulink - url="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list - of categories</ulink> in the Porter's + <para>the <link xlink:href="&url.books.porters-handbook;/makefile-categories.html#PORTING-CATEGORIES">list + of categories</link> in the Porter's Handbook</para> </listitem> @@ -4170,8 +4112,7 @@ ControlPersist yes</screen> </question> <answer> - <para>First, go check <ulink - url="http://pointyhat.FreeBSD.org/errorlogs/"></ulink>. + <para>First, go check <uri xlink:href="http://pointyhat.FreeBSD.org/errorlogs/">http://pointyhat.FreeBSD.org/errorlogs/</uri>. There you will find error logs from the latest package building runs on all supported platforms for the most recent branches.</para> @@ -4180,8 +4121,7 @@ ControlPersist yes</screen> there does not mean it is building correctly. (One of the dependencies may have failed, for instance.) The relevant directories are available on - <hostid>pointyhat</hostid> under <filename - class="directory">/a/portbuild/<arch>/<major_version></filename> + <systemitem>pointyhat</systemitem> under <filename>/a/portbuild/<arch>/<major_version></filename> so feel free to dig around. Each architecture and version has the following subdirectories:</para> @@ -4259,7 +4199,7 @@ bak/packages packages from last complete <major_version> run on <arch& </qandaset> </sect1> - <sect1 id="non-committers"> + <sect1 xml:id="non-committers"> <title>Issues Specific to Developers Who Are Not Committers</title> @@ -4280,8 +4220,7 @@ bak/packages packages from last complete <major_version> run on <arch& </listitem> <listitem> - <para><link - linkend="conventions-everyone">Conventions</link></para> + <para><link linkend="conventions-everyone">Conventions</link></para> <note> <para>You should get your mentor to add you to the @@ -4292,8 +4231,7 @@ bak/packages packages from last complete <major_version> run on <arch& </listitem> <listitem> - <para><link - linkend="developer.relations">Developer + <para><link linkend="developer.relations">Developer Relations</link></para> </listitem> @@ -4310,7 +4248,7 @@ bak/packages packages from last complete <major_version> run on <arch& </sect1> - <sect1 id="google-analytics"> + <sect1 xml:id="google-analytics"> <title>Information About &ga;</title> <para>As of December 12, 2012, &ga; was enabled on the @@ -4319,7 +4257,7 @@ bak/packages packages from last complete <major_version> run on <arch& valuable to the &os; Documentation Project, in order to identify various problems on the &os; website.</para> - <sect2 id="google-analytics-policy"> + <sect2 xml:id="google-analytics-policy"> <title>&ga; General Policy</title> <para>The &os; Project takes visitor privacy very @@ -4327,8 +4265,8 @@ bak/packages packages from last complete <major_version> run on <arch& <quote>Do Not Track</quote> header <emphasis>before</emphasis> fetching the tracking code from Google. For more information, please see the - <ulink url="http://www.FreeBSD.org/privacy.html">&os; Privacy - Policy</ulink>.</para> + <link xlink:href="http://www.FreeBSD.org/privacy.html">&os; Privacy + Policy</link>.</para> <para>&ga; access is <emphasis>not</emphasis> arbitrarily allowed — access must be requested, voted on by the @@ -4355,7 +4293,7 @@ bak/packages packages from last complete <major_version> run on <arch& rejected.</para> </sect2> - <sect2 id="google-analytics-data"> + <sect2 xml:id="google-analytics-data"> <title>Data Available Through &ga;</title> <para>A few examples of the types of &ga; data available @@ -4377,7 +4315,7 @@ bak/packages packages from last complete <major_version> run on <arch& </sect2> </sect1> - <sect1 id="perks"> + <sect1 xml:id="perks"> <title>Perks of the Job</title> <para>Unfortunately, there are not many perks involved with being @@ -4391,8 +4329,8 @@ bak/packages packages from last complete <major_version> run on <arch& <listitem> <para>&os; committers can get a free 4-CD or DVD set at - conferences from <ulink url="http://www.freebsdmall.com"> - &os; Mall, Inc.</ulink>. The sets are no longer + conferences from <link xlink:href="http://www.freebsdmall.com"> + &os; Mall, Inc.</link>. The sets are no longer available as a subscription due to the high shipment costs to countries outside the USA.</para> </listitem> @@ -4415,7 +4353,7 @@ bak/packages packages from last complete <major_version> run on <arch& </variablelist> </sect1> - <sect1 id="misc"> + <sect1 xml:id="misc"> <title>Miscellaneous Questions</title> <qandaset> @@ -4454,10 +4392,8 @@ bak/packages packages from last complete <major_version> run on <arch& <literal>ports</literal> trees. The <literal>src</literal> tree uses SVN and requires more care because of the <literal>mergeinfo</literal> - properties. See section 1.4.6 of the <ulink - url="http://wiki.freebsd.org/SubversionPrimer">Subversion - Primer</ulink> for details. Refer to <ulink - url="http://wiki.freebsd.org/SubversionPrimer/Merging">SubversionPrimer/Merging</ulink> + properties. See section 1.4.6 of the <link xlink:href="http://wiki.freebsd.org/SubversionPrimer">Subversion + Primer</link> for details. Refer to <link xlink:href="http://wiki.freebsd.org/SubversionPrimer/Merging">SubversionPrimer/Merging</link> for details on how to perform an MFC.</para> </answer> </qandaentry> @@ -4558,7 +4494,7 @@ bak/packages packages from last complete <major_version> run on <arch& <programlisting>... PR: foo/12345 -Submitted by: John Smith <John.Smith@example.com></programlisting> +Submitted by: John Smith <John.Smith@example.com></programlisting> </example> <example> @@ -4641,7 +4577,7 @@ MFC after: <replaceable>2 weeks</replaceable></programlisting> look something like</para> <programlisting>PR: foo/54321 -Submitted by: John Smith <John.Smith@example.com> +Submitted by: John Smith <John.Smith@example.com> Reviewed by: -arch Obtained from: NetBSD MFC after: 1 month</programlisting> @@ -4651,18 +4587,17 @@ MFC after: 1 month</programlisting> <qandaentry> <question> <para>How do I access - <hostid role="fqdn">people.FreeBSD.org</hostid> to put up + <systemitem class="fqdomainname">people.FreeBSD.org</systemitem> to put up personal or project information?</para> </question> <answer> - <para><hostid role="fqdn">people.FreeBSD.org</hostid> is the + <para><systemitem class="fqdomainname">people.FreeBSD.org</systemitem> is the same as - <hostid role="fqdn">freefall.FreeBSD.org</hostid>. Just + <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem>. Just create a <filename>public_html</filename> directory. Anything you place in that directory will automatically be - visible under <ulink - url="http://people.FreeBSD.org/"></ulink>.</para> + visible under <uri xlink:href="http://people.FreeBSD.org/">http://people.FreeBSD.org/</uri>.</para> </answer> </qandaentry> @@ -4687,9 +4622,8 @@ MFC after: 1 month</programlisting> </question> <answer> - <para>See the <ulink - url="http://www.freebsd.org/internal/new-account.html">New - Account Creation Procedure</ulink> document on the + <para>See the <link xlink:href="http://www.freebsd.org/internal/new-account.html">New + Account Creation Procedure</link> document on the internal pages.</para> </answer> </qandaentry> diff --git a/en_US.ISO8859-1/articles/compiz-fusion/article.xml b/en_US.ISO8859-1/articles/compiz-fusion/article.xml index 951829cb0a..9634942140 100644 --- a/en_US.ISO8859-1/articles/compiz-fusion/article.xml +++ b/en_US.ISO8859-1/articles/compiz-fusion/article.xml @@ -1,18 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Installing and using Compiz Fusion</title> + -<article lang="en"> - <articleinfo> - <title>Installing and using Compiz Fusion</title> - - <author> - <firstname>Manolis</firstname> - <surname>Kiagias</surname> - <affiliation> + <author><personname><firstname>Manolis</firstname><surname>Kiagias</surname></personname><affiliation> <address><email>manolis@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2008</year> @@ -23,7 +18,7 @@ <releaseinfo>$FreeBSD$</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -33,19 +28,18 @@ the latest fashion: 3D Desktop effects. While their usefulness is rather heavily debated, the wow factor behind the composited desktop holds quite well. Several different programs have emerged, like - <ulink url="http://compiz.org/"><application>Compiz</application></ulink>, - <ulink url="http://www.beryl-project.org/"><application>Beryl</application></ulink>, - and the latest <ulink - url="http://www.compiz-fusion.org/"><application>Compiz Fusion</application></ulink>. + <link xlink:href="http://compiz.org/"><application>Compiz</application></link>, + <link xlink:href="http://www.beryl-project.org/"><application>Beryl</application></link>, + and the latest <link xlink:href="http://www.compiz-fusion.org/"><application>Compiz Fusion</application></link>. You do not need to miss these effects when using &os;. These instructions will help you install and configure your system for the latest 3D desktop experience using <application>Compiz Fusion</application> and nVidia drivers (if applicable).</para> </abstract> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>While installing <application>Compiz Fusion</application> from @@ -82,7 +76,7 @@ </itemizedlist> </sect1> - <sect1 id="nvidia-setup"> + <sect1 xml:id="nvidia-setup"> <title>Setting up the &os; nVidia driver</title> <para>Desktop effects can cause quite a load on your graphics card. @@ -92,7 +86,7 @@ desktop effects, you may skip this section and continue with the <filename>xorg.conf</filename> configuration.</para> - <sect2 id="determine-driver"> + <sect2 xml:id="determine-driver"> <title>Determining the correct driver to use</title> <para>There are various versions of the nVidia drivers in the @@ -102,13 +96,13 @@ <itemizedlist> <listitem> <para>The latest versions of nVidia cards are supported by the - <filename role="package">x11/nvidia-driver</filename> port.</para> + <package>x11/nvidia-driver</package> port.</para> </listitem> <listitem> <para>nVidia cards like the GeForce 2MX/3/4 series are supported by the 96<replaceable>XX</replaceable> series of drivers, available - in the <filename role="package">x11/nvidia-driver-96xx</filename> + in the <package>x11/nvidia-driver-96xx</package> port.</para> </listitem> @@ -116,18 +110,17 @@ <para>Even older cards, like GeForce and RIVA TNT are supported by the 71<replaceable>XX</replaceable> series of drivers, available in the - <filename role="package">x11/nvidia-driver-71xx</filename> + <package>x11/nvidia-driver-71xx</package> port.</para> </listitem> </itemizedlist> <para>In fact, nVidia provides detailed information on which card is supported by which driver. This information is available directly - on their web site: <ulink - url="http://www.nvidia.com/object/IO_32667.html"></ulink>.</para> + on their web site: <uri xlink:href="http://www.nvidia.com/object/IO_32667.html">http://www.nvidia.com/object/IO_32667.html</uri>.</para> </sect2> - <sect2 id="install-driver"> + <sect2 xml:id="install-driver"> <title>Installing the nVidia driver</title> <para>Having determined the correct driver to use for your card, @@ -184,8 +177,8 @@ <note> <para>Although not strictly necessary, you may also wish to install - <filename role="package">x11/nvidia-xconfig</filename> and - <filename role="package">x11/nvidia-settings</filename> ports. The + <package>x11/nvidia-xconfig</package> and + <package>x11/nvidia-settings</package> ports. The former can assist you in writing settings to <filename>/etc/X11/xorg.conf</filename> from the command line, and the latter will allow you to modify screen settings from a GUI while @@ -194,7 +187,7 @@ </sect2> </sect1> - <sect1 id="xorg-configuration"> + <sect1 xml:id="xorg-configuration"> <title>Configuring xorg.conf for desktop effects</title> <para>Before you install and run @@ -253,7 +246,7 @@ Load "glx" <note> <para>If you installed the - <filename role="package">x11/nvidia-xconfig</filename> port, + <package>x11/nvidia-xconfig</package> port, you should be able to perform most of the above settings by entering the following commands (as root):</para> @@ -266,7 +259,7 @@ Load "glx" </note> </sect1> - <sect1 id="compiz-fusion"> + <sect1 xml:id="compiz-fusion"> <title>Installing and configuring Compiz Fusion</title> <para>Installing <application>Compiz Fusion</application> @@ -340,7 +333,7 @@ emerald --replace &</programlisting> </para> </sect1> - <sect1 id="compiz-troubleshooting"> + <sect1 xml:id="compiz-troubleshooting"> <title>Troubleshooting Compiz Fusion</title> <para>The following section covers frequently asked questions regarding @@ -349,7 +342,7 @@ emerald --replace &</programlisting> <qandaset> <qandaentry> - <question id="no-decorations"> + <question xml:id="no-decorations"> <para>I have installed <application>Compiz Fusion</application>, and after running the commands you mention, my windows are left @@ -365,7 +358,7 @@ emerald --replace &</programlisting> </qandaentry> <qandaentry> - <question id="xorg-crash"> + <question xml:id="xorg-crash"> <para>When I run the command to start <application>Compiz Fusion</application>, the X server crashes and I am back at the console. What is wrong?</para> @@ -384,7 +377,7 @@ emerald --replace &</programlisting> <para>This is usually the case when you upgrade <application>&xorg;</application>. You will need to reinstall the - <filename role="package">x11/nvidia-driver</filename> port so + <package>x11/nvidia-driver</package> port so glx is built again.</para> </answer> </qandaentry> diff --git a/en_US.ISO8859-1/articles/console-server/article.xml b/en_US.ISO8859-1/articles/console-server/article.xml index 1360b58373..49763be90c 100644 --- a/en_US.ISO8859-1/articles/console-server/article.xml +++ b/en_US.ISO8859-1/articles/console-server/article.xml @@ -1,21 +1,15 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Console Server</title> + -<article lang='en'> - <articleinfo> - <title>Console Server</title> - - <author> - <firstname>Gregory</firstname> - <surname>Bond</surname> - - <affiliation> + <author><personname><firstname>Gregory</firstname><surname>Bond</surname></personname><affiliation> <address><email>gnb@itga.com.au</email></address> - </affiliation> - </author> + </affiliation></author> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.cisco; &tm-attrib.intel; @@ -36,11 +30,11 @@ a machine that you can use to monitor the consoles of many other machines, instead of a bunch of serial terminals.</para> </abstract> - </articleinfo> + </info> <indexterm><primary>console-server</primary></indexterm> - <sect1 id="problem"> + <sect1 xml:id="problem"> <title>The Problem</title> <para>You have a computer room with lots of &unix; server machines and lots @@ -103,7 +97,7 @@ </itemizedlist> </sect1> - <sect1 id="possible-solutions"> + <sect1 xml:id="possible-solutions"> <title>Possible Solutions</title> <para>If you use PC hardware for your servers, then a so-called <quote><acronym>KVM</acronym> @@ -122,7 +116,7 @@ <para>Actually, Doug Schache has pointed out that you <emphasis>can</emphasis> get <acronym>KVM</acronym> switches that also do serial consoles or Sun compatible <acronym>KVM</acronym> switching as well as PCs, but they are - expensive. See <ulink url="http://www.avocent.com/">Avocent</ulink> + expensive. See <link xlink:href="http://www.avocent.com/">Avocent</link> for example.)</para> </note> @@ -179,15 +173,15 @@ <para>Or, if your budget exceeds your willingness to hack, you can buy an off-the-shelf solution. These vary in price and capability. See, for example, - <ulink url="http://www.lightwavecom.com/">Lightwave</ulink>, - <ulink url="http://www.perle.com/">Perle</ulink>, - <ulink url="http://www.avocent.com/">Avocent</ulink> or - <ulink url="http://www.blackbox.com/faxbacks/23000/23362.PDF">Black Box</ulink>. + <link xlink:href="http://www.lightwavecom.com/">Lightwave</link>, + <link xlink:href="http://www.perle.com/">Perle</link>, + <link xlink:href="http://www.avocent.com/">Avocent</link> or + <link xlink:href="http://www.blackbox.com/faxbacks/23000/23362.PDF">Black Box</link>. These solutions can be quite expensive - typically $USD100 - $USD400 per port.</para> </sect1> - <sect1 id="our-solution"> + <sect1 xml:id="our-solution"> <title>Our Solution</title> <para>In light of the above requirements, we chose a solution based on a @@ -204,18 +198,16 @@ </listitem> <listitem> - <para>A PC &unix; system. We used <ulink - url="&url.base;/index.html">&os; 4.3</ulink> as that is used for + <para>A PC &unix; system. We used <link xlink:href="&url.base;/index.html">&os; 4.3</link> as that is used for other tasks within our office.</para> </listitem> <listitem> - <para>A multi-port serial card. We chose the <ulink - url="http://www.stallion.com/html/products/easyio.html">&easyio; PCI</ulink> - 8-port card from <ulink url="http://www.stallion.com/">Stallion - Technologies</ulink>. This cost us about $AUD740, or under - $100/port, from <ulink url="http://www.ht.com.au/">Harris - Technologies</ulink> (which has lots of stuff but is by no means the + <para>A multi-port serial card. We chose the <link xlink:href="http://www.stallion.com/html/products/easyio.html">&easyio; PCI</link> + 8-port card from <link xlink:href="http://www.stallion.com/">Stallion + Technologies</link>. This cost us about $AUD740, or under + $100/port, from <link xlink:href="http://www.ht.com.au/">Harris + Technologies</link> (which has lots of stuff but is by no means the cheapest place in town - shop around and you might get it a lot cheaper). This card has a big DB80 connector on the back, and a cable plugs into that which has a block with 8 RJ-45 sockets on it. @@ -246,8 +238,7 @@ </listitem> <listitem> - <para>A program called <ulink - url="http://www.conserver.com/">conserver</ulink>. This program + <para>A program called <link xlink:href="http://www.conserver.com/">conserver</link>. This program does all the magic required to enable remote access to consoles, and do the replaying and logging etc. It comes in two parts: a server called <application>conserver</application> that runs as a daemon @@ -313,35 +304,33 @@ </itemizedlist> </sect1> - <sect1 id="setting-up-server"> + <sect1 xml:id="setting-up-server"> <title>Setting Up The Server</title> - <sect2 id="patching-stallion"> + <sect2 xml:id="patching-stallion"> <title>Checking the Stallion driver</title> <para>&os; has adequate support for modern Stallion cards since 4.4 release. If you are running an older version of &os;, you will need to upgrade to a more modern version of &os; (which you should do anyway, to make sure your system is not - vulnerable to known security issues). See the <ulink - url="&url.books.handbook;/makeworld.html">&os; - Handbook</ulink> for information about updating your + vulnerable to known security issues). See the <link xlink:href="&url.books.handbook;/makeworld.html">&os; + Handbook</link> for information about updating your system.</para> </sect2> - <sect2 id="configuring-kernel"> + <sect2 xml:id="configuring-kernel"> <title>Configuring a new kernel</title> <para>The Stallion driver is not included in the default <literal>GENERIC</literal> kernel, so you will need to create a kernel config file with the appropriate entries. See &man.stl.4; and the - appropriate section of the <ulink - url="&url.books.handbook;/kernelconfig.html">&os; - Handbook</ulink>.</para> + appropriate section of the <link xlink:href="&url.books.handbook;/kernelconfig.html">&os; + Handbook</link>.</para> </sect2> - <sect2 id="making-devices"> + <sect2 xml:id="making-devices"> <title>Making The Devices</title> <para>You will need to make the device notes for the Stallion card @@ -364,7 +353,7 @@ for more details.</para> </sect2> - <sect2 id="compiling-conserver"> + <sect2 xml:id="compiling-conserver"> <title>Compiling conserver</title> <note> @@ -378,17 +367,17 @@ You can either compile from the source or use the &os; ports framework.</para> - <sect3 id="using-ports"> + <sect3 xml:id="using-ports"> <title>Using the ports framework</title> <para>Using the ports is a bit cleaner, as the package system can then keep track of installed software and cleanly delete them when not being used. I recommend using the - <filename role="package">comms/conserver-com</filename> port. + <package>comms/conserver-com</package> port. Change into the - port directory and (as <username>root</username>) type:</para> + port directory and (as <systemitem class="username">root</systemitem>) type:</para> - <screen>&prompt.root; <userinput>make DEFAULTHOST=<replaceable>consolehost</replaceable> install</userinput></screen> + <screen>&prompt.root; <userinput>make DEFAULTHOST=consolehost install</userinput></screen> <para>where <replaceable>consolehost</replaceable> is the name of the machine running the console server. Specifying this when the binary @@ -405,7 +394,7 @@ a <literal>DEFAULTHOST</literal> argument, and one for all the other hosts with a <literal>DEFAULTHOST</literal> argument. This will mean the console client program on the console server machine will - default to <hostid>localhost</hostid>, which will work in the + default to <systemitem>localhost</systemitem>, which will work in the absence of name servers when the network is busted, and also allow <quote>trusted</quote> (i.e. no password required) connections via the localhost IP address for users logged into the console @@ -417,7 +406,7 @@ <filename>conserver.cf</filename> file on every machine.</para> </sect3> - <sect3 id="from-tarball"> + <sect3 xml:id="from-tarball"> <title>From the source tarball</title> <para>If you prefer, you can download <application>conserver</application> @@ -429,9 +418,8 @@ whom have PCs and no &os; host access on their desk) to access the console server.</para> - <para>Download the file from the <ulink - url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">conserver.com - FTP site</ulink>. Extract it into a handy directory then + <para>Download the file from the <link xlink:href="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">conserver.com + FTP site</link>. Extract it into a handy directory then configure it by running</para> <screen>&prompt.user; ./configure <option>--with-master=<replaceable>consoleserver</replaceable></option> <option>--with-port=<replaceable>782</replaceable></option></screen> @@ -447,7 +435,7 @@ </sect3> </sect2> - <sect2 id="configuring-conserver"> + <sect2 xml:id="configuring-conserver"> <title>Configuring conserver</title> <para>The <application>conserver</application> program is configured via a file called @@ -469,24 +457,24 @@ trusted: 127.0.0.1 buzz</programlisting> the <filename>/var/log/consoles</filename> directory. The <quote>&</quote> in each line says the log file for that machine will be - <filename>/var/log/consoles/<replaceable>machine</replaceable></filename>.</para> + <filename>/var/log/consoles/machine</filename>.</para> <para>The next three lines show three machines to which we need to connect. We use the - <devicename>cuaE<replaceable>x</replaceable></devicename> devices + <filename>cuaEx</filename> devices rather than the - <devicename>ttyE<replaceable>x</replaceable></devicename> + <filename>ttyEx</filename> devices because console ports typically do not show carrier. This means that opening - <devicename>ttyE<replaceable>x</replaceable></devicename> would hang + <filename>ttyEx</filename> would hang and <application>conserver</application> would never connect. Using the - <devicename>cuaE<replaceable>x</replaceable></devicename> + <filename>cuaEx</filename> device avoids this problem. Another solution would be to use the - <devicename>ttyE<replaceable>x</replaceable></devicename> + <filename>ttyEx</filename> devices and enable <quote>soft carrier</quote> on these ports, perhaps by setting this using the - <devicename>ttyiE<replaceable>x</replaceable></devicename> + <filename>ttyiEx</filename> device in the <filename>/etc/rc.serial</filename> file. See the comments in this file for more details. Also see &man.sio.4; for information on the initial-state and locked-state devices. (The @@ -504,7 +492,7 @@ trusted: 127.0.0.1 buzz</programlisting> section).</para> </sect2> - <sect2 id="setting-passwords"> + <sect2 xml:id="setting-passwords"> <title>Setting conserver passwords</title> <para>The <filename>conserver.passwd</filename> file contains the @@ -528,7 +516,7 @@ $salt = '$1$' . $salt . '$'; print 'Enter password: '; `stty -echo`; -$cleartext = <>; +$cleartext = <>; `stty echo`; chop($cleartext); print crypt($cleartext, $salt), "\n";</programlisting> @@ -547,7 +535,7 @@ Password: <userinput>password</userinput> $1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/</screen> </sect2> - <sect2 id="starting-conserver"> + <sect2 xml:id="starting-conserver"> <title>Starting <application>conserver</application> at system boot time</title> <para>There are two ways this can be done. Firstly, you could start up @@ -563,7 +551,7 @@ $1$VTd27V2G$eFu23iHpLvCBM5nQtNlKj/</screen> crashes so far), and it arranges for standard output of the <application>conserver</application> process to be directed to the named tty (in this case - <devicename>cuaE0</devicename>). This is useful because you + <filename>cuaE0</filename>). This is useful because you can plug a terminal into this port, and the <application>conserver</application> program will show all console output not otherwise captured by a @@ -600,8 +588,8 @@ PATH=/usr/bin:/usr/local/bin case "$1" in 'start') TTY=/dev/cuaE7 - conserver -d > $TTY - # get NL->CR+NL mapping so msgs look right + conserver -d > $TTY + # get NL->CR+NL mapping so msgs look right stty < /dev/cuaE7 opost onlcr echo -n ' conserver' ;; @@ -618,13 +606,13 @@ esac exit 0</programlisting> <note> - <para>Note the use of <devicename>cuaE0</devicename> device + <para>Note the use of <filename>cuaE0</filename> device and the need to set tty modes for proper NL-<CR handling).</para> </note> </sect2> - <sect2 id="trimming-logs"> + <sect2 xml:id="trimming-logs"> <title>Keeping the log files trimmed</title> <para>&os; has a program called @@ -650,7 +638,7 @@ exit 0</programlisting> </sect2> </sect1> - <sect1 id="cabling"> + <sect1 xml:id="cabling"> <title>Cabling</title> <para>This is always the hardest part of this kind of problem. We had @@ -677,7 +665,7 @@ exit 0</programlisting> represent serial connections on the RJ-45 plug. So the cabling has to be very careful to use the right mapping.</para> - <sect2 id="rj45-colors"> + <sect2 xml:id="rj45-colors"> <title>RJ-45 colors</title> <para>RJ-45 cables and plugs have 8 pins/conductors. These are used as @@ -770,9 +758,8 @@ exit 0</programlisting> <para>Note EIA 468A and EIA 568B are very similar, simply swapping the colors assigned to pair 2 and pair 3.</para> - <para>See for example the <ulink - url="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron - Tech Support Site</ulink> for more details.</para> + <para>See for example the <link xlink:href="http://www.cabletron.com/support/techtips/tk0231-9.html">Cabletron + Tech Support Site</link> for more details.</para> <para>The pins in the RJ-45 plug are numbered from 1 to 8. Holding a patch lead with the cable pointing down and the clip away from you, @@ -813,14 +800,12 @@ exit 0</programlisting> into the DB-25 plug as required. This allows us to create a custom RJ-45-DB-25 mapping. We used a couple of different sorts, including the - <ulink url="http://www.molexpn.com.au/">MOD-TAP</ulink> - part no. <ulink - url="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00</ulink> - and the <ulink - url="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730 - series</ulink> from - <ulink url="http://www.blackboxoz.com.au/">Black - Box</ulink>.</para> + <link xlink:href="http://www.molexpn.com.au/">MOD-TAP</link> + part no. <link xlink:href="http://www.molexpn.com.au/products/index.nsx/1/7/0/0/id=340">06-9888-999-00</link> + and the <link xlink:href="http://www.blackbox.com/faxbacks/12000/12654.PDF">FA730 + series</link> from + <link xlink:href="http://www.blackboxoz.com.au/">Black + Box</link>.</para> <para>On our version of the headshells, these flyleads had the following colours (from Pin 1-8): Blue, Orange, Black, Red, @@ -1106,8 +1091,8 @@ exit 0</programlisting> <para>We run &os; 4 on a couple of &i386; PCs for various peripheral uses. &os; usually uses a screen and keyboard for the console, but can be configured to use a serial port (usually the - first serial port known as <devicename>COM1</devicename> in DOS/&windows; or - <devicename>ttyd0</devicename> in &unix;).</para> + first serial port known as <filename>COM1</filename> in DOS/&windows; or + <filename>ttyd0</filename> in &unix;).</para> <para>The cabling for these servers depends on the PC hardware. If the PC has DB-25 female socket on board (as most older PCs do), @@ -1209,7 +1194,7 @@ exit 0</programlisting> </sect2> </sect1> - <sect1 id="solaris"> + <sect1 xml:id="solaris"> <title>On Sun Systems And Break</title> <para>Anyone who has turned off a terminal used as a console for a Sun @@ -1267,27 +1252,27 @@ exit 0</programlisting> power-on or reboot.</para> </sect1> - <sect1 id="freebsd"> + <sect1 xml:id="freebsd"> <title>Using a Serial Console on &os;</title> <para>The procedure for doing this is described in detail in the - <ulink url="&url.books.handbook;/serialconsole-setup.html">&os; - Handbook</ulink>. This is a quick summary.</para> + <link xlink:href="&url.books.handbook;/serialconsole-setup.html">&os; + Handbook</link>. This is a quick summary.</para> - <sect2 id="freebsd-kernconf"> + <sect2 xml:id="freebsd-kernconf"> <title>Check the kernel configuration</title> <para>Check that the kernel configuration file has <literal>flags 0x10</literal> in the config line for the - <devicename>sio0</devicename> device. This signals this device (known - as <devicename>COM1</devicename> in DOS/&windows; or - <devicename>/dev/ttyd0</devicename> in &os;) can be used as a + <filename>sio0</filename> device. This signals this device (known + as <filename>COM1</filename> in DOS/&windows; or + <filename>/dev/ttyd0</filename> in &os;) can be used as a console. This flag is set on the <filename>GENERIC</filename> and <filename>LINT</filename> sample configs, so is likely to be set in your kernel.</para> </sect2> - <sect2 id="freebsd-bootconf"> + <sect2 xml:id="freebsd-bootconf"> <title>Create the <filename>/boot.conf</filename> file</title> @@ -1296,14 +1281,14 @@ exit 0</programlisting> tells the &os; boot blocks to use the serial console.</para> </sect2> - <sect2 id="freebsd-ttys"> + <sect2 xml:id="freebsd-ttys"> <title>Edit <filename>/etc/ttys</filename></title> <para>Edit this file and make the following changes.</para> <para>If you are not going to have any keyboard/video screen on this server at all, you should find all the lines for - <devicename>ttyv</devicename> devices like</para> + <filename>ttyv</filename> devices like</para> <programlisting>ttyv1 "/usr/libexec/getty Pc" cons25 on secure</programlisting> @@ -1311,7 +1296,7 @@ exit 0</programlisting> will stop login screens being run on the useless video consoles.</para> - <para>Find the line containing <devicename>ttyd0</devicename>. Change + <para>Find the line containing <filename>ttyd0</filename>. Change it from</para> <programlisting>ttyd0 "/usr/libexec/getty std.9600" dialup off secure</programlisting> @@ -1329,7 +1314,7 @@ exit 0</programlisting> </sect2> </sect1> - <sect1 id="security"> + <sect1 xml:id="security"> <title>Security Implications</title> <para>The client-server protocol for <application>conserver</application> @@ -1347,7 +1332,7 @@ exit 0</programlisting> server machine, and run the console client there.</para> </sect1> - <sect1 id="conserver-versions"> + <sect1 xml:id="conserver-versions"> <title>On Conserver Versions</title> <para>The <application>conserver</application> program has fractured into @@ -1359,7 +1344,7 @@ exit 0</programlisting> <para>The &os; ports collection contains a port for version 8.5 of <application>conserver</application> at - <filename role="package">comms/conserver</filename>. + <package>comms/conserver</package>. This seems to be older and less featureful than the 8.1.9 version (in particular, it does not support consoles connected to terminal server ports and does not support a @@ -1375,18 +1360,18 @@ exit 0</programlisting> <para>Beginning with December 2001, Brian's version (currently 8.1.9) is also presented in ports collection at - <filename role="package">comms/conserver-com</filename>. We therefore + <package>comms/conserver-com</package>. We therefore recommend you to use this version as it is much more appropriate for console server building.</para> </sect1> - <sect1 id="links"> + <sect1 xml:id="links"> <title>Links</title> <variablelist> <varlistentry> - <term><ulink url="http://www.conserver.com/"></ulink></term> + <term><uri xlink:href="http://www.conserver.com/">http://www.conserver.com/</uri></term> <listitem> <para>Homepage for the latest version of <application>conserver</application>.</para> @@ -1394,7 +1379,7 @@ exit 0</programlisting> </varlistentry> <varlistentry> - <term><ulink url="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz</ulink></term> + <term><link xlink:href="ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz">ftp://ftp.conserver.com/conserver/conserver-8.1.9.tar.gz</link></term> <listitem> <para>The source tarball for version 8.1.9 of @@ -1403,7 +1388,7 @@ exit 0</programlisting> </varlistentry> <varlistentry> - <term><ulink url="http://www.stallion.com/"></ulink></term> + <term><uri xlink:href="http://www.stallion.com/">http://www.stallion.com/</uri></term> <listitem> <para>Homepage of Stallion Technologies.</para> @@ -1411,7 +1396,7 @@ exit 0</programlisting> </varlistentry> <varlistentry> - <term><ulink url="http://www.conserver.com/consoles/msock.html"></ulink></term> + <term><uri xlink:href="http://www.conserver.com/consoles/msock.html">http://www.conserver.com/consoles/msock.html</uri></term> <listitem> <para>Davis Harris' <quote>Minor Scroll of Console Knowledge</quote> @@ -1421,7 +1406,7 @@ exit 0</programlisting> </varlistentry> <varlistentry> - <term><ulink url="http://www.conserver.com/consoles/"></ulink></term> + <term><uri xlink:href="http://www.conserver.com/consoles/">http://www.conserver.com/consoles/</uri></term> <listitem> <para>The <quote>Greater Scroll of Console Knowledge</quote> @@ -1431,7 +1416,7 @@ exit 0</programlisting> </varlistentry> <varlistentry> - <term><ulink url="http://www.eng.auburn.edu/users/doug/console.html"></ulink></term> + <term><uri xlink:href="http://www.eng.auburn.edu/users/doug/console.html">http://www.eng.auburn.edu/users/doug/console.html</uri></term> <listitem> <para>Doug Hughes has a similar console server, based on the @@ -1440,7 +1425,7 @@ exit 0</programlisting> </varlistentry> <varlistentry> - <term><ulink url="http://www.realweasel.com/"></ulink></term> + <term><uri xlink:href="http://www.realweasel.com/">http://www.realweasel.com/</uri></term> <listitem> <para>The Real Weasel company makes a ISA or PCI video card that @@ -1455,22 +1440,24 @@ exit 0</programlisting> </variablelist> </sect1> - <sect1 id="manpages"> + <sect1 xml:id="manpages"> <title>Manual Pages</title> <itemizedlist> <listitem> - <para><ulink url="http://www.conserver.com/docs/console.man.html">console(8)</ulink></para> + <para><link xlink:href="http://www.conserver.com/docs/console.man.html">console(8)</link></para> </listitem> <listitem> - <para><ulink url="http://www.conserver.com/docs/conserver.man.html">conserver(8)</ulink></para> + <para><link xlink:href="http://www.conserver.com/docs/conserver.man.html">conserver(8)</link></para> </listitem> <listitem> - <para><ulink url="http://www.conserver.com/docs/conserver.cf.man.html">conserver.cf(5)</ulink></para> + <para><link xlink:href="http://www.conserver.com/docs/conserver.cf.man.html">conserver.cf(5)</link></para> </listitem> </itemizedlist> </sect1> + <index/> + </article> diff --git a/en_US.ISO8859-1/articles/contributing-ports/article.xml b/en_US.ISO8859-1/articles/contributing-ports/article.xml index f9778f0e7d..6bee0dfecd 100644 --- a/en_US.ISO8859-1/articles/contributing-ports/article.xml +++ b/en_US.ISO8859-1/articles/contributing-ports/article.xml @@ -1,10 +1,9 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Contributing to the FreeBSD Ports Collection</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Contributing to the FreeBSD Ports Collection</title> + <abstract> <title>Abstract</title> @@ -14,17 +13,11 @@ </abstract> <authorgroup> - <author> - <firstname>Sam</firstname> - <surname>Lawrance</surname> - </author> - <author> - <firstname>Mark</firstname> - <surname>Linimon</surname> - </author> + <author><personname><firstname>Sam</firstname><surname>Lawrance</surname></personname></author> + <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -32,7 +25,7 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> <indexterm><primary>contributing to ports</primary></indexterm> @@ -57,7 +50,7 @@ to take this into account before deciding to volunteer.</para> </sect1> - <sect1 id="what-contribute"> + <sect1 xml:id="what-contribute"> <title>What you can do to help</title> <para>There are a number of easy ways you can contribute to @@ -91,18 +84,17 @@ </itemizedlist> </sect1> - <sect1 id="create-port"> + <sect1 xml:id="create-port"> <title>Creating a new port</title> <para>There is a separate document available to help guide you - through creating (and upgrading) a port called the <ulink - url="&url.books.porters-handbook;">Porter's Handbook</ulink>. + through creating (and upgrading) a port called the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link>. The Porter's Handbook is the best reference to working with the ports system. It provides details about how the ports system operates and discusses recommended practices.</para> </sect1> - <sect1 id="adopt-port"> + <sect1 xml:id="adopt-port"> <title>Adopting an unmaintained port</title> <sect2> @@ -116,12 +108,11 @@ you use regularly.</para> <para>Unmaintained ports have their - <makevar>MAINTAINER</makevar> set to + <varname>MAINTAINER</varname> set to <literal>ports@FreeBSD.org</literal>. A list of unmaintained ports and their current errors and problem reports can be seen - at the <ulink - url="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os; - Ports Monitoring System</ulink>.</para> + at the <link xlink:href="http://portsmon.FreeBSD.org/portsconcordanceformaintainer.py?maintainer=ports%40FreeBSD.org">&os; + Ports Monitoring System</link>.</para> <para>Some ports affect a large number of others due to dependencies and slave port relationships. Generally, we @@ -145,13 +136,13 @@ <para>First make sure you understand your <link linkend="maintain-port">responsibilities as a maintainer</link>. Also read the - <ulink url="&url.books.porters-handbook;">Porter's - Handbook</ulink>. <emphasis>Please do not commit yourself + <link xlink:href="&url.books.porters-handbook;">Porter's + Handbook</link>. <emphasis>Please do not commit yourself to more than you feel you can comfortably handle.</emphasis></para> <para>You may request maintainership of any unmaintained port - as soon as you wish. Simply set <makevar>MAINTAINER</makevar> + as soon as you wish. Simply set <varname>MAINTAINER</varname> to your own email address and send a PR (Problem Report) with the change. If the port has build errors or needs updating, you may wish to include any other changes in the same PR. @@ -168,14 +159,14 @@ </sect2> </sect1> - <sect1 id="maintain-port"> + <sect1 xml:id="maintain-port"> <title>The challenge for port maintainers</title> <para>This section will give you an idea of why ports need to be maintained and outline the responsibilities of a port maintainer.</para> - <sect2 id="why-maintenance"> + <sect2 xml:id="why-maintenance"> <title>Why ports require maintenance</title> <para>Creating a port is a once-off task. Ensuring that a @@ -284,8 +275,8 @@ <para>This is an overview. More information about upgrading a port is available in the - <ulink url="&url.books.porters-handbook;"> - Porter's Handbook</ulink>.</para> + <link xlink:href="&url.books.porters-handbook;"> + Porter's Handbook</link>.</para> <procedure> <step> @@ -345,8 +336,7 @@ <listitem> <para>Verify your port using &man.portlint.1; as a - guide. See <link - linkend="resources">resources</link> for important + guide. See <link linkend="resources">resources</link> for important information about using <application>portlint</application>.</para> </listitem> @@ -358,7 +348,7 @@ those ports. This is especially important if your update changes the shared library version; in this case, at the very least, the dependent ports will - need to get a <makevar>PORTREVISION</makevar> bump + need to get a <varname>PORTREVISION</varname> bump so that they will automatically be upgraded by automated tools such as <application>portmaster</application> or @@ -373,9 +363,8 @@ <para>Send your update by submitting a PR with an explanation of the changes and a patch containing the differences between the original port and the updated - one. Please refer to <ulink - url="&url.articles.problem-reports;">Writing FreeBSD - Problem Reports</ulink> for information on how to + one. Please refer to <link xlink:href="&url.articles.problem-reports;">Writing FreeBSD + Problem Reports</link> for information on how to write a really good PR.</para> <note> @@ -383,8 +372,7 @@ entire port; instead, use &man.diff.1; <literal>-ruN</literal>. In this way, committers can much more easily see exactly what changes are being - made. The Porter's Handbook section on <ulink - url="&url.books.porters-handbook;/port-upgrading.html">Upgrading</ulink> + made. The Porter's Handbook section on <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Upgrading</link> has more information.</para> </note> </step> @@ -460,12 +448,10 @@ <title>Watch for build failures</title> <para>Regularly check the automated ports building - cluster, <ulink - url="http://pointyhat.FreeBSD.org">pointyhat</ulink>, - and the <ulink url="http://portscout.FreeBSD.org">distfiles - scanner</ulink> to see if any of the ports you - maintain are failing to build or fetch (see <link - linkend="resources">resources</link> for more + cluster, <link xlink:href="http://pointyhat.FreeBSD.org">pointyhat</link>, + and the <link xlink:href="http://portscout.FreeBSD.org">distfiles + scanner</link> to see if any of the ports you + maintain are failing to build or fetch (see <link linkend="resources">resources</link> for more information about these systems). Reports of failures may also come to you from other users or automated systems via email.</para> @@ -571,9 +557,8 @@ <title>Respond to bug reports</title> <para>Bugs may be reported to you through email via the - <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - GNATS Problem Report database</ulink>. Bugs may also be + <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + GNATS Problem Report database</link>. Bugs may also be reported directly to you by users.</para> <para>You should respond to PRs and other reports within @@ -716,26 +701,24 @@ </sect2> </sect1> - <sect1 id="fix-broken"> + <sect1 xml:id="fix-broken"> <title>Finding and fixing a broken port</title> <para>There are two really good places to find a port that needs some attention.</para> - <para>You can use the <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">web - interface</ulink> to the Problem Report database to search + <para>You can use the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">web + interface</link> to the Problem Report database to search through and view unresolved PRs. The majority of ports PRs are updates, but with a little searching and skimming over synopses you should be able to find something interesting to work on (the <literal>sw-bug</literal> class is a good place to start).</para> - <para>The other place is the <ulink - url="http://portsmon.FreeBSD.org/">&os; Ports Monitoring - System</ulink>. In particular look for unmaintained ports + <para>The other place is the <link xlink:href="http://portsmon.FreeBSD.org/">&os; Ports Monitoring + System</link>. In particular look for unmaintained ports with build errors and ports that are marked - <makevar>BROKEN</makevar>. It is OK to send changes for a + <varname>BROKEN</varname>. It is OK to send changes for a maintained port as well, but remember to ask the maintainer in case they are already working on the problem.</para> @@ -745,7 +728,7 @@ and, if everything checks out, committed.</para> </sect1> - <sect1 id="mortal-coil"> + <sect1 xml:id="mortal-coil"> <title>When to call it quits</title> <para>As your interests and commitments change, you may find that @@ -766,39 +749,38 @@ have not been worked on during that time.</para> </sect1> - <sect1 id="resources"> + <sect1 xml:id="resources"> <title>Resources for ports maintainers and contributors</title> - <para>The <ulink url="&url.books.porters-handbook;">Porter's - Handbook</ulink> is your hitchhiker's guide to the ports + <para>The <link xlink:href="&url.books.porters-handbook;">Porter's + Handbook</link> is your hitchhiker's guide to the ports system. Keep it handy!</para> - <para><ulink url="&url.articles.problem-reports;">Writing FreeBSD - Problem Reports</ulink> describes how to best formulate and + <para><link xlink:href="&url.articles.problem-reports;">Writing FreeBSD + Problem Reports</link> describes how to best formulate and submit a PR. In 2005 more than eleven thousand ports PRs were submitted! Following this article will greatly assist us in reducing the time needed to handle your PRs.</para> - <para>The <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - Problem Report database</ulink>.</para> + <para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + Problem Report database</link>.</para> - <para><ulink url="http://pointyhat.FreeBSD.org/">Pointyhat</ulink> + <para><link xlink:href="http://pointyhat.FreeBSD.org/">Pointyhat</link> is the ports build cluster. You can use Pointyhat to check port build logs across all architectures and major releases.</para> - <para>The <ulink url="http://portsmon.FreeBSD.org/">FreeBSD Ports - Monitoring System</ulink> can show you cross-referenced + <para>The <link xlink:href="http://portsmon.FreeBSD.org/">FreeBSD Ports + Monitoring System</link> can show you cross-referenced information about ports such as build errors and problem reports. If you are a maintainer you can use it to check on the build status of your ports. As a contributor you can use it to find broken and unmaintained ports that need to be fixed.</para> - <para>The <ulink url="http://portscout.FreeBSD.org">FreeBSD Ports - distfile scanner</ulink> can show you ports for which the + <para>The <link xlink:href="http://portscout.FreeBSD.org">FreeBSD Ports + distfile scanner</link> can show you ports for which the distfiles are not fetchable. You can check on your own ports or use it to find ports that need their - <makevar>MASTER_SITES</makevar> updated.</para> + <varname>MASTER_SITES</varname> updated.</para> <para>The ports <application>tinderbox</application> is the most thorough way to test a port through the entire cycle of @@ -806,9 +788,8 @@ command-line interface but also can be controlled via a web interface. Please see <filename>ports/ports-mgmt/tinderbox</filename>. More - documentation is located at the <ulink - url="http://tinderbox.marcuscom.com/">marcuscom tinderbox home - page</ulink>.</para> + documentation is located at the <link xlink:href="http://tinderbox.marcuscom.com/">marcuscom tinderbox home + page</link>.</para> <para>&man.portlint.1; is an application which can be used to verify that your port conforms to many important stylistic and @@ -816,15 +797,15 @@ simple heuristic application, so you should use it <emphasis>only as a guide</emphasis>. If <application>portlint</application> suggests changes which seem - unreasonable, consult the <ulink - url="&url.books.porters-handbook;">Porter's Handbook</ulink> + unreasonable, consult the <link xlink:href="&url.books.porters-handbook;">Porter's Handbook</link> or ask for advice.</para> <para>The &a.ports; is for general ports-related discussion. It - is a good place to ask for help. You can <ulink - url="http://lists.freebsd.org/mailman/listinfo">subscribe, or - read and search the list archives</ulink>. Reading the + is a good place to ask for help. You can <link xlink:href="http://lists.freebsd.org/mailman/listinfo">subscribe, or + read and search the list archives</link>. Reading the archives of the &a.ports-bugs; and the &a.cvs-ports; may also be of interest.</para> </sect1> + + <index/> </article> diff --git a/en_US.ISO8859-1/articles/contributing/article.xml b/en_US.ISO8859-1/articles/contributing/article.xml index c790885285..069f3c2d67 100644 --- a/en_US.ISO8859-1/articles/contributing/article.xml +++ b/en_US.ISO8859-1/articles/contributing/article.xml @@ -1,10 +1,9 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Contributing to FreeBSD</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Contributing to FreeBSD</title> + <abstract> <para>This article describes the different ways in which an @@ -13,14 +12,10 @@ </abstract> <authorgroup> - <author> - <firstname>Jordan</firstname> - <surname>Hubbard</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.ieee; &tm-attrib.general; @@ -29,7 +24,7 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> <indexterm><primary>contributing</primary></indexterm> @@ -64,14 +59,14 @@ developed, sold, and maintained, and we urge you to at least give it a second look.</para> - <sect1 id="contrib-what"> + <sect1 xml:id="contrib-what"> <title>What Is Needed</title> <para>The following list of tasks and sub-projects represents something of an amalgam of various <filename>TODO</filename> lists and user requests.</para> - <sect2 id="non-programmer-tasks"> + <sect2 xml:id="non-programmer-tasks"> <title>Ongoing Non-Programmer Tasks</title> <para>Many people who are involved in FreeBSD are not @@ -94,9 +89,8 @@ language. If documentation already exists for your language, you can help translate additional documents or verify that the translations are up-to-date. First take a - look at the <ulink - url="&url.books.fdp-primer;/translations.html">Translations - FAQ</ulink> in the FreeBSD Documentation Project Primer. + look at the <link xlink:href="&url.books.fdp-primer;/translations.html">Translations + FAQ</link> in the FreeBSD Documentation Project Primer. You are not committing yourself to translating every single FreeBSD document by doing this — as a volunteer, you can do as much or as little translation as @@ -117,7 +111,7 @@ </orderedlist> </sect2> - <sect2 id="ongoing-programmer-tasks"> + <sect2 xml:id="ongoing-programmer-tasks"> <title>Ongoing Programmer Tasks</title> <para>Most of the tasks listed here require either a @@ -130,7 +124,7 @@ <listitem> <para>If you run FreeBSD-CURRENT and have a good Internet connection, there is a machine - <hostid role="fqdn">current.FreeBSD.org</hostid> which + <systemitem class="fqdomainname">current.FreeBSD.org</systemitem> which builds a full release once a day—every now and again, try to install the latest release from it and report any failures in the process.</para> @@ -152,13 +146,13 @@ <listitem> <para>Move contributed software to - <filename class="directory">src/contrib</filename> in the + <filename>src/contrib</filename> in the source tree.</para> </listitem> <listitem> <para>Make sure code in - <filename class="directory">src/contrib</filename> is up + <filename>src/contrib</filename> is up to date.</para> </listitem> @@ -183,8 +177,8 @@ <listitem> <para>Get copies of formal standards like &posix;. You can get some links about these standards at the - <ulink url="&url.base;/projects/c99/index.html">FreeBSD - C99 & POSIX Standards Conformance Project</ulink> + <link xlink:href="&url.base;/projects/c99/index.html">FreeBSD + C99 & POSIX Standards Conformance Project</link> web site. Compare FreeBSD's behavior to that required by the standard. If the behavior differs, particularly in subtle or obscure corners of the specification, send in a @@ -207,9 +201,8 @@ <primary>problem reports database</primary> </indexterm> - <para>The <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD - PR list</ulink> shows all the current active problem reports + <para>The <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi">FreeBSD + PR list</link> shows all the current active problem reports and requests for enhancement that have been submitted by FreeBSD users. The PR database includes both programmer and non-programmer tasks. Look through the open PRs, and see if @@ -231,8 +224,8 @@ <title>Pick one of the items from the <quote>Ideas</quote> page</title> - <para>The <ulink url="http://wiki.freebsd.org/IdeasPage">&os; - list of projects and ideas for volunteers</ulink> is also + <para>The <link xlink:href="http://wiki.freebsd.org/IdeasPage">&os; + list of projects and ideas for volunteers</link> is also available for people willing to contribute to the &os; project. The list is being regularly updated and contains items for both programmers and non-programmers with @@ -240,28 +233,27 @@ </sect2> </sect1> - <sect1 id="contrib-how"> + <sect1 xml:id="contrib-how"> <title>How to Contribute</title> <para>Contributions to the system generally fall into one or more of the following 5 categories:</para> - <sect2 id="contrib-general"> + <sect2 xml:id="contrib-general"> <title>Bug Reports and General Commentary</title> <para>An idea or suggestion of <emphasis>general</emphasis> technical interest should be mailed to the &a.hackers;. Likewise, people with an interest in such things (and a tolerance for a <emphasis>high</emphasis> volume of mail!) may - subscribe to the &a.hackers;. See <ulink - url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The - FreeBSD Handbook</ulink> for more information about this and + subscribe to the &a.hackers;. See <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">The + FreeBSD Handbook</link> for more information about this and other mailing lists.</para> <para>If you find a bug or are submitting a specific change, please report it using the &man.send-pr.1; program or its - <ulink url="&url.base;/send-pr.html">WEB-based - equivalent</ulink>. Try to fill-in each field of the bug + <link xlink:href="&url.base;/send-pr.html">WEB-based + equivalent</link>. Try to fill-in each field of the bug report. Unless they exceed 65KB, include any patches directly in the report. If the patch is suitable to be applied to the source tree put <literal>[PATCH]</literal> in the synopsis of @@ -287,9 +279,8 @@ then you may ask someone to file it for you by sending mail to the &a.bugs;.</para> - <para>See also <ulink - url="&url.articles.problem-reports;/article.html">this - article</ulink> on how to write good problem + <para>See also <link xlink:href="&url.articles.problem-reports;/article.html">this + article</link> on how to write good problem reports.</para> </sect2> @@ -302,8 +293,8 @@ <para>Changes to the documentation are overseen by the &a.doc;. Please look at the - <ulink url="&url.books.fdp-primer;/index.html">FreeBSD - Documentation Project Primer</ulink> for complete + <link xlink:href="&url.books.fdp-primer;/index.html">FreeBSD + Documentation Project Primer</link> for complete instructions. Send submissions and changes (even small ones are welcome!) using &man.send-pr.1; as described in <link linkend="contrib-general">Bug Reports and General @@ -321,9 +312,8 @@ There is a special on-going release of FreeBSD known as <quote>FreeBSD-CURRENT</quote> which is made available in a variety of ways for the convenience of developers working - actively on the system. See <ulink - url="&url.books.handbook;/current-stable.html">The FreeBSD - Handbook</ulink> for more information about getting and + actively on the system. See <link xlink:href="&url.books.handbook;/current-stable.html">The FreeBSD + Handbook</link> for more information about getting and using FreeBSD-CURRENT.</para> <para>Working from older sources unfortunately means that your @@ -440,8 +430,8 @@ formatter, etc) it would be silly to refuse additional contributions under this license. Code under the GPL also goes into a different part of the tree, that being - <filename class="directory">/sys/gnu</filename> or - <filename class="directory">/usr/src/gnu</filename>, and + <filename>/sys/gnu</filename> or + <filename>/usr/src/gnu</filename>, and is therefore easily identifiable to anyone for whom the GPL presents a problem.</para> </listitem> @@ -501,7 +491,7 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. peripherals since we generally lack the funds to buy such items ourselves.</para> - <sect3 id="donation"> + <sect3 xml:id="donation"> <title>Donating Funds</title> <para>The FreeBSD Foundation is a non-profit, tax-exempt @@ -523,13 +513,12 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <para>The FreeBSD Foundation is now able to accept donations through the web with PayPal. To place a donation, please visit the Foundation - <ulink url="http://www.freebsdfoundation.org">web - site</ulink>.</para> + <link xlink:href="http://www.freebsdfoundation.org">web + site</link>.</para> <para>More information about the FreeBSD Foundation can be - found in <ulink - url="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The - FreeBSD Foundation -- an Introduction</ulink>. To contact + found in <link xlink:href="http://people.FreeBSD.org/~jdp/foundation/announcement.html">The + FreeBSD Foundation -- an Introduction</link>. To contact the Foundation by email, write to <email>bod@FreeBSDFoundation.org</email>.</para> </sect3> @@ -542,9 +531,11 @@ THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. <para>The FreeBSD Project happily accepts donations of hardware that it can find good use for. If you are interested in donating hardware, please contact the - <ulink url="&url.base;/donations/">Donations Liaison - Office</ulink>.</para> + <link xlink:href="&url.base;/donations/">Donations Liaison + Office</link>.</para> </sect3> </sect2> </sect1> + + <index/> </article> diff --git a/en_US.ISO8859-1/articles/contributors/article.xml b/en_US.ISO8859-1/articles/contributors/article.xml index 6d66577526..8c30cb7e4a 100644 --- a/en_US.ISO8859-1/articles/contributors/article.xml +++ b/en_US.ISO8859-1/articles/contributors/article.xml @@ -1,16 +1,15 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY % contrib.ent SYSTEM "contrib.ent"> %contrib.ent; <!ENTITY % not.published "IGNORE"> ]> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Contributors to FreeBSD</title> + -<article lang='en'> - <articleinfo> - <title>Contributors to FreeBSD</title> - - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.sun; &tm-attrib.general; @@ -24,15 +23,15 @@ <para>This article lists individuals and organizations who have made a contribution to FreeBSD.</para> </abstract> - </articleinfo> + </info> - <sect1 id="donors"> + <sect1 xml:id="donors"> <title>Donors Gallery</title> <note> <para>As of 2010, the following section is several years out-of-date. Donations from the past several years appear - <ulink url="&url.base;/donations/donors.html">here</ulink>. + <link xlink:href="&url.base;/donations/donors.html">here</link>. </para> </note> @@ -46,26 +45,24 @@ <para>The following individuals and businesses made it possible for the FreeBSD Project to build a new central server machine, which - has replaced <hostid role="fqdn">freefall.FreeBSD.org</hostid> at + has replaced <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> at one point, by donating the following items:</para> <itemizedlist> <listitem> - <para>&a.mbarkah.email; and his employer, <ulink - url="http://www.hemi.com/"> Hemisphere Online</ulink>, + <para>&a.mbarkah.email; and his employer, <link xlink:href="http://www.hemi.com/"> Hemisphere Online</link>, donated a <emphasis>Pentium Pro (P6) 200MHz CPU</emphasis> </para> </listitem> <listitem> - <para><ulink url="http://www.asacomputers.com/">ASA - Computers</ulink> donated a <emphasis>Tyan 1662 + <para><link xlink:href="http://www.asacomputers.com/">ASA + Computers</link> donated a <emphasis>Tyan 1662 motherboard</emphasis>.</para> </listitem> <listitem> - <para>Joe McGuckin <email>joe@via.net</email> of <ulink - url="http://www.via.net/">ViaNet Communications</ulink> donated + <para>Joe McGuckin <email>joe@via.net</email> of <link xlink:href="http://www.via.net/">ViaNet Communications</link> donated a <emphasis>Kingston ethernet controller.</emphasis></para> </listitem> @@ -76,8 +73,7 @@ </listitem> <listitem> - <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <ulink - url="http://www.Alameda.net/">Alameda Networks</ulink> donated + <para>Ulf Zimmermann <email>ulf@Alameda.net</email> of <link xlink:href="http://www.Alameda.net/">Alameda Networks</link> donated <emphasis>128MB of memory</emphasis>, a <emphasis>4 Gb disk drive and the case.</emphasis></para> </listitem> @@ -101,13 +97,13 @@ </listitem> <listitem> - <para><ulink url="http://www.bluemountain.com/">Blue Mountain - Arts</ulink></para> + <para><link xlink:href="http://www.bluemountain.com/">Blue Mountain + Arts</link></para> </listitem> <listitem> - <para><ulink url="http://www.epilogue.com/">Epilogue Technology - Corporation</ulink></para> + <para><link xlink:href="http://www.epilogue.com/">Epilogue Technology + Corporation</link></para> </listitem> <listitem> @@ -115,8 +111,8 @@ </listitem> <listitem> - <para><ulink url="http://www.gta.com/">Global Technology - Associates, Inc</ulink></para> + <para><link xlink:href="http://www.gta.com/">Global Technology + Associates, Inc</link></para> </listitem> <listitem> @@ -142,8 +138,8 @@ <listitem> <para>Kenneth P. Stox <email>ken@stox.sa.enteract.com</email> of - <ulink url="http://www.imagescape.com/">Imaginary Landscape, - LLC.</ulink></para> + <link xlink:href="http://www.imagescape.com/">Imaginary Landscape, + LLC.</link></para> </listitem> <listitem> @@ -151,41 +147,41 @@ </listitem> <listitem> - <para><ulink url="http://www.cdrom.co.jp/">Laser5</ulink> of Japan + <para><link xlink:href="http://www.cdrom.co.jp/">Laser5</link> of Japan (a portion of the profits from sales of their various FreeBSD CDROMs).</para> </listitem> <listitem> - <para><ulink url="http://www.mmjp.or.jp/fuki/">Fuki Shuppan - Publishing Co.</ulink> donated a portion of their profits from + <para><link xlink:href="http://www.mmjp.or.jp/fuki/">Fuki Shuppan + Publishing Co.</link> donated a portion of their profits from <emphasis>Hajimete no FreeBSD</emphasis> (FreeBSD, Getting started) to the FreeBSD and XFree86 projects.</para> </listitem> <listitem> - <para><ulink url="http://www.ascii.co.jp/">ASCII Corp.</ulink> + <para><link xlink:href="http://www.ascii.co.jp/">ASCII Corp.</link> donated a portion of their profits from several FreeBSD-related books to the FreeBSD project.</para> </listitem> <listitem> - <para><ulink url="http://www.yokogawa.co.jp/">Yokogawa Electric - Corp</ulink> has generously donated significant funding to the + <para><link xlink:href="http://www.yokogawa.co.jp/">Yokogawa Electric + Corp</link> has generously donated significant funding to the FreeBSD project.</para> </listitem> <listitem> - <para><ulink url="http://www.buffnet.net/">BuffNET</ulink></para> + <para><link xlink:href="http://www.buffnet.net/">BuffNET</link></para> </listitem> <listitem> - <para><ulink url="http://www.pacificsolutions.com/">Pacific - Solutions</ulink></para> + <para><link xlink:href="http://www.pacificsolutions.com/">Pacific + Solutions</link></para> </listitem> <listitem> - <para><ulink url="http://www.siemens.de/">Siemens AG</ulink> + <para><link xlink:href="http://www.siemens.de/">Siemens AG</link> via Andre Albsmeier <email>andre.albsmeier@mchp.siemens.de</email></para> </listitem> @@ -213,7 +209,7 @@ </listitem> <listitem> - <para><ulink url="http://www.compaq.com">Compaq</ulink> + <para><link xlink:href="http://www.compaq.com">Compaq</link> has donated a variety of Alpha systems to the FreeBSD Project. Among the many generous donations are 4 AlphaStation DS10s, an AlphaServer DS20, @@ -243,24 +239,23 @@ <listitem> <para>Larry Altneu <email>larry@ALR.COM</email>, and &a.wilko.email;, provided Wangtek and Archive QIC-02 tape drives in order to - improve the <devicename>wt</devicename> driver.</para> + improve the <filename>wt</filename> driver.</para> </listitem> <listitem> - <para>Ernst Winter (<ulink url="http://berklix.org/ewinter/">Deceased</ulink>) + <para>Ernst Winter (<link xlink:href="http://berklix.org/ewinter/">Deceased</link>) contributed a 2.88 MB floppy drive to the project. This will hopefully increase the pressure for rewriting the floppy disk driver. </para> </listitem> <listitem> - <para><ulink url="http://www.tekram.com/">Tekram - Technologies</ulink> sent one each of their DC-390, DC-390U + <para><link xlink:href="http://www.tekram.com/">Tekram + Technologies</link> sent one each of their DC-390, DC-390U and DC-390F FAST and ULTRA SCSI host adapter cards for regression testing of the NCR and AMD drivers with their cards. They are also to be applauded for making driver sources for free - operating systems available from their FTP server <ulink - url="ftp://ftp.tekram.com/scsi/FreeBSD/"></ulink>.</para> + operating systems available from their FTP server <uri xlink:href="ftp://ftp.tekram.com/scsi/FreeBSD/">ftp://ftp.tekram.com/scsi/FreeBSD/</uri>.</para> </listitem> <listitem> @@ -293,22 +288,20 @@ <itemizedlist> <listitem> - <para><ulink url="http://www.osd.bsdi.com/">BSDi</ulink> (formerly Walnut Creek CDROM) + <para><link xlink:href="http://www.osd.bsdi.com/">BSDi</link> (formerly Walnut Creek CDROM) has donated almost more than we can say (see the 'About the FreeBSD Project' - section of the <ulink url="&url.books.handbook;/index.html">FreeBSD Handbook</ulink> for more details). + section of the <link xlink:href="&url.books.handbook;/index.html">FreeBSD Handbook</link> for more details). In particular, we would like to thank them for the original - hardware used for <hostid - role="fqdn">freefall.FreeBSD.org</hostid>, our primary - development machine, and for <hostid - role="fqdn">thud.FreeBSD.org</hostid>, a testing and build + hardware used for <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem>, our primary + development machine, and for <systemitem class="fqdomainname">thud.FreeBSD.org</systemitem>, a testing and build box. We are also indebted to them for funding various contributors over the years and providing us with unrestricted use of their T1 connection to the Internet.</para> </listitem> <listitem> - <para>The <ulink url="http://www.interface-business.de/">interface - business GmbH, Dresden</ulink> has been patiently supporting + <para>The <link xlink:href="http://www.interface-business.de/">interface + business GmbH, Dresden</link> has been patiently supporting &a.joerg.email; who has often preferred FreeBSD work over paid work, and used to fall back to their (quite expensive) EUnet Internet connection whenever his private connection became too slow or @@ -316,8 +309,8 @@ </listitem> <listitem> - <para><ulink url="http://www.bsdi.com/">Berkeley Software Design, - Inc.</ulink> has contributed their DOS emulator code to the + <para><link xlink:href="http://www.bsdi.com/">Berkeley Software Design, + Inc.</link> has contributed their DOS emulator code to the remaining BSD world, which is used in the <emphasis>doscmd</emphasis> command.</para> </listitem> @@ -326,7 +319,7 @@ </itemizedlist> </sect1> - <sect1 id="staff-committers"> + <sect1 xml:id="staff-committers"> <title>The FreeBSD Developers</title> <para>These are the people who have commit privileges and do the @@ -338,7 +331,7 @@ &contrib.committers; </sect1> - <sect1 id="contrib-corealumni"> + <sect1 xml:id="contrib-corealumni"> <title>Core Team Alumni</title> <indexterm><primary>core team</primary></indexterm> @@ -351,7 +344,7 @@ &contrib.corealumni; </sect1> - <sect1 id="contrib-develalumni"> + <sect1 xml:id="contrib-develalumni"> <title>Development Team Alumni</title> <indexterm><primary>development team</primary></indexterm> @@ -364,7 +357,7 @@ &contrib.develalumni; </sect1> - <sect1 id="contrib-portmgralumni"> + <sect1 xml:id="contrib-portmgralumni"> <title>Ports Management Team Alumni</title> <indexterm><primary>portmgr team</primary></indexterm> @@ -377,7 +370,7 @@ &contrib.portmgralumni; </sect1> - <sect1 id="contrib-develinmemoriam"> + <sect1 xml:id="contrib-develinmemoriam"> <title>Development Team: In Memoriam</title> <indexterm><primary>development team</primary></indexterm> @@ -391,7 +384,7 @@ &contrib.develinmemoriam; </sect1> - <sect1 id="contrib-derived"> + <sect1 xml:id="contrib-derived"> <title>Derived Software Contributors</title> <para>This software was originally derived from William F. Jolitz's 386BSD @@ -406,7 +399,7 @@ all the contributors to NetBSD and OpenBSD for their work.</para> </sect1> - <sect1 id="contrib-additional"> + <sect1 xml:id="contrib-additional"> <title>Additional FreeBSD Contributors</title> <para>(in alphabetical order by first name):</para> @@ -414,11 +407,13 @@ &contrib.additional; </sect1> - <sect1 id="contrib-386bsd"> + <sect1 xml:id="contrib-386bsd"> <title>386BSD Patch Kit Patch Contributors</title> <para>(in alphabetical order by first name):</para> &contrib.386bsd; </sect1> + + <index/> </article> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.386bsd.xml b/en_US.ISO8859-1/articles/contributors/contrib.386bsd.xml index 398ff330aa..de54542dfa 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.386bsd.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.386bsd.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> <!-- $FreeBSD$ --> - - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>Adam Glass <email>glass@postgres.berkeley.edu</email></para> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.additional.xml b/en_US.ISO8859-1/articles/contributors/contrib.additional.xml index a99cb74711..da89e64cbd 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.additional.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.additional.xml @@ -4,8 +4,7 @@ NOTE TO COMMITTERS: Contributors lists are sorted in alphabetical order by first name. --> - - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>ABURAYA Ryushirou <email>rewsirow@ff.iij4u.or.jp</email></para> @@ -2466,7 +2465,7 @@ <listitem> <para>Denis Generalov - <email>gd@rambler-co.ru></email></para> + <email>gd@rambler-co.ru></email></para> </listitem> <listitem> @@ -3023,8 +3022,7 @@ </listitem> <listitem> - <para>Ernst Winter (<ulink - url="http://berklix.org/ewinter/">Deceased</ulink>)</para> + <para>Ernst Winter (<link xlink:href="http://berklix.org/ewinter/">Deceased</link>)</para> </listitem> <listitem> @@ -6327,7 +6325,7 @@ <listitem> <para>Martin Kropfinger - <email>freebsd@rakor-net.de></email></para> + <email>freebsd@rakor-net.de></email></para> </listitem> <listitem> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.committers.xml b/en_US.ISO8859-1/articles/contributors/contrib.committers.xml index 011458eae1..e7e4e64031 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.committers.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.committers.xml @@ -5,8 +5,7 @@ alphabetical order by last name. Please keep in mind that fact while adding your entity to the list of developers. --> - - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>&a.tabthorpe.email;</para> </listitem> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml b/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml index e2a4163d48..0a9f3f90c7 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.corealumni.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> <!-- $FreeBSD$ --> - - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>&a.attilio.email; (2012)</para> </listitem> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml b/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml index fa3f4f16ba..d9056fdc67 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.develalumni.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> - <!-- $FreeBSD$ --> - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>&a.kmacy.email; (2005 - 2012)</para> diff --git a/en_US.ISO8859-1/articles/contributors/contrib.develinmemoriam.xml b/en_US.ISO8859-1/articles/contributors/contrib.develinmemoriam.xml index 52c4849be6..1229621c15 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.develinmemoriam.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.develinmemoriam.xml @@ -1,11 +1,10 @@ <?xml version="1.0" encoding="iso-8859-1"?> <!-- $FreeBSD$ --> - - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>&a.jb.email; (1997 - 2009; RIP 2009)</para> <para> - <ulink url="http://hub.opensolaris.org/bin/view/Community+Group+ogb/In+Memoriam">John</ulink> + <link xlink:href="http://hub.opensolaris.org/bin/view/Community+Group+ogb/In+Memoriam">John</link> made major contributions to FreeBSD, the best known of which is the import of the &man.dtrace.1; code. John's unique sense of humor and plain-spokenness either ruffled feathers or @@ -18,10 +17,10 @@ <listitem> <para>&a.jmz.email; (1994 - 2009; RIP 2009)</para> <para> - <ulink url="http://www.obs-besancon.fr/article.php3?id_article=323">Jean-Marc</ulink> + <link xlink:href="http://www.obs-besancon.fr/article.php3?id_article=323">Jean-Marc</link> was an astrophysicist who made important contributions to the modeling of the atmospheres of both planets and comets at - <ulink url="http://www.obs-besancon.fr/">l'Observatoire de Besançon</ulink> + <link xlink:href="http://www.obs-besancon.fr/">l'Observatoire de Besançon</link> in Besançon, France. While there, he participated in the conception and construction of the Vega tricanal spectrometer that studied Halley's Comet. He had also been a long-time @@ -31,9 +30,9 @@ <listitem> <para>&a.itojun.email; (1997 - 2001; RIP 2008)</para> <para>Known to everyone as - <ulink url="http://astralblue.livejournal.com/350702.html">itojun</ulink>, + <link xlink:href="http://astralblue.livejournal.com/350702.html">itojun</link>, Jun-ichiro Hagino was was a core researcher at the - <ulink url="http://www.kame.net/">KAME Project</ulink>, + <link xlink:href="http://www.kame.net/">KAME Project</link>, which aimed to provide IPv6 and IPsec technology in freely redistributable form. Much of this code was incorporated into FreeBSD. Without his efforts, the state of IPv6 on the @@ -43,7 +42,7 @@ <listitem> <para>&a.cg.email; (1999 - 2005; RIP 2005)</para> <para> - <ulink url="http://www.dbsi.org/cam/">Cameron</ulink> + <link xlink:href="http://www.dbsi.org/cam/">Cameron</link> was a unique individual who contributed to the project despite serious physical disabilities. He was responsible for a complete rewrite of our sound system during the @@ -55,7 +54,7 @@ <listitem> <para>&a.alane.email; (2002 - 2003; RIP 2003)</para> <para> - <ulink url="http://freebsd.kde.org/memoriam/alane.php">Alan</ulink> + <link xlink:href="http://freebsd.kde.org/memoriam/alane.php">Alan</link> was a major contributor to the KDE on FreeBSD group. In addition, he maintained many other difficult and time-consuming ports such as <application>autoconf</application>, diff --git a/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml b/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml index d422aa16c2..6086fdab04 100644 --- a/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml +++ b/en_US.ISO8859-1/articles/contributors/contrib.portmgralumni.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> <!-- $FreeBSD$ --> - - <itemizedlist> +<itemizedlist xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"> <listitem> <para>&a.beat.email; (2011 - 2013)</para> </listitem> diff --git a/en_US.ISO8859-1/articles/cups/article.xml b/en_US.ISO8859-1/articles/cups/article.xml index 7f4f83578b..90a108b519 100644 --- a/en_US.ISO8859-1/articles/cups/article.xml +++ b/en_US.ISO8859-1/articles/cups/article.xml @@ -1,21 +1,16 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>CUPS on FreeBSD</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>CUPS on FreeBSD</title> + <authorgroup> - <author> - <firstname>Chess</firstname> - <surname>Griffin</surname> - <affiliation> + <author><personname><firstname>Chess</firstname><surname>Griffin</surname></personname><affiliation> <address><email>chess@chessgriffin.com</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -27,9 +22,9 @@ <abstract> <para>An article about configuring CUPS on &os;.</para> </abstract> - </articleinfo> + </info> - <sect1 id="printing-cups"> + <sect1 xml:id="printing-cups"> <title>An Introduction to the Common Unix Printing System (CUPS)</title> <indexterm><primary>printing</primary></indexterm> @@ -54,11 +49,10 @@ sharing and accessing printers in mixed environments of &os;, &linux;, &macos; X, or &windows;.</para> - <para>The main site for <application>CUPS</application> is <ulink - url="http://www.cups.org/"></ulink>.</para> + <para>The main site for <application>CUPS</application> is <uri xlink:href="http://www.cups.org/">http://www.cups.org/</uri>.</para> </sect1> - <sect1 id="printing-cups-install"> + <sect1 xml:id="printing-cups-install"> <title>Installing the CUPS Print Server</title> <para><application>CUPS</application> can be installed from ports or @@ -74,15 +68,15 @@ <screen>&prompt.root; <userinput>pkg_add -r cups</userinput></screen> <para>Other optional, but recommended, ports or packages are - <filename role="package">print/gutenprint-cups</filename> and - <filename role="package">print/hplip</filename>, both of which add + <package>print/gutenprint-cups</package> and + <package>print/hplip</package>, both of which add drivers and utilities for a variety of printers. Once installed, the <application>CUPS</application> configuration files can be found in the directory <filename>/usr/local/etc/cups</filename>.</para> </sect1> - <sect1 id="printing-cups-configuring-server"> + <sect1 xml:id="printing-cups-configuring-server"> <title>Configuring the CUPS Print Server</title> <para>After installation, a few files must edited in order to @@ -91,7 +85,7 @@ <filename>/etc/devfs.rules</filename> and add the following information to set the proper permissions on all potential printer devices and to associate printers with the - <groupname>cups</groupname> user group:</para> + <systemitem class="groupname">cups</systemitem> user group:</para> <programlisting>[system=10] add path 'unlpt*' mode 0660 group cups @@ -103,13 +97,12 @@ add path 'usb/<replaceable>X</replaceable>.<replaceable>Y</replaceable>.<replace <para>Note that <replaceable>X</replaceable>, <replaceable>Y</replaceable>, and <replaceable>Z</replaceable> should be replaced with the target USB device listed in the - <filename class="directory">/dev/usb</filename> directory that + <filename>/dev/usb</filename> directory that corresponds to the printer. To find the correct device, examine the output of &man.dmesg.8;, where - <filename>ugen<replaceable>X</replaceable>.<replaceable>Y</replaceable></filename> + <filename>ugenX.Y</filename> lists the printer device, which is a symbolic link to a USB - device in <filename - class="directory">/dev/usb</filename>.</para> + device in <filename>/dev/usb</filename>.</para> </note> <para>Next, add two lines to <filename>/etc/rc.conf</filename> as @@ -139,7 +132,7 @@ devfs_system_ruleset="system"</programlisting> &prompt.root; <userinput>/usr/local/etc/rc.d/cupsd restart</userinput></screen> </sect1> - <sect1 id="printing-cups-configuring-printers"> + <sect1 xml:id="printing-cups-configuring-printers"> <title>Configuring Printers on the CUPS Print Server</title> <para>After the <application>CUPS</application> system has been @@ -153,11 +146,11 @@ devfs_system_ruleset="system"</programlisting> <para>The primary means for managing and administering the <application>CUPS</application> server is through the web-based interface, which can be found by launching a web browser and - entering <ulink url="http://localhost:631"></ulink> in the + entering <uri xlink:href="http://localhost:631">http://localhost:631</uri> in the browser's URL bar. If the <application>CUPS</application> server is on another machine on the network, substitute the server's local <acronym>IP</acronym> address for - <hostid>localhost</hostid>. The <application>CUPS</application> + <systemitem>localhost</systemitem>. The <application>CUPS</application> web interface is fairly self-explanatory, as there are sections for managing printers and print jobs, authorizing users, and more. Additionally, on the right-hand side of the Administration screen @@ -175,15 +168,13 @@ devfs_system_ruleset="system"</programlisting> Administration screen. When presented with the <quote>Device</quote> drop-down box, simply select the desired locally-attached printer, and then continue through the process. - If one has added the <filename - role="package">print/gutenprint-cups</filename> or <filename - role="package">print/hplip</filename> ports or packages as + If one has added the <package>print/gutenprint-cups</package> or <package>print/hplip</package> ports or packages as referenced above, then additional print drivers will be available in the subsequent screens that might provide more stability or features.</para> </sect1> - <sect1 id="printing-cups-clients"> + <sect1 xml:id="printing-cups-clients"> <title>Configuring CUPS Clients</title> <para>Once the <application>CUPS</application> server has been @@ -194,7 +185,7 @@ devfs_system_ruleset="system"</programlisting> desktop machine that is acting as both server and client, then much of this information may not be needed.</para> - <sect2 id="printing-cups-clients-unix"> + <sect2 xml:id="printing-cups-clients-unix"> <title>&unix; Clients</title> <para><application>CUPS</application> will also need to be @@ -206,7 +197,7 @@ devfs_system_ruleset="system"</programlisting> <application>GNOME</application> or <application>KDE</application>. Alternatively, one can access the local <application>CUPS</application> interface on the - client machine at <ulink url="http://localhost:631"></ulink> and + client machine at <uri xlink:href="http://localhost:631">http://localhost:631</uri> and click on <quote>Add Printer</quote> in the Administration section. When presented with the <quote>Device</quote> drop-down box, simply select the networked @@ -235,7 +226,7 @@ devfs_system_ruleset="system"</programlisting> <application>CUPS</application> server on the network.</para> </sect2> - <sect2 id="printing-cups-clients-windows"> + <sect2 xml:id="printing-cups-clients-windows"> <title>&windows; Clients</title> <para>Versions of &windows; prior to XP did not have the @@ -253,20 +244,20 @@ devfs_system_ruleset="system"</programlisting> <para>If one has an older version of &windows; without native <acronym>IPP</acronym> printing support, then the general means of connecting to a <application>CUPS</application> printer is to - use <filename role="package">net/samba3</filename> and + use <package>net/samba3</package> and <application>CUPS</application> together, which is a topic outside the scope of this chapter.</para> </sect2> </sect1> - <sect1 id="printing-cups-troubleshooting"> + <sect1 xml:id="printing-cups-troubleshooting"> <title>CUPS Troubleshooting</title> <para>Difficulties with <application>CUPS</application> often lies in permissions. First, double check the &man.devfs.8; permissions as outlined above. Next, check the actual permissions of the devices created in the file system. It is also helpful to make - sure your user is a member of the <groupname>cups</groupname> + sure your user is a member of the <systemitem class="groupname">cups</systemitem> group. If the permissions check boxes in the Administration section of the <application>CUPS</application> web interface do not seem to be working, another fix might be to manually backup @@ -363,7 +354,7 @@ CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default> </Policy></programlisting> </sect1> - <sect1 id="printing-cups-ports-knobs"> + <sect1 xml:id="printing-cups-ports-knobs"> <title>Fine Tuning CUPS-Related Ports</title> <para>If <application>CUPS</application> is going to serve as the @@ -377,15 +368,17 @@ CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default> CUPS_OVERWRITE_BASE=YES WITHOUT_LPR=YES</programlisting> - <para>The first knob, <makevar>WITH_CUPS</makevar>, adds + <para>The first knob, <varname>WITH_CUPS</varname>, adds <application>CUPS</application> support to ports where applicable. - The second knob, <makevar>CUPS_OVERWRITE_BASE</makevar>, will fix + The second knob, <varname>CUPS_OVERWRITE_BASE</varname>, will fix certain symlinks and paths that would otherwise apply to the default &os; printing system, <application>LPR</application>, and will prevent these fixes from being reverted upon the next - <maketarget>buildworld</maketarget> system upgrade. The third - knob, <makevar>WITHOUT_LPR</makevar>, will prevent + <buildtarget>buildworld</buildtarget> system upgrade. The third + knob, <varname>WITHOUT_LPR</varname>, will prevent <application>LPR</application> support from being added to ports where applicable.</para> </sect1> + + <index/> </article> diff --git a/en_US.ISO8859-1/articles/custom-gcc/article.xml b/en_US.ISO8859-1/articles/custom-gcc/article.xml index f003443fe1..680d734c94 100644 --- a/en_US.ISO8859-1/articles/custom-gcc/article.xml +++ b/en_US.ISO8859-1/articles/custom-gcc/article.xml @@ -1,22 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Using newer version of <application>GCC</application> and +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Using newer version of <application>GCC</application> and <application>binutils</application> with the &os; Ports Collection</title> + - <author> - <firstname>Martin</firstname> - <surname>Matuska</surname> - <affiliation> + <author><personname><firstname>Martin</firstname><surname>Matuska</surname></personname><affiliation> <address><email>mm@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -37,9 +32,9 @@ Custom <application>GCC</application> configurations are also discussed.</para> </abstract> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction</title> <para>The default system compiler as of &os; 8.0 is @@ -56,10 +51,10 @@ tree.</para> </sect1> - <sect1 id="prerequisites"> + <sect1 xml:id="prerequisites"> <title>Prerequisites</title> - <sect2 id="installing-binutils"> + <sect2 xml:id="installing-binutils"> <title>Installing binutils from ports</title> <para>To make use of all of the new features in the latest @@ -77,25 +72,25 @@ <screen>&prompt.root; <userinput>cd /usr/ports/devel/binutils && make install</userinput></screen> </sect2> - <sect2 id="installing-gcc"> + <sect2 xml:id="installing-gcc"> <title>Installing GCC from ports</title> <para>The &os; ports tree offers several new versions of <application>GCC</application>. The following example is for the stable version 4.4. However, it is possible to install previous or later development versions (e.g. - <filename role="package">lang/gcc43</filename> or - <filename role="package">lang/gcc45</filename>).</para> + <package>lang/gcc43</package> or + <package>lang/gcc45</package>).</para> <para>To install one of the mentioned <application>GCC</application> ports, run the following command:</para> - <screen>&prompt.root; <userinput>cd /usr/ports/lang/<replaceable>gcc44</replaceable> && make install</userinput></screen> + <screen>&prompt.root; <userinput>cd /usr/ports/lang/gcc44 && make install</userinput></screen> </sect2> </sect1> - <sect1 id="configuring-ports-gcc"> + <sect1 xml:id="configuring-ports-gcc"> <title>Configuring ports for custom version of <application>GCC</application></title> @@ -103,7 +98,7 @@ custom version of <application>GCC</application> installed from the &os; ports tree.</para> - <sect2 id="adjusting-make.conf"> + <sect2 xml:id="adjusting-make.conf"> <title>Adjusting <filename>make.conf</filename></title> <para>Add the following lines to the @@ -129,7 +124,7 @@ CPP=cpp44 </note> </sect2> - <sect2 id="adjusting-libmap.conf"> + <sect2 xml:id="adjusting-libmap.conf"> <title>Adjusting <filename>libmap.conf</filename></title> <para>Many of the ports' binaries and libraries link to libgcc_s @@ -161,7 +156,7 @@ libstdc++.so.6 gcc44/libstdc++.so.6</programlisting> </warning> </sect2> - <sect2 id="custom-cflags"> + <sect2 xml:id="custom-cflags"> <title>Custom <literal>CFLAGS</literal> for the ports tree</title> <para>To add custom <literal>CFLAGS</literal> for the ports tree @@ -183,7 +178,7 @@ CFLAGS+=-mssse3 optimizations flags based on this variable.</para> </sect2> - <sect2 id="excluding-unbuildable-ports"> + <sect2 xml:id="excluding-unbuildable-ports"> <title>Excluding ports that do not build with new version of <application>GCC</application></title> @@ -202,14 +197,14 @@ CPP=cpp44 <para>The example above excludes the forced use of <command>gcc</command> 4.4 for the - <filename role="package">net/openldap</filename>* ports. It is + <package>net/openldap</package>* ports. It is also possible to specify more ports on a single line:</para> <programlisting>.if empty(.CURDIR:M/usr/ports/net/openldap*) && empty(.CURDIR:M/usr/ports/xxx/yyy) && ...</programlisting> </sect2> </sect1> - <sect1 id="performance-imparct"> + <sect1 xml:id="performance-imparct"> <title>Impact on the binary performance</title> <para>Using <application>GCC</application> version 4.4 with @@ -219,8 +214,7 @@ CPP=cpp44 more than a 20% performance boost (e.g. in multimedia processing).</para> - <para>The table located at <ulink - url="http://people.freebsd.org/~mm/benchmarks/perlbench/"></ulink> + <para>The table located at <uri xlink:href="http://people.freebsd.org/~mm/benchmarks/perlbench/">http://people.freebsd.org/~mm/benchmarks/perlbench/</uri> shows a comparison of <application>GCC</application> versions currently available in base &os; system, <application>GCC</application> version 4.3 and diff --git a/en_US.ISO8859-1/articles/cvs-freebsd/article.xml b/en_US.ISO8859-1/articles/cvs-freebsd/article.xml index 234a19f0a9..3ab3fc66f4 100644 --- a/en_US.ISO8859-1/articles/cvs-freebsd/article.xml +++ b/en_US.ISO8859-1/articles/cvs-freebsd/article.xml @@ -1,18 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Setting up a CVS repository - the FreeBSD way</title> + -<article lang='en'> - <articleinfo> - <title>Setting up a CVS repository - the FreeBSD way</title> - - <author> - <firstname>Stijn</firstname> - <surname>Hoop</surname> - <affiliation> + <author><personname><firstname>Stijn</firstname><surname>Hoop</surname></personname><affiliation> <address><email>stijn@win.tue.nl</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2001</year> @@ -25,7 +20,7 @@ <releaseinfo>$FreeBSD$</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -37,9 +32,9 @@ granular access control to the source tree and generation of readable email of every commit.</para> </abstract> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>Most of the open source software projects use @@ -62,7 +57,7 @@ <application>CVS</application>.</para> </sect1> - <sect1 id="first-setup"> + <sect1 xml:id="first-setup"> <title>First setup</title> <warning> @@ -77,10 +72,10 @@ <para>The first thing to do when setting up a new repository is to tell <application>CVS</application> to initialize it:</para> - <screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-repository</replaceable> init</userinput></screen> + <screen>&prompt.user; <userinput>cvs -d path-to-repository init</userinput></screen> <para>This tells <application>CVS</application> to create the - <filename class="directory">CVSROOT</filename> administrative directory, where all the + <filename>CVSROOT</filename> administrative directory, where all the customization takes place.</para> </sect2> @@ -92,12 +87,12 @@ repository. We will assume the FreeBSD default of <literal>ncvs</literal> for this group.</para> - <screen>&prompt.root; <userinput>pw groupadd <replaceable>ncvs</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw groupadd ncvs</userinput></screen> <para>Next, you should &man.chown.8; the directory to the group you just added:</para> - <screen>&prompt.root; <userinput>chown -R :<replaceable>ncvs</replaceable> <replaceable>path-to-your-repository</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>chown -R :ncvs path-to-your-repository</userinput></screen> <para>This ensures that no one can write to the repository without proper group permissions.</para> @@ -106,25 +101,24 @@ <sect2> <title>Getting the sources</title> - <para>Now you need to obtain the <filename class="directory">CVSROOT</filename> directory + <para>Now you need to obtain the <filename>CVSROOT</filename> directory from the FreeBSD repository. This is most easily done by checking it - out from a FreeBSD anonymous CVS mirror. See <ulink - url="&url.books.handbook;/anoncvs.html">the relevant chapter in - the handbook</ulink> for more information. Let us assume that the - sources are stored in <filename class="directory">CVSROOT-freebsd</filename> in the + out from a FreeBSD anonymous CVS mirror. See <link xlink:href="&url.books.handbook;/anoncvs.html">the relevant chapter in + the handbook</link> for more information. Let us assume that the + sources are stored in <filename>CVSROOT-freebsd</filename> in the current directory.</para> </sect2> <sect2> <title>Copying the FreeBSD scripts</title> - <para>Next, we will copy the FreeBSD <filename class="directory">CVSROOT</filename> + <para>Next, we will copy the FreeBSD <filename>CVSROOT</filename> sources into your own repository. If you are accustomed to <application>CVS</application>, you might be thinking that you can just import the scripts, in an attempt to make synchronizing with later versions easier. However, it turns out that <application>CVS</application> has a deficiency in this area: - when importing sources into the <filename class="directory">CVSROOT</filename> directory, + when importing sources into the <filename>CVSROOT</filename> directory, it will not update the needed administrative files. In order to make it recognize those, you will need to checkin each file after importing them, losing the value of <literal>cvs import</literal>. Therefore, @@ -132,10 +126,10 @@ <para>It does not matter if the above paragraph did not make sense to you—the end result is the same. Simply check out your - <filename class="directory">CVSROOT</filename> and copy the FreeBSD files over your + <filename>CVSROOT</filename> and copy the FreeBSD files over your local (untouched) copies:</para> - <screen>&prompt.user; <userinput>cvs -d <replaceable>path-to-your-repository</replaceable> checkout CVSROOT</userinput> + <screen>&prompt.user; <userinput>cvs -d path-to-your-repository checkout CVSROOT</userinput> &prompt.user; <userinput>cd CVSROOT</userinput> &prompt.user; <userinput>cp ../CVSROOT-freebsd/* .</userinput> &prompt.user; <userinput>cvs add *</userinput></screen> @@ -277,7 +271,7 @@ match one of the lines in this file are exempted from this check. You should add expressions to this file as you checkin files that cannot have a revision header. For the purpose of installing the - scripts, it may be best to exclude <filename class="directory">CVSROOT/</filename> + scripts, it may be best to exclude <filename>CVSROOT/</filename> from header checks.</para> </listitem> @@ -466,7 +460,7 @@ <para><literal>@LOG_FILE_MAP</literal> - change this array as you wish - each regexp is matched on the directory of the commit, and the commit log message gets stored in - the <filename class="directory">commitlogs</filename> subdirectory in + the <filename>commitlogs</filename> subdirectory in the filename mentioned.</para> </listitem> @@ -495,7 +489,7 @@ <literal>^CVSROOT/</literal>, and add one line with only <literal>^CVSROOT/</literal> on it. After the wrapper is installed, you can add your header to the files in the - <filename class="directory">CVSROOT</filename> directory and restore these lines, + <filename>CVSROOT</filename> directory and restore these lines, but for now they will only be in the way when you try to commit later on.</para> </step> @@ -533,7 +527,7 @@ <para>The last thing to do before you are finished, is to make sure the commitlogs can be stored. By default these are stored in the repository, in the <filename>commitlogs</filename> subdirectory - of the <filename class="directory">CVSROOT</filename> directory. This directory + of the <filename>CVSROOT</filename> directory. This directory needs to be created, so do the following:</para> <screen>&prompt.user; <userinput>mkdir commitlogs</userinput> @@ -543,12 +537,12 @@ <para>Now, after careful review, you should commit your changes. Be sure that you have granted yourself access to the - <filename class="directory">CVSROOT</filename> directory in your + <filename>CVSROOT</filename> directory in your <filename>avail</filename> before you do this, because otherwise you will lock yourself out. So make sure everything is as you intend, and then do the following:</para> - <screen>&prompt.user; <userinput>cvs commit -m '<replaceable>- Initial FreeBSD scripts commit</replaceable>'</userinput></screen> + <screen>&prompt.user; <userinput>cvs commit -m '- Initial FreeBSD scripts commit'</userinput></screen> </sect2> <sect2> @@ -558,7 +552,7 @@ <filename>avail</filename> file, to make sure everything works as expected.</para> - <screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' avail</userinput></screen> + <screen>&prompt.user; <userinput>cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' avail</userinput></screen> <para>If everything works, congratulations! You now have a working setup of the FreeBSD scripts for your repository. If @@ -568,12 +562,12 @@ </sect2> </sect1> - <sect1 id="freebsdspecific"> + <sect1 xml:id="freebsdspecific"> <title>FreeBSD specific setup</title> <para>The FreeBSD project itself uses a slightly different setup, which - also uses files from the <filename class="directory">freebsd</filename> subdirectory of - the FreeBSD <filename class="directory">CVSROOT</filename>. The project uses this because + also uses files from the <filename>freebsd</filename> subdirectory of + the FreeBSD <filename>CVSROOT</filename>. The project uses this because of the large number of committers, which all would have to be in the same group. So, a simple wrapper was written which ensures that people have the correct credentials to commit, and then sets the group id @@ -642,7 +636,7 @@ <para>Next up is installing the wrapper to ensure you become the correct group when committing. The sources for this live in <filename>cvswrap.c</filename> in your - <filename class="directory">CVSROOT</filename>.</para> + <filename>CVSROOT</filename>.</para> <para>Compile the sources that you edited to include the correct paths:</para> @@ -653,7 +647,7 @@ <screen>&prompt.root; <userinput>mv /usr/bin/cvs /usr/bin/ncvs</userinput> &prompt.root; <userinput>mv cvs /usr/bin/cvs</userinput> -&prompt.root; <userinput>chown root:<replaceable>ncvs</replaceable> /usr/bin/cvs /usr/bin/ncvs</userinput> +&prompt.root; <userinput>chown root:ncvs /usr/bin/cvs /usr/bin/ncvs</userinput> &prompt.root; <userinput>chmod o-rx /usr/bin/ncvs</userinput> &prompt.root; <userinput>chmod u-w,g+s /usr/bin/cvs</userinput></screen> @@ -676,7 +670,7 @@ <para>Your wrapper should now be setup. You can of course test this by making a forced commit to the <filename>access</filename> file:</para> - <screen>&prompt.user; <userinput>cvs commit -f -m '<replaceable>Forced commit to test the new CVSROOT scripts</replaceable>' access</userinput></screen> + <screen>&prompt.user; <userinput>cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' access</userinput></screen> <para>Again, if this fails, check to see whether all of the above steps have been executed correctly.</para> diff --git a/en_US.ISO8859-1/articles/explaining-bsd/article.xml b/en_US.ISO8859-1/articles/explaining-bsd/article.xml index eb6f1530d5..688f8bdad7 100644 --- a/en_US.ISO8859-1/articles/explaining-bsd/article.xml +++ b/en_US.ISO8859-1/articles/explaining-bsd/article.xml @@ -1,24 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- The FreeBSD Documentation Project --> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Explaining BSD</title> + -<article lang='en'> - <articleinfo> - <title>Explaining BSD</title> - - <author> - <firstname>Greg</firstname> - <surname>Lehey</surname> - - <affiliation> + <author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><affiliation> <address><email>grog@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.amd; &tm-attrib.apple; @@ -39,14 +32,11 @@ <para>In the open source world, the word <quote>Linux</quote> is almost synonymous with <quote>Operating System</quote>, but it is not the only open source &unix; operating system. According - to the <ulink - url="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet - Operating System Counter</ulink>, as of April 1999 31.3% of the + to the <link xlink:href="http://www.leb.net/hzo/ioscount/data/r.9904.txt">Internet + Operating System Counter</link>, as of April 1999 31.3% of the world's network connected machines run Linux. 14.6% run BSD &unix;. - Some of the world's largest web operations, such as <ulink - url="http://www.yahoo.com/">Yahoo!</ulink>, run BSD. The world's - busiest FTP server of 1999 (now defunct), <ulink - url="ftp://ftp.cdrom.com/">ftp.cdrom.com</ulink>, used BSD to + Some of the world's largest web operations, such as <link xlink:href="http://www.yahoo.com/">Yahoo!</link>, run BSD. The world's + busiest FTP server of 1999 (now defunct), <link xlink:href="ftp://ftp.cdrom.com/">ftp.cdrom.com</link>, used BSD to transfer 1.4 TB of data a day. Clearly this is not a niche market: BSD is a well-kept secret.</para> @@ -56,9 +46,9 @@ <para>Throughout this paper, differences between BSD and Linux will be noted <emphasis>like this</emphasis>.</para> </abstract> - </articleinfo> + </info> - <sect1 id="what-is-bsd"> + <sect1 xml:id="what-is-bsd"> <title>What is BSD?</title> <para>BSD stands for <quote>Berkeley Software Distribution</quote>. It is @@ -100,7 +90,7 @@ <para>The X Window system used in most versions of BSD is maintained by the - <ulink url="http://www.X.org/">X.Org project</ulink>. + <link xlink:href="http://www.X.org/">X.Org project</link>. &os; allows the user to choose from a variety of desktop environments, such as <application>Gnome</application>, <application>KDE</application>, or <application>Xfce</application>; @@ -116,7 +106,7 @@ </itemizedlist> </sect1> - <sect1 id="what-a-real-unix"> + <sect1 xml:id="what-a-real-unix"> <title>What, a real &unix;?</title> <para>The BSD operating systems are not clones, but open source @@ -165,29 +155,29 @@ CSRG members, William F. Jolitz, wrote the remaining code and released it in early 1992 as <emphasis>386BSD</emphasis>. At the same time, another group of ex-CSRG members formed a commercial company called - <ulink url="http://www.bsdi.com/">Berkeley Software Design Inc.</ulink> + <link xlink:href="http://www.bsdi.com/">Berkeley Software Design Inc.</link> and released a beta version of an operating system called - <ulink url="http://www.bsdi.com/">BSD/386</ulink>, which was based on + <link xlink:href="http://www.bsdi.com/">BSD/386</link>, which was based on the same sources. The name of the operating system was later changed to BSD/OS.</para> <para>386BSD never became a stable operating system. Instead, two other projects split off from it in 1993: - <ulink url="http://www.NetBSD.org/">NetBSD</ulink> and - <ulink url="&url.base;/index.html">FreeBSD</ulink>. The two projects + <link xlink:href="http://www.NetBSD.org/">NetBSD</link> and + <link xlink:href="&url.base;/index.html">FreeBSD</link>. The two projects originally diverged due to differences in patience waiting for improvements to 386BSD: the NetBSD people started early in the year, and the first version of FreeBSD was not ready until the end of the year. In the meantime, the code base had diverged sufficiently to make it difficult to merge. In addition, the projects had different aims, as we will see below. In 1996, - <ulink url="http://www.OpenBSD.org/">OpenBSD</ulink> split off from + <link xlink:href="http://www.OpenBSD.org/">OpenBSD</link> split off from NetBSD, and in 2003, - <ulink url="http://www.dragonflybsd.org/">DragonFlyBSD</ulink> split + <link xlink:href="http://www.dragonflybsd.org/">DragonFlyBSD</link> split off from FreeBSD.</para> </sect1> - <sect1 id="why-is-bsd-not-better-known"> + <sect1 xml:id="why-is-bsd-not-better-known"> <title>Why is BSD not better known?</title> <para>For a number of reasons, BSD is relatively unknown:</para> @@ -213,7 +203,7 @@ <listitem> <para>In 1992, AT&T sued - <ulink url="http://www.bsdi.com/">BSDI</ulink>, + <link xlink:href="http://www.bsdi.com/">BSDI</link>, the vendor of BSD/386, alleging that the product contained AT&T-copyrighted code. The case was settled out of court in 1994, but the spectre of the litigation continues to haunt people. @@ -232,15 +222,15 @@ <listitem> <para>There is a perception that the BSD projects are fragmented and belligerent. The - <ulink url="http://interactive.wsj.com/bin/login?Tag=/&URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&">Wall Street - Journal</ulink> spoke of <quote>balkanization</quote> of the + <link xlink:href="http://interactive.wsj.com/bin/login?Tag=/&URI=/archive/retrieve.cgi%253Fid%253DSB952470579348918651.djm&">Wall Street + Journal</link> spoke of <quote>balkanization</quote> of the BSD projects. Like the law suit, this perception bases mainly on ancient history.</para> </listitem> </orderedlist> </sect1> - <sect1 id="comparing-bsd-and-linux"> + <sect1 xml:id="comparing-bsd-and-linux"> <title>Comparing BSD and Linux</title> <para>So what is really the difference between, say, Debian Linux and @@ -269,8 +259,8 @@ <para>The BSD kernels are developed and updated following the Open Source development model. Each project maintains a publicly accessible <emphasis>source tree</emphasis> under the - <ulink url="http://www.cvshome.org/">Concurrent Versions - System</ulink> (CVS), which contains all source files for the + <link xlink:href="http://www.cvshome.org/">Concurrent Versions + System</link> (CVS), which contains all source files for the project, including documentation and other incidental files. CVS allows users to <quote>check out</quote> (in other words, to extract a copy of) any desired version of the system.</para> @@ -474,12 +464,11 @@ </listitem> <listitem> - <para><ulink url="http://www.apple.com/macosx/server/">&macos; - X</ulink> is the latest version of the operating system for - <ulink url="http://www.apple.com/">Apple Computer Inc.'s</ulink> + <para><link xlink:href="http://www.apple.com/macosx/server/">&macos; + X</link> is the latest version of the operating system for + <link xlink:href="http://www.apple.com/">Apple Computer Inc.'s</link> &macintosh; line. The BSD core of this operating - system, <ulink - url="http://developer.apple.com/darwin/">Darwin</ulink>, + system, <link xlink:href="http://developer.apple.com/darwin/">Darwin</link>, is available as a fully functional open source operating system for x86 and PPC computers. The Aqua/Quartz graphics system and many other proprietary aspects of @@ -495,13 +484,13 @@ license?</title> <para>Linux is available under the - <ulink url="http://www.fsf.org/copyleft/gpl.html">GNU General Public - License</ulink> (GPL), which is designed to eliminate closed + <link xlink:href="http://www.fsf.org/copyleft/gpl.html">GNU General Public + License</link> (GPL), which is designed to eliminate closed source software. In particular, any derivative work of a product released under the GPL must also be supplied with source code if requested. By contrast, the - <ulink url="http://www.opensource.org/licenses/bsd-license.html">BSD - license</ulink> is less restrictive: binary-only distributions are + <link xlink:href="http://www.opensource.org/licenses/bsd-license.html">BSD + license</link> is less restrictive: binary-only distributions are allowed. This is particularly attractive for embedded applications.</para> </sect2> @@ -578,15 +567,15 @@ <sect2> <title>Who provides support, service, and training for BSD?</title> - <para>BSDi / <ulink url="http://www.freebsdmall.com">FreeBSD - Mall, Inc.</ulink> have been providing support contracts for + <para>BSDi / <link xlink:href="http://www.freebsdmall.com">FreeBSD + Mall, Inc.</link> have been providing support contracts for FreeBSD for nearly a decade.</para> <para>In addition, each of the projects has a list of consultants for hire: - <ulink url="&url.base;/commercial/consult_bycat.html">FreeBSD</ulink>, - <ulink url="http://www.netbsd.org/gallery/consultants.html">NetBSD</ulink>, - and <ulink url="http://www.openbsd.org/support.html">OpenBSD</ulink>.</para> + <link xlink:href="&url.base;/commercial/consult_bycat.html">FreeBSD</link>, + <link xlink:href="http://www.netbsd.org/gallery/consultants.html">NetBSD</link>, + and <link xlink:href="http://www.openbsd.org/support.html">OpenBSD</link>.</para> </sect2> </sect1> </article> diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.xml b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.xml index 8adbfcb619..16ae1f14fe 100644 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/article.xml +++ b/en_US.ISO8859-1/articles/fbsd-from-scratch/article.xml @@ -1,26 +1,21 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ -<!ENTITY scratch.ap "<application>FreeBSD From Scratch</application>"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ +<!ENTITY scratch.ap "<application xmlns='http://docbook.org/ns/docbook'>FreeBSD From Scratch</application>"> ]> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD From Scratch</title> + -<article xmlns:xi="http://www.w3.org/2001/XInclude" lang='en'> - <articleinfo> - <title>FreeBSD From Scratch</title> - - <author> - <firstname>Jens</firstname> - <surname>Schweikhardt</surname> - <affiliation> + <author><personname><firstname>Jens</firstname><surname>Schweikhardt</surname></personname><affiliation> <address><email>schweikh@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2002,2003,2004,2008</year> <holder>Jens Schweikhardt</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.general; @@ -29,7 +24,6 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> <abstract> <para>This article describes my efforts at &scratch.ap;: a fully @@ -39,15 +33,16 @@ think <command>make world</command> is a wonderful concept, &scratch.ap; extends it to <command>make evenmore</command>.</para> </abstract> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>Have you ever upgraded your system with <command>make world</command>? There is a problem if you have only one system on your disks. If - the <maketarget>installworld</maketarget> fails partway through, + the <buildtarget>installworld</buildtarget> fails partway through, you are left with a broken system that might not even boot any - longer. Or maybe the <maketarget>installworld</maketarget> runs + longer. Or maybe the <buildtarget>installworld</buildtarget> runs smoothly but the new kernel does not boot. Then it is time to reach for the Fixit CD and dig for those backups you have taken half a year ago.</para> @@ -61,7 +56,7 @@ If you think that this task should be automated as well, read on.</para> </sect1> - <sect1 id="why"> + <sect1 xml:id="why"> <title>Why would I (not) want &scratch.ap;?</title> <para>This is a legitimate question. We have @@ -104,8 +99,8 @@ </itemizedlist> <para>The well known way to build and install the world, as - described in <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html">the - Handbook</ulink>, by default replaces + described in <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/makeworld.html">the + Handbook</link>, by default replaces the existing system. Only the kernel and modules are saved. System binaries, headers and a lot of other files are overwritten; obsolete files are still present and can cause surprises. If the @@ -148,8 +143,7 @@ you feel like an update is in order, you simply toggle the partitions you want to wipe and reinstall.</para> - <para>Maybe you have heard of or even tried <ulink - url="http://www.linuxfromscratch.org/">Linux From Scratch</ulink>, + <para>Maybe you have heard of or even tried <link xlink:href="http://www.linuxfromscratch.org/">Linux From Scratch</link>, or LFS for short. LFS also describes how to build and install a system from scratch in empty partitions using a running system. The focus in LFS seems to be to show the role of each system @@ -186,7 +180,7 @@ </itemizedlist> </sect1> - <sect1 id="prerequisites"> + <sect1 xml:id="prerequisites"> <title>Prerequisites</title> <para>For going the &scratch.ap; way, you need to have:</para> @@ -224,7 +218,7 @@ </itemizedlist> </sect1> - <sect1 id="stage1"> + <sect1 xml:id="stage1"> <title>Stage One: System Installation</title> <para>The first version of this article used a single shell script @@ -239,7 +233,7 @@ argument, like</para> <informalexample> - <screen>&prompt.root; <userinput>./stage_1.sh <replaceable>default</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>./stage_1.sh default</userinput></screen> </informalexample> <para>will read its configuration from @@ -292,7 +286,7 @@ call, these binaries will die with <literal>SIGSYS, Bad system call</literal>, because the old kernel does not have that system call. I have seen other issues when I tried - building <filename role="package">lang/perl5.8</filename>.</para> + building <package>lang/perl5.8</package>.</para> </listitem> </itemizedlist> @@ -312,7 +306,7 @@ <listitem> <para>successfully completed <command>make buildkernel - KERNCONF=<replaceable>whatever</replaceable></command></para> + KERNCONF=whatever</command></para> </listitem> </itemizedlist> @@ -376,16 +370,14 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput> <para>The answer does not matter since <filename>stage_1.sh</filename> will run &man.cap.mkdb.1; for you in any case.</para> - <para>Here is the author's <ulink - url="stage_1.conf.default"><filename>stage_1.conf.default</filename></ulink>, + <para>Here is the author's <link xlink:href="stage_1.conf.default"><filename>stage_1.conf.default</filename></link>, which you need to modify substantially. The comments give you enough information what to change.</para> -<programlisting><xi:include href="stage_1.conf.default" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_1.conf.default" parse="text"/></programlisting> - <para>Download <ulink - url="stage_1.conf.default"><filename>stage_1.conf.default</filename> - </ulink>.</para> + <para>Download <link xlink:href="stage_1.conf.default"><filename>stage_1.conf.default</filename> + </link>.</para> <para>Running this script installs a system that when booted provides:</para> @@ -414,7 +406,7 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput> libraries and programs.</para> </sect1> - <sect1 id="stage2"> + <sect1 xml:id="stage2"> <title>Stage Two: Ports Installation</title> <note> @@ -434,7 +426,7 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput> with exactly one argument to denote a config file, e.g.</para> <informalexample> - <screen>&prompt.root; <userinput>./stage_2.sh <replaceable>default</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>./stage_2.sh default</userinput></screen> </informalexample> <para>which will read the list of ports from @@ -454,14 +446,14 @@ Do you wish to delete what is left of /var/tmp/temproot.stage1? [no] <userinput> <para>In fact you can specify arbitrary shell commands, so you are not restricted to simple <command>make</command> invocations:</para> - <programlisting>java jdk16 echo true > files/license.sh; make install BATCH=yes < /dev/null + <programlisting>java jdk16 echo true > files/license.sh; make install BATCH=yes < /dev/null print acroread8 yes accept | make install PAGER=ls x11-fonts gnu-unifont make install && mkfontdir /usr/local/lib/X11/fonts/local news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install</programlisting> <para>The first two lines are examples how you can handle ports asking you to accept a licence. Note how the line for - <filename role="package">news/inn-stable</filename> is an example + <package>news/inn-stable</package> is an example for a one-shot shell variable assignment to <literal>CONFIGURE_ARGS</literal>. The port <filename>Makefile</filename> will use this as an initial value @@ -485,13 +477,12 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" <filename>LOGDIR/category+port</filename> is created for each port it actually installs.</para> -<programlisting><xi:include href="stage_2.conf.default" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_2.conf.default" parse="text"/></programlisting> - <para>Download <ulink - url="stage_2.conf.default"><filename>stage_2.conf.default</filename></ulink>.</para> + <para>Download <link xlink:href="stage_2.conf.default"><filename>stage_2.conf.default</filename></link>.</para> </sect1> - <sect1 id="stage3"> + <sect1 xml:id="stage3"> <title>Stage Three</title> <para>You have installed your beloved ports during stage two. Some @@ -507,7 +498,7 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" what you want to configure simply by running:</para> <informalexample> - <screen>&prompt.root; <userinput>make -f stage_3.mk <replaceable>target</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make -f stage_3.mk target</userinput></screen> </informalexample> <para>As with <filename>stage_2.sh</filename> make sure you have @@ -516,7 +507,7 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" somewhere on the new system.</para> </sect1> - <sect1 id="limitations"> + <sect1 xml:id="limitations"> <title>Limitations</title> <para>The automated installation of a port may prove difficult if it @@ -528,8 +519,8 @@ news inn-stable CONFIGURE_ARGS="--enable-uucp-rnews --enable-setgid-inews" make install</command>. For other ports you need to investigate where exactly the interactive command is located and deal with it appropriately. See the examples above for - <filename role="package">print/acroread8</filename> and - <filename role="package">java/jdk16</filename>.</para> + <package>print/acroread8</package> and + <package>java/jdk16</package>.</para> <para>You should also be aware of upgrade issues for config files. In general you do not know when and if the format or contents of a @@ -576,39 +567,33 @@ fi </sect1> - <sect1 id="files"> + <sect1 xml:id="files"> <title>The Files</title> <para>Here are the three files you need beside the config files already shown above.</para> - <para>This is the <ulink - url="stage_1.sh"><filename>stage_1.sh</filename></ulink> + <para>This is the <link xlink:href="stage_1.sh"><filename>stage_1.sh</filename></link> script, which you should not need to modify.</para> -<programlisting><xi:include href="stage_1.sh" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_1.sh" parse="text"/></programlisting> - <para>Download <ulink - url="stage_1.sh"><filename>stage_1.sh</filename></ulink>.</para> + <para>Download <link xlink:href="stage_1.sh"><filename>stage_1.sh</filename></link>.</para> - <para>This is the <ulink - url="stage_2.sh"><filename>stage_2.sh</filename></ulink> + <para>This is the <link xlink:href="stage_2.sh"><filename>stage_2.sh</filename></link> script. You may want to modify the variables at the beginning.</para> -<programlisting><xi:include href="stage_2.sh" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_2.sh" parse="text"/></programlisting> - <para>Download <ulink - url="stage_2.sh"><filename>stage_2.sh</filename></ulink>.</para> + <para>Download <link xlink:href="stage_2.sh"><filename>stage_2.sh</filename></link>.</para> - <para>This is my <ulink - url="stage_3.mk"><filename>stage_3.mk</filename></ulink> to + <para>This is my <link xlink:href="stage_3.mk"><filename>stage_3.mk</filename></link> to give you an idea how to automate all reconfiguration.</para> -<programlisting><xi:include href="stage_3.mk" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="stage_3.mk" parse="text"/></programlisting> - <para>Download <ulink - url="stage_3.mk"><filename>stage_3.mk</filename></ulink>.</para> + <para>Download <link xlink:href="stage_3.mk"><filename>stage_3.mk</filename></link>.</para> </sect1> </article> diff --git a/en_US.ISO8859-1/articles/filtering-bridges/article.xml b/en_US.ISO8859-1/articles/filtering-bridges/article.xml index bf122f7872..efc0542f48 100644 --- a/en_US.ISO8859-1/articles/filtering-bridges/article.xml +++ b/en_US.ISO8859-1/articles/filtering-bridges/article.xml @@ -1,22 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Filtering Bridges</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Filtering Bridges</title> + <authorgroup> - <author> - <firstname>Alex</firstname> - <surname>Dupre</surname> - <affiliation> + <author><personname><firstname>Alex</firstname><surname>Dupre</surname></personname><affiliation> <address><email>ale@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.intel; @@ -41,9 +36,9 @@ segments. Under many points of view a bridge is similar to an Ethernet switch with only two ports.</para> </abstract> - </articleinfo> + </info> - <sect1 id="filtering-bridges-why"> + <sect1 xml:id="filtering-bridges-why"> <title>Why use a filtering bridge?</title> <para>More and more frequently, thanks to the lowering costs of broad band @@ -63,7 +58,7 @@ issues.</para> </sect1> - <sect1 id="filtering-bridges-how"> + <sect1 xml:id="filtering-bridges-how"> <title>How to Install</title> <para>Adding bridge functionalities to a FreeBSD system is not difficult. @@ -89,7 +84,7 @@ which interface is connected to the router and which to the inner network.</para> - <sect2 id="filtering-bridges-kernel"> + <sect2 xml:id="filtering-bridges-kernel"> <title>Kernel Configuration</title> <para>So you have decided to use the older but well tested installation @@ -105,13 +100,12 @@ options IPFIREWALL_VERBOSE</programlisting> firewall.</para> <para>Now it is necessary to build and install the new kernel. You may - find detailed instructions in the <ulink - url="&url.books.handbook;/kernelconfig-building.html">Building - and Installing a Custom Kernel</ulink> section of the FreeBSD + find detailed instructions in the <link xlink:href="&url.books.handbook;/kernelconfig-building.html">Building + and Installing a Custom Kernel</link> section of the FreeBSD Handbook.</para> </sect2> - <sect2 id="filtering-bridges-modules"> + <sect2 xml:id="filtering-bridges-modules"> <title>Modules Loading</title> <para>If you have chosen to use the new and simpler installation @@ -129,7 +123,7 @@ options IPFIREWALL_VERBOSE</programlisting> </sect2> </sect1> - <sect1 id="filtering-bridges-finalprep"> + <sect1 xml:id="filtering-bridges-finalprep"> <title>Final Preparation</title> <para>Before rebooting in order to load the new kernel or the required @@ -164,9 +158,9 @@ firewall_logging="YES"</programlisting> assign an IP to the external interface (the one connected to Internet, where <acronym>DNS</acronym> server resides), since the bridge will be activated at the end of the startup procedure. It means that the - <devicename>fxp0</devicename> interface (in our case) must be mentioned + <filename>fxp0</filename> interface (in our case) must be mentioned in the ifconfig section of the <filename>/etc/rc.conf</filename> file, - while the <devicename>xl0</devicename> is not. Assigning an IP to both + while the <filename>xl0</filename> is not. Assigning an IP to both the network cards does not make much sense, unless, during the start procedure, applications should access to services on both Ethernet segments.</para> @@ -193,13 +187,13 @@ firewall_logging="YES"</programlisting> before proceeding.</para> </sect1> - <sect1 id="filtering-bridges-enabling"> + <sect1 xml:id="filtering-bridges-enabling"> <title>Enabling the Bridge</title> <para>At this point, to enable the bridge, you have to execute the following commands (having the shrewdness to replace the names of the - two network interfaces <devicename>fxp0</devicename> and - <devicename>xl0</devicename> with your own ones):</para> + two network interfaces <filename>fxp0</filename> and + <filename>xl0</filename> with your own ones):</para> <screen>&prompt.root; <userinput>sysctl net.link.ether.bridge.config=fxp0:0,xl0:0</userinput> &prompt.root; <userinput>sysctl net.link.ether.bridge.ipfw=1</userinput> @@ -217,12 +211,12 @@ firewall_logging="YES"</programlisting> <para>At this point you should be able to insert the machine between two sets of hosts without compromising any communication abilities between them. If so, the next step is to add the - <literal>net.link.ether.bridge.<replaceable>[blah]</replaceable>=<replaceable>[blah]</replaceable></literal> + <literal>net.link.ether.bridge.[blah]=[blah]</literal> portions of these rows to the <filename>/etc/sysctl.conf</filename> file, in order to have them execute at startup.</para> </sect1> - <sect1 id="filtering-bridges-ipfirewall"> + <sect1 xml:id="filtering-bridges-ipfirewall"> <title>Configuring The Firewall</title> <para>Now it is time to create your own file with custom firewall rules, @@ -257,7 +251,7 @@ firewall_logging="YES"</programlisting> <para>Let's look at an example setup. Note first that at the top of <filename>/etc/rc.firewall</filename> there are already standard rules - for the loopback interface <devicename>lo0</devicename>, so we should not + for the loopback interface <filename>lo0</filename>, so we should not have to care for them anymore. Custom rules should be put in a separate file (say <filename>/etc/rc.firewall.local</filename>) and loaded at system startup, by modifying the row of @@ -272,11 +266,10 @@ firewall_logging="YES"</programlisting> network.</para> </important> - <para>For our example imagine to have the <devicename>fxp0</devicename> + <para>For our example imagine to have the <filename>fxp0</filename> interface connected towards the outside (Internet) and the - <devicename>xl0</devicename> towards the inside - (<acronym>LAN</acronym>). The bridge machine has the IP <hostid - role="ipaddr">1.2.3.4</hostid> (it is not possible that your + <filename>xl0</filename> towards the inside + (<acronym>LAN</acronym>). The bridge machine has the IP <systemitem class="ipaddress">1.2.3.4</systemitem> (it is not possible that your <acronym>ISP</acronym> can give you an address quite like this, but for our example it is good).</para> @@ -374,13 +367,13 @@ add drop log all from any to any</programlisting> packet filter. The inside net will go through the bridge, while the local machine will use the normal IP stack to speak. Thus the two rules to handle the different cases. The <literal>in via - <devicename>fxp0</devicename></literal> rules work for both paths. In general, if + fxp0</literal> rules work for both paths. In general, if you use <option>in via</option> rules throughout the filter, you will need to make an exception for locally generated packets, because they did not come in via any of our interfaces.</para> </sect1> - <sect1 id="filtering-bridges-contributors"> + <sect1 xml:id="filtering-bridges-contributors"> <title>Contributors</title> <para>Many parts of this article have been taken, updated and adapted from diff --git a/en_US.ISO8859-1/articles/fonts/article.xml b/en_US.ISO8859-1/articles/fonts/article.xml index 8715ce7311..e2fbf32499 100644 --- a/en_US.ISO8859-1/articles/fonts/article.xml +++ b/en_US.ISO8859-1/articles/fonts/article.xml @@ -1,10 +1,8 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- The FreeBSD Documentation Project --> - <!-- Recently, I wanted to figure out how to use some additional fonts that I had accumulated. I finally figured out *how to do it* from the various manual pages and documentation. Since it might be of use to other users, @@ -21,37 +19,29 @@ it is pretty raw. There are probably better ways to do some of this stuff, and I would welcome being corrected. --> - <!-- The section "Setting a virtual console to 80x60 line mode" was updated to reflect changes in FreeBSD system configuration files by Mark Ovens <mark@ukug.uk.FreeBSD.org> 27/5/00 --> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Fonts and FreeBSD</title><subtitle>A Tutorial</subtitle> + -<article lang='en'> - <articleinfo> - <title>Fonts and FreeBSD</title> - - <subtitle>A Tutorial</subtitle> + <authorgroup> - <author> - <firstname>Dave</firstname> - - <surname>Bodenstab</surname> - - <affiliation> + <author><personname><firstname>Dave</firstname><surname>Bodenstab</surname></personname><affiliation> <address> <email>imdave@synet.net</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> <pubdate>Wed Aug 7, 1996</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.apple; @@ -69,9 +59,9 @@ for switching the syscons display to 80x60 mode, and for using type 1 fonts with the above application programs.</para> </abstract> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction</title> <para>There are many sources of fonts available, and one might ask @@ -82,7 +72,7 @@ might be interested.</para> </sect1> - <sect1 id="terminology"> + <sect1 xml:id="terminology"> <title>Basic terminology</title> <para>There are many different font formats and associated font @@ -151,7 +141,7 @@ this font format with FreeBSD.</para> </sect1> - <sect1 id="font-formats"> + <sect1 xml:id="font-formats"> <title>What font formats can I use?</title> <para>Which font file format is useful depends on the application @@ -234,7 +224,7 @@ other than those provided with FreeBSD.</para> </sect1> - <sect1 id="virtual-console"> + <sect1 xml:id="virtual-console"> <title>Setting a virtual console to 80x60 line mode</title> <para>First, an 8x8 font must be loaded. To do this, @@ -272,7 +262,7 @@ <para>References: &man.rc.conf.5;, &man.vidcontrol.1;.</para> </sect1> - <sect1 id="type1-fonts-x11"> + <sect1 xml:id="type1-fonts-x11"> <title>Using type 1 fonts with <application>X11</application></title> <para><application>X11</application> can use either the <filename>.pfa</filename> or the @@ -398,9 +388,7 @@ end readonly def <term>Slant</term> <listitem> - <para><emphasis remap="bf">r</emphasis>oman, <emphasis - remap="bf">i</emphasis>talic, <emphasis - remap="bf">o</emphasis>blique, etc. Since the + <para><emphasis remap="bf">r</emphasis>oman, <emphasis remap="bf">i</emphasis>talic, <emphasis remap="bf">o</emphasis>blique, etc. Since the <emphasis>ItalicAngle</emphasis> is zero, <emphasis>roman</emphasis> will be used.</para> </listitem> @@ -472,7 +460,7 @@ showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 . :wq</userinput> -<lineannotation><filename>fonts.scale</filename> seems to be identical to <filename>fonts.dir</filename>…</lineannotation> +<lineannotation>fonts.scale seems to be identical to fonts.dir…</lineannotation> &prompt.user; <userinput>cp fonts.dir fonts.scale</userinput> <lineannotation>Tell X11 that things have changed</lineannotation> @@ -483,12 +471,11 @@ showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 </informalexample> <para>References: &man.xfontsel.1;, &man.xset.1;, <citetitle>The X - Windows System in a Nutshell</citetitle>, <ulink - url="http://www.ora.com/">O'Reilly & - Associates</ulink>.</para> + Windows System in a Nutshell</citetitle>, <link xlink:href="http://www.ora.com/">O'Reilly & + Associates</link>.</para> </sect1> - <sect1 id="type1-fonts-ghostscript"> + <sect1 xml:id="type1-fonts-ghostscript"> <title>Using type 1 fonts with Ghostscript</title> <para><application>Ghostscript</application> references a font via its <filename>Fontmap</filename> @@ -532,7 +519,7 @@ GS><userinput>quit</userinput></screen> <application>Ghostscript 4.01</application> distribution</para> </sect1> - <sect1 id="type1-fonts-groff"> + <sect1 xml:id="type1-fonts-groff"> <title>Using type 1 fonts with Groff</title> <para>Now that the new font can be used by both <application>X11</application> and @@ -566,7 +553,7 @@ GS><userinput>quit</userinput></screen> example:</para> <informalexample> - <screen><lineannotation>Many <filename>.afm</filename> files are in Mac format… ^M delimited lines + <screen><lineannotation>Many .afm files are in Mac format… ^M delimited lines We need to convert them to &unix; style ^J delimited lines</lineannotation> &prompt.user; <userinput>cd /tmp</userinput> &prompt.user; <userinput>cat /usr/local/share/fonts/type1/showboat.afm | @@ -594,7 +581,7 @@ We need to convert them to &unix; style ^J delimited lines</lineannotation> the groff font file as illustrated:</para> <informalexample> - <screen><lineannotation>Create the <filename>.pfa</filename> font file</lineannotation> + <screen><lineannotation>Create the .pfa font file</lineannotation> &prompt.user; <userinput>pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa</userinput></screen> </informalexample> @@ -658,7 +645,7 @@ EOF</userinput> &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;.</para> </sect1> - <sect1 id="convert-truetype"> + <sect1 xml:id="convert-truetype"> <title>Converting TrueType fonts to a groff/PostScript format for groff</title> @@ -675,8 +662,7 @@ EOF</userinput> allows conversion of a TrueType font to an ascii font metric (<filename>.afm</filename>) file.</para> - <para>Currently available at <ulink - url="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/"></ulink>. + <para>Currently available at <uri xlink:href="http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/">http://sunsite.icm.edu.pl/pub/GUST/contrib/BachoTeX98/ttf2pf/</uri>. Note: These files are PostScript programs and must be downloaded to disk by holding down the <keycap>Shift</keycap> key when clicking on the link. @@ -752,7 +738,7 @@ EOF</userinput> <para>Create the <filename>.afm</filename> file by typing:</para> - <screen><prompt>%</prompt> <userinput>gs <optional>-dNODISPLAY</optional> <optional>-q</optional> -- ttf2pf.ps <replaceable>TTF_name</replaceable> <optional><replaceable>PS_font_name</replaceable> <optional><replaceable>AFM_name</replaceable></optional></optional></userinput> + <screen><prompt>%</prompt> <userinput>gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name</userinput> </screen> <para>Where, <replaceable>TTF_name</replaceable> is your @@ -806,7 +792,7 @@ Converting 3of9.ttf to A.pfa and B.afm. directory.)</para> <screen><prompt>%</prompt> <userinput>afmtodit -d DESC -e text.enc file.afm \ - generate/textmap <replaceable>PS_font_name</replaceable></userinput> + generate/textmap PS_font_name</userinput> </screen> <para>Where, <filename>file.afm</filename> is the @@ -841,7 +827,7 @@ Converting 3of9.ttf to A.pfa and B.afm. </orderedlist> </sect1> - <sect1 id="truetype-for-other-programs"> + <sect1 xml:id="truetype-for-other-programs"> <title>Can TrueType fonts be used with other programs?</title> <para>The TrueType font format is used by Windows, Windows 95, and @@ -857,8 +843,7 @@ Converting 3of9.ttf to A.pfa and B.afm. fonts, but I rather doubt many people will be creating documents as a series of raytraced pages :-).</para> - <para>This rather dismal situation may soon change. The <ulink - url="http://www.freetype.org/">FreeType Project</ulink> is + <para>This rather dismal situation may soon change. The <link xlink:href="http://www.freetype.org/">FreeType Project</link> is currently developing a useful set of FreeType tools:</para> <itemizedlist> @@ -867,26 +852,22 @@ Converting 3of9.ttf to A.pfa and B.afm. <para>The <command>xfsft</command> font server for <application>X11</application> can serve TrueType fonts in addition to regular fonts. Though currently in beta, it is said to be quite usable. See - <ulink - url="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz - Chroboczek's page</ulink> for further information. - Porting instructions for FreeBSD can be found at <ulink - url="http://math.missouri.edu/~stephen/software/">Stephen - Montgomery's software page</ulink>.</para> + <link xlink:href="http://www.dcs.ed.ac.uk/home/jec/programs/xfsft/">Juliusz + Chroboczek's page</link> for further information. + Porting instructions for FreeBSD can be found at <link xlink:href="http://math.missouri.edu/~stephen/software/">Stephen + Montgomery's software page</link>.</para> </listitem> <listitem> <para><application>xfstt</application> is another font server for <application>X11</application>, - available under <ulink url=" - ftp://sunsite.unc.edu/pub/Linux/X11/fonts/"></ulink>.</para> + available under <uri xlink:href=" ftp://sunsite.unc.edu/pub/Linux/X11/fonts/"> ftp://sunsite.unc.edu/pub/Linux/X11/fonts/</uri>.</para> </listitem> <listitem> <para>A program called <command>ttf2bdf</command> can produce BDF files suitable for use in an X environment from TrueType - files. Linux binaries are said to be available from <ulink - url="ftp://crl.nmsu.edu/CLR/multiling/General/"></ulink>.</para> + files. Linux binaries are said to be available from <uri xlink:href="ftp://crl.nmsu.edu/CLR/multiling/General/">ftp://crl.nmsu.edu/CLR/multiling/General/</uri>.</para> </listitem> <listitem> @@ -895,7 +876,7 @@ Converting 3of9.ttf to A.pfa and B.afm. </itemizedlist> </sect1> - <sect1 id="obtaining-additional-fonts"> + <sect1 xml:id="obtaining-additional-fonts"> <title>Where can additional fonts be obtained?</title> <para>Many fonts are available on the Internet. They are either @@ -905,11 +886,11 @@ Converting 3of9.ttf to A.pfa and B.afm. <itemizedlist> <listitem> - <para><ulink url="http://www.simtel.net/"></ulink></para> + <para><uri xlink:href="http://www.simtel.net/">http://www.simtel.net/</uri></para> </listitem> <listitem> - <para><ulink url="http://www.freshmeat.net/"></ulink></para> + <para><uri xlink:href="http://www.freshmeat.net/">http://www.freshmeat.net/</uri></para> </listitem> <listitem> @@ -919,7 +900,7 @@ Converting 3of9.ttf to A.pfa and B.afm. </itemizedlist> </sect1> - <sect1 id="additional-questions"> + <sect1 xml:id="additional-questions"> <title>Additional questions</title> <itemizedlist> diff --git a/en_US.ISO8859-1/articles/freebsd-questions/article.xml b/en_US.ISO8859-1/articles/freebsd-questions/article.xml index 0ea4545f87..824800c866 100644 --- a/en_US.ISO8859-1/articles/freebsd-questions/article.xml +++ b/en_US.ISO8859-1/articles/freebsd-questions/article.xml @@ -1,22 +1,16 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>How to get best results from the FreeBSD-questions mailing +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>How to get best results from the FreeBSD-questions mailing list</title> + - <author> - <firstname>Greg</firstname> - <surname>Lehey</surname> - - <affiliation> + <author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><affiliation> <address><email>grog@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.microsoft; &tm-attrib.opengroup; @@ -37,10 +31,10 @@ <para>This document is regularly posted to the FreeBSD-questions mailing list.</para> </abstract> - </articleinfo> + </info> <sect1> - <title id="Introduction">Introduction</title> + <title xml:id="Introduction">Introduction</title> <para><literal>FreeBSD-questions</literal> is a mailing list maintained by the FreeBSD project to help people who have questions about the normal @@ -54,9 +48,8 @@ activity is <quote>cracker</quote>, but the popular press has not found out yet. The FreeBSD hackers disapprove strongly of cracking security, and have nothing to do with it. For a longer description of - hackers, see Eric Raymond's <ulink - url="http://www.catb.org/~esr/faqs/hacker-howto.html">How To Become - A Hacker</ulink></para> + hackers, see Eric Raymond's <link xlink:href="http://www.catb.org/~esr/faqs/hacker-howto.html">How To Become + A Hacker</link></para> </note> <para>This is a regular posting aimed to help both those seeking advice @@ -78,10 +71,10 @@ </sect1> <sect1> - <title id="subscribe">How to subscribe to FreeBSD-questions</title> + <title xml:id="subscribe">How to subscribe to FreeBSD-questions</title> <para>FreeBSD-questions is a mailing list, so you need mail access. Point - your WWW browser to the <ulink url="&a.questions.url;">information page of the FreeBSD-questions mailing list</ulink>. + your WWW browser to the <link xlink:href="&a.questions.url;">information page of the FreeBSD-questions mailing list</link>. In the section titled <quote>Subscribing to freebsd-questions</quote> fill in the <quote>Your email address</quote> field; the other fields are optional. </para> @@ -105,7 +98,7 @@ </sect1> <sect1> - <title id="unsubscribe">How to unsubscribe from FreeBSD-questions</title> + <title xml:id="unsubscribe">How to unsubscribe from FreeBSD-questions</title> <para>When you subscribed to FreeBSD-questions, you got a welcome message from <application>mailman</application>. In this message, amongst @@ -163,7 +156,7 @@ your options page that will email your current password to you.</literallayout> </sect1> <sect1> - <title id="askwho">Should I ask <literal>-questions</literal> or + <title xml:id="askwho">Should I ask <literal>-questions</literal> or <literal>-hackers</literal>?</title> <para>Two mailing lists handle general questions about FreeBSD, @@ -211,7 +204,7 @@ your options page that will email your current password to you.</literallayout> </sect1> <sect1> - <title id="before">Before submitting a question</title> + <title xml:id="before">Before submitting a question</title> <para>You can (and should) do some things yourself before asking a question on one of the mailing lists:</para> @@ -230,9 +223,9 @@ your options page that will email your current password to you.</literallayout> <listitem> <para>Read the manual pages, and the FreeBSD documentation (either installed in <filename>/usr/doc</filename> or accessible via WWW at - <ulink url="http://www.FreeBSD.org"></ulink>), especially the - <ulink url="&url.books.handbook;/index.html">handbook</ulink> - and the <ulink url="&url.books.faq;/index.html">FAQ</ulink>. + <uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>), especially the + <link xlink:href="&url.books.handbook;/index.html">handbook</link> + and the <link xlink:href="&url.books.faq;/index.html">FAQ</link>. </para> </listitem> @@ -240,25 +233,24 @@ your options page that will email your current password to you.</literallayout> <para>Browse and/or search the archives for the mailing list, to see if your question or a similar one has been asked (and possibly answered) on the list. You can browse and/or search the mailing list archives - at <ulink url="http://www.FreeBSD.org/mail"></ulink> - and <ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink> + at <uri xlink:href="http://www.FreeBSD.org/mail">http://www.FreeBSD.org/mail</uri> + and <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri> respectively. This can be done at other WWW sites as well, for example - at <ulink url="http://marc.theaimsgroup.com"></ulink>. + at <uri xlink:href="http://marc.theaimsgroup.com">http://marc.theaimsgroup.com</uri>. </para> </listitem> <listitem> - <para>Use a search engine such as <ulink url="http://www.google.com">Google</ulink> - or <ulink url="http://www.yahoo.com">Yahoo</ulink> to find answers to your question. - Google even has a <ulink - url="http://www.google.com/bsd">BSD-specific search interface</ulink>. + <para>Use a search engine such as <link xlink:href="http://www.google.com">Google</link> + or <link xlink:href="http://www.yahoo.com">Yahoo</link> to find answers to your question. + Google even has a <link xlink:href="http://www.google.com/bsd">BSD-specific search interface</link>. </para> </listitem> </itemizedlist> </sect1> <sect1> - <title id="submit">How to submit a question</title> + <title xml:id="submit">How to submit a question</title> <para>When submitting a question to FreeBSD-questions, consider the following points:</para> @@ -301,8 +293,8 @@ your options page that will email your current password to you.</literallayout> errors, it will give people a poor impression of you.</para> <para>A lot of badly formatted messages come from - <ulink url="http://www.lemis.com/email.html">bad mailers or badly - configured mailers</ulink>. The following mailers are known to + <link xlink:href="http://www.lemis.com/email.html">bad mailers or badly + configured mailers</link>. The following mailers are known to send out badly formatted messages without you finding out about them:</para> @@ -459,7 +451,7 @@ fine, but when I try to reboot the system, I get the message </sect1> <sect1> - <title id="followup">How to follow up to a question</title> + <title xml:id="followup">How to follow up to a question</title> <para>Often you will want to send in additional information to a question you have already sent. The best way to do this is to reply to your @@ -481,7 +473,7 @@ fine, but when I try to reboot the system, I get the message <listitem> <para>The message reference numbers in the header will refer to the previous message. Some mailers, such as - <ulink url="http://www.mutt.org/">mutt</ulink>, can + <link xlink:href="http://www.mutt.org/">mutt</link>, can <emphasis>thread</emphasis> messages, showing the exact relationships between the messages.</para> </listitem> @@ -489,7 +481,7 @@ fine, but when I try to reboot the system, I get the message </sect1> <sect1> - <title id="answer">How to answer a question</title> + <title xml:id="answer">How to answer a question</title> <para>Before you answer a question to FreeBSD-questions, consider:</para> diff --git a/en_US.ISO8859-1/articles/freebsd-update-server/article.xml b/en_US.ISO8859-1/articles/freebsd-update-server/article.xml index 0a760f67ca..60e14c8010 100644 --- a/en_US.ISO8859-1/articles/freebsd-update-server/article.xml +++ b/en_US.ISO8859-1/articles/freebsd-update-server/article.xml @@ -1,20 +1,15 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ -<!ENTITY fbus.ap "<application>FreeBSD Update Server</application>"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ +<!ENTITY fbus.ap "<application xmlns='http://docbook.org/ns/docbook'>FreeBSD Update Server</application>"> ]> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Build Your Own &os; Update Server</title> + -<article lang="en"> - <articleinfo> - <title>Build Your Own &os; Update Server</title> - - <author> - <firstname>Jason</firstname> - <surname>Helfman</surname> - <affiliation> + <author><personname><firstname>Jason</firstname><surname>Helfman</surname></personname><affiliation> <address>&a.jgh.email;</address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2009</year> @@ -24,7 +19,7 @@ <holder role="mailto:jgh@FreeBSD.org">Jason Helfman</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; &tm-attrib.intel; @@ -34,12 +29,10 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> <abstract> <para>This article describes building an internal &fbus.ap;. - The <ulink - url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</ulink> + The <link xlink:href="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</link> is written by &a.cperciva.email;, Security Officer Emeritus of &os;. For users that think it is convenient to update their systems against an official update server, building their own &fbus.ap; may @@ -47,15 +40,15 @@ &os; releases or by providing a local mirror that will allow faster updates for a number of machines.</para> </abstract> + </info> - <sect1 id="acknowledgments"> + <sect1 xml:id="acknowledgments"> <title>Acknowledgments</title> - <para>This article was subsequently printed at <ulink - url="http://bsdmag.org/magazine/1021-bsd-as-a-desktop">BSD - Magazine</ulink>.</para> + <para>This article was subsequently printed at <link xlink:href="http://bsdmag.org/magazine/1021-bsd-as-a-desktop">BSD + Magazine</link>.</para> </sect1> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>Experienced users or administrators are often responsible for @@ -69,7 +62,7 @@ &fbus.ap;.</para> </sect1> - <sect1 id="prerequisites"> + <sect1 xml:id="prerequisites"> <title>Prerequisites</title> <para>To build an internal &fbus.ap; some requirements should be @@ -98,8 +91,7 @@ </listitem> <listitem> - <para>A web server, like <ulink - url="&url.books.handbook;/network-apache.html">Apache</ulink>, + <para>A web server, like <link xlink:href="&url.books.handbook;/network-apache.html">Apache</link>, with over half of the space required for the build. For instance, test builds for 7.1 and 7.2 consume a total amount of 4 GB, and the webserver space needed to distribute these updates is @@ -113,13 +105,11 @@ </itemizedlist> </sect1> - <sect1 id="Configuration"> + <sect1 xml:id="Configuration"> <title>Configuration: Installation & Setup</title> - <para>Download the <ulink - url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/"> - freebsd-update-server</ulink> software by installing <filename - role="package">devel/subversion </filename>, and execute:</para> + <para>Download the <link xlink:href="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/"> + freebsd-update-server</link> software by installing <package>devel/subversion </package>, and execute:</para> <screen>&prompt.user; <userinput>svn co http://svn.freebsd.org/base/user/cperciva/freebsd-update-build freebsd-update-server</userinput></screen> @@ -137,22 +127,22 @@ # the scripts tree. # Location from which to fetch releases -export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases<co id="ftp-id"/> +export FTP=ftp://ftp2.freebsd.org/pub/FreeBSD/releases<co xml:id="ftp-id"/> # Host platform export HOSTPLATFORM=`uname -m` # Host name to use inside jails -export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net<co id="buildhost-id"/> +export BUILDHOSTNAME=${HOSTPLATFORM}-builder.daemonology.net<co xml:id="buildhost-id"/> # Location of SSH key -export SSHKEY=/root/.ssh/id_dsa<co id="sshkey-id"/> +export SSHKEY=/root/.ssh/id_dsa<co xml:id="sshkey-id"/> # SSH account into which files are uploaded -MASTERACCT=builder@wadham.daemonology.net<co id="mstacct-id"/> +MASTERACCT=builder@wadham.daemonology.net<co xml:id="mstacct-id"/> # Directory into which files are uploaded -MASTERDIR=update-master.freebsd.org<co id="mstdir-id"/></programlisting> +MASTERDIR=update-master.freebsd.org<co xml:id="mstdir-id"/></programlisting> </informalexample> <para>Parameters for consideration would be:</para> @@ -228,7 +218,7 @@ MASTERDIR=update-master.freebsd.org<co id="mstdir-id"/></programlisting> <informalexample> <programlisting># SHA256 hash of RELEASE disc1.iso image. -export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5<co id="sha256-id"/> +export RELH=1ea1f6f652d7c5f5eab7ef9f8edbed50cb664b08ed761850f95f48e86cc71ef5<co xml:id="sha256-id"/> # Components of the world, source, and kernels export WORLDPARTS="base catpages dict doc games info manpages proflibs lib32" @@ -238,22 +228,20 @@ export SOURCEPARTS="base bin contrib crypto etc games gnu include krb5 \ export KERNELPARTS="generic" # EOL date -export EOL=1275289200<co id="eol-id"/></programlisting> +export EOL=1275289200<co xml:id="eol-id"/></programlisting> </informalexample> <calloutlist> <callout arearefs="sha256-id"> <para>The &man.sha256.1; hash key for the desired release, is - published within the respective <ulink - url="&url.base;/releases/">release announcement</ulink>.</para> + published within the respective <link xlink:href="&url.base;/releases/">release announcement</link>.</para> </callout> <callout arearefs="eol-id"> <para>To generate the "End of Life" number for <filename>build.conf</filename>, refer to the "Estimated - EOL" posted on the <ulink - url="&url.base;/security/security.html">&os; - Security Website</ulink>. The value + EOL" posted on the <link xlink:href="&url.base;/security/security.html">&os; + Security Website</link>. The value of <literal>EOL</literal> can be derived from the date listed on the web site, using the &man.date.1; utility, for example:</para> <screen>&prompt.user; <userinput>date -j -f '%Y%m%d-%H%M%S' '20090401-000000' '+%s'</userinput></screen> @@ -263,7 +251,7 @@ export EOL=1275289200<co id="eol-id"/></programlisting> </procedure> </sect1> - <sect1 id="build"> + <sect1 xml:id="build"> <title>Building Update Code</title> <para>The first step is to run <filename>scripts/make.sh</filename>. @@ -301,7 +289,7 @@ Verifying - enter aes-256-cbc encryption password:</screen> <informalexample> <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput> -&prompt.root; <userinput>sh scripts/init.sh <replaceable>amd64 7.2-RELEASE</replaceable></userinput></screen> +&prompt.root; <userinput>sh scripts/init.sh amd64 7.2-RELEASE</userinput></screen> </informalexample> <para>What follows is a sample of an <emphasis>initial</emphasis> build @@ -353,8 +341,7 @@ world|base|/usr/lib/libalias_ftp.a <warning> <para>During this second build cycle, the network time protocol daemon, &man.ntpd.8;, is turned off. Per &a.cperciva.email;, - Security Officer Emeritus of &os;, "the <ulink - url="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</ulink> + Security Officer Emeritus of &os;, "the <link xlink:href="http://svnweb.freebsd.org/base/user/cperciva/freebsd-update-build/">freebsd-update-server</link> build code needs to identify timestamps which are stored in files so that they can be ignored when comparing builds to determine which files need to be updated. This timestamp-finding works by doing two @@ -454,7 +441,7 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE <informalexample> <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput> -&prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 7.2-RELEASE</replaceable></userinput></screen> +&prompt.root; <userinput>sh scripts/upload.sh amd64 7.2-RELEASE</userinput></screen> </informalexample> <note> @@ -464,8 +451,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE <emphasis>uploaded</emphasis> file.</para> <informalexample> - <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server/pub/<replaceable>7.2-RELEASE/amd64</replaceable></userinput> -&prompt.root; <userinput>touch -t <replaceable>200801010101.01</replaceable> uploaded</userinput></screen> + <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server/pub/7.2-RELEASE/amd64</userinput> +&prompt.root; <userinput>touch -t 200801010101.01 uploaded</userinput></screen> </informalexample> </note> @@ -477,9 +464,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE document root of the webserver in order for updates to be distributed. The exact configuration will vary depending on the web server used. For the <application>Apache</application> web server, - please refer to the <ulink - url="&url.books.handbook;/network-apache.html">Configuration of - Apache servers</ulink> section in the Handbook.</para> + please refer to the <link xlink:href="&url.books.handbook;/network-apache.html">Configuration of + Apache servers</link> section in the Handbook.</para> <!-- This note seems either out of place. I find it hard to read and it is a bit difficult to understand why it is related to the rest of @@ -504,9 +490,8 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE <para>Update client's <literal>KeyPrint</literal> and <literal>ServerName</literal> in <filename>/etc/freebsd-update.conf</filename>, and perform updates as - instructed in the <ulink - url="&url.books.handbook;/updating-upgrading-freebsdupdate.html">&os; - Update</ulink> + instructed in the <link xlink:href="&url.books.handbook;/updating-upgrading-freebsdupdate.html">&os; + Update</link> <!-- One sentence, two instances of 'in'. We can probably reword this part to avoid repetition. --> <!-- What about "place client's new keyprint and servername values to @@ -525,17 +510,15 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE and uploaded to your distribution server for both versions.</para> </important> - <para>For reference, the entire run of <ulink - url="init.txt"><filename>init.sh</filename></ulink> is + <para>For reference, the entire run of <link xlink:href="init.txt"><filename>init.sh</filename></link> is attached.</para> </sect1> - <sect1 id="patch"> + <sect1 xml:id="patch"> <title>Building a Patch</title> - <para>Every time a <ulink - url="&url.base;/security/advisories.html">security advisory</ulink> - or <ulink url="&url.base;/security/notices.html">security notice</ulink> + <para>Every time a <link xlink:href="&url.base;/security/advisories.html">security advisory</link> + or <link xlink:href="&url.base;/security/notices.html">security notice</link> is announced, a patch update can be built.</para> <para>For this example, 7.1-RELEASE will be used.</para> @@ -555,8 +538,7 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE </itemizedlist> <para>Create the patch directory of the respective release - under <filename - class="directory">/usr/local/freebsd-update-server/patches/</filename>.</para> + under <filename>/usr/local/freebsd-update-server/patches/</filename>.</para> <informalexample> <screen>&prompt.user; <userinput>mkdir -p /usr/local/freebsd-update-server/patches/7.1-RELEASE/</userinput> @@ -564,14 +546,11 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE </informalexample> <para>As an example, take the patch for &man.named.8;. Read the advisory, - and grab the necessary file from <ulink - url="&url.base;/security/advisories.html">&os; Security - Advisories</ulink>. More information on interpreting the advisory, - can be found in the <ulink - url="&url.books.handbook;/security-advisories.html">&os; Handbook</ulink>.</para> - - <para>In the <ulink - url="http://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc">security brief</ulink>, + and grab the necessary file from <link xlink:href="&url.base;/security/advisories.html">&os; Security + Advisories</link>. More information on interpreting the advisory, + can be found in the <link xlink:href="&url.books.handbook;/security-advisories.html">&os; Handbook</link>.</para> + + <para>In the <link xlink:href="http://security.freebsd.org/advisories/FreeBSD-SA-09:12.bind.asc">security brief</link>, this advisory is called <literal>SA-09:12.bind</literal>. After downloading the file, it is required to rename the file to an appropriate patch level. It is suggested to keep this consistent with @@ -605,7 +584,7 @@ Wed Aug 26 12:50:07 PDT 2009 Cleaning staging area for FreeBSD/amd64 7.2-RELEASE <informalexample> <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput> -&prompt.root; <userinput>sh scripts/diff.sh <replaceable>amd64 7.1-RELEASE 7</replaceable></userinput></screen> +&prompt.root; <userinput>sh scripts/diff.sh amd64 7.1-RELEASE 7</userinput></screen> </informalexample> <para>What follows is a sample of a <emphasis>differential</emphasis> @@ -722,15 +701,15 @@ the new builds.</screen> <informalexample> <screen>&prompt.root; <userinput>cd /usr/local/freebsd-update-server</userinput> -&prompt.root; <userinput>sh scripts/upload.sh <replaceable>amd64 7.1-RELEASE</replaceable></userinput></screen> +&prompt.root; <userinput>sh scripts/upload.sh amd64 7.1-RELEASE</userinput></screen> </informalexample> <para>For reference, the entire run of - <ulink url="diff.txt"><filename>diff.sh</filename></ulink> is + <link xlink:href="diff.txt"><filename>diff.sh</filename></link> is attached.</para> </sect1> - <sect1 id="tips"> + <sect1 xml:id="tips"> <title>Tips</title> <!-- These are nice tips, but there are only a few of them and they need a @@ -753,8 +732,7 @@ the new builds.</screen> <itemizedlist> <listitem> <para>If a custom release is built using the native - <command>make release</command> <ulink - url="&url.articles.releng;/release-build.html">procedure</ulink>, + <command>make release</command> <link xlink:href="&url.articles.releng;/release-build.html">procedure</link>, <application>freebsd-update-server</application> code will work from your release. As an example, a release without ports or documentation can be built by clearing functionality pertaining @@ -779,8 +757,8 @@ the new builds.</screen> </listitem> <listitem> <para>Adding <option>-j <replaceable>NUMBER</replaceable></option> - flags to <maketarget>buildworld</maketarget> and - <maketarget>obj</maketarget> targets in the + flags to <buildtarget>buildworld</buildtarget> and + <buildtarget>obj</buildtarget> targets in the <filename>scripts/build.subr</filename> script may speed up processing depending on the hardware used, however it is not necessary. Using these flags in other targets is not @@ -789,18 +767,17 @@ the new builds.</screen> <screen> # Build the world log "Building world" cd /usr/src && - make -j 2 ${COMPATFLAGS} buildworld 2>&1 + make -j 2 ${COMPATFLAGS} buildworld 2>&1 # Distribute the world log "Distributing world" cd /usr/src/release && make -j 2 obj && - make ${COMPATFLAGS} release.1 release.2 2>&1</screen> + make ${COMPATFLAGS} release.1 release.2 2>&1</screen> </listitem> <listitem> - <para>Create an appropriate <ulink - url="&url.books.handbook;/network-dns.html">DNS</ulink> + <para>Create an appropriate <link xlink:href="&url.books.handbook;/network-dns.html">DNS</link> SRV record for the update server, and put others behind it with variable weights. Using this facility will provide update mirrors, however this tip is not necessary unless you wish to diff --git a/en_US.ISO8859-1/articles/geom-class/article.xml b/en_US.ISO8859-1/articles/geom-class/article.xml index e089c2b054..4b399367ad 100644 --- a/en_US.ISO8859-1/articles/geom-class/article.xml +++ b/en_US.ISO8859-1/articles/geom-class/article.xml @@ -1,23 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <title>Writing a GEOM Class</title> - <articleinfo> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + + <info><title>Writing a GEOM Class</title> <authorgroup> - <author> - <firstname>Ivan</firstname> - <surname>Voras</surname> - <affiliation> + <author><personname><firstname>Ivan</firstname><surname>Voras</surname></personname><affiliation> <address><email>ivoras@FreeBSD.org</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.general; @@ -35,13 +30,13 @@ </abstract> - </articleinfo> + </info> <!-- Introduction --> -<sect1 id="intro"> +<sect1 xml:id="intro"> <title>Introduction</title> - <sect2 id="intro-docs"> + <sect2 xml:id="intro-docs"> <title>Documentation</title> <para>Documentation on kernel programming is scarce — it is one of @@ -53,30 +48,25 @@ <itemizedlist> - <listitem><para>The <ulink - url="&url.books.developers-handbook;/index.html">FreeBSD - Developer's Handbook</ulink> — part of the documentation + <listitem><para>The <link xlink:href="&url.books.developers-handbook;/index.html">FreeBSD + Developer's Handbook</link> — part of the documentation project, it does not contain anything specific to kernel programming, but rather some general useful information.</para></listitem> - <listitem><para>The <ulink - url="&url.books.arch-handbook;/index.html">FreeBSD - Architecture Handbook</ulink> — also from the documentation + <listitem><para>The <link xlink:href="&url.books.arch-handbook;/index.html">FreeBSD + Architecture Handbook</link> — also from the documentation project, contains descriptions of several low-level facilities - and procedures. The most important chapter is 13, <ulink - url="&url.books.arch-handbook;/driverbasics.html">Writing - FreeBSD device drivers</ulink>.</para></listitem> + and procedures. The most important chapter is 13, <link xlink:href="&url.books.arch-handbook;/driverbasics.html">Writing + FreeBSD device drivers</link>.</para></listitem> - <listitem><para>The Blueprints section of <ulink - url="http://www.freebsddiary.org">FreeBSD Diary</ulink> web + <listitem><para>The Blueprints section of <link xlink:href="http://www.freebsddiary.org">FreeBSD Diary</link> web site — contains several interesting articles on kernel facilities.</para></listitem> <listitem><para>The man pages in section 9 — for important documentation on kernel functions.</para></listitem> - <listitem><para>The &man.geom.4; man page and <ulink - url="http://phk.freebsd.dk/pubs/">PHK's GEOM slides</ulink> + <listitem><para>The &man.geom.4; man page and <link xlink:href="http://phk.freebsd.dk/pubs/">PHK's GEOM slides</link> — for general introduction of the GEOM subsystem.</para></listitem> @@ -95,7 +85,7 @@ </sect2> </sect1> - <sect1 id="prelim"> + <sect1 xml:id="prelim"> <title>Preliminaries</title> <para>The best way to do kernel development is to have (at least) @@ -112,11 +102,11 @@ <para>But, since not everybody has two or more computers handy, there are a few things that can be done to prepare an otherwise <quote>live</quote> system for developing kernel code. This setup is also applicable - for developing in a <ulink url="http://www.vmware.com/">VMWare</ulink> - or <ulink url="http://www.qemu.org/">QEmu</ulink> virtual machine (the + for developing in a <link xlink:href="http://www.vmware.com/">VMWare</link> + or <link xlink:href="http://www.qemu.org/">QEmu</link> virtual machine (the next best thing after a dedicated development machine).</para> - <sect2 id="prelim-system"> + <sect2 xml:id="prelim-system"> <title>Modifying a system for development</title> <para>For any kernel programming a kernel with @@ -193,7 +183,7 @@ dumpdir="/usr/core </programlisting> where in the filesystem to relocate the core dump on reboot.</para> <para>Writing kernel core dumps is slow and takes a long time so - if you have lots of memory (>256M) and lots of panics it could + if you have lots of memory (>256M) and lots of panics it could be frustrating to sit and wait while it is done (twice — first to write it to swap, then to relocate it to filesystem). It is convenient then to limit the amount of RAM the system will use @@ -215,7 +205,7 @@ dumpdir="/usr/core </programlisting> server.</para> </sect2> - <sect2 id="prelim-starting"> + <sect2 xml:id="prelim-starting"> <title>Starting the project</title> <para>For the purpose of creating a new GEOM class, an empty @@ -224,7 +214,7 @@ dumpdir="/usr/core </programlisting> <filename>/usr/src</filename>.</para> </sect2> - <sect2 id="prelim-makefile"> + <sect2 xml:id="prelim-makefile"> <title>The Makefile</title> <para>It is good practice to create @@ -249,10 +239,10 @@ KMOD=geom_journal </sect2> </sect1> - <sect1 id="kernelprog"> + <sect1 xml:id="kernelprog"> <title>On FreeBSD kernel programming</title> - <sect2 id="kernelprog-memalloc"> + <sect2 xml:id="kernelprog-memalloc"> <title>Memory allocation</title> <para>See &man.malloc.9;. Basic memory allocation is only @@ -278,7 +268,7 @@ KMOD=geom_journal example, dynamic arrays of structs).</para> </sect2> - <sect2 id="kernelprog-lists"> + <sect2 xml:id="kernelprog-lists"> <title>Lists and queues</title> <para>See &man.queue.3;. There are a LOT of cases when a list of @@ -295,17 +285,17 @@ KMOD=geom_journal &man.tree.3; and &man.hashinit.9;.</para> </sect2> - <sect2 id="kernelprog-bios"> + <sect2 xml:id="kernelprog-bios"> <title>BIOs</title> - <para>Structure <structname>bio</structname> is used for any and + <para>Structure <varname remap="structname">bio</varname> is used for any and all Input/Output operations concerning GEOM. It basically contains information about what device ('provider') should satisfy the request, request type, offset, length, pointer to a buffer, and a bunch of <quote>user-specific</quote> flags and fields that can help implement various hacks.</para> - <para>The important thing here is that <structname>bio</structname>s + <para>The important thing here is that <varname remap="structname">bio</varname>s are handled asynchronously. That means that, in most parts of the code, there is no analogue to userland's &man.read.2; and &man.write.2; calls that do not return until a request is @@ -328,10 +318,10 @@ KMOD=geom_journal </sect2> </sect1> - <sect1 id="geom"> + <sect1 xml:id="geom"> <title>On GEOM programming</title> - <sect2 id="geom-ggate"> + <sect2 xml:id="geom-ggate"> <title>Ggate</title> <para>If maximum performance is not needed, a much simpler way @@ -341,7 +331,7 @@ KMOD=geom_journal two approaches.</para> </sect2> - <sect2 id="geom-class"> + <sect2 xml:id="geom-class"> <title>GEOM class</title> <para>GEOM classes are transformations on the data. These transformations @@ -379,14 +369,14 @@ KMOD=geom_journal copied to the geom instance.</para> <para>Field <function>.geom</function> in the - <structname>g_class</structname> structure is a LIST of geoms + <varname remap="structname">g_class</varname> structure is a LIST of geoms instantiated from the class.</para> <para>These functions are called from the g_event kernel thread.</para> </sect2> - <sect2 id="geom-softc"> + <sect2 xml:id="geom-softc"> <title>Softc</title> <para>The name <quote>softc</quote> is a legacy term for @@ -410,12 +400,12 @@ KMOD=geom_journal are created on our behalf by GEOM).</para></listitem> </itemizedlist> - <para>The <structname>softc</structname> structure contains all + <para>The <varname remap="structname">softc</varname> structure contains all the state of geom instance. Every geom instance has its own softc.</para> </sect2> - <sect2 id="geom-metadata"> + <sect2 xml:id="geom-metadata"> <title>Metadata</title> <para>Format of metadata is more-or-less class-dependent, but @@ -440,7 +430,7 @@ KMOD=geom_journal code works like that, and it is supported by libraries.)</para> </sect2> - <sect2 id="geom-creating"> + <sect2 xml:id="geom-creating"> <title>Labeling/creating a geom</title> <para>The sequence of events is:</para> @@ -452,7 +442,7 @@ KMOD=geom_journal <listitem><para>the utility figures out which geom class it is supposed to handle and searches for - <filename>geom_<replaceable>CLASSNAME</replaceable>.so</filename> + <filename>geom_CLASSNAME.so</filename> library (usually in <filename>/lib/geom</filename>).</para></listitem> @@ -488,12 +478,12 @@ KMOD=geom_journal </sect2> - <sect2 id="geom-command"> + <sect2 xml:id="geom-command"> <title>Geom command structure</title> <para>The helper <filename>geom_CLASSNAME.so</filename> library - exports <structname>class_commands</structname> structure, - which is an array of <structname>struct g_command</structname> + exports <varname remap="structname">class_commands</varname> structure, + which is an array of <varname remap="structname">struct g_command</varname> elements. Commands are of uniform format and look like:</para> <programlisting> verb [-options] geomname [other]</programlisting> @@ -518,8 +508,8 @@ KMOD=geom_journal </itemizedlist> <para>Many actions, such as labeling and destroying metadata can - be performed in userland. For this, <structname>struct - g_command</structname> provides field + be performed in userland. For this, <varname remap="structname">struct + g_command</varname> provides field <varname>gc_func</varname> that can be set to a function (in the same <filename>.so</filename>) that will be called to process a verb. If <varname>gc_func</varname> is NULL, the @@ -528,7 +518,7 @@ KMOD=geom_journal class.</para> </sect2> - <sect2 id="geom-geoms"> + <sect2 xml:id="geom-geoms"> <title>Geoms</title> <para>Geoms are instances of GEOM classes. They have internal @@ -564,7 +554,7 @@ KMOD=geom_journal managed by a instance of geom class.</para> </sect2> - <sect2 id="geom-threads"> + <sect2 xml:id="geom-threads"> <title>Geom threads</title> <para>There are three kernel threads created and run by the GEOM @@ -619,7 +609,7 @@ KMOD=geom_journal thread. First the partition slicer gets <function>.done</function>() called in the <literal>g_up</literal> thread, it uses information stored - in the bio to free the cloned <structname>bio</structname> + in the bio to free the cloned <varname remap="structname">bio</varname> structure (with <function>g_destroy_bio</function>()) and calls <function>g_io_deliver</function>() on the original request.</para></listitem> @@ -629,7 +619,7 @@ KMOD=geom_journal </itemizedlist> <para>See &man.g.bio.9; man page for information how the data is - passed back and forth in the <structname>bio</structname> + passed back and forth in the <varname remap="structname">bio</varname> structure (note in particular the <varname>bio_parent</varname> and <varname>bio_children</varname> fields and how they are handled).</para> @@ -667,7 +657,7 @@ KMOD=geom_journal additional kernel threads.</para> </sect2> - <sect2 id="geom-kernelthreads"> + <sect2 xml:id="geom-kernelthreads"> <title>Kernel threads for use in geom code</title> <para>Kernel threads are created with &man.kthread.create.9; diff --git a/en_US.ISO8859-1/articles/gjournal-desktop/article.xml b/en_US.ISO8859-1/articles/gjournal-desktop/article.xml index aadd5cf22c..7d8af3fcd8 100644 --- a/en_US.ISO8859-1/articles/gjournal-desktop/article.xml +++ b/en_US.ISO8859-1/articles/gjournal-desktop/article.xml @@ -1,18 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Implementing UFS Journaling on a Desktop PC</title> + -<article lang="en"> - <articleinfo> - <title>Implementing UFS Journaling on a Desktop PC</title> - - <author> - <firstname>Manolis</firstname> - <surname>Kiagias</surname> - <affiliation> + <author><personname><firstname>Manolis</firstname><surname>Kiagias</surname></personname><affiliation> <address><email>manolis@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2008</year> @@ -23,7 +18,7 @@ <releaseinfo>$FreeBSD$</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -42,9 +37,9 @@ explains how to implement UFS journaling on a typical desktop PC scenario.</para> </abstract> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>While professional servers are usually well protected from @@ -120,7 +115,7 @@ </warning> </sect1> - <sect1 id="understanding-journaling"> + <sect1 xml:id="understanding-journaling"> <title>Understanding Journaling in &os;</title> <para>The journaling provided by GEOM in &os; 7.<replaceable>X</replaceable> is not file system @@ -151,20 +146,19 @@ <itemizedlist> <listitem> <para>You wish to journal your <filename>/usr</filename> file system, - stored in <filename class="devicefile">/dev/ad0s1f</filename> (which + stored in <filename>/dev/ad0s1f</filename> (which already contains data).</para> </listitem> <listitem> <para>You reserved some free disk space in a partition in - <filename class="devicefile">/dev/ad0s1g</filename>.</para> + <filename>/dev/ad0s1g</filename>.</para> </listitem> <listitem> - <para>Using <command>gjournal</command>, a new <filename - class="devicefile">/dev/ad0s1f.journal</filename> device is created - where <filename class="devicefile">/dev/ad0s1f</filename> is the data - provider, and <filename class="devicefile">/dev/ad0s1g</filename> is + <para>Using <command>gjournal</command>, a new <filename>/dev/ad0s1f.journal</filename> device is created + where <filename>/dev/ad0s1f</filename> is the data + provider, and <filename>/dev/ad0s1g</filename> is the journal provider. This new device is then used for all subsequent file operations.</para> </listitem> @@ -194,7 +188,7 @@ page of &man.gjournal.8;.</para> </sect1> - <sect1 id="reserve-space"> + <sect1 xml:id="reserve-space"> <title>Steps During the Installation of &os;</title> <sect2> @@ -325,7 +319,7 @@ (packages) until you have completely setup journaling.</para> </sect2> - <sect2 id="first-boot"> + <sect2 xml:id="first-boot"> <title>Booting for the first time</title> <para>Your system will come up normally, but you will need to edit @@ -340,15 +334,15 @@ </sect2> </sect1> - <sect1 id="configure-journal"> + <sect1 xml:id="configure-journal"> <title>Setting Up Journaling</title> - <sect2 id="running-gjournal"> + <sect2 xml:id="running-gjournal"> <title>Executing <command>gjournal</command></title> <para>Having prepared all the required partitions, it is quite easy to configure journaling. We will need to switch to single user - mode, so login as <username>root</username> and type:</para> + mode, so login as <systemitem class="username">root</systemitem> and type:</para> <screen>&prompt.root; <userinput>shutdown now</userinput></screen> @@ -364,11 +358,10 @@ <para>Now, use your notes to determine which partition will be used for each journal. In our example, <filename>/usr</filename> is - <filename class="devicefile">ad0s1f</filename> and its journal will be - <filename class="devicefile">ad0s1g</filename>, while - <filename>/var</filename> is <filename - class="devicefile">ad0s1d</filename> and will - be journaled to <filename class="devicefile">ad0s1h</filename>. + <filename>ad0s1f</filename> and its journal will be + <filename>ad0s1g</filename>, while + <filename>/var</filename> is <filename>ad0s1d</filename> and will + be journaled to <filename>ad0s1h</filename>. The following commands are required:</para> <screen>&prompt.root; <userinput>gjournal label ad0s1f ad0s1g</userinput> @@ -393,8 +386,8 @@ GEOM_JOURNAL: Journal 3193218002: ad0s1h contains journal.</screen> anything will be actually overwritten.</para></note> <para>At this point, two new devices are created, namely - <filename class="devicefile">ad0s1d.journal</filename> and - <filename class="devicefile">ad0s1f.journal</filename>. These represent + <filename>ad0s1d.journal</filename> and + <filename>ad0s1f.journal</filename>. These represent the <filename>/var</filename> and <filename>/usr</filename> partitions we have to mount. Before mounting, we must however set the journal flag on them and clear the Soft Updates flag:</para> @@ -456,14 +449,14 @@ GEOM_JOURNAL: Journal ad0s1f clean.</screen> state.</para> </sect2> - <sect2 id="gjournal-new"> + <sect2 xml:id="gjournal-new"> <title>Journaling Newly Created Partitions</title> <para>While the above procedure is necessary for journaling partitions that already contain data, journaling an empty partition is somewhat easier, since both the data and the journal provider can be stored in the same partition. For example, assume a new disk was installed, - and a new partition <filename class="devicefile">/dev/ad1s1d</filename> + and a new partition <filename>/dev/ad1s1d</filename> was created. Creating the journal would be as simple as:</para> <screen>&prompt.root; <userinput>gjournal label ad1s1d</userinput></screen> @@ -486,7 +479,7 @@ GEOM_JOURNAL: Journal ad0s1f clean.</screen> <screen>&prompt.root; <userinput>newfs -J /dev/ad1s1d.journal</userinput></screen> </sect2> - <sect2 id="configure-kernel"> + <sect2 xml:id="configure-kernel"> <title>Building Journaling into Your Custom Kernel</title> <para>If you do not wish to load <literal>geom_journal</literal> as a @@ -499,8 +492,8 @@ GEOM_JOURNAL: Journal ad0s1f clean.</screen> options GEOM_JOURNAL # You will have to add this one</programlisting> <para>Rebuild and reinstall your kernel following the relevant - <ulink url="&url.books.handbook;/kernelconfig.html">instructions in - the &os; Handbook.</ulink></para> + <link xlink:href="&url.books.handbook;/kernelconfig.html">instructions in + the &os; Handbook.</link></para> <para>Do not forget to remove the relevant <quote>load</quote> entry from <filename>/boot/loader.conf</filename> if you have previously @@ -508,7 +501,7 @@ options GEOM_JOURNAL # You will have to add this one</programlisting> </sect2> </sect1> - <sect1 id="troubleshooting-gjournal"> + <sect1 xml:id="troubleshooting-gjournal"> <title>Troubleshooting Journaling</title> <para>The following section covers frequently asked questions regarding @@ -516,7 +509,7 @@ options GEOM_JOURNAL # You will have to add this one</programlisting> <qandaset> <qandaentry> - <question id="kernel-panic"> + <question xml:id="kernel-panic"> <para>I am getting kernel panics during periods of high disk activity. How is this related to journaling?</para> </question> @@ -526,13 +519,12 @@ options GEOM_JOURNAL # You will have to add this one</programlisting> committed (flushed) to disk. Keep in mind the size of the journal depends on the usage load, and not the size of the data provider. If your disk activity is high, you need a larger - partition for the journal. See the note in the <link - linkend="understanding-journaling">Understanding Journaling</link> section.</para> + partition for the journal. See the note in the <link linkend="understanding-journaling">Understanding Journaling</link> section.</para> </answer> </qandaentry> <qandaentry> - <question id="unable-boot"> + <question xml:id="unable-boot"> <para>I made some mistake during configuration, and I cannot boot normally now. Can this be fixed some way?</para> </question> @@ -572,7 +564,7 @@ GEOM_JOURNAL: Journal ad0s1f clean. </qandaentry> <qandaentry> - <question id="remove-journaling"> + <question xml:id="remove-journaling"> <para>Can I remove journaling and return to my standard file system with Soft Updates?</para> </question> @@ -582,7 +574,7 @@ GEOM_JOURNAL: Journal ad0s1f clean. changes. The partitions you created for the journal providers can then be used for other purposes, if you so wish.</para> - <para>Login as <username>root</username> and switch to single user mode:</para> + <para>Login as <systemitem class="username">root</systemitem> and switch to single user mode:</para> <screen>&prompt.root; <userinput>shutdown now</userinput></screen> @@ -639,7 +631,7 @@ tunefs: soft updates set</screen> </qandaset> </sect1> - <sect1 id="further-reading"> + <sect1 xml:id="further-reading"> <title>Further Reading</title> <para>Journaling is a fairly new feature of &os;, and as such, it is @@ -648,17 +640,17 @@ tunefs: soft updates set</screen> <itemizedlist> <listitem> - <para>A <ulink url="&url.books.handbook;/geom-gjournal.html">new section on journaling</ulink> + <para>A <link xlink:href="&url.books.handbook;/geom-gjournal.html">new section on journaling</link> is now part of the &os; Handbook.</para> </listitem> <listitem> - <para><ulink url="http://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html">This post</ulink> + <para><link xlink:href="http://lists.freebsd.org/pipermail/freebsd-current/2006-June/064043.html">This post</link> in &a.current.name; by &man.gjournal.8;'s developer, &a.pjd.email;.</para> </listitem> <listitem> - <para><ulink url="http://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html">This post</ulink> + <para><link xlink:href="http://lists.freebsd.org/pipermail/freebsd-questions/2008-April/173501.html">This post</link> in &a.questions.name; by &a.ivoras.email;.</para> </listitem> diff --git a/en_US.ISO8859-1/articles/hubs/article.xml b/en_US.ISO8859-1/articles/hubs/article.xml index 0408d9b70e..aeb46b2192 100644 --- a/en_US.ISO8859-1/articles/hubs/article.xml +++ b/en_US.ISO8859-1/articles/hubs/article.xml @@ -1,42 +1,25 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Mirroring FreeBSD</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Mirroring FreeBSD</title> + <authorgroup> - <author> - <firstname>Jun</firstname> - <surname>Kuriyama</surname> - <affiliation> + <author><personname><firstname>Jun</firstname><surname>Kuriyama</surname></personname><affiliation> <address><email>kuriyama@FreeBSD.org</email></address> - </affiliation> - </author> - <author> - <firstname>Valentino</firstname> - <surname>Vaschetto</surname> - <affiliation> + </affiliation></author> + <author><personname><firstname>Valentino</firstname><surname>Vaschetto</surname></personname><affiliation> <address><email>logo@FreeBSD.org</email></address> - </affiliation> - </author> - <author> - <firstname>Daniel</firstname> - <surname>Lang</surname> - <affiliation> + </affiliation></author> + <author><personname><firstname>Daniel</firstname><surname>Lang</surname></personname><affiliation> <address><email>dl@leo.org</email></address> - </affiliation> - </author> - <author> - <firstname>Ken</firstname> - <surname>Smith</surname> - <affiliation> + </affiliation></author> + <author><personname><firstname>Ken</firstname><surname>Smith</surname></personname><affiliation> <address><email>kensmith@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.general; @@ -50,13 +33,13 @@ <para>An in-progress article on how to mirror FreeBSD, aimed at hub administrators.</para> </abstract> - </articleinfo> + </info> <note> <para>We are not accepting new mirrors at this time.</para> </note> - <sect1 id="mirror-contact"> + <sect1 xml:id="mirror-contact"> <title>Contact Information</title> <para>The Mirror System Coordinators can be reached through email @@ -64,9 +47,9 @@ a &a.hubs;.</para> </sect1> - <sect1 id="mirror-requirements"> + <sect1 xml:id="mirror-requirements"> <title>Requirements for FreeBSD mirrors</title> - <sect2 id="mirror-diskspace"> + <sect2 xml:id="mirror-diskspace"> <title>Disk Space</title> <para> Disk space is one of the most important requirements. @@ -91,10 +74,10 @@ </itemizedlist> <para> The current disk usage of FTP Distribution can be found at - <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes">ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes</ulink>. + <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes">ftp://ftp.FreeBSD.org/pub/FreeBSD/dir.sizes</link>. </para> </sect2> - <sect2 id="mirror-bandwidth"> + <sect2 xml:id="mirror-bandwidth"> <title>Network Connection/Bandwidth</title> <para> Of course, you need to be connected to the Internet. @@ -114,7 +97,7 @@ should be connected as close as possible to your border router.</para></listitem> </itemizedlist> </sect2> - <sect2 id="mirror-system"> + <sect2 xml:id="mirror-system"> <title>System Requirements, CPU, RAM</title> <para> One thing this depends on the expected number of clients, @@ -151,7 +134,7 @@ large number of small modifications to the disk. </para> </sect2> - <sect2 id="mirror-services"> + <sect2 xml:id="mirror-services"> <title>Services to offer</title> <para> Every mirror site is required to have a set of core services @@ -160,7 +143,7 @@ server administrators may choose to offer. This section explains which services you can provide and how to go about implementing them. </para> - <sect3 id="mirror-serv-ftp"> + <sect3 xml:id="mirror-serv-ftp"> <title>FTP (required for FTP fileset)</title> <para> This is one of the most basic services, and @@ -182,24 +165,24 @@ can be used. Be sure to read &man.ftpd.8;.</para> </listitem> <listitem> - <para><filename role="package">ftp/ncftpd</filename>: A commercial package, + <para><package>ftp/ncftpd</package>: A commercial package, free for educational use.</para> </listitem> <listitem> - <para><filename role="package">ftp/oftpd</filename>: An ftpd designed with + <para><package>ftp/oftpd</package>: An ftpd designed with security as a main focus.</para> </listitem> <listitem> - <para><filename role="package">ftp/proftpd</filename>: A modular and very flexible ftpd.</para> + <para><package>ftp/proftpd</package>: A modular and very flexible ftpd.</para> </listitem> <listitem> - <para><filename role="package">ftp/pure-ftpd</filename>: Another ftpd developed with + <para><package>ftp/pure-ftpd</package>: Another ftpd developed with security in mind.</para> </listitem> - <listitem><para><filename role="package">ftp/twoftpd</filename>: As above.</para></listitem> - <listitem><para><filename role="package">ftp/vsftpd</filename>: The <quote>very secure</quote> ftpd.</para></listitem> + <listitem><para><package>ftp/twoftpd</package>: As above.</para></listitem> + <listitem><para><package>ftp/vsftpd</package>: The <quote>very secure</quote> ftpd.</para></listitem> <listitem> - <para><filename role="package">ftp/wu-ftpd</filename>: The ftpd from Washington + <para><package>ftp/wu-ftpd</package>: The ftpd from Washington University. It has become infamous, because of the huge amount of security issues that have been found in it. If you do choose to use this software be sure to @@ -216,7 +199,7 @@ much network bandwidth and system resources are consumed. </para> </sect3> - <sect3 id="mirror-serv-rsync"> + <sect3 xml:id="mirror-serv-rsync"> <title>Rsync (optional for FTP fileset)</title> <para> <application>Rsync</application> is often offered for access to the @@ -236,10 +219,10 @@ may be applied. There is just one software package available:</para> <itemizedlist> - <listitem><para><filename role="package">net/rsync</filename></para></listitem> + <listitem><para><package>net/rsync</package></para></listitem> </itemizedlist> </sect3> - <sect3 id="mirror-serv-http"> + <sect3 xml:id="mirror-serv-http"> <title>HTTP (required for web pages, optional for FTP fileset)</title> <para> If you want to offer the FreeBSD web pages, you will need @@ -250,14 +233,14 @@ <itemizedlist> <listitem> - <para><filename role="package">www/apache22</filename>: + <para><package>www/apache22</package>: <application>Apache</application> is the most widely deployed web server on the Internet. It is used extensively by the FreeBSD Project.</para> </listitem> <listitem> - <para><filename role="package">www/thttpd</filename>: + <para><package>www/thttpd</package>: If you are going to be serving a large amount of static content you may find that using an application such as thttpd is more efficient than <application>Apache</application>. It is @@ -265,7 +248,7 @@ </listitem> <listitem> - <para><filename role="package">www/boa</filename>: + <para><package>www/boa</package>: <application>Boa</application> is another alternative to <application>thttpd</application> and <application>Apache</application>. It should provide @@ -277,7 +260,7 @@ </listitem> </itemizedlist> </sect3> - <sect3 id="mirror-serv-cvsup"> + <sect3 xml:id="mirror-serv-cvsup"> <title>CVSup (desired for CVS repository)</title> <para> <application>CVSup</application> is a very efficient way of distributing files. @@ -294,26 +277,26 @@ a Modula-3 environment. &a.jdp; has built a stripped down version of M3 that is sufficient to run <application>CVSup</application>, and can be installed much easier. - See <ulink url="http://www.polstra.com/projects/freeware/ezm3/">Ezm3</ulink> + See <link xlink:href="http://www.polstra.com/projects/freeware/ezm3/">Ezm3</link> for details. Related ports are:</para> <itemizedlist> <listitem> - <para><filename role="package">net/cvsup</filename>: The native CVSup port (client and server) - which requires <filename role="package">lang/ezm3</filename> now.</para> + <para><package>net/cvsup</package>: The native CVSup port (client and server) + which requires <package>lang/ezm3</package> now.</para> </listitem> <listitem> - <para><filename role="package">net/cvsup-mirror</filename>: The CVSup mirror kit, which requires - <filename role="package">net/cvsup-without-gui</filename>, and configures it mirror-ready. Some + <para><package>net/cvsup-mirror</package>: The CVSup mirror kit, which requires + <package>net/cvsup-without-gui</package>, and configures it mirror-ready. Some site administrators may want a different setup though. </para> </listitem> </itemizedlist> <para>There are a few more like - <filename role="package">net/cvsup-without-gui</filename> you might want to have + <package>net/cvsup-without-gui</package> you might want to have a look at. If you prefer a static binary package, take a look - <ulink url="http://people.FreeBSD.org/~jdp/s1g/">here</ulink>. + <link xlink:href="http://people.FreeBSD.org/~jdp/s1g/">here</link>. This page still refers to the S1G bug that was present in <application>CVSup</application>. Maybe John will set up a generic download-site to get @@ -327,7 +310,7 @@ client, since it needs to compare lots of files. </para> </sect3> - <sect3 id="mirror-anoncvs"> + <sect3 xml:id="mirror-anoncvs"> <title>AnonCVS (optional for CVS repository)</title> <para> If you have the CVS repository, you may want to offer @@ -344,7 +327,7 @@ For anonymous access, <emphasis>pserver</emphasis> is very well suited, but some still offer <command>ssh</command> access as well. There is a custom crafted - <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/FreeBSD-CVS/anoncvs.shar">wrapper</ulink> + <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/FreeBSD-CVS/anoncvs.shar">wrapper</link> in the CVS repository, to be used as a login-shell for the anonymous ssh account. It does a chroot, and therefore requires the CVS repository to be available under the @@ -362,7 +345,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all <para>See the manpage for details of the options. Also see the CVS <emphasis>info</emphasis> page about additional ways to make sure access is read-only. It is advised that you create an unprivileged account, - preferably called <username>anoncvs</username>. + preferably called <systemitem class="username">anoncvs</systemitem>. Also you need to create a file <filename>passwd</filename> in your <filename>/home/ncvs/CVSROOT</filename> and assign a CVS password (empty or <literal>anoncvs</literal>) to that user. @@ -382,7 +365,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </sect3> </sect2> </sect1> - <sect1 id="mirror-howto"> + <sect1 xml:id="mirror-howto"> <title>How to Mirror FreeBSD</title> <para> Ok, now you know the requirements and how to offer @@ -391,7 +374,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all the various parts of FreeBSD, what tools to use, and where to mirror from. </para> - <sect2 id="mirror-ftp"> + <sect2 xml:id="mirror-ftp"> <title>FTP</title> <para> The FTP area is the largest amount of data that @@ -405,21 +388,21 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all for various FreeBSD versions, and various architectures. </para> - <sect3 id="mirror-ftp-ftp"> + <sect3 xml:id="mirror-ftp-ftp"> <title>With FTP mirror</title> <para> You can use a <application>FTP mirror</application> program to get the files. Some of the most commonly used are:</para> <itemizedlist> - <listitem><para><filename role="package">ftp/mirror</filename></para></listitem> - <listitem><para><filename role="package">ftp/ftpmirror</filename></para></listitem> - <listitem><para><filename role="package">ftp/emirror</filename></para></listitem> - <listitem><para><filename role="package">ftp/spegla</filename></para></listitem> - <listitem><para><filename role="package">ftp/omi</filename></para></listitem> - <listitem><para><filename role="package">ftp/wget</filename></para></listitem> + <listitem><para><package>ftp/mirror</package></para></listitem> + <listitem><para><package>ftp/ftpmirror</package></para></listitem> + <listitem><para><package>ftp/emirror</package></para></listitem> + <listitem><para><package>ftp/spegla</package></para></listitem> + <listitem><para><package>ftp/omi</package></para></listitem> + <listitem><para><package>ftp/wget</package></para></listitem> </itemizedlist> - <para><filename role="package">ftp/mirror</filename> was very popular, but seemed + <para><package>ftp/mirror</package> was very popular, but seemed to have some drawbacks, as it is written in &man.perl.1;, and had real problems with mirroring large directories like a FreeBSD site. There are rumors that @@ -434,11 +417,11 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all a large TCP congestion window. </para> </sect3> - <sect3 id="mirror-ftp-rsync"> + <sect3 xml:id="mirror-ftp-rsync"> <title>With rsync</title> <para> A better way to mirror the FTP area is <application>rsync</application>. - You can install the port <filename role="package">net/rsync</filename> and then use + You can install the port <package>net/rsync</package> and then use rsync to sync with your upstream host. <application>rsync</application> is already mentioned in <xref linkend="mirror-serv-rsync"/>. @@ -461,7 +444,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </screen> <para>Consult the documentation for <application>rsync</application>, which is also available at - <ulink url="http://rsync.samba.org/">http://rsync.samba.org/</ulink>, + <link xlink:href="http://rsync.samba.org/">http://rsync.samba.org/</link>, about the various options to be used with rsync. If you sync the whole module (unlike subdirectories), be aware that the module-directory (here "FreeBSD") @@ -471,15 +454,15 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all via &man.cron.8;. </para> </sect3> - <sect3 id="mirror-ftp-cvsup"> + <sect3 xml:id="mirror-ftp-cvsup"> <title>With CVSup</title> <para> - A few sites, including the one-and-only <hostid role="fqdn">ftp-master.FreeBSD.org</hostid> + A few sites, including the one-and-only <systemitem class="fqdomainname">ftp-master.FreeBSD.org</systemitem> even offer <application>CVSup</application> to mirror the contents of the FTP space. You need to install a <application>CVSup</application> - client, preferably from the port <filename role="package">net/cvsup</filename>. + client, preferably from the port <package>net/cvsup</package>. (Also reread <xref linkend="mirror-serv-cvsup"/>.) - A sample <filename>supfile</filename> suitable for <hostid role="fqdn">ftp-master.FreeBSD.org</hostid> + A sample <filename>supfile</filename> suitable for <systemitem class="fqdomainname">ftp-master.FreeBSD.org</systemitem> looks like this:</para> <programlisting> # @@ -501,7 +484,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all <para>It seems <application>CVSup</application> would be the best way to mirror the archive in terms of efficiency, but it is only available from few sites.</para> - <note id="mirror-cvsup-s-option"> + <note xml:id="mirror-cvsup-s-option"> <para> Please have look at the <application>CVSup</application> documentation like &man.cvsup.1; and consider using the <option>-s</option> @@ -510,12 +493,12 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </note> </sect3> </sect2> - <sect2 id="mirror-cvs"> + <sect2 xml:id="mirror-cvs"> <title>Mirroring the CVS repository</title> <para>There are various ways to mirror the CVS repository. <application>CVSup</application> is the most common method.</para> - <sect3 id="mirror-cvs-cvsup"> + <sect3 xml:id="mirror-cvs-cvsup"> <title>Using CVSup</title> <para> <application>CVSup</application> is described in some @@ -523,7 +506,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </para> <para>It is very easy to setup a <application>CVSup</application> mirror. Installing - <filename role="package">net/cvsup-mirror</filename> will + <package>net/cvsup-mirror</package> will make sure all of the needed programs are installed and then gather all the needed information to configure the mirror.</para> <note> @@ -534,7 +517,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </para> </note> </sect3> - <sect3 id="mirror-cvs-other"> + <sect3 xml:id="mirror-cvs-other"> <title>Using other methods</title> <para> Using other methods than <application>CVSup</application> is @@ -556,7 +539,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </important> </sect3> </sect2> - <sect2 id="mirror-www"> + <sect2 xml:id="mirror-www"> <title>Mirroring the WWW pages</title> <para> The best way is to check out the <emphasis>www</emphasis> @@ -593,10 +576,10 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all www </programlisting> <para> - Using <filename role="package">ftp/wget</filename> or other web-mirror tools is + Using <package>ftp/wget</package> or other web-mirror tools is not recommended. </para> - <sect3 id="mirror-www-doc"> + <sect3 xml:id="mirror-www-doc"> <title>Mirroring the FreeBSD documentation</title> <para> Since the documentation is referenced a lot from the @@ -628,7 +611,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all <para> Then you need to install a couple of ports. You are lucky, there is a meta-port: - <filename role="package">textproc/docproj</filename> to do the work + <package>textproc/docproj</package> to do the work for you. You need to set up some environment variables, like <literal>SGML_CATALOG_FILES</literal>. @@ -645,15 +628,15 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all <para> The building of the documentation, as well as lots of side issues, is documented itself in the - <ulink url="&url.books.fdp-primer;">&os; Documentation - Project Primer</ulink>. + <link xlink:href="&url.books.fdp-primer;">&os; Documentation + Project Primer</link>. Please read this piece of documentation, especially if you have problems building the documentation. </para> </important> </sect3> </sect2> - <sect2 id="mirror-how-often"> + <sect2 xml:id="mirror-how-often"> <title>How often should I mirror?</title> <para> Every mirror should be updated on a regular @@ -705,37 +688,37 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </itemizedlist> </sect2> </sect1> - <sect1 id="mirror-where"> + <sect1 xml:id="mirror-where"> <title>Where to mirror from</title> <para> This is an important issue. So this section will spend some effort to explain the backgrounds. We will say this several times: under no circumstances should you mirror from - <hostid role="fqdn">ftp.FreeBSD.org</hostid>. + <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>. </para> - <sect2 id="mirror-where-organization"> + <sect2 xml:id="mirror-where-organization"> <title>A few words about the organization</title> <para> Mirrors are organized by country. All official mirrors have a DNS entry of the form - <hostid role="fqdn">ftpN.CC.FreeBSD.org</hostid>. + <systemitem class="fqdomainname">ftpN.CC.FreeBSD.org</systemitem>. <emphasis>CC</emphasis> (i.e. country code) is the <emphasis>top level domain</emphasis> (TLD) of the country where this mirror is located. <emphasis>N</emphasis> is a number, telling that the host would be the <emphasis>Nth</emphasis> mirror in that country. - (Same applies to <hostid>cvsupN.CC.FreeBSD.org</hostid>, - <hostid>wwwN.CC.FreeBSD.org</hostid>, etc.) + (Same applies to <systemitem>cvsupN.CC.FreeBSD.org</systemitem>, + <systemitem>wwwN.CC.FreeBSD.org</systemitem>, etc.) There are mirrors with no <emphasis>CC</emphasis> part. These are the mirror sites that are very well connected and allow a large number of concurrent users. - <hostid role="fqdn">ftp.FreeBSD.org</hostid> is actually two machines, one currently + <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> is actually two machines, one currently located in Denmark and the other in the United States. It is <emphasis>NOT</emphasis> a master site and should never be used to mirror from. Lots of online documentation leads <quote>interactive</quote>users to - <hostid role="fqdn">ftp.FreeBSD.org</hostid> so automated mirroring + <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> so automated mirroring systems should find a different machine to mirror from. </para> <para> @@ -758,16 +741,15 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all (this is just a rough hint, and there is no rule). </para> </sect2> - <sect2 id="mirror-where-where"> + <sect2 xml:id="mirror-where-where"> <title>Ok, but where should I get the stuff now?</title> <para> - Under no circumstances should you mirror from <hostid - role="fqdn">ftp.FreeBSD.org</hostid>. + Under no circumstances should you mirror from <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>. The short answer is: from the site that is closest to you in Internet terms, or gives you the fastest access. </para> - <sect3 id="mirror-where-simple"> + <sect3 xml:id="mirror-where-simple"> <title>I just want to mirror from somewhere!</title> <para> If you have no special intentions or @@ -798,7 +780,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </step> </procedure> </sect3> - <sect3 id="mirror-where-official"> + <sect3 xml:id="mirror-where-official"> <title>I am an official mirror, what is the right site for me?</title> <para> In general the description in <xref linkend="mirror-where-simple"/> @@ -809,7 +791,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all mirrors that are described in <xref linkend="mirror-official"/>. </para> </sect3> - <sect3 id="mirror-where-master"> + <sect3 xml:id="mirror-where-master"> <title>I want to access the master sites!</title> <para> If you have good reasons and good prerequisites, @@ -834,13 +816,13 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all one for the CVS repository (the web pages and docs are obtained from CVS, so there is no need for master). </para> - <sect4 id="mirror-where-master-ftp"> + <sect4 xml:id="mirror-where-master-ftp"> <title>ftp-master.FreeBSD.org</title> <para> This is the master site for the FTP fileset. </para> <para> - <hostid>ftp-master.FreeBSD.org</hostid> provides + <systemitem>ftp-master.FreeBSD.org</systemitem> provides <application>rsync</application> and <application>CVSup</application> access, in addition to FTP. Refer to <xref linkend="mirror-ftp-rsync"/> and @@ -853,43 +835,43 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all <emphasis>Tier-1</emphasis>-mirrors. </para> </sect4> - <sect4 id="mirror-where-master-cvsup"> + <sect4 xml:id="mirror-where-master-cvsup"> <title>cvsup-master.FreeBSD.org</title> <para> This is the master site for the CVS repository. </para> <para> - <hostid>cvsup-master.FreeBSD.org</hostid> provides + <systemitem>cvsup-master.FreeBSD.org</systemitem> provides <application>CVSup</application> access only. See <xref linkend="mirror-cvs-cvsup"/> for details. </para> <para> To get access, you need to contact the &a.cvsup-master;. Make sure you read the - <ulink url="http://people.FreeBSD.org/~jdp/cvsup-access/">FreeBSD CVSup Access Policy</ulink> + <link xlink:href="http://people.FreeBSD.org/~jdp/cvsup-access/">FreeBSD CVSup Access Policy</link> first! </para> <para> Set up the required authentication by following - <ulink url="http://people.FreeBSD.org/~jdp/cvpasswd/">these - instructions</ulink>. Make sure you specify the server as - <hostid>freefall.FreeBSD.org</hostid> on the <command>cvpasswd</command> + <link xlink:href="http://people.FreeBSD.org/~jdp/cvpasswd/">these + instructions</link>. Make sure you specify the server as + <systemitem>freefall.FreeBSD.org</systemitem> on the <command>cvpasswd</command> command line, as described in this document, even when you are contacting - <hostid>cvsup-master.FreeBSD.org</hostid> + <systemitem>cvsup-master.FreeBSD.org</systemitem> </para> </sect4> </sect3> </sect2> </sect1> - <sect1 id="mirror-official"> + <sect1 xml:id="mirror-official"> <title>Official Mirrors</title> <para> Official mirrors are mirrors that</para> <itemizedlist> <listitem> <para> - a) have a <hostid>FreeBSD.org</hostid> DNS entry + a) have a <systemitem>FreeBSD.org</systemitem> DNS entry (usually a CNAME). </para> </listitem> @@ -906,7 +888,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all However you probably will not find a <emphasis>Tier-1</emphasis>-mirror, that is not also official. </para> - <sect2 id="mirror-official-requirements"> + <sect2 xml:id="mirror-official-requirements"> <title>Special Requirements for official (tier-1) mirrors</title> <para> It is not so easy to state requirements for all @@ -933,12 +915,12 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </itemizedlist> <para>Furthermore, admins should be subscribed to the &a.hubs;. - See <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">this link</ulink> for details, how to subscribe. + See <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">this link</link> for details, how to subscribe. </para> <important> <para>It is <emphasis>very</emphasis> important for a hub administrator, especially Tier-1 hub admins, to check the - <ulink url="http://www.FreeBSD.org/releng/">release schedule</ulink> + <link xlink:href="http://www.FreeBSD.org/releng/">release schedule</link> for the next FreeBSD release. This is important because it will tell you when the next release is scheduled to come out, and thus giving you time to prepare for the big spike of traffic which follows it. @@ -951,7 +933,7 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </para> </important> </sect2> - <sect2 id="mirror-official-become"> + <sect2 xml:id="mirror-official-become"> <title>How to become official then?</title> <!-- <para> @@ -1013,52 +995,51 @@ cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --all </para> </sect2> </sect1> - <sect1 id="mirror-statpages"> + <sect1 xml:id="mirror-statpages"> <title>Some statistics from mirror sites</title> <para> Here are links to the stat pages of your favorite mirrors (a.k.a. the only ones who feel like providing stats). </para> - <sect2 id="mirror-statpagesftp"> + <sect2 xml:id="mirror-statpagesftp"> <title>FTP site statistics</title> <itemizedlist> <listitem> <para>ftp.is.FreeBSD.org - <email>hostmaster@is.FreeBSD.org</email> - - <ulink url="http://www.rhnet.is/status/draupnir/draupnir.html"> - (Bandwidth)</ulink> <ulink url="http://www.rhnet.is/status/ftp/ftp-notendur.html">(FTP - processes)</ulink> <ulink url="http://www.rhnet.is/status/ftp/http-notendur.html">(HTTP processes) - </ulink> + <link xlink:href="http://www.rhnet.is/status/draupnir/draupnir.html"> + (Bandwidth)</link> <link xlink:href="http://www.rhnet.is/status/ftp/ftp-notendur.html">(FTP + processes)</link> <link xlink:href="http://www.rhnet.is/status/ftp/http-notendur.html">(HTTP processes) + </link> </para> </listitem> <listitem> <para>ftp.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> - - <ulink url="http://www.cz.FreeBSD.org/stats/mrtg/net.html">(Bandwidth)</ulink> - <ulink url="http://www.freebsd.cz/stats/mrtg/ftpd.html">(FTP processes)</ulink> - <ulink url="http://www.freebsd.cz/stats/mrtg/rsyncd.html">(rsync processes)</ulink> + <link xlink:href="http://www.cz.FreeBSD.org/stats/mrtg/net.html">(Bandwidth)</link> + <link xlink:href="http://www.freebsd.cz/stats/mrtg/ftpd.html">(FTP processes)</link> + <link xlink:href="http://www.freebsd.cz/stats/mrtg/rsyncd.html">(rsync processes)</link> </para> </listitem> <listitem> <para>ftp2.ru.FreeBSD.org - <email>mirror@macomnet.ru</email> - - <ulink url="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html">(Bandwidth)</ulink> - <ulink url="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html">(HTTP and FTP users)</ulink> + <link xlink:href="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_195.128.64.25.html">(Bandwidth)</link> + <link xlink:href="http://mirror.macomnet.net/mrtg/mirror.macomnet.net_proc.html">(HTTP and FTP users)</link> </para> </listitem> </itemizedlist> </sect2> - <sect2 id="mirror-statpagescvsup"> + <sect2 xml:id="mirror-statpagescvsup"> <title>CVSup site stats</title> <itemizedlist> <listitem> - <para>cvsup[23456].jp.FreeBSD.org - <email>kuriyama@FreeBSD.org</email> - <ulink - url="http://home.jp.FreeBSD.org/stats/mrtg/cvsup/index.en.html">(CVSup processes)</ulink></para> + <para>cvsup[23456].jp.FreeBSD.org - <email>kuriyama@FreeBSD.org</email> - <link xlink:href="http://home.jp.FreeBSD.org/stats/mrtg/cvsup/index.en.html">(CVSup processes)</link></para> </listitem> <listitem> <para>cvsup.cz.FreeBSD.org - <email>cejkar@fit.vutbr.cz</email> - - <ulink url="http://www.freebsd.cz/stats/mrtg/cvsupd.html">(CVSup processes)</ulink></para> + <link xlink:href="http://www.freebsd.cz/stats/mrtg/cvsupd.html">(CVSup processes)</link></para> </listitem> <listitem> <para>cvsup4.ru.FreeBSD.org - <email>maxim@FreeBSD.org</email> - - <ulink url="http://ftp.mtu.ru/mrtg/ftp.mtu.ru_proc2.html">(CVSup processes)</ulink></para> + <link xlink:href="http://ftp.mtu.ru/mrtg/ftp.mtu.ru_proc2.html">(CVSup processes)</link></para> </listitem> </itemizedlist> </sect2> diff --git a/en_US.ISO8859-1/articles/ipsec-must/article.xml b/en_US.ISO8859-1/articles/ipsec-must/article.xml index 80abb023d0..492170a30d 100644 --- a/en_US.ISO8859-1/articles/ipsec-must/article.xml +++ b/en_US.ISO8859-1/articles/ipsec-must/article.xml @@ -1,29 +1,22 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- The FreeBSD Documentation Project $FreeBSD$ --> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Independent Verification of IPsec Functionality in FreeBSD</title> + -<article lang='en'> - <articleinfo> - <title>Independent Verification of IPsec Functionality in FreeBSD</title> - - <author> - <firstname>David</firstname> - <surname>Honig</surname> - - <affiliation> + <author><personname><firstname>David</firstname><surname>Honig</surname></personname><affiliation> <address><email>honig@sprynet.com</email></address> - </affiliation> - </author> + </affiliation></author> - <pubdate>3 May 1999</pubdate> + <pubdate>1999-05-03</pubdate> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; @@ -36,9 +29,9 @@ know? I describe a method for experimentally verifying that IPsec is working.</para> </abstract> - </articleinfo> + </info> - <sect1 id="problem"> + <sect1 xml:id="problem"> <title>The Problem</title> <para>First, lets assume you have <link linkend="ipsec-install"> @@ -49,7 +42,7 @@ But can you independently confirm it?</para> </sect1> - <sect1 id="solution"> + <sect1 xml:id="solution"> <title>The Solution</title> <para>First, some crypto-relevant info theory:</para> @@ -73,20 +66,18 @@ not encrypted---as the outermost IP header must be if the packet is to be routable.</para> - <sect2 id="MUST"> + <sect2 xml:id="MUST"> <title>MUST</title> <para>Ueli Maurer's <quote>Universal Statistical Test for Random - Bit Generators</quote>(<ulink - url="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf"> - <acronym>MUST</acronym></ulink>) quickly measures the entropy - of a sample. It uses a compression-like algorithm. <link - linkend="code">The code is given below</link> for a variant + Bit Generators</quote>(<link xlink:href="http://www.geocities.com/SiliconValley/Code/4704/universal.pdf"> + <acronym>MUST</acronym></link>) quickly measures the entropy + of a sample. It uses a compression-like algorithm. <link linkend="code">The code is given below</link> for a variant which measures successive (~quarter megabyte) chunks of a file.</para> </sect2> - <sect2 id="tcpdump"> + <sect2 xml:id="tcpdump"> <title>Tcpdump</title> <para>We also need a way to capture the raw network data. A @@ -97,7 +88,7 @@ <para>The command:</para> - <screen><userinput><command>tcpdump</command> -c 4000 -s 10000 -w <replaceable>dumpfile.bin</replaceable></userinput></screen> + <screen><userinput>tcpdump -c 4000 -s 10000 -w dumpfile.bin</userinput></screen> <para>will capture 4000 raw packets to <replaceable>dumpfile.bin</replaceable>. Up to 10,000 bytes per @@ -105,7 +96,7 @@ </sect2> </sect1> - <sect1 id="experiment"> + <sect1 xml:id="experiment"> <title>The Experiment</title> <para>Here is the experiment:</para> @@ -136,8 +127,8 @@ the <quote>normal</quote> connection has 29% (2.1) of the expected value.</para> - <screen>&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w <replaceable>ipsecdemo.bin</replaceable></userinput> -&prompt.user; <userinput>uliscan <replaceable>ipsecdemo.bin</replaceable></userinput> + <screen>&prompt.user; <userinput>tcpdump -c 4000 -s 10000 -w ipsecdemo.bin</userinput> +&prompt.user; <userinput>uliscan ipsecdemo.bin</userinput> Uliscan 21 Dec 98 L=8 256 258560 @@ -154,7 +145,7 @@ Expected value for L=8 is 7.1836656 </procedure> </sect1> - <sect1 id="caveat"> + <sect1 xml:id="caveat"> <title>Caveat</title> <para>This experiment shows that IPsec <emphasis>does</emphasis> @@ -168,7 +159,7 @@ Expected value for L=8 is 7.1836656 code.</para> </sect1> - <sect1 id="IPsec"> + <sect1 xml:id="IPsec"> <title>IPsec---Definition</title> <para>Internet Protocol security extensions to IPv4; required for @@ -179,7 +170,7 @@ Expected value for L=8 is 7.1836656 message. IPsec encrypts everything between two hosts.</para> </sect1> - <sect1 id="ipsec-install"> + <sect1 xml:id="ipsec-install"> <title>Installing IPsec</title> <para>Most of the modern versions of FreeBSD have IPsec support @@ -189,12 +180,11 @@ Expected value for L=8 is 7.1836656 &man.setkey.8; command.</para> <para>A comprehensive guide on running IPsec on FreeBSD is - provided in <ulink - url="&url.books.handbook;/ipsec.html">FreeBSD - Handbook</ulink>.</para> + provided in <link xlink:href="&url.books.handbook;/ipsec.html">FreeBSD + Handbook</link>.</para> </sect1> - <sect1 id="kernel"> + <sect1 xml:id="kernel"> <title>src/sys/i386/conf/KERNELNAME</title> <para>This needs to be present in the kernel config file in order @@ -205,13 +195,12 @@ Expected value for L=8 is 7.1836656 <programlisting>device bpf</programlisting> </sect1> - <sect1 id="code"> + <sect1 xml:id="code"> <title>Maurer's Universal Statistical Test (for block size=8 bits)</title> - <para>You can find the same code at <ulink - url="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt"> - this link</ulink>.</para> + <para>You can find the same code at <link xlink:href="http://www.geocities.com/SiliconValley/Code/4704/uliscanc.txt"> + this link</link>.</para> <programlisting>/* ULISCAN.c ---blocksize of 8 diff --git a/en_US.ISO8859-1/articles/laptop/article.xml b/en_US.ISO8859-1/articles/laptop/article.xml index c283427099..f619424f9d 100644 --- a/en_US.ISO8859-1/articles/laptop/article.xml +++ b/en_US.ISO8859-1/articles/laptop/article.xml @@ -1,10 +1,9 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>FreeBSD on Laptops</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD on Laptops</title> + <abstract> <para>FreeBSD works fine on most laptops, with a few caveats. @@ -13,7 +12,7 @@ discussed below.</para> </abstract> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.microsoft; @@ -23,7 +22,7 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> <para>FreeBSD is often thought of as a server operating system, but it works just fine on the desktop, and if you want to use it on @@ -43,15 +42,15 @@ word <quote>&os;</quote> into a search engine of your choice. Additionally there is a &os;-specific online database which aims to give information on hardware issues with laptops, - <ulink url="http://laptop.bsdgroup.de/freebsd/">The &os; - Laptop Compatibility List</ulink>.</para> + <link xlink:href="http://laptop.bsdgroup.de/freebsd/">The &os; + Laptop Compatibility List</link>.</para> <para>If you want to communicate with other &os; laptop users, check out the &a.mobile.name; list. You can also get additional information about using Laptops on &os; at - <ulink url="http://tuxmobil.org/mobile_bsd.html"></ulink>.</para> + <uri xlink:href="http://tuxmobil.org/mobile_bsd.html">http://tuxmobil.org/mobile_bsd.html</uri>.</para> - <sect1 id="xorg"> + <sect1 xml:id="xorg"> <title>&xorg;</title> <para>Recent versions of <application>&xorg;</application> work with most display adapters @@ -91,7 +90,7 @@ section.</para> </sect1> - <sect1 id="modems"> + <sect1 xml:id="modems"> <title>Modems</title> <para> Laptops usually come with internal (on-board) modems. @@ -99,7 +98,7 @@ <quote>winmodems</quote> whose functionality is implemented in software, for which only &windows; drivers are normally available (though a few drivers are beginning - to show up for other operating systems; for example, if your modem has a Lucent LT chipset it might be supported by the <filename role="package">comms/ltmdm</filename> port). If that is the case, you + to show up for other operating systems; for example, if your modem has a Lucent LT chipset it might be supported by the <package>comms/ltmdm</package> port). If that is the case, you need to buy an external modem: the most compact option is probably a PC Card (PCMCIA) modem, discussed below, but serial or USB modems may be cheaper. Generally, regular @@ -108,16 +107,16 @@ </sect1> - <sect1 id="pcmcia"> + <sect1 xml:id="pcmcia"> <title>PCMCIA (PC Card) devices</title> <para> Most laptops come with PCMCIA (also called PC Card) slots; these are supported fine under FreeBSD. Look through your boot-up messages (using &man.dmesg.8;) and see whether these were detected correctly (they should appear as - <devicename>pccard0</devicename>, - <devicename>pccard1</devicename> etc on devices like - <devicename>pcic0</devicename>).</para> + <filename>pccard0</filename>, + <filename>pccard1</filename> etc on devices like + <filename>pcic0</filename>).</para> <para>&os; 4.X supports 16-bit PCMCIA cards, and &os; 5.X supports both 16-bit and @@ -156,7 +155,7 @@ </sect1> - <sect1 id="power-management"> + <sect1 xml:id="power-management"> <title>Power management</title> @@ -225,8 +224,7 @@ SC_NO_SUSPEND_VTYSWITCH</literal> in your kernel configuration file and recompile your kernel. Another workaround is to switch to a virtual console (using - <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> or another function key) and then execute &man.apm.8;. You can automate this with &man.vidcontrol.1;, if you are running &man.apmd.8;. Simply edit diff --git a/en_US.ISO8859-1/articles/ldap-auth/article.xml b/en_US.ISO8859-1/articles/ldap-auth/article.xml index 7f055fa72a..d52067546f 100644 --- a/en_US.ISO8859-1/articles/ldap-auth/article.xml +++ b/en_US.ISO8859-1/articles/ldap-auth/article.xml @@ -1,19 +1,14 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang="en"> - <articleinfo> - <title>LDAP Authentication</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>LDAP Authentication</title> + <authorgroup> - <author> - <firstname>Toby</firstname> - <surname>Burress</surname> - <affiliation> + <author><personname><firstname>Toby</firstname><surname>Burress</surname></personname><affiliation> <address><email>kurin@causa-sui.net</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> <copyright> @@ -22,7 +17,7 @@ <holder>The FreeBSD Documentation Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -38,16 +33,16 @@ where many servers need the same user accounts, for example as a replacement for <application>NIS</application>.</para> </abstract> - </articleinfo> + </info> - <sect1 id="preface"> + <sect1 xml:id="preface"> <title>Preface</title> <para>This document is intended to give the reader enough of an understanding of LDAP to configure an LDAP server. This document will attempt to provide an - explanation of <filename role="package">net/nss_ldap</filename> - and <filename role="package">security/pam_ldap</filename> for use with + explanation of <package>net/nss_ldap</package> + and <package>security/pam_ldap</package> for use with client machines services for use with the LDAP server.</para> <para>When finished, the reader should be able to configure and @@ -65,32 +60,28 @@ analysis.</para> </sect1> - <sect1 id="ldap"> + <sect1 xml:id="ldap"> <title>Configuring LDAP</title> <para>LDAP stands for <quote>Lightweight Directory Access Protocol</quote> and is a subset of the X.500 Directory Access - Protocol. Its most recent specifications are in <ulink - url="http://www.ietf.org/rfc/rfc4510.txt">RFC4510</ulink> and + Protocol. Its most recent specifications are in <link xlink:href="http://www.ietf.org/rfc/rfc4510.txt">RFC4510</link> and friends. Essentially it is a database that expects to be read from more often than it is written to.</para> - <para>The LDAP server <ulink - url="http://www.openldap.org/">OpenLDAP</ulink> will be used in the + <para>The LDAP server <link xlink:href="http://www.openldap.org/">OpenLDAP</link> will be used in the examples in this document; while the principles here should be generally applicable to many different servers, most of the concrete administration is <application>OpenLDAP</application>-specific. There are several - server versions in ports, for example <filename - role="package">net/openldap24-server</filename>. Client servers - will need the corresponding <filename - role="package">net/openldap24-client</filename> libraries.</para> + server versions in ports, for example <package>net/openldap24-server</package>. Client servers + will need the corresponding <package>net/openldap24-client</package> libraries.</para> <para>There are (basically) two areas of the LDAP service which need configuration. The first is setting up a server to receive connections properly, and the second is adding entries to the server's directory so that &os; tools know how to interact with it.</para> - <sect2 id="ldap-connect"> + <sect2 xml:id="ldap-connect"> <title>Setting Up the Server for Connections</title> <note> @@ -100,12 +91,12 @@ documentation.</para> </note> - <sect3 id="ldap-connect-install"> + <sect3 xml:id="ldap-connect-install"> <title>Installing <application>OpenLDAP</application></title> <para>First, install <application>OpenLDAP</application>:</para> - <example id="oldap-install"> + <example xml:id="oldap-install"> <title>Installing <application>OpenLDAP</application></title> <screen>&prompt.root; <userinput>cd /usr/ports/net/openldap24-server</userinput> @@ -117,7 +108,7 @@ <application>OpenLDAP</application> libraries.</para> </sect3> - <sect3 id="ldap-connect-config"> + <sect3 xml:id="ldap-connect-config"> <title>Configuring <application>OpenLDAP</application></title> <para>Next we must configure @@ -179,7 +170,7 @@ TLSCACertificateFile /path/to/your/cacert.crt</programlisting> server. If you simply want a server that runs, you can create a self-signed certificate with OpenSSL:</para> - <example id="genrsa"> + <example xml:id="genrsa"> <title>Generating an RSA key</title> <screen>&prompt.user; <userinput>openssl genrsa -out cert.key 1024</userinput> @@ -204,7 +195,7 @@ e is 65537 (0x10001) <para>Finally, the certificate signing request needs to be signed:</para> - <example id="self-sign"> + <example xml:id="self-sign"> <title>Self-signing the certificate</title> <screen>&prompt.user; <userinput>openssl x509 -req -in cert.csr -days 365 -signkey cert.key -out cert.crt</userinput> @@ -236,16 +227,13 @@ Getting Private key</screen> ldap slapd 3261 7 tcp4 *:389 *:*</screen> </sect3> - <sect3 id="ldap-connect-client"> + <sect3 xml:id="ldap-connect-client"> <title>Configuring the Client</title> - <para>Install the <filename - role="package">net/openldap24-client</filename> port for the + <para>Install the <package>net/openldap24-client</package> port for the <application>OpenLDAP</application> libraries. The client machines will always have <application>OpenLDAP</application> - libraries since that is all <filename - role="package">security/pam_ldap</filename> and <filename - role="package">net/nss_ldap</filename> support, at least for the + libraries since that is all <package>security/pam_ldap</package> and <package>net/nss_ldap</package> support, at least for the moment.</para> <para>The configuration file for the @@ -283,7 +271,7 @@ tls_cacert /path/to/your/cacert.crt</programlisting> </sect3> </sect2> - <sect2 id="ldap-database"> + <sect2 xml:id="ldap-database"> <title>Entries in the Database</title> <para>Authentication against an LDAP directory is generally @@ -300,7 +288,7 @@ tls_cacert /path/to/your/cacert.crt</programlisting> <para>The base entry for our database is <literal>dc=example,dc=org</literal>. The default location for users that most clients seem to expect is something like - <literal>ou=people,<replaceable>base</replaceable></literal>, so + <literal>ou=people,base</literal>, so that is what will be used here. However keep in mind that this is configurable.</para> @@ -366,7 +354,7 @@ cn: tuser</programlisting> <para>To enter these into your database, you can use <command>slapadd</command> or <command>ldapadd</command> on a file containing these entries. Alternatively, you can use - <filename role="package">sysutils/ldapvi</filename>.</para> + <package>sysutils/ldapvi</package>.</para> <para>The <command>ldapsearch</command> utility on the client machine should now return these entries. If it does, your database is @@ -374,25 +362,21 @@ cn: tuser</programlisting> </sect2> </sect1> - <sect1 id="client"> + <sect1 xml:id="client"> <title>Client Configuration</title> <para>The client should already have - <application>OpenLDAP</application> libraries from <xref - linkend="ldap-connect-client"/>, but if you are installing several - client machines you will need to install <filename - role="package">net/openldap24-client</filename> on each of + <application>OpenLDAP</application> libraries from <xref linkend="ldap-connect-client"/>, but if you are installing several + client machines you will need to install <package>net/openldap24-client</package> on each of them.</para> <para>&os; requires two ports to be installed to authenticate - against an LDAP server, <filename - role="package">security/pam_ldap</filename> and <filename - role="package">net/nss_ldap</filename>.</para> + against an LDAP server, <package>security/pam_ldap</package> and <package>net/nss_ldap</package>.</para> - <sect2 id="client-auth"> + <sect2 xml:id="client-auth"> <title>Authentication</title> - <para><filename role="package">security/pam_ldap</filename> is + <para><package>security/pam_ldap</package> is configured via <filename>/usr/local/etc/ldap.conf</filename>.</para> <note> @@ -410,7 +394,7 @@ cn: tuser</programlisting> configuration parameters from <filename>openldap/ldap.conf</filename> to the new <filename>ldap.conf</filename>. Once this is done, we want to - tell <filename role="package">security/pam_ldap</filename> what to + tell <package>security/pam_ldap</package> what to look for on the directory server.</para> <para>We are identifying our users with the <literal>uid</literal> @@ -418,21 +402,20 @@ cn: tuser</programlisting> <literal>pam_login_attribute</literal> directive in <filename>ldap.conf</filename>:</para> - <example id="set-pam-login-attr"> + <example xml:id="set-pam-login-attr"> <title>Setting <literal>pam_login_attribute</literal></title> <programlisting>pam_login_attribute uid</programlisting> </example> - <para>With this set, <filename - role="package">security/pam_ldap</filename> will search the entire + <para>With this set, <package>security/pam_ldap</package> will search the entire LDAP directory under <literal>base</literal> for the value - <literal>uid=<replaceable>username</replaceable></literal>. If it + <literal>uid=username</literal>. If it finds one and only one entry, it will attempt to bind as that user with the password it was given. If it binds correctly, then it will allow access. Otherwise it will fail.</para> - <sect3 id="client-auth-pam"> + <sect3 xml:id="client-auth-pam"> <title>PAM</title> <para>PAM, which stands for <quote>Pluggable Authentication @@ -501,7 +484,7 @@ cn: tuser</programlisting> <para>Your <filename>pam.d/sshd</filename> might then end up looking like this:</para> - <example id="pam"> + <example xml:id="pam"> <title>Sample <filename>pam.d/sshd</filename></title> <programlisting>auth required pam_nologin.so no_warn @@ -525,7 +508,7 @@ account required /usr/local/lib/pam_ldap.so no_warn ignore_a </sect3> </sect2> - <sect2 id="client-nss"> + <sect2 xml:id="client-nss"> <title>Name Service Switch</title> <para><application>NSS</application> is the service that maps @@ -539,9 +522,8 @@ account required /usr/local/lib/pam_ldap.so no_warn ignore_a tell <application>NSS</application> to look there when queried.</para> - <para>The <filename role="package">net/nss_ldap</filename> port - does this. It uses the same configuration file as <filename - role="package">security/pam_ldap</filename>, and should not need + <para>The <package>net/nss_ldap</package> port + does this. It uses the same configuration file as <package>security/pam_ldap</package>, and should not need any extra parameters once it is installed. Instead, what is left is simply to edit <filename>/etc/nsswitch.conf</filename> to take advantage of the directory. Simply replace the following @@ -562,7 +544,7 @@ passwd: files ldap</programlisting> authentication.</para> </sect2> - <sect2 id="caveats"> + <sect2 xml:id="caveats"> <title>Caveats</title> <para>Unfortunately, as of the time this was written &os; did not @@ -570,10 +552,9 @@ passwd: files ldap</programlisting> this, most administrators are left to implement a solution themselves. I provide some examples here. Note that if you write your own password change script, there are some security issues - you should be made aware of; see <xref - linkend="security-passwd"/></para> + you should be made aware of; see <xref linkend="security-passwd"/></para> - <example id="chpw-shell"> + <example xml:id="chpw-shell"> <title>Shell script for changing passwords</title> <programlisting><![CDATA[#!/bin/sh @@ -611,7 +592,7 @@ ldappasswd -D uid="$USER",ou=people,dc=example,dc=org \ that can change LDAP passwords. It sees use both on the command line, and on the web.</para> - <example id="chpw-ruby"> + <example xml:id="chpw-ruby"> <title>Ruby script for changing passwords</title> <programlisting><![CDATA[require 'ldap' @@ -658,7 +639,7 @@ conn.modify(luser, [replace])]]></programlisting> </sect2> </sect1> - <sect1 id="secure"> + <sect1 xml:id="secure"> <title>Security Considerations</title> <para>Now that your machines (and possibly other services) are @@ -672,20 +653,20 @@ conn.modify(luser, [replace])]]></programlisting> continually review your configuration and procedures for improvements.</para> - <sect2 id="secure-readonly"> + <sect2 xml:id="secure-readonly"> <title>Setting attributes read-only</title> <para>Several attributes in LDAP should be read-only. If left writable by the user, for example, a user could change his <literal>uidNumber</literal> attribute to <literal>0</literal> and - get <username>root</username> access!</para> + get <systemitem class="username">root</systemitem> access!</para> <para>To begin with, the <literal>userPassword</literal> attribute should not be world-readable. By default, anyone who can connect to the LDAP server can read this attribute. To disable this, put the following in <filename>slapd.conf</filename>:</para> - <example id="hide-userpass"> + <example xml:id="hide-userpass"> <title>Hide passwords</title> <programlisting>access to dn.subtree="ou=people,dc=example,dc=org" @@ -709,7 +690,7 @@ access to * changes), such as <literal>uidNumber</literal>. To close this hole, modify the above to</para> - <example id="attrib-readonly"> + <example xml:id="attrib-readonly"> <title>Read-only attributes</title> <programlisting>access to dn.subtree="ou=people,dc=example,dc=org" @@ -730,25 +711,25 @@ access to * users.</para> </sect2> - <sect2 id="secure-root"> - <title><username>Root</username> account definition</title> + <sect2 xml:id="secure-root"> + <title><systemitem class="username">Root</systemitem> account definition</title> - <para>Often the <username>root</username> or manager account for + <para>Often the <systemitem class="username">root</systemitem> or manager account for the LDAP service will be defined in the configuration file. <application>OpenLDAP</application> supports this, for example, and it works, but it can lead to trouble if <filename>slapd.conf</filename> is compromised. It may be better to use this only to bootstrap yourself into LDAP, and then define - a <username>root</username> account there.</para> + a <systemitem class="username">root</systemitem> account there.</para> <para>Even better is to define accounts that have limited - permissions, and omit a <username>root</username> account entirely. + permissions, and omit a <systemitem class="username">root</systemitem> account entirely. For example, users to can add or remove user accounts are added to one group, but they cannot themselves change the membership of this group. Such a security policy would help mitigate the effects of a leaked password.</para> - <sect3 id="manager-acct"> + <sect3 xml:id="manager-acct"> <title>Creating a management group</title> <para>Say you want your IT department to be able to change home @@ -756,7 +737,7 @@ access to * to add or remove users. The way to do this is to add a group for these admins:</para> - <example id="manager-acct-dn"> + <example xml:id="manager-acct-dn"> <title>Creating a management group</title> <programlisting>dn: cn=homemanagement,dc=example,dc=org @@ -771,7 +752,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> <para>And then change the permissions attributes in <filename>slapd.conf</filename>:</para> - <example id="management-acct-acl"> + <example xml:id="management-acct-acl"> <title>ACLs for a home directory management group</title> <programlisting>access to dn.subtree="ou=people,dc=example,dc=org" @@ -780,19 +761,19 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> dnattr=memberUid write</programlisting> </example> - <para>Now <username>tuser</username> and <username>user2</username> + <para>Now <systemitem class="username">tuser</systemitem> and <systemitem class="username">user2</systemitem> can change other users' home directories.</para> <para>In this example we've given a subset of administrative power to certain users without giving them power in other domains. The idea is that soon no single user account has the - power of a <username>root</username> account, but every power - root had is had by at least one user. The <username>root</username> + power of a <systemitem class="username">root</systemitem> account, but every power + root had is had by at least one user. The <systemitem class="username">root</systemitem> account then becomes unnecessary and can be removed.</para> </sect3> </sect2> - <sect2 id="security-passwd"> + <sect2 xml:id="security-passwd"> <title>Password storage</title> <para>By default <application>OpenLDAP</application> will store @@ -807,41 +788,41 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> </sect2> </sect1> - <appendix id="useful"> + <appendix xml:id="useful"> <title>Useful Aids</title> <para>There are a few other programs that might be useful, particularly if you have many users and do not want to configure everything manually.</para> - <para><filename role="package">security/pam_mkhomedir</filename> is + <para><package>security/pam_mkhomedir</package> is a PAM module that always succeeds; its purpose is to create home directories for users which do not have them. If you have dozens of client servers and hundreds of users, it is much easier to use this and set up skeleton directories than to prepare every home directory.</para> - <para><filename role="package">sysutils/cpu</filename> is a + <para><package>sysutils/cpu</package> is a &man.pw.8;-like utility that can be used to manage users in the LDAP directory. You can call it directly, or wrap scripts around it. It can handle both TLS (with the <option>-x</option> flag) and SSL (directly).</para> - <para><filename role="package">sysutils/ldapvi</filename> is a great + <para><package>sysutils/ldapvi</package> is a great utility for editing LDAP values in an LDIF-like syntax. The directory (or subsection of the directory) is presented in the editor chosen by the <envar>EDITOR</envar> environment variable. This makes it easy to enable large-scale changes in the directory without having to write a custom tool.</para> - <para><filename role="package">security/openssh-portable</filename> + <para><package>security/openssh-portable</package> has the ability to contact an LDAP server to verify <application>SSH</application> keys. This is extremely nice if you have many servers and do not want to copy your public keys across all of them.</para> </appendix> - <appendix id="ssl-ca"> + <appendix xml:id="ssl-ca"> <title><application>OpenSSL</application> Certificates For LDAP</title> <para>If you are hosting two or more LDAP servers, you will probably @@ -859,7 +840,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> self-signed certificate and key. The steps for this again are</para> - <example id="make-cert"> + <example xml:id="make-cert"> <title>Creating a certificate</title> <screen>&prompt.user; <userinput>openssl genrsa -out root.key 1024</userinput> @@ -890,7 +871,7 @@ memberUid: uid=user2,ou=people,dc=example,dc=org</programlisting> <option>-CAkey</option> instead of <option>-signkey</option>:</para> - <example id="ca-sign"> + <example xml:id="ca-sign"> <title>Signing as a certificate authority</title> <screen>&prompt.user; <userinput>openssl x509 -req -days 1024 \ diff --git a/en_US.ISO8859-1/articles/linux-comparison/article.xml b/en_US.ISO8859-1/articles/linux-comparison/article.xml index 4e48dfcc31..aaf41b6491 100644 --- a/en_US.ISO8859-1/articles/linux-comparison/article.xml +++ b/en_US.ISO8859-1/articles/linux-comparison/article.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- Copyright (c) 2005 Dru Lavigne @@ -34,18 +33,13 @@ Copyright (c) 2005 Dru Lavigne $FreeBSD$ --> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD: An Open Source Alternative to Linux</title> + -<article lang='en'> - <articleinfo> - <title>FreeBSD: An Open Source Alternative to Linux</title> - - <author> - <firstname>Dru</firstname> - <surname>Lavigne</surname> - <affiliation> + <author><personname><firstname>Dru</firstname><surname>Lavigne</surname></personname><affiliation> <address><email>dru@isecom.org</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2005</year> @@ -56,7 +50,7 @@ Copyright (c) 2005 Dru Lavigne <releaseinfo>$FreeBSD$</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.unix; @@ -72,9 +66,9 @@ Copyright (c) 2005 Dru Lavigne provides a starting point for those interested in exploring Open Source alternatives to &linux;.</para> </abstract> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>&os; is a &unix; like operating system based on the @@ -102,8 +96,7 @@ Copyright (c) 2005 Dru Lavigne roots of Unix development. <footnote> - <para>See also <ulink - url="http://www.oreilly.com/catalog/opensources/book/kirkmck.html"></ulink> + <para>See also <uri xlink:href="http://www.oreilly.com/catalog/opensources/book/kirkmck.html">http://www.oreilly.com/catalog/opensources/book/kirkmck.html</uri> for a brief history.</para> </footnote> @@ -114,8 +107,7 @@ Copyright (c) 2005 Dru Lavigne addressed quickly by the security team. When new utilities or kernel features are added, the user simply needs to read one file, the Release Notes, which is publicly available on - the main page of the <ulink - url="http://www.FreeBSD.org">&os; website</ulink>.</para> + the main page of the <link xlink:href="http://www.FreeBSD.org">&os; website</link>.</para> </listitem> <listitem> @@ -142,11 +134,11 @@ Copyright (c) 2005 Dru Lavigne <para>While both &os; and &linux; use an Open Source licensing model, the actual licenses used differ. The Linux - kernel is under the <ulink url="http://www.opensource.org/licenses/gpl-license.php">GPL license</ulink> while - &os; uses the <ulink url="http://www.opensource.org/licenses/bsd-license.php">BSD license</ulink>. These, + kernel is under the <link xlink:href="http://www.opensource.org/licenses/gpl-license.php">GPL license</link> while + &os; uses the <link xlink:href="http://www.opensource.org/licenses/bsd-license.php">BSD license</link>. These, and other Open Source licenses, are described in more detail - at the website of the <ulink url="http://www.opensource.org/licenses/">Open Source - Initiative</ulink>.</para> + at the website of the <link xlink:href="http://www.opensource.org/licenses/">Open Source + Initiative</link>.</para> <para>The driving philosophy behind the GPL is to ensure that code remains Open Source; it does this by placing @@ -157,13 +149,12 @@ Copyright (c) 2005 Dru Lavigne <footnote> <para>For a fairly unbiased view of the merits of each - license, see <ulink - url="http://en.wikipedia.org/wiki/BSD_and_GPL_licensing"></ulink>.</para> + license, see <uri xlink:href="http://en.wikipedia.org/wiki/BSD_and_GPL_licensing">http://en.wikipedia.org/wiki/BSD_and_GPL_licensing</uri>.</para> </footnote> Having stable and reliable code under the attractive BSD license - means that many operating systems, such as <ulink url="http://developer.apple.com/darwin/projects/darwin/faq.html">Apple OS X</ulink> + means that many operating systems, such as <link xlink:href="http://developer.apple.com/darwin/projects/darwin/faq.html">Apple OS X</link> are based on FreeBSD code. It also means that if you choose to use BSD licensed code in your own projects, you can do so without threat of future legal liability.</para> @@ -171,10 +162,10 @@ Copyright (c) 2005 Dru Lavigne </orderedlist> </sect1> - <sect1 id="freebsd-features"> + <sect1 xml:id="freebsd-features"> <title>&os; Features</title> - <sect2 id="freebsd-features-platforms"> + <sect2 xml:id="freebsd-features-platforms"> <title>Supported Platforms</title> <para>&os; has gained a reputation as a secure, stable, @@ -210,8 +201,8 @@ Copyright (c) 2005 Dru Lavigne third-party applications, <footnote> - <para>Using <ulink url="&url.base;/ports">FreeBSD's ports - collection</ulink>: software installation is as easy as + <para>Using <link xlink:href="&url.base;/ports">FreeBSD's ports + collection</link>: software installation is as easy as <command>pkg_add -r application_name</command>.</para> </footnote> @@ -222,23 +213,20 @@ Copyright (c) 2005 Dru Lavigne &os; as a desktop. The most notable are:</para> <itemizedlist> - <listitem><para><ulink - url="http://www.desktopbsd.net">DesktopBSD</ulink> which + <listitem><para><link xlink:href="http://www.desktopbsd.net">DesktopBSD</link> which aims at being a stable and powerful operating system for desktop users.</para></listitem> - <listitem><para><ulink - url="http://www.freesbie.org">FreeSBIE</ulink> which + <listitem><para><link xlink:href="http://www.freesbie.org">FreeSBIE</link> which provides a LiveCD of &os;.</para></listitem> - <listitem><para><ulink - url="http://www.pcbsd.com">PC-BSD</ulink> which provides an + <listitem><para><link xlink:href="http://www.pcbsd.com">PC-BSD</link> which provides an easy-to-use GUI installer for &os; aimed at the desktop user.</para></listitem> </itemizedlist> </sect2> - <sect2 id="freebsd-features-frameworks"> + <sect2 xml:id="freebsd-features-frameworks"> <title>Extensible Frameworks</title> <para>&os; provides many extensible frameworks to easily @@ -306,7 +294,7 @@ Copyright (c) 2005 Dru Lavigne <varlistentry> <term>MAC</term> - <listitem><para><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/mac.html">MAC</ulink>, + <listitem><para><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/mac.html">MAC</link>, or Mandatory Access Control, provides fine-tuned access to files and is meant to augment traditional operating system authorization provided by file permissions. Since MAC is @@ -331,7 +319,7 @@ Copyright (c) 2005 Dru Lavigne <varlistentry> <term>PAM</term> - <listitem><para>Like &linux;, &os; provides support for <ulink url="&url.base;/doc/en_US.ISO8859-1/articles/pam/">PAM</ulink>, + <listitem><para>Like &linux;, &os; provides support for <link xlink:href="&url.base;/doc/en_US.ISO8859-1/articles/pam/">PAM</link>, Pluggable Authentication Modules. This allows an administrator to augment the traditional &unix; username/password authentication model. &os; provides modules to integrate @@ -353,13 +341,12 @@ Copyright (c) 2005 Dru Lavigne </sect2> </sect1> - <sect1 id="freebsd-security"> + <sect1 xml:id="freebsd-security"> <title>Security</title> - <para>Security is very important to the <ulink -url="&url.base;/doc/en_US.ISO8859-1/articles/releng/">FreeBSD + <para>Security is very important to the <link xlink:href="&url.base;/doc/en_US.ISO8859-1/articles/releng/">FreeBSD Release - Engineering Team</ulink>. This + Engineering Team</link>. This manifests itself in several concrete areas:</para> <itemizedlist> @@ -369,17 +356,15 @@ Release resolving known security issues. Full information regarding FreeBSD's security handling procedures and where to find security information is available at - <ulink url="http://www.FreeBSD.org/security/"></ulink>.</para></listitem> + <uri xlink:href="http://www.FreeBSD.org/security/">http://www.FreeBSD.org/security/</uri>.</para></listitem> <listitem><para>One of the problems associated with Open Source software is the sheer volume of available applications. There are literally tens of thousands of Open Source application projects each with varying levels of responsiveness to security - incidents. &os; has met this challenge head-on with <ulink - url="http://www.vuxml.org/freebsd/">VuXML</ulink>. All software + incidents. &os; has met this challenge head-on with <link xlink:href="http://www.vuxml.org/freebsd/">VuXML</link>. All software shipped with the FreeBSD operating system as well any software - available in the <ulink - url="&url.base;/ports/">Ports Collection</ulink> + available in the <link xlink:href="&url.base;/ports/">Ports Collection</link> is compared to a database of known, unresolved vulnerabilities. An administrator can use the &man.portaudit.1; utility to quickly determine if any software on a &os; @@ -418,13 +403,13 @@ Release </itemizedlist> </sect1> - <sect1 id="freebsd-support"> + <sect1 xml:id="freebsd-support"> <title>Support</title> <para>Like &linux;, &os; offers many venues for support, both freely available and commercial.</para> - <sect2 id="freebsd-support-free"> + <sect2 xml:id="freebsd-support-free"> <title>Free Offerings</title> <itemizedlist> @@ -433,26 +418,23 @@ Release operating systems, and the documentation is available both as part of the operating system and on the Internet. Manual pages are clear, concise and provide working - examples. <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/handbook/"> - The FreeBSD Handbook</ulink> + examples. <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/"> + The FreeBSD Handbook</link> provides background information and configuration examples for nearly every task one would wish to complete using &os;.</para></listitem> - <listitem><para>&os; provides many support <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">mailing - lists</ulink>. + <listitem><para>&os; provides many support <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/eresources.html#ERESOURCES-MAIL">mailing + lists</link>. where answers are archived and fully searchable. If you have a question that wasn't addressed by the Handbook, it most likely has already been answered on a mailing list. The Handbook and mailing lists are also available in several languages, all of which are easily accessible from - <ulink url="http://www.FreeBSD.org"></ulink>.</para></listitem> + <uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>.</para></listitem> <listitem><para>There are many FreeBSD IRC channels, forums - and user groups. See <ulink - url="http://www.FreeBSD.org/support.html"></ulink> for a + and user groups. See <uri xlink:href="http://www.FreeBSD.org/support.html">http://www.FreeBSD.org/support.html</uri> for a selection.</para></listitem> </itemizedlist> @@ -461,7 +443,7 @@ Release geographic location to <email>freebsd-jobs@FreeBSD.org</email>.</para> </sect2> - <sect2 id="freebsd-support-commercial"> + <sect2 xml:id="freebsd-support-commercial"> <title>Commercial Offerings</title> <para>There are many vendors who provide commercial &os; @@ -470,30 +452,26 @@ Release <itemizedlist> <listitem><para>The Commercial Vendors page at the &os; - site: <ulink - url="http://www.FreeBSD.org/commercial/"></ulink></para></listitem> + site: <uri xlink:href="http://www.FreeBSD.org/commercial/">http://www.FreeBSD.org/commercial/</uri></para></listitem> <listitem><para>FreeBSDMall, who have been selling support contracts for nearly 10 years. - <ulink url="http://www.freebsdmall.com"></ulink></para></listitem> + <uri xlink:href="http://www.freebsdmall.com">http://www.freebsdmall.com</uri></para></listitem> - <listitem><para>The BSDTracker Database at: <ulink - url="http://www.nycbug.org/index.php?NAV=BSDTracker"></ulink></para></listitem> + <listitem><para>The BSDTracker Database at: <uri xlink:href="http://www.nycbug.org/index.php?NAV=BSDTracker">http://www.nycbug.org/index.php?NAV=BSDTracker</uri></para></listitem> </itemizedlist> <para>There is also an initiative to provide certification of BSD - system administrators. <ulink - url="http://www.bsdcertification.org"></ulink>.</para> + system administrators. <uri xlink:href="http://www.bsdcertification.org">http://www.bsdcertification.org</uri>.</para> <para>If your project requires Common Criteria certification, - &os; includes the <ulink - url="http://www.trustedbsd.org">TrustedBSD</ulink> MAC + &os; includes the <link xlink:href="http://www.trustedbsd.org">TrustedBSD</link> MAC framework to ease the certification process.</para> </sect2> </sect1> - <sect1 id="freebsd-advantages"> + <sect1 xml:id="freebsd-advantages"> <title>Advantages to Choosing &os;</title> <para>There are many advantages to including &os; solutions in @@ -510,8 +488,7 @@ Release <footnote> <para>In addition, all code is browsable through a - web-interface: <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/"></ulink>.</para> + web-interface: <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/">http://www.FreeBSD.org/cgi/cvsweb.cgi/</uri>.</para> </footnote> for all releases going back to the original @@ -525,19 +502,17 @@ Release <footnote> <para>An interesting overview of the evolving Linux - development model can be found at <ulink - url="http://linuxdevices.com/articles/AT4155251624.html"></ulink>.</para> + development model can be found at <uri xlink:href="http://linuxdevices.com/articles/AT4155251624.html">http://linuxdevices.com/articles/AT4155251624.html</uri>.</para> </footnote> </para></listitem> <listitem><para>In-house developers also have full access to - FreeBSD's <ulink - url="http://www.gnu.org/software/gnats/">GNATS</ulink> + FreeBSD's <link xlink:href="http://www.gnu.org/software/gnats/">GNATS</link> bug-tracking database. They are able to query and track existing bugs as well as submit their own patches for approval and possible committal into the FreeBSD base code. - <ulink url="http://www.FreeBSD.org/support.html#gnats"></ulink></para></listitem> + <uri xlink:href="http://www.FreeBSD.org/support.html#gnats">http://www.FreeBSD.org/support.html#gnats</uri></para></listitem> <listitem><para>The BSD license allows you to freely modify the code to suit your business purposes. Unlike the GPL, there are @@ -546,7 +521,7 @@ Release </itemizedlist> </sect1> - <sect1 id="freebsd-conclusion"> + <sect1 xml:id="freebsd-conclusion"> <title>Conclusion</title> <para>&os; is a mature &unix;-like operating system which diff --git a/en_US.ISO8859-1/articles/linux-emulation/article.xml b/en_US.ISO8859-1/articles/linux-emulation/article.xml index eec01db036..7c4191fd72 100644 --- a/en_US.ISO8859-1/articles/linux-emulation/article.xml +++ b/en_US.ISO8859-1/articles/linux-emulation/article.xml @@ -1,24 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- The FreeBSD Documentation Project --> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>&linux; emulation in &os;</title> + -<article lang='en'> - <articleinfo> - <title>&linux; emulation in &os;</title> - - <author> - <firstname>Roman</firstname> - <surname>Divacky</surname> - - <affiliation> + <author><personname><firstname>Roman</firstname><surname>Divacky</surname></personname><affiliation> <address><email>rdivacky@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.adobe; &tm-attrib.ibm; &tm-attrib.freebsd; @@ -52,9 +45,9 @@ the emulation development team, are working on making the &linux; 2.6 emulation the default emulation layer in &os;.</para> </abstract> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction</title> <para>In the last few years the open source &unix; based operating systems @@ -79,7 +72,7 @@ part of this project.</para> </sect1> - <sect1 id="inside"> + <sect1 xml:id="inside"> <title>A look inside…</title> <para>In this section we are going to describe every operating system in @@ -89,7 +82,7 @@ subsection we talk about how &unix; on &unix; emulation could be done in general.</para> - <sect2 id="what-is-unix"> + <sect2 xml:id="what-is-unix"> <title>What is &unix;</title> <para>&unix; is an operating system with a long history that has @@ -110,7 +103,7 @@ &unix; characteristics.</para> </sect2> - <sect2 id="tech-details"> + <sect2 xml:id="tech-details"> <title>Technical details</title> <para>Every running program constitutes a process that represents a state @@ -122,7 +115,7 @@ provides a standard unified &unix; API to the user space. The most important ones are covered below.</para> - <sect3 id="kern-proc-comm"> + <sect3 xml:id="kern-proc-comm"> <title>Communication between kernel and user space process</title> <para>Common &unix; API defines a syscall as a way to issue commands @@ -145,7 +138,7 @@ (division by zero).</para> </sect3> - <sect3 id="proc-proc-comm"> + <sect3 xml:id="proc-proc-comm"> <title>Communication between processes</title> <para>There are other APIs (System V IPC, shared memory etc.) but the @@ -155,7 +148,7 @@ in a predefined action that cannot be altered or ignored.</para> </sect3> - <sect3 id="proc-mgmt"> + <sect3 xml:id="proc-mgmt"> <title>Process management</title> <para>Kernel instances are processed first in the system (so called @@ -170,7 +163,7 @@ defined parent (identified by its PID).</para> </sect3> - <sect3 id="thread-mgmt"> + <sect3 xml:id="thread-mgmt"> <title>Thread management</title> <para>Traditional &unix; does not define any API nor implementation @@ -218,7 +211,7 @@ </sect3> </sect2> - <sect2 id="what-is-freebsd"> + <sect2 xml:id="what-is-freebsd"> <title>What is &os;?</title> <para>The &os; project is one of the oldest open source operating @@ -293,7 +286,7 @@ <para>More info about the &os; operating system can be found at [2].</para> - <sect3 id="freebsd-tech-details"> + <sect3 xml:id="freebsd-tech-details"> <title>Technical details</title> <para>&os; is traditional flavor of &unix; in the sense of dividing the @@ -305,7 +298,7 @@ only exists there but the concept is similar on other architectures. The information was taken from [1] and the source code.</para> - <sect4 id="freebsd-sys-entries"> + <sect4 xml:id="freebsd-sys-entries"> <title>System entries</title> <para>&os; has an abstraction called an execution class loader, @@ -320,7 +313,7 @@ kernel-space and the user-space at once.</para> </sect4> - <sect4 id="freebsd-syscalls"> + <sect4 xml:id="freebsd-syscalls"> <title>Syscalls</title> <para>Syscalls on &os; are issued by executing interrupt @@ -349,7 +342,7 @@ parameters.</para> </sect4> - <sect4 id="freebsd-traps"> + <sect4 xml:id="freebsd-traps"> <title>Traps</title> <para>Handling of traps in &os; is similar to the handling of @@ -363,7 +356,7 @@ <literal>userret()</literal>.</para> </sect4> - <sect4 id="freebsd-exits"> + <sect4 xml:id="freebsd-exits"> <title>Exits</title> <para>Exits from kernel to userspace happen using the assembler @@ -372,7 +365,7 @@ status from the stack and returns to the userspace.</para> </sect4> - <sect4 id="freebsd-unix-primitives"> + <sect4 xml:id="freebsd-unix-primitives"> <title>&unix; primitives</title> <para>&os; operating system adheres to the traditional &unix; scheme, @@ -419,7 +412,7 @@ </sect3> </sect2> - <sect2 id="what-is-linux"> + <sect2 xml:id="what-is-linux"> <title>What is &linux;</title> <para>&linux; is a &unix;-like kernel originally developed by Linus @@ -453,7 +446,7 @@ <para>More information can be obtained from [4].</para> - <sect3 id="linux-tech-details"> + <sect3 xml:id="linux-tech-details"> <title>Technical details</title> <para>&linux; follows the traditional &unix; scheme of dividing the run @@ -463,7 +456,7 @@ &linux; 2.6 on the &i386; architecture. This information was taken from [3].</para> - <sect4 id="linux-syscalls"> + <sect4 xml:id="linux-syscalls"> <title>Syscalls</title> <para>Syscalls in &linux; are performed (in userspace) using @@ -483,22 +476,22 @@ <orderedlist> <listitem> - <para>parameter -> <varname>%ebx</varname></para> + <para>parameter -> <varname>%ebx</varname></para> </listitem> <listitem> - <para>parameter -> <varname>%ecx</varname></para> + <para>parameter -> <varname>%ecx</varname></para> </listitem> <listitem> - <para>parameter -> <varname>%edx</varname></para> + <para>parameter -> <varname>%edx</varname></para> </listitem> <listitem> - <para>parameter -> <varname>%esi</varname></para> + <para>parameter -> <varname>%esi</varname></para> </listitem> <listitem> - <para>parameter -> <varname>%edi</varname></para> + <para>parameter -> <varname>%edi</varname></para> </listitem> <listitem> - <para>parameter -> <varname>%ebp</varname></para> + <para>parameter -> <varname>%ebp</varname></para> </listitem> </orderedlist> @@ -507,7 +500,7 @@ syscall).</para> </sect4> - <sect4 id="linux-traps"> + <sect4 xml:id="linux-traps"> <title>Traps</title> <para>The trap handlers are introduced in @@ -516,7 +509,7 @@ where handling of the traps happens.</para> </sect4> - <sect4 id="linux-exits"> + <sect4 xml:id="linux-exits"> <title>Exits</title> <para>Return from the syscall is managed by syscall &man.exit.3;, @@ -526,7 +519,7 @@ stack and the process returns to the userspace.</para> </sect4> - <sect4 id="linux-unix-primitives"> + <sect4 xml:id="linux-unix-primitives"> <title>&unix; primitives</title> <para>In the 2.6 version, the &linux; operating system redefined some @@ -648,7 +641,7 @@ </sect3> </sect2> - <sect2 id="what-is-emu"> + <sect2 xml:id="what-is-emu"> <title>What is emulation</title> <para>According to a dictionary definition, emulation is the ability of @@ -719,7 +712,7 @@ </sect2> </sect1> - <sect1 id="freebsd-emulation"> + <sect1 xml:id="freebsd-emulation"> <title>Emulation</title> <sect2> @@ -763,14 +756,14 @@ only things necessary to implement the &linux; emulation layer.</para> </sect2> - <sect2 id="freebsd-common-primitives"> + <sect2 xml:id="freebsd-common-primitives"> <title>Common primitives in the &os; kernel</title> <para>Emulation layers need some support from the operating system. I am going to describe some of the supported primitives in the &os; operating system.</para> - <sect3 id="freebsd-locking-primitives"> + <sect3 xml:id="freebsd-locking-primitives"> <title>Locking primitives</title> <para>Contributed by: &a.attilio.email;</para> @@ -799,7 +792,7 @@ you should really check the linked manpage (where possible) for more detailed explanations.</para> - <sect4 id="freebsd-atomic-op"> + <sect4 xml:id="freebsd-atomic-op"> <title>Atomic operations and memory barriers</title> <para>Atomic operations are implemented through a set of functions @@ -828,7 +821,7 @@ mutexes).</para> </sect4> - <sect4 id="freebsd-refcounts"> + <sect4 xml:id="freebsd-refcounts"> <title>Refcounts</title> <para>Refcounts are interfaces for handling reference counters. @@ -843,7 +836,7 @@ existing API.</para> </sect4> - <sect4 id="freebsd-locks"> + <sect4 xml:id="freebsd-locks"> <title>Locks</title> <para>&os; kernel has huge classes of locks. Every lock is defined @@ -869,7 +862,7 @@ </note> </sect4> - <sect4 id="freebsd-spinlocks"> + <sect4 xml:id="freebsd-spinlocks"> <title>Spinning locks</title> <para>Spin locks let waiters to spin until they cannot acquire the @@ -884,7 +877,7 @@ requested (explained later).</para> </sect4> - <sect4 id="freebsd-blocking"> + <sect4 xml:id="freebsd-blocking"> <title>Blocking</title> <para>Block locks let waiters to be descheduled and blocked until @@ -896,7 +889,7 @@ particular conditions are met.</para> </sect4> - <sect4 id="freebsd-sleeping"> + <sect4 xml:id="freebsd-sleeping"> <title>Sleeping</title> <para>Sleep locks let waiters to be descheduled and fall asleep @@ -958,7 +951,7 @@ supported by mutexes and lockmgrs.</para> </sect4> - <sect4 id="freebsd-scheduling"> + <sect4 xml:id="freebsd-scheduling"> <title>Scheduling barriers</title> <para>Scheduling barriers are intended to be used in order to drive @@ -983,7 +976,7 @@ with locking debugging tools (as &man.witness.4;).</para> </sect4> - <sect4 id="freebsd-critical"> + <sect4 xml:id="freebsd-critical"> <title>Critical sections</title> <para>The &os; kernel has been made preemptive basically to deal with @@ -1002,7 +995,7 @@ brings.</para> </sect4> - <sect4 id="freebsd-schedpin"> + <sect4 xml:id="freebsd-schedpin"> <title>sched_pin/sched_unpin</title> <para>Another way to deal with preemption is the @@ -1017,7 +1010,7 @@ as a too strong condition for our code.</para> </sect4> - <sect4 id="freebsd-schedbind"> + <sect4 xml:id="freebsd-schedbind"> <title>sched_bind/sched_unbind</title> <para><function>sched_bind</function> is an API used in order to bind @@ -1034,7 +1027,7 @@ </sect4> </sect3> - <sect3 id="freebsd-proc"> + <sect3 xml:id="freebsd-proc"> <title>Proc structure</title> <para>Various emulation layers sometimes require some additional @@ -1055,7 +1048,7 @@ whether the process belongs to our emulation layer. The code typically looks like:</para> - <programlisting>if (__predict_true(p->p_sysent != &elf_&linux;_sysvec)) + <programlisting>if (__predict_true(p->p_sysent != &elf_&linux;_sysvec)) return;</programlisting> <para>As you can see, we effectively use the @@ -1067,7 +1060,7 @@ on i386.</para> </sect3> - <sect3 id="freebsd-vfs"> + <sect3 xml:id="freebsd-vfs"> <title>VFS</title> <para>The &os; VFS subsystem is very complex but the &linux; emulation @@ -1079,7 +1072,7 @@ an ordinary file. A file handler contains a pointer to its vnode. More then one file handler can point to the same vnode.</para> - <sect4 id="freebsd-namei"> + <sect4 xml:id="freebsd-namei"> <title>namei</title> <para>The &man.namei.9; routine is a central entry point to pathname @@ -1092,7 +1085,7 @@ performance is very critical.</para> </sect4> - <sect4 id="freebsd-vn"> + <sect4 xml:id="freebsd-vn"> <title>vn_fullpath</title> <para>The &man.vn.fullpath.9; function takes the best effort to @@ -1104,7 +1097,7 @@ Linuxulator.</para> </sect4> - <sect4 id="freebsd-vnode"> + <sect4 xml:id="freebsd-vnode"> <title>Vnode operations</title> <itemizedlist> @@ -1151,7 +1144,7 @@ </itemizedlist> </sect4> - <sect4 id="freebsd-file-handler"> + <sect4 xml:id="freebsd-file-handler"> <title>File handler operations</title> <itemizedlist> @@ -1174,7 +1167,7 @@ </sect2> </sect1> - <sect1 id="md"> + <sect1 xml:id="md"> <title>&linux; emulation layer -MD part</title> <para>This section deals with implementation of &linux; emulation layer in @@ -1186,7 +1179,7 @@ independent part of the Linuxulator. This section only covers i386 and ELF handling. A.OUT is obsolete and untested.</para> - <sect2 id="syscall-handling"> + <sect2 xml:id="syscall-handling"> <title>Syscall handling</title> <para>Syscall handling is mostly written in @@ -1195,7 +1188,7 @@ &linux; process running on &os; issues a syscall, the general syscall routine calls linux prepsyscall routine for the &linux; ABI.</para> - <sect3 id="linux-prepsyscall"> + <sect3 xml:id="linux-prepsyscall"> <title>&linux; prepsyscall</title> <para>&linux; passes arguments to syscalls via registers (that is why @@ -1211,7 +1204,7 @@ in the <function>linux_clone</function> prototype.</para> </sect3> - <sect3 id="syscall-writing"> + <sect3 xml:id="syscall-writing"> <title>Syscall writing</title> <para>Every syscall implemented in the Linuxulator must have its @@ -1274,7 +1267,7 @@ with linux as it calls the real &man.close.2; in the kernel.</para> </sect3> - <sect3 id="dummy-syscalls"> + <sect3 xml:id="dummy-syscalls"> <title>Dummy syscalls</title> <para>The &linux; emulation layer is not complete, as some syscalls are @@ -1291,7 +1284,7 @@ </sect3> </sect2> - <sect2 id="signal-handling"> + <sect2 xml:id="signal-handling"> <title>Signal handling</title> <para>Signal handling is done generally in the &os; kernel for all @@ -1299,7 +1292,7 @@ &linux; compatibility layer defines <function>linux_sendsig</function> routine for this purpose.</para> - <sect3 id="linux-sendsig"> + <sect3 xml:id="linux-sendsig"> <title>&linux; sendsig</title> <para>This routine first checks whether the signal has been installed @@ -1315,7 +1308,7 @@ signal handler to run.</para> </sect3> - <sect3 id="linux-rt-sendsig"> + <sect3 xml:id="linux-rt-sendsig"> <title>linux_rt_sendsig</title> <para>This routine is similar to <function>linux_sendsig</function> @@ -1326,7 +1319,7 @@ and possibly even faster execution.</para> </sect3> - <sect3 id="linux-sigreturn"> + <sect3 xml:id="linux-sigreturn"> <title>linux_sigreturn</title> <para>This syscall is used for return from the signal handler. It does @@ -1335,7 +1328,7 @@ </sect3> </sect2> - <sect2 id="ptrace"> + <sect2 xml:id="ptrace"> <title>Ptrace</title> <para>Many &unix; derivates implement the &man.ptrace.2; syscall in order @@ -1367,7 +1360,7 @@ implemented.</para> </sect2> - <sect2 id="traps"> + <sect2 xml:id="traps"> <title>Traps</title> <para>Whenever a &linux; process running in the emulation layer traps @@ -1397,7 +1390,7 @@ translate_traps(int signal, int trap_code) }</programlisting> </sect2> - <sect2 id="stack-fixup"> + <sect2 xml:id="stack-fixup"> <title>Stack fixup</title> <para>The RTLD run-time link-editor expects so called AUX tags on stack @@ -1410,7 +1403,7 @@ translate_traps(int signal, int trap_code) smart way.</para> </sect2> - <sect2 id="aout-support"> + <sect2 xml:id="aout-support"> <title>A.OUT support</title> <para>The &linux; emulation layer on i386 also supports &linux; A.OUT @@ -1425,7 +1418,7 @@ translate_traps(int signal, int trap_code) </sect2> </sect1> - <sect1 id="mi"> + <sect1 xml:id="mi"> <title>&linux; emulation layer -MI part</title> <para>This section talks about machine independent part of the @@ -1433,7 +1426,7 @@ translate_traps(int signal, int trap_code) 2.6 emulation, the thread local storage (TLS) implementation (on i386) and futexes. Then we talk briefly about some syscalls.</para> - <sect2 id="nptl-desc"> + <sect2 xml:id="nptl-desc"> <title>Description of NPTL</title> <para>One of the major areas of progress in development of &linux; 2.6 @@ -1464,13 +1457,13 @@ translate_traps(int signal, int trap_code) areas.</para> </sect2> - <sect2 id="linux26-emu"> + <sect2 xml:id="linux26-emu"> <title>&linux; 2.6 emulation infrastructure</title> <para>These sections deal with the way &linux; threads are managed and how we simulate that in &os;.</para> - <sect3 id="linux26-runtime"> + <sect3 xml:id="linux26-runtime"> <title>Runtime determining of 2.6 emulation</title> <para>The &linux; emulation layer in &os; supports runtime setting of @@ -1489,7 +1482,7 @@ translate_traps(int signal, int trap_code) &linux; binary as it might harm things.</para> </sect3> - <sect3 id="linux-proc-thread"> + <sect3 xml:id="linux-proc-thread"> <title>&linux; processes and thread identifiers</title> <para>The semantics of &linux; threading are a little confusing and @@ -1572,7 +1565,7 @@ translate_traps(int signal, int trap_code) later.</para> </sect3> - <sect3 id="pid-mangling"> + <sect3 xml:id="pid-mangling"> <title>PID mangling</title> <para>Because of the described different view knowing what a process @@ -1592,7 +1585,7 @@ translate_traps(int signal, int trap_code) <function>child_set_tid</function> we copy out &os; PID.</para> </sect3> - <sect3 id="clone-syscall"> + <sect3 xml:id="clone-syscall"> <title>Clone syscall</title> <para>The <function>clone</function> syscall is the way threads are @@ -1654,7 +1647,7 @@ void * child_tidptr);</programlisting> to implement &man.fork.2; and &man.vfork.2; syscalls.</para> </sect3> - <sect3 id="locking"> + <sect3 xml:id="locking"> <title>Locking</title> <para>The locking is implemented to be per-subsystem because we do not @@ -1671,13 +1664,13 @@ void * child_tidptr);</programlisting> </sect3> </sect2> - <sect2 id="tls"> + <sect2 xml:id="tls"> <title>TLS</title> <para>This section deals with TLS also known as thread local storage.</para> - <sect3 id="trheading-intro"> + <sect3 xml:id="trheading-intro"> <title>Introduction to threading</title> <para>Threads in computer science are entities within a process that @@ -1717,7 +1710,7 @@ void * child_tidptr);</programlisting> switches.</para> </sect3> - <sect3 id="i386-segs"> + <sect3 xml:id="i386-segs"> <title>Segments on i386</title> <para>The i386 architecture implements the so called segments. A @@ -1743,7 +1736,7 @@ void * child_tidptr);</programlisting> Both tables define up to 8191 entries.</para> </sect3> - <sect3 id="linux-i386"> + <sect3 xml:id="linux-i386"> <title>Implementation on &linux; i386</title> <para>There are two main ways of setting up TLS in &linux;. It can be @@ -1761,10 +1754,10 @@ void * child_tidptr);</programlisting> emulation and in fact depend on it.</para> </sect3> - <sect3 id="tls-emu"> + <sect3 xml:id="tls-emu"> <title>Emulation of &linux; TLS</title> - <sect4 id="tls-i386"> + <sect4 xml:id="tls-i386"> <title>i386</title> <para>Loading of TLS for the current thread happens by calling @@ -1799,7 +1792,7 @@ void * child_tidptr);</programlisting> plain &os;.</para> </sect4> - <sect4 id="tls-amd64"> + <sect4 xml:id="tls-amd64"> <title>amd64</title> <para>The amd64 implementation is similar to the i386 one but there @@ -1814,10 +1807,10 @@ void * child_tidptr);</programlisting> </sect3> </sect2> - <sect2 id="futexes"> + <sect2 xml:id="futexes"> <title>Futexes</title> - <sect3 id="sync-intro"> + <sect3 xml:id="sync-intro"> <title>Introduction to synchronization</title> <para>Threads need some kind of synchronization and &posix; provides @@ -1847,7 +1840,7 @@ void * child_tidptr);</programlisting> threaded programs show little locks contention.</para> </sect3> - <sect3 id="futex-intro"> + <sect3 xml:id="futex-intro"> <title>Futexes introduction</title> <para>&linux; implements 1:1 threading, i.e. it has to use in-kernel @@ -1872,7 +1865,7 @@ pthread_mutex_unlock(&mutex);</programlisting> implementation.</para> </sect3> - <sect3 id="futex-api"> + <sect3 xml:id="futex-api"> <title>Futex API</title> <para>The futex syscall looks like this:</para> @@ -1907,7 +1900,7 @@ pthread_mutex_unlock(&mutex);</programlisting> </listitem> </itemizedlist> - <sect4 id="futex-wait"> + <sect4 xml:id="futex-wait"> <title>FUTEX_WAIT</title> <para>This operation verifies that on address @@ -1919,7 +1912,7 @@ pthread_mutex_unlock(&mutex);</programlisting> otherwise the sleeping is infinite.</para> </sect4> - <sect4 id="futex-wake"> + <sect4 xml:id="futex-wake"> <title>FUTEX_WAKE</title> <para>This operation takes a futex at <varname>uaddr</varname> @@ -1927,14 +1920,14 @@ pthread_mutex_unlock(&mutex);</programlisting> on this futex.</para> </sect4> - <sect4 id="futex-fd"> + <sect4 xml:id="futex-fd"> <title>FUTEX_FD</title> <para>This operations associates a file descriptor with a given futex.</para> </sect4> - <sect4 id="futex-requeue"> + <sect4 xml:id="futex-requeue"> <title>FUTEX_REQUEUE</title> <para>This operation takes <varname>val</varname> threads @@ -1943,7 +1936,7 @@ pthread_mutex_unlock(&mutex);</programlisting> on futex at <varname>uaddr2</varname>.</para> </sect4> - <sect4 id="futex-cmp-requeue"> + <sect4 xml:id="futex-cmp-requeue"> <title>FUTEX_CMP_REQUEUE</title> <para>This operation does the same as @@ -1952,7 +1945,7 @@ pthread_mutex_unlock(&mutex);</programlisting> first.</para> </sect4> - <sect4 id="futex-wake-op"> + <sect4 xml:id="futex-wake-op"> <title>FUTEX_WAKE_OP</title> <para>This operation performs an atomic operation on @@ -1995,7 +1988,7 @@ pthread_mutex_unlock(&mutex);</programlisting> </sect4> </sect3> - <sect3 id="futex-emu"> + <sect3 xml:id="futex-emu"> <title>Futex emulation in &os;</title> <para>The futex emulation in &os; is taken from NetBSD and further @@ -2023,7 +2016,7 @@ pthread_mutex_unlock(&mutex);</programlisting> TAILQ_ENTRY(waiting_proc) wp_list; };</programlisting> - <sect4 id="futex-get"> + <sect4 xml:id="futex-get"> <title>futex_get / futex_put</title> <para>A futex is obtained using the <function>futex_get</function> @@ -2034,7 +2027,7 @@ pthread_mutex_unlock(&mutex);</programlisting> reaches zero it is released.</para> </sect4> - <sect4 id="futex-sleep"> + <sect4 xml:id="futex-sleep"> <title>futex_sleep</title> <para>When a futex queues a thread for sleeping it creates a @@ -2050,7 +2043,7 @@ pthread_mutex_unlock(&mutex);</programlisting> the actual requeueing is done in this function.</para> </sect4> - <sect4 id="futex-wake-2"> + <sect4 xml:id="futex-wake-2"> <title>futex_wake</title> <para>Waking up a thread sleeping on a futex is performed in the @@ -2065,7 +2058,7 @@ pthread_mutex_unlock(&mutex);</programlisting> <function>futex_sleep</function>.</para> </sect4> - <sect4 id="futex-wake-op-2"> + <sect4 xml:id="futex-wake-op-2"> <title>futex_wake_op</title> <para>The <literal>FUTEX_WAKE_OP</literal> operation is quite @@ -2078,7 +2071,7 @@ pthread_mutex_unlock(&mutex);</programlisting> <varname>timeout</varname>) waiter on the second futex.</para> </sect4> - <sect4 id="futex-atomic-op"> + <sect4 xml:id="futex-atomic-op"> <title>futex atomic operation</title> <para>The atomic operation takes two parameters @@ -2097,7 +2090,7 @@ pthread_mutex_unlock(&mutex);</programlisting> <varname>cmparg</varname> argument with cmp comparator.</para> </sect4> - <sect4 id="futex-locking"> + <sect4 xml:id="futex-locking"> <title>Futex locking</title> <para>Futex implementation uses two lock lists protecting @@ -2108,14 +2101,14 @@ pthread_mutex_unlock(&mutex);</programlisting> </sect3> </sect2> - <sect2 id="syscall-impl"> + <sect2 xml:id="syscall-impl"> <title>Various syscalls implementation</title> <para>In this section I am going to describe some smaller syscalls that are worth mentioning because their implementation is not obvious or those syscalls are interesting from other point of view.</para> - <sect3 id="syscall-at"> + <sect3 xml:id="syscall-at"> <title>*at family of syscalls</title> <para>During development of &linux; 2.6.16 kernel, the *at syscalls @@ -2168,7 +2161,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo using the modified &man.namei.9; routine and simple wrapping layer.</para> - <sect4 id="implementation"> + <sect4 xml:id="implementation"> <title>Implementation</title> <para>The implementation is done by altering the @@ -2194,7 +2187,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo levels. For example the <function>openat</function> goes like this:</para> - <programlisting>openat() --> kern_openat() --> vn_open() -> namei()</programlisting> + <programlisting>openat() --> kern_openat() --> vn_open() -> namei()</programlisting> <para>For this reason <function>kern_open</function> and <function>vn_open</function> must be altered to incorporate @@ -2206,7 +2199,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo </sect4> </sect3> - <sect3 id="ioctl"> + <sect3 xml:id="ioctl"> <title>Ioctl</title> <para>The ioctl interface is quite fragile due to its generality. @@ -2234,7 +2227,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo because of the easy porting of applications.</para> </sect3> - <sect3 id="debugging"> + <sect3 xml:id="debugging"> <title>Debugging</title> <para>Every syscall should be debuggable. For this purpose we @@ -2246,10 +2239,10 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo </sect2> </sect1> - <sect1 id="conclusion"> + <sect1 xml:id="conclusion"> <title>Conclusion</title> - <sect2 id="results"> + <sect2 xml:id="results"> <title>Results</title> <para>As of April 2007 the &linux; emulation layer is capable of @@ -2267,9 +2260,9 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo stuff.</para> <para>We are able to run the most used applications like - <filename role="package">www/linux-firefox</filename>, - <filename role="package">www/linux-opera</filename>, - <filename role="package">net-im/skype</filename> and some games from + <package>www/linux-firefox</package>, + <package>www/linux-opera</package>, + <package>net-im/skype</package> and some games from the Ports Collection. Some of the programs exhibit bad behaviour under 2.6 emulation but this is currently under investigation and hopefully will be fixed soon. The only big application that is @@ -2284,7 +2277,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo Fedora Core 6 linux_base, which is the ultimate plan.</para> </sect2> - <sect2 id="future-work"> + <sect2 xml:id="future-work"> <title>Future work</title> <para>Future work should focus on fixing the remaining issues with @@ -2310,7 +2303,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo improvements can also be made, finer grained locking and others.</para> </sect2> - <sect2 id="team"> + <sect2 xml:id="team"> <title>Team</title> <para>I cooperated on this project with (in alphabetical order):</para> @@ -2350,7 +2343,7 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo </sect2> </sect1> - <sect1 id="literatures"> + <sect1 xml:id="literatures"> <title>Literatures</title> <orderedlist> @@ -2360,13 +2353,13 @@ openat(stdio, bah\, flags, mode) /* returns error because stdio is not a directo 2005.</para> </listitem> <listitem> - <para><ulink url="http://www.FreeBSD.org"></ulink></para> + <para><uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri></para> </listitem> <listitem> - <para><ulink url="http://tldp.org"></ulink></para> + <para><uri xlink:href="http://tldp.org">http://tldp.org</uri></para> </listitem> <listitem> - <para><ulink url="http://www.linux.org"></ulink></para> + <para><uri xlink:href="http://www.linux.org">http://www.linux.org</uri></para> </listitem> </orderedlist> </sect1> diff --git a/en_US.ISO8859-1/articles/linux-users/article.xml b/en_US.ISO8859-1/articles/linux-users/article.xml index d5a00d5dd6..e67cbcc2fc 100644 --- a/en_US.ISO8859-1/articles/linux-users/article.xml +++ b/en_US.ISO8859-1/articles/linux-users/article.xml @@ -1,16 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>FreeBSD Quickstart Guide for &linux; Users</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD Quickstart Guide for &linux; Users</title> + <authorgroup> - <author> - <firstname>John</firstname> - <surname>Ferrell</surname> - </author> + <author><personname><firstname>John</firstname><surname>Ferrell</surname></personname></author> </authorgroup> <copyright> @@ -22,7 +18,7 @@ <releaseinfo>$FreeBSD$</releaseinfo> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.intel; @@ -35,9 +31,9 @@ <para>This document is intended to quickly familiarize intermediate to advanced &linux; users with the basics of FreeBSD.</para> </abstract> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction</title> <para>This document will highlight the differences between &os; and @@ -50,11 +46,11 @@ <para>This document assumes that you have already installed &os;. If you have not installed &os; or need help with the installation process please refer to the - <ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/install.html"> - Installing FreeBSD</ulink> chapter of the &os; Handbook.</para> + <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/install.html"> + Installing FreeBSD</link> chapter of the &os; Handbook.</para> </sect1> - <sect1 id="shells"> + <sect1 xml:id="shells"> <title>Shells: No Bash?</title> <para>Those coming from &linux; are often surprised to find that @@ -62,35 +58,32 @@ In fact, <application>Bash</application> is not even in the default installation. Instead, &os; uses &man.tcsh.1; as the default shell. Although, <application>Bash</application> and your other favorite - shells are available in &os;'s <ulink - url="article.html#SOFTWARE">Packages and Ports Collection</ulink>.</para> + shells are available in &os;'s <link xlink:href="article.html#SOFTWARE">Packages and Ports Collection</link>.</para> <para>If you do install other shells you can use &man.chsh.1; to set a user's default shell. It is, however, recommended that the - <username>root</username>'s default shell remain unchanged. The + <systemitem class="username">root</systemitem>'s default shell remain unchanged. The reason for this is that shells not included in the base distribution are normally installed in <filename>/usr/local/bin</filename> or <filename>/usr/bin</filename>. In the event of a problem the file systems where <filename>/usr/local/bin</filename> and <filename>/usr/bin</filename> are located may not be mounted. In this - case <username>root</username> would not have access to its default - shell, preventing <username>root</username> from logging in. For this - reason a second <username>root</username> account, the - <username>toor</username> account, was created for use with non-default - shells. See the security FAQ for information regarding the <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/faq/security.html#TOOR-ACCOUNT">toor account</ulink>.</para> + case <systemitem class="username">root</systemitem> would not have access to its default + shell, preventing <systemitem class="username">root</systemitem> from logging in. For this + reason a second <systemitem class="username">root</systemitem> account, the + <systemitem class="username">toor</systemitem> account, was created for use with non-default + shells. See the security FAQ for information regarding the <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/faq/security.html#TOOR-ACCOUNT">toor account</link>.</para> </sect1> - <sect1 id="software"> + <sect1 xml:id="software"> <title>Packages and Ports: Adding software in &os;</title> <para>In addition to the traditional &unix; method of installing software (download source, extract, edit source code, and compile), &os; offers two other methods for installing applications: packages and ports. A - complete list of of all available ports and packages can be found <ulink - url="http://www.freebsd.org/ports/master-index.html">here</ulink>.</para> + complete list of of all available ports and packages can be found <link xlink:href="http://www.freebsd.org/ports/master-index.html">here</link>.</para> - <sect2 id="packages"> + <sect2 xml:id="packages"> <title>Packages</title> <para>Packages are pre-compiled applications, the &os; equivalents @@ -100,13 +93,13 @@ the following command installs <application>Apache 2.2</application>:</para> - <screen>&prompt.root; <userinput>pkg_add <replaceable>/tmp/apache-2.2.6_2.tbz</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg_add /tmp/apache-2.2.6_2.tbz</userinput></screen> <para>Using the <option>-r</option> switch will tell &man.pkg.add.1; to automatically fetch a package and install it, as well as any dependencies:</para> - <screen>&prompt.root; <userinput>pkg_add -r <replaceable>apache22</replaceable></userinput> + <screen>&prompt.root; <userinput>pkg_add -r apache22</userinput> Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/Latest/apache22.tbz... Done. Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/All/expat-2.0.0_1.tbz... Done. Fetching ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6.2-release/All/perl-5.8.8_1.tbz... Done. @@ -123,17 +116,16 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen> version of the application. You can use the <envar>PACKAGESITE</envar> variable to override this default behavior. For example, set <envar>PACKAGESITE</envar> to - <ulink url="ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/"></ulink> + <uri xlink:href="ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/">ftp://ftp.freebsd.org/pub/FreeBSD/ports/i386/packages-6-stable/Latest/</uri> to download the most recent packages built for the 6.X series.</para> </note> <para>For more information on packages please refer to section 4.4 of - the &os; Handbook: <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/handbook/packages-using.html">Using the Packages System</ulink>.</para> + the &os; Handbook: <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/packages-using.html">Using the Packages System</link>.</para> </sect2> - <sect2 id="ports"> + <sect2 xml:id="ports"> <title>Ports</title> <para>&os;'s second method for installing applications is the @@ -151,8 +143,7 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen> added from the installation discs using &man.sysinstall.8;, or pulled from the &os; servers using &man.csup.1; or &man.portsnap.8;. Detailed instructions for installing the Ports Collection can be - found in <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">section 4.5.1</ulink> + found in <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">section 4.5.1</link> of the handbook.</para> <para>Installing a port is as simple (generally) as changing in to the @@ -167,18 +158,17 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen> ability to customize the installation options. For example, when installing <application>Apache 2.2</application> from ports you can enable <application>mod_ldap</application> by setting the - <makevar>WITH_LDAP</makevar> &man.make.1; variable:</para> + <varname>WITH_LDAP</varname> &man.make.1; variable:</para> <screen>&prompt.root; <userinput>cd /usr/ports/www/apache22</userinput> &prompt.root; <userinput>make WITH_LDAP="YES" install clean</userinput></screen> - <para>Please see section 4.5 of the &os; Handbook, <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">Using - the Ports Collection</ulink>, for more information about the + <para>Please see section 4.5 of the &os; Handbook, <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/ports-using.html">Using + the Ports Collection</link>, for more information about the Ports Collection.</para> </sect2> - <sect2 id="which"> + <sect2 xml:id="which"> <title>Ports or packages, which one should I use?</title> <para>Packages are just pre-compiled ports, so it is really a matter @@ -215,12 +205,12 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen> customize, ports are the way to go. (And remember, if you need to customize but prefer packages, you can build a custom package from ports using <command>make</command> - <maketarget>package</maketarget> and then copy the package to + <buildtarget>package</buildtarget> and then copy the package to other servers.)</para> </sect2> </sect1> - <sect1 id="startup"> + <sect1 xml:id="startup"> <title>System Startup: Where are the run-levels?</title> <para>&linux; uses the SysV init system, whereas &os; uses the @@ -257,8 +247,7 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen> the <quote>base</quote> system, such as <application>Apache</application>, <application>X11</application>, <application>Mozilla Firefox</application>, etc. These - user-installed applications are generally installed using &os;'s <ulink - url="article.html#SOFTWARE">Packages and Ports Collection</ulink>. + user-installed applications are generally installed using &os;'s <link xlink:href="article.html#SOFTWARE">Packages and Ports Collection</link>. In order to keep them separate from the <quote>base</quote> system, user-installed applications are normally installed under <filename>/usr/local/</filename>. Therefore the user-installed @@ -268,7 +257,7 @@ in your /etc/rc.conf. Extra options can be found in startup script.</screen> </sidebar> <para>Services are enabled by specifying - <literal><replaceable>ServiceName</replaceable>_enable="YES"</literal> in + <literal>ServiceName_enable="YES"</literal> in <filename>/etc/rc.conf</filename> (&man.rc.conf.5;). Take a look at <filename>/etc/defaults/rc.conf</filename> for the system defaults, these default settings are overridden by settings in @@ -291,25 +280,25 @@ apache22_flags="-DSSL"</programlisting> the service can be started from the command line (without rebooting the system):</para> - <screen>&prompt.root; <userinput><replaceable>/etc/rc.d/sshd</replaceable> start</userinput></screen> + <screen>&prompt.root; <userinput>/etc/rc.d/sshd start</userinput></screen> <para>If a service has not been enabled it can be started from the command line using <option>forcestart</option>:</para> - <screen>&prompt.root; <userinput><replaceable>/etc/rc.d/sshd</replaceable> forcestart</userinput></screen> + <screen>&prompt.root; <userinput>/etc/rc.d/sshd forcestart</userinput></screen> </sect1> - <sect1 id="network"> + <sect1 xml:id="network"> <title>Network configuration</title> - <sect2 id="interfaces"> + <sect2 xml:id="interfaces"> <title>Network Interfaces</title> <para>Instead of a generic <emphasis>ethX</emphasis> identifier that &linux; uses to identify a network interface, &os; uses the driver name followed by a number as the identifier. The following output from &man.ifconfig.8; shows two &intel; Pro 1000 network - interfaces (<devicename>em0</devicename> and <devicename>em1</devicename>):</para> + interfaces (<filename>em0</filename> and <filename>em1</filename>):</para> <screen>&prompt.user; <userinput>ifconfig</userinput> em0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 @@ -326,7 +315,7 @@ em1: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 status: active</screen> </sect2> - <sect2 id="ipaddress"> + <sect2 xml:id="ipaddress"> <title>IP Configuration</title> <para>An IP address can be assigned to an interface using @@ -347,16 +336,16 @@ ifconfig_em0="DHCP"</programlisting> </sect2> </sect1> - <sect1 id="firewall"> + <sect1 xml:id="firewall"> <title>Firewall</title> <para>Like <application>IPTABLES</application> in &linux;, &os; also offers a kernel level firewall; actually &os; offers three firewalls:</para> <itemizedlist> - <listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipfw.html">IPFIREWALL</ulink></simpara></listitem> - <listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipf.html">IPFILTER</ulink></simpara></listitem> - <listitem><simpara><ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html">PF</ulink></simpara></listitem> + <listitem><simpara><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipfw.html">IPFIREWALL</link></simpara></listitem> + <listitem><simpara><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-ipf.html">IPFILTER</link></simpara></listitem> + <listitem><simpara><link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/firewalls-pf.html">PF</link></simpara></listitem> </itemizedlist> <para><application>IPFIREWALL</application> or @@ -395,7 +384,7 @@ ifconfig_em0="DHCP"</programlisting> <programlisting>pass in on $ext_if inet proto tcp from any to ($ext_if) port 22</programlisting> </sect1> - <sect1 id="updates"> + <sect1 xml:id="updates"> <title>Updating &os;</title> <para>There are three methods for updating a &os; system: from source, @@ -407,7 +396,7 @@ ifconfig_em0="DHCP"</programlisting> <application>Subversion</application> servers. Once the local source code is up to date you can build new versions of the kernel and userland. For more information on source updates see - <ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/updating-upgrading.html">the chapter on updating</ulink> + <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/updating-upgrading.html">the chapter on updating</link> in the &os; Handbook.</para> <para>Binary updates are similar to using <command>yum</command> or @@ -429,7 +418,7 @@ ifconfig_em0="DHCP"</programlisting> the option to upgrade.</para> </sect1> - <sect1 id="procfs"> + <sect1 xml:id="procfs"> <title>procfs: Gone But Not Forgotten</title> <para>In &linux;, you may have looked at @@ -472,7 +461,7 @@ kern.posix1version: 200112 <para>There are occasions where procfs is required, such as running older software, using &man.truss.1; to trace system calls, and - <ulink url="&url.base;/doc/en_US.ISO8859-1/books/handbook/linuxemu.html">&linux; Binary Compatibility</ulink>. + <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/linuxemu.html">&linux; Binary Compatibility</link>. (Although, &linux; Binary Compatibility uses its own procfs, &man.linprocfs.5;.) If you need to mount procfs you can add the following to <filename>/etc/fstab</filename>:</para> @@ -489,10 +478,10 @@ kern.posix1version: 200112 <screen>&prompt.root; <userinput>mount /proc</userinput></screen> </sect1> - <sect1 id="commands"> + <sect1 xml:id="commands"> <title>Common Commands</title> - <sect2 id="packageCommands"> + <sect2 xml:id="packageCommands"> <title>Package Management</title> <para> @@ -508,14 +497,14 @@ kern.posix1version: 200112 <tbody> <row> - <entry><command>yum install <replaceable>package</replaceable></command> / <command>apt-get install <replaceable>package</replaceable></command></entry> - <entry><command>pkg_add -r <replaceable>package</replaceable></command></entry> + <entry><command>yum install package</command> / <command>apt-get install package</command></entry> + <entry><command>pkg_add -r package</command></entry> <entry>Install <replaceable>package</replaceable> from remote repository</entry> </row> <row> - <entry><command>rpm -ivh <replaceable>package</replaceable></command> / <command>dpkg -i <replaceable>package</replaceable></command></entry> - <entry><command>pkg_add -v <replaceable>package</replaceable></command></entry> + <entry><command>rpm -ivh package</command> / <command>dpkg -i package</command></entry> + <entry><command>pkg_add -v package</command></entry> <entry>Install package</entry> </row> @@ -530,7 +519,7 @@ kern.posix1version: 200112 </para> </sect2> - <sect2 id="systemCommands"> + <sect2 xml:id="systemCommands"> <title>System Management</title> <para> @@ -575,12 +564,11 @@ kern.posix1version: 200112 </sect2> </sect1> - <sect1 id="conclusion"> + <sect1 xml:id="conclusion"> <title>Conclusion</title> <para>Hopefully this document has provided you with enough to get - started with &os;. Be sure to take a look at the <ulink - url="&url.base;/doc/en_US.ISO8859-1/books/handbook/index.html">&os; Handbook</ulink> + started with &os;. Be sure to take a look at the <link xlink:href="&url.base;/doc/en_US.ISO8859-1/books/handbook/index.html">&os; Handbook</link> for more in depth coverage of the topics touched on as well as the many topics not covered in this document.</para> </sect1> diff --git a/en_US.ISO8859-1/articles/mailing-list-faq/article.xml b/en_US.ISO8859-1/articles/mailing-list-faq/article.xml index d1423db9ca..6fc2bcbea0 100644 --- a/en_US.ISO8859-1/articles/mailing-list-faq/article.xml +++ b/en_US.ISO8859-1/articles/mailing-list-faq/article.xml @@ -1,18 +1,14 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- The FreeBSD Documentation Project --> - -<article lang='en'> - <articleinfo> - <title>Frequently Asked Questions About The &os; Mailing Lists</title> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Frequently Asked Questions About The &os; Mailing Lists</title> + <authorgroup> - <author> - <surname>The &os; Documentation Project</surname> - </author> + <author><personname><surname>The &os; Documentation Project</surname></personname></author> </authorgroup> <copyright> @@ -29,19 +25,16 @@ <para>This is the FAQ for the &os; mailing lists. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the - <ulink - url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/mailing-list-faq/index.html">&os; - World Wide Web server</ulink>. It may also be downloaded as - one large <ulink url="article.html">HTML</ulink> file with HTTP - or as plain text, PostScript, PDF, etc. from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP - server</ulink>. You may also want to <ulink - url="&url.base;/search/index.html">Search the - FAQ</ulink>.</para> + <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/articles/mailing-list-faq/index.html">&os; + World Wide Web server</link>. It may also be downloaded as + one large <link xlink:href="article.html">HTML</link> file with HTTP + or as plain text, PostScript, PDF, etc. from the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP + server</link>. You may also want to <link xlink:href="&url.base;/search/index.html">Search the + FAQ</link>.</para> </abstract> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>As is usual with FAQs, this document aims to cover the @@ -59,7 +52,7 @@ <qandaset> <qandaentry> - <question id="purpose"> + <question xml:id="purpose"> <para>What is the purpose of the &os; mailing lists?</para> </question> @@ -71,21 +64,20 @@ </qandaentry> <qandaentry> - <question id="audience"> + <question xml:id="audience"> <para>Who is the audience for the &os; mailing lists?</para> </question> <answer> <para>This depends on charter of each individual list. Some lists are more oriented to developers; some are more oriented - towards the &os; community as a whole. Please see <ulink - url="http://lists.FreeBSD.org/mailman/listinfo">this list</ulink> + towards the &os; community as a whole. Please see <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo">this list</link> for the current summary.</para> </answer> </qandaentry> <qandaentry> - <question id="participation-who"> + <question xml:id="participation-who"> <para>Are the &os; mailing lists open for anyone to participate?</para> </question> @@ -111,20 +103,19 @@ </qandaentry> <qandaentry> - <question id="subscribe"> + <question xml:id="subscribe"> <para>How can I subscribe?</para> </question> <answer> - <para>You can use <ulink - url="http://lists.FreeBSD.org/mailman/listinfo"> - the Mailman web interface</ulink> to subscribe to any + <para>You can use <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo"> + the Mailman web interface</link> to subscribe to any of the public lists.</para> </answer> </qandaentry> <qandaentry> - <question id="unsubscribe"> + <question xml:id="unsubscribe"> <para>How can I unsubscribe?</para> </question> @@ -143,31 +134,30 @@ </qandaentry> <qandaentry> - <question id="archives"> + <question xml:id="archives"> <para>Are archives available?</para> </question> <answer> <para>Yes. Threaded archives are available - <ulink url="http://docs.FreeBSD.org/mail/">here</ulink>.</para> + <link xlink:href="http://docs.FreeBSD.org/mail/">here</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="digest"> + <question xml:id="digest"> <para>Are mailing lists available in a digest format?</para> </question> <answer> - <para>Yes. See <ulink - url="http://lists.FreeBSD.org/mailman/listinfo"> - the Mailman web interface</ulink>.</para> + <para>Yes. See <link xlink:href="http://lists.FreeBSD.org/mailman/listinfo"> + the Mailman web interface</link>.</para> </answer> </qandaentry> </qandaset> </sect1> - <sect1 id="etiquette"> + <sect1 xml:id="etiquette"> <title>Mailing List Etiquette</title> <para>Participation in the mailing lists, like participation @@ -177,7 +167,7 @@ <qandaset> <qandaentry> - <question id="before-posting"> + <question xml:id="before-posting"> <para>What should I do before I post?</para> </question> @@ -187,23 +177,18 @@ you may first need to familiarize yourself with the software, and all the social history around it, by reading the numerous - <ulink url="&url.base;/docs/books.html">books and articles</ulink> + <link xlink:href="&url.base;/docs/books.html">books and articles</link> that are available. Items of particular interest - include the <ulink - url="&url.books.faq;/index.html"> - &os; Frequently Asked Questions (FAQ)</ulink> document, - the <ulink - url="&url.books.handbook;/index.html"> - &os; Handbook</ulink>, - and the articles <ulink - url="&url.articles.freebsd-questions;/article.html"> - How to get best results from the FreeBSD-questions mailing list</ulink>, - <ulink - url="&url.articles.explaining-bsd;/article.html"> - Explaining BSD</ulink>, - and <ulink - url="&url.articles.new-users;/article.html"> - &os; First Steps</ulink>.</para> + include the <link xlink:href="&url.books.faq;/index.html"> + &os; Frequently Asked Questions (FAQ)</link> document, + the <link xlink:href="&url.books.handbook;/index.html"> + &os; Handbook</link>, + and the articles <link xlink:href="&url.articles.freebsd-questions;/article.html"> + How to get best results from the FreeBSD-questions mailing list</link>, + <link xlink:href="&url.articles.explaining-bsd;/article.html"> + Explaining BSD</link>, + and <link xlink:href="&url.articles.new-users;/article.html"> + &os; First Steps</link>.</para> <para>It is always considered bad form to ask a question that is already answered in the above documents. This is not because @@ -219,7 +204,7 @@ </qandaentry> <qandaentry> - <question id="inappropriate"> + <question xml:id="inappropriate"> <para>What constitutes an inappropriate posting?</para> </question> @@ -245,7 +230,7 @@ </qandaentry> <qandaentry> - <question id="etiquette-posting"> + <question xml:id="etiquette-posting"> <para>What is considered proper etiquette when posting to the mailing lists?</para> </question> @@ -284,8 +269,8 @@ <para>Please use an appropriate human language for a particular mailing list. Many non-English mailing lists are - <ulink url="&url.base;/community/mailinglists.html"> - available</ulink>.</para> + <link xlink:href="&url.base;/community/mailinglists.html"> + available</link>.</para> <para>For the ones that are not, we do appreciate that many people do not speak English as their first language, @@ -299,8 +284,8 @@ <listitem> <para>Please use a standards-compliant Mail User Agent (MUA). A lot of badly formatted messages come from - <ulink url="http://www.lemis.com/email.html">bad mailers - or badly configured mailers</ulink>. The following mailers + <link xlink:href="http://www.lemis.com/email.html">bad mailers + or badly configured mailers</link>. The following mailers are known to send out badly formatted messages without you finding out about them:</para> @@ -360,8 +345,8 @@ <filename>Makefiles</filename>, where <literal>tab</literal> is a significant character. This is a very common, and very annoying, problem with submissions to the - <ulink url="&url.base;/support.html#gnats"> - GNATS Problem Reports database</ulink>. + <link xlink:href="&url.base;/support.html#gnats"> + GNATS Problem Reports database</link>. <filename>Makefiles</filename> with tabs changed to either spaces, or the annoying <literal>=3B</literal> escape sequence, create a great deal of aggravation for @@ -372,7 +357,7 @@ </qandaentry> <qandaentry> - <question id="etiquette-replying"> + <question xml:id="etiquette-replying"> <para>What are the special etiquette consideration when replying to an existing posting on the mailing lists?</para> </question> @@ -431,7 +416,7 @@ </qandaset> </sect1> - <sect1 id="recurring"> + <sect1 xml:id="recurring"> <title>Recurring Topics On The Mailing Lists</title> <para>Participation in the mailing lists, like participation @@ -445,12 +430,11 @@ and probably save yourself being flamed in the process.</para> <para>The best method to avoid this is to familiarize yourself - with the <ulink url="http://docs.FreeBSD.org/mail/"> - mailing list archives</ulink>, + with the <link xlink:href="http://docs.FreeBSD.org/mail/"> + mailing list archives</link>, to help yourself understand the background of - what has gone before. In this, the <ulink - url="http://www.FreeBSD.org/search/search.html#mailinglists"> - mailing list search interface</ulink> + what has gone before. In this, the <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists"> + mailing list search interface</link> is invaluable. (If that method does not yield useful results, please supplement it with a search with your favorite major search engine).</para> @@ -469,16 +453,15 @@ to help avoid these recurring topics.</para> </sect1> - <sect1 id="bikeshed"> + <sect1 xml:id="bikeshed"> <title>What Is A "Bikeshed"?</title> <para>Literally, a <literal>bikeshed</literal> is a small outdoor shelter into which one may store one's two-wheeled form of transportation. However, in &os; parlance, the term refers to topics that are simple enough that (nearly) anyone can offer an opinion about, and often (nearly) everyone does. The - genesis of this term is explained in more detail <ulink - url="&url.books.faq;/misc.html#BIKESHED-PAINTING"> - in this document</ulink>. You simply must have a working + genesis of this term is explained in more detail <link xlink:href="&url.books.faq;/misc.html#BIKESHED-PAINTING"> + in this document</link>. You simply must have a working knowledge of this concept before posting to any &os; mailing list.</para> @@ -491,7 +474,7 @@ Thanks.</para> </sect1> - <sect1 id="acknowledgments"> + <sect1 xml:id="acknowledgments"> <title>Acknowledgments</title> <variablelist> @@ -499,9 +482,8 @@ <term>&a.grog.email;</term> <listitem> <para>Original author of most of the material on mailing - list etiquette, taken from the article on <ulink - url="&url.articles.freebsd-questions;/article.html"> - How to get best results from the FreeBSD-questions mailing list</ulink>.</para> + list etiquette, taken from the article on <link xlink:href="&url.articles.freebsd-questions;/article.html"> + How to get best results from the FreeBSD-questions mailing list</link>.</para> </listitem> </varlistentry> diff --git a/en_US.ISO8859-1/articles/mh/article.xml b/en_US.ISO8859-1/articles/mh/article.xml index 5f31506852..9c3ff1518f 100644 --- a/en_US.ISO8859-1/articles/mh/article.xml +++ b/en_US.ISO8859-1/articles/mh/article.xml @@ -1,31 +1,23 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- FreeBSD Documentation Project --> - -<article lang='en'> - <articleinfo> - <title>An <application>MH</application> Primer</title> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>An <application>MH</application> Primer</title> + <authorgroup> - <author> - <firstname>Matt</firstname> - - <surname>Midboe</surname> - - <affiliation> + <author><personname><firstname>Matt</firstname><surname>Midboe</surname></personname><affiliation> <address> <email>matt@garply.com</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> <pubdate>v1.0, 16 January 1996</pubdate> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; @@ -37,9 +29,9 @@ <para>This document contains an introduction to using <application>MH</application> on FreeBSD</para> </abstract> - </articleinfo> + </info> - <sect1 id="mhintro"> + <sect1 xml:id="mhintro"> <title>Introduction</title> <para><application>MH</application> started back in 1977 at the @@ -82,23 +74,18 @@ You will notice that it created a <filename>/usr/local/lib/mh</filename> directory for you as well as adding several binaries to the <filename>/usr/local/bin</filename> directory. If you would prefer to - compile it yourself then you can anonymous ftp it from <ulink - url="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</ulink> or <ulink - url="ftp://louie.udel.edu/">louie.udel.edu</ulink>.</para> + compile it yourself then you can anonymous ftp it from <link xlink:href="ftp://ftp.ics.uci.edu/">ftp.ics.uci.edu</link> or <link xlink:href="ftp://louie.udel.edu/">louie.udel.edu</link>.</para> <para>This primer is not a full comprehensive explanation of how <application>MH</application> works. This is just intended to get you started on the road to happier, faster mail reading. You should read the manual pages for the various commands. You might - also want to read the <ulink - url="news:comp.mail.mh">comp.mail.mh</ulink> newsgroup. Also you - can read the <ulink - url="http://www.faqs.org/faqs/mail/mh-faq/">FAQ for - <application>MH</application></ulink>. The best resource for - <application>MH</application> is <ulink - url="http://www.ics.uci.edu/~mh/book/">Jerry Peek's + also want to read the <link xlink:href="news:comp.mail.mh">comp.mail.mh</link> newsgroup. Also you + can read the <link xlink:href="http://www.faqs.org/faqs/mail/mh-faq/">FAQ for + <application>MH</application></link>. The best resource for + <application>MH</application> is <link xlink:href="http://www.ics.uci.edu/~mh/book/">Jerry Peek's <application>MH</application> & nmh: Email for Users & - Programmers</ulink>.</para> + Programmers</link>.</para> </sect1> <sect1> @@ -128,7 +115,7 @@ that refer to the current, last or first message in the folder.</para> - <sect2 id="inc"> + <sect2 xml:id="inc"> <title><command>inc</command>, <command>msgchk</command>—read in your new email or check it</title> @@ -162,7 +149,7 @@ command line arguments.</para> <informalexample> - <screen>&prompt.user; <userinput>inc -host mail.pop.org -user <replaceable>username</replaceable> -norpop</userinput></screen> + <screen>&prompt.user; <userinput>inc -host mail.pop.org -user username -norpop</userinput></screen> </informalexample> <para>That tells <command>inc</command> to go to @@ -183,7 +170,7 @@ options that <command>inc</command> takes.</para> </sect2> - <sect2 id="show"> + <sect2 xml:id="show"> <title><command>show</command>, <command>next</command> and <command>prev</command>—displaying and moving through email</title> @@ -211,7 +198,7 @@ it.</para> </sect2> - <sect2 id="scan"> + <sect2 xml:id="scan"> <title><command>scan</command>—shows you a scan of your messages</title> @@ -241,11 +228,11 @@ have it read from a file. If you want to scan your incoming mailbox on FreeBSD without having to <command>inc</command> it you can do <command>scan -file - /var/mail/<replaceable>username</replaceable></command>. This can be used + /var/mail/username</command>. This can be used with any file that is in the <database>mbox</database> format.</para> </sect2> - <sect2 id="rmm"> + <sect2 xml:id="rmm"> <title><command>rmm</command> and <command>rmf</command>—remove the current message or folder</title> @@ -262,7 +249,7 @@ command.</para> </sect2> - <sect2 id="samplereading"> + <sect2 xml:id="samplereading"> <title>A typical session of reading with MH</title> <para>The first thing that you will want to do is @@ -541,8 +528,7 @@ which I am probably the guilty party).</screen> <screen>&prompt.user; <userinput>pick -to freebsd-hackers -or -cc freebsd-hackers</userinput></screen> </informalexample> - <para>That will grab all the email in your <filename - class="directory">inbox</filename> that was sent to + <para>That will grab all the email in your <filename>inbox</filename> that was sent to freebsd-hackers or cc'd to that list. The brace options allow you to group search criteria together. This is sometimes very necessary as in the following example</para> @@ -576,7 +562,7 @@ which I am probably the guilty party).</screen> manipulating your folders. The <command>folder</command> program is used to switch between folders, pack them, and list them. At its simplest level you can do a <command>folder - +<replaceable>newfolder</replaceable></command> and you will + +newfolder</command> and you will be switched into <replaceable>newfolder</replaceable>. From there on out all your <application>MH</application> commands like <command>comp</command>, <command>repl</command>, diff --git a/en_US.ISO8859-1/articles/nanobsd/article.xml b/en_US.ISO8859-1/articles/nanobsd/article.xml index a12c10305d..52d64f9bd6 100644 --- a/en_US.ISO8859-1/articles/nanobsd/article.xml +++ b/en_US.ISO8859-1/articles/nanobsd/article.xml @@ -1,17 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Introduction to NanoBSD</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Introduction to NanoBSD</title> + <authorgroup> - <author> - <firstname>Daniel</firstname> - <surname>Gerzo</surname> - <!-- 14 March 2006 --> - </author> + <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname></author> </authorgroup> <copyright> @@ -19,7 +14,7 @@ <holder>The FreeBSD Documentation Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -34,9 +29,9 @@ create &os; system images for embedded applications, suitable for use on a Compact Flash card (or other mass storage medium).</para> </abstract> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction to NanoBSD</title> <indexterm><primary>NanoBSD</primary></indexterm> @@ -87,10 +82,10 @@ </itemizedlist> </sect1> - <sect1 id="howto"> + <sect1 xml:id="howto"> <title>NanoBSD Howto</title> - <sect2 id="design"> + <sect2 xml:id="design"> <title>The design of NanoBSD</title> <para>Once the image is present on the medium, it is possible to @@ -105,24 +100,24 @@ <listitem> <para>The configuration file partition, which can be mounted - under the <filename class="directory">/cfg</filename> directory + under the <filename>/cfg</filename> directory at run time.</para> </listitem> </itemizedlist> <para>These partitions are normally mounted read-only.</para> - <para>The <filename class="directory">/etc</filename> and - <filename class="directory">/var</filename> directories are + <para>The <filename>/etc</filename> and + <filename>/var</filename> directories are &man.md.4; (malloc) disks.</para> <para>The configuration file partition persists under the - <filename class="directory">/cfg</filename> directory. It - contains files for <filename class="directory">/etc</filename> + <filename>/cfg</filename> directory. It + contains files for <filename>/etc</filename> directory and is briefly mounted read-only right after the system boot, therefore it is required to copy modified files - from <filename class="directory">/etc</filename> back to the - <filename class="directory">/cfg</filename> directory if changes + from <filename>/etc</filename> back to the + <filename>/cfg</filename> directory if changes are expected to persist after the system restarts.</para> <example> @@ -137,11 +132,11 @@ <note> <para>The partition containing - <filename class="directory">/cfg</filename> should be mounted + <filename>/cfg</filename> should be mounted only at boot time and while overriding the configuration files.</para> - <para>Keeping <filename class="directory">/cfg</filename> mounted at + <para>Keeping <filename>/cfg</filename> mounted at all times is not a good idea, especially if the <application>NanoBSD</application> system runs off a mass storage medium that may be adversely affected by a large number @@ -156,17 +151,17 @@ <para>A <application>NanoBSD</application> image is built using a simple <filename>nanobsd.sh</filename> shell script, which can be found in the - <filename class="directory"><replaceable>/usr</replaceable>/src/tools/tools/nanobsd</filename> + <filename>/usr/src/tools/tools/nanobsd</filename> directory. This script creates an image, which can be copied on the storage medium using the &man.dd.1; utility.</para> <para>The necessary commands to build a <application>NanoBSD</application> image are:</para> - <screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput> <co id="nbsd-cd"/> -&prompt.root; <userinput>sh nanobsd.sh</userinput> <co id="nbsd-sh"/> -&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co id="nbsd-cd2"/> -&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co id="nbsd-dd"/></screen> + <screen>&prompt.root; <userinput>cd /usr/src/tools/tools/nanobsd</userinput> <co xml:id="nbsd-cd"/> +&prompt.root; <userinput>sh nanobsd.sh</userinput> <co xml:id="nbsd-sh"/> +&prompt.root; <userinput>cd /usr/obj/nanobsd.full</userinput> <co xml:id="nbsd-cd2"/> +&prompt.root; <userinput>dd if=_.disk.full of=/dev/da0 bs=64k</userinput> <co xml:id="nbsd-dd"/></screen> <calloutlist> <callout arearefs="nbsd-cd"> @@ -221,8 +216,8 @@ <title>Configuration options</title> <para>With configuration settings, it is possible to configure options - passed to both the <maketarget>buildworld</maketarget> - and <maketarget>installworld</maketarget> stages of the + passed to both the <buildtarget>buildworld</buildtarget> + and <buildtarget>installworld</buildtarget> stages of the <application>NanoBSD</application> build process, as well as internal options passed to the main build process of <application>NanoBSD</application>. Through these options it is @@ -253,18 +248,18 @@ <listitem> <para><literal>CONF_BUILD</literal> — Options passed - to the <maketarget>buildworld</maketarget> stage of the build.</para> + to the <buildtarget>buildworld</buildtarget> stage of the build.</para> </listitem> <listitem> <para><literal>CONF_INSTALL</literal> — Options passed - to the <maketarget>installworld</maketarget> stage of the build.</para> + to the <buildtarget>installworld</buildtarget> stage of the build.</para> </listitem> <listitem> <para><literal>CONF_WORLD</literal> — Options passed to both - the <maketarget>buildworld</maketarget> and - the <maketarget>installworld</maketarget> stage of the build.</para> + the <buildtarget>buildworld</buildtarget> and + the <buildtarget>installworld</buildtarget> stage of the build.</para> </listitem> <listitem> @@ -291,7 +286,7 @@ customize_cmd cust_foo</programlisting> <para>A more useful example of a customization function is the following, which changes the default size of the - <filename class="directory">/etc</filename> directory + <filename>/etc</filename> directory from 5MB to 30MB:</para> <programlisting>cust_etc_size () ( @@ -313,13 +308,13 @@ customize_cmd cust_etc_size</programlisting> <listitem> <para><literal>cust_allow_ssh_root</literal> — Allow - <username>root</username> to login via &man.sshd.8;.</para> + <systemitem class="username">root</systemitem> to login via &man.sshd.8;.</para> </listitem> <listitem> <para><literal>cust_install_files</literal> — Installs files from the - <filename class="directory">nanobsd/Files</filename> + <filename>nanobsd/Files</filename> directory, which contains some useful scripts for system administration.</para> </listitem> @@ -447,7 +442,7 @@ customize_cmd cust_nobeastie</programlisting> <application>NanoBSD</application> system, it is possible to use either the <filename>updatep1</filename> or <filename>updatep2</filename> script located in the - <filename class="directory">/root</filename> directory, depending + <filename>/root</filename> directory, depending from which partition is running the current system.</para> <para>According to which services are available on host serving @@ -485,7 +480,7 @@ get _.disk.image "| sh updatep1"</userinput></screen> <para>At first, open a TCP listener on host serving the image and make it send the image to client:</para> - <screen>myhost&prompt.root; <userinput>nc -l <replaceable>2222</replaceable> < _.disk.image</userinput></screen> + <screen>myhost&prompt.root; <userinput>nc -l 2222 < _.disk.image</userinput></screen> <note> <para>Make sure that the used port is not blocked to @@ -498,10 +493,12 @@ get _.disk.image "| sh updatep1"</userinput></screen> <para>Connect to the host serving new image and execute <filename>updatep1</filename> script:</para> - <screen>&prompt.root; <userinput>nc myhost <replaceable>2222</replaceable> | sh updatep1</userinput></screen> + <screen>&prompt.root; <userinput>nc myhost 2222 | sh updatep1</userinput></screen> </step> </procedure> </sect3> </sect2> </sect1> + + <index/> </article> diff --git a/en_US.ISO8859-1/articles/new-users/article.xml b/en_US.ISO8859-1/articles/new-users/article.xml index d298a80c6d..2caedf67e1 100644 --- a/en_US.ISO8859-1/articles/new-users/article.xml +++ b/en_US.ISO8859-1/articles/new-users/article.xml @@ -1,29 +1,21 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- The FreeBSD Documentation Project --> - -<article lang='en'> - <articleinfo> - <title>For People New to Both FreeBSD and &unix;</title> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>For People New to Both FreeBSD and &unix;</title> + <authorgroup> - <author> - <firstname>Annelise</firstname> - - <surname>Anderson</surname> - - <affiliation> + <author><personname><firstname>Annelise</firstname><surname>Anderson</surname></personname><affiliation> <address><email>andrsn@andrsn.stanford.edu</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <pubdate>August 15, 1997</pubdate> + <pubdate>1997-08-15</pubdate> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.microsoft; @@ -42,21 +34,21 @@ (you)—and you are probably pretty good with DOS/&windows; or &os2;.</para> </abstract> - </articleinfo> + </info> - <sect1 id="in-and-out"> + <sect1 xml:id="in-and-out"> <title>Logging in and Getting Out</title> - <para>Log in (when you see <prompt >login:</prompt>) as a user you - created during installation or as <username>root</username>. + <para>Log in (when you see <prompt>login:</prompt>) as a user you + created during installation or as <systemitem class="username">root</systemitem>. (Your FreeBSD installation will already have an account for - <username>root</username>; who can go anywhere and do anything, including deleting + <systemitem class="username">root</systemitem>; who can go anywhere and do anything, including deleting essential files, so be careful!) The symbols &prompt.user; and &prompt.root; in the following stand for the prompt (yours may be different), with &prompt.user; indicating an ordinary user - and &prompt.root; indicating <username>root</username>.</para> + and &prompt.root; indicating <systemitem class="username">root</systemitem>.</para> - <para>To log out (and get a new <prompt >login:</prompt> prompt) + <para>To log out (and get a new <prompt>login:</prompt> prompt) type</para> <informalexample> @@ -94,11 +86,11 @@ do not want to have to reinstall this thing, do you?</para> </sect1> - <sect1 id="adding-a-user"> + <sect1 xml:id="adding-a-user"> <title>Adding A User with Root Privileges</title> <para>If you did not create any users when you installed the system - and are thus logged in as <username>root</username>, you should probably create a + and are thus logged in as <systemitem class="username">root</systemitem>, you should probably create a user now with</para> <informalexample> @@ -112,39 +104,39 @@ enter to accept each default. These defaults are saved in <filename>/etc/adduser.conf</filename>, an editable file.</para> - <para>Suppose you create a user <username>jack</username> with - full name <emphasis>Jack Benimble</emphasis>. Give <username>jack</username> a + <para>Suppose you create a user <systemitem class="username">jack</systemitem> with + full name <emphasis>Jack Benimble</emphasis>. Give <systemitem class="username">jack</systemitem> a password if security (even kids around who might pound on the keyboard) is an issue. When it asks you if you want to invite - <username>jack</username> into other groups, type <groupname>wheel</groupname></para> + <systemitem class="username">jack</systemitem> into other groups, type <systemitem class="groupname">wheel</systemitem></para> <informalexample> <screen>Login group is ``jack''. Invite jack into other groups: <userinput>wheel</userinput></screen> </informalexample> <para>This will make it possible to log in as - <username>jack</username> and use the &man.su.1; - command to become <username>root</username>. Then you will not get scolded any more for - logging in as <username>root</username>.</para> + <systemitem class="username">jack</systemitem> and use the &man.su.1; + command to become <systemitem class="username">root</systemitem>. Then you will not get scolded any more for + logging in as <systemitem class="username">root</systemitem>.</para> <para>You can quit <command>adduser</command> any time by typing <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>, and at the end you will have a chance to approve your new user or simply type <keycap>n</keycap> for no. You might want to create - a second new user so that when you edit <username>jack</username>'s login + a second new user so that when you edit <systemitem class="username">jack</systemitem>'s login files, you will have a hot spare in case something goes wrong.</para> <para>Once you have done this, use <command>exit</command> to get - back to a login prompt and log in as <username>jack</username>. + back to a login prompt and log in as <systemitem class="username">jack</systemitem>. In general, it is a good idea to do as much work as possible as an ordinary user who does not have the power—and - risk—of <username>root</username>.</para> + risk—of <systemitem class="username">root</systemitem>.</para> <para>If you already created a user and you want the user to be - able to <command>su</command> to <username>root</username>, you can log in as <username>root</username> - and edit the file <filename>/etc/group</filename>, adding <username>jack</username> - to the first line (the group <groupname>wheel</groupname>). But + able to <command>su</command> to <systemitem class="username">root</systemitem>, you can log in as <systemitem class="username">root</systemitem> + and edit the file <filename>/etc/group</filename>, adding <systemitem class="username">jack</systemitem> + to the first line (the group <systemitem class="groupname">wheel</systemitem>). But first you need to practice &man.vi.1;, the text editor—or use the simpler text editor, &man.ee.1;, installed on recent versions of FreeBSD.</para> @@ -153,7 +145,7 @@ command.</para> </sect1> - <sect1 id="looking-around"> + <sect1 xml:id="looking-around"> <title>Looking Around</title> <para>Logged in as an ordinary user, look around and try out some @@ -189,7 +181,7 @@ </varlistentry> <varlistentry> - <term><command>ls <option>-F</option></command></term> + <term><command>ls -F</command></term> <listitem> <para>Lists the files in the current directory with a @@ -200,7 +192,7 @@ </varlistentry> <varlistentry> - <term><command>ls <option>-l</option></command></term> + <term><command>ls -l</command></term> <listitem> <para>Lists the files in long format—size, date, @@ -209,11 +201,11 @@ </varlistentry> <varlistentry> - <term><command>ls <option>-a</option></command></term> + <term><command>ls -a</command></term> <listitem> <para>Lists hidden <quote>dot</quote> files with the others. - If you are <username>root</username>, the <quote>dot</quote> files show up + If you are <systemitem class="username">root</systemitem>, the <quote>dot</quote> files show up without the <option>-a</option> switch.</para> </listitem> </varlistentry> @@ -223,13 +215,13 @@ <listitem> <para>Changes directories. <command>cd - <parameter>..</parameter></command> backs up one level; + ..</command> backs up one level; note the space after <command>cd</command>. <command>cd - <parameter>/usr/local</parameter></command> goes there. - <command>cd <parameter>~</parameter></command> goes to the + /usr/local</command> goes there. + <command>cd ~</command> goes to the home directory of the person logged in—e.g., <filename>/usr/home/jack</filename>. Try <command>cd - <parameter>/cdrom</parameter></command>, and then + /cdrom</command>, and then <command>ls</command>, to find out if your CDROM is mounted and working.</para> </listitem> @@ -237,20 +229,20 @@ <varlistentry> <term><command>view - <replaceable>filename</replaceable></command></term> + filename</command></term> <listitem> <para>Lets you look at a file (named <replaceable>filename</replaceable>) without changing it. Try <command>view - <parameter>/etc/fstab</parameter></command>. + /etc/fstab</command>. Type <command>:q</command> to quit.</para> </listitem> </varlistentry> <varlistentry> <term><command>cat - <replaceable>filename</replaceable></command></term> + filename</command></term> <listitem> <para>Displays <replaceable>filename</replaceable> on @@ -261,9 +253,9 @@ <keycap>ScrollLock</keycap> again to quit scrolling. You might want to try <command>cat</command> on some of the dot files in your home directory—<command>cat - <parameter>.cshrc</parameter></command>, <command>cat - <parameter>.login</parameter></command>, <command>cat - <parameter>.profile</parameter></command>.</para> + .cshrc</command>, <command>cat + .login</command>, <command>cat + .profile</command>.</para> </listitem> </varlistentry> </variablelist> @@ -277,7 +269,7 @@ <filename>/etc/csh.cshrc</filename>.</para> </sect1> - <sect1 id="getting-help"> + <sect1 xml:id="getting-help"> <title>Getting Help and Information</title> <para>Here are some useful sources of help. @@ -288,7 +280,7 @@ <variablelist> <varlistentry> <term><command>apropos - <replaceable>text</replaceable></command></term> + text</command></term> <listitem> <para>Everything containing string @@ -299,12 +291,12 @@ <varlistentry> <term><command>man - <replaceable>text</replaceable></command></term> + text</command></term> <listitem> <para>The manual page for <replaceable>text</replaceable>. The major source of documentation for &unix; systems. - <command>man <parameter>ls</parameter></command> will tell + <command>man ls</command> will tell you all the ways to use the <command>ls</command> command. Press <keycap>Enter</keycap> to move through text, <keycombo><keycap>Ctrl</keycap><keycap>B</keycap></keycombo> @@ -318,7 +310,7 @@ <varlistentry> <term><command>which - <replaceable>text</replaceable></command></term> + text</command></term> <listitem> <para>Tells you where in the user's path the command @@ -328,7 +320,7 @@ <varlistentry> <term><command>locate - <replaceable>text</replaceable></command></term> + text</command></term> <listitem> <para>All the paths where the string @@ -338,7 +330,7 @@ <varlistentry> <term><command>whatis - <replaceable>text</replaceable></command></term> + text</command></term> <listitem> <para>Tells you what the command @@ -350,7 +342,7 @@ <varlistentry> <term><command>whereis - <replaceable>text</replaceable></command></term> + text</command></term> <listitem> <para>Finds the file <replaceable>text</replaceable>, giving @@ -368,7 +360,7 @@ <command>script</command>. <command>more</command> lets you read a page at a time as it does in DOS, e.g., <command>ls -l | more</command> or <command>more - <replaceable>filename</replaceable></command>. The + filename</command>. The <literal>*</literal> works as a wildcard—e.g., <command>ls w*</command> will show you files beginning with <literal>w</literal>.</para> @@ -378,7 +370,7 @@ on a database that is rebuilt weekly. If your machine is not going to be left on over the weekend (and running FreeBSD), you might want to run the commands for daily, weekly, and monthly - maintenance now and then. Run them as <username>root</username> and, for now, give each one + maintenance now and then. Run them as <systemitem class="username">root</systemitem> and, for now, give each one time to finish before you start the next one.</para> <informalexample> @@ -404,7 +396,7 @@ <para>Running such commands is part of system administration—and as a single user of a &unix; system, you are your own system administrator. Virtually everything you - need to be <username>root</username> to do is system administration. Such + need to be <systemitem class="username">root</systemitem> to do is system administration. Such responsibilities are not covered very well even in those big fat books on &unix;, which seem to devote a lot of space to pulling down menus in windows managers. You might want to get one of @@ -417,12 +409,12 @@ ISBN 0-596-00343-9). I used Nemeth.</para> </sect1> - <sect1 id="editing-text"> + <sect1 xml:id="editing-text"> <title>Editing Text</title> <para>To configure your system, you need to edit text files. Most of them will be in the <filename>/etc</filename> directory; and - you will need to <command>su</command> to <username>root</username> to be able to + you will need to <command>su</command> to <systemitem class="username">root</systemitem> to be able to change them. You can use the easy <command>ee</command>, but in the long run the text editor <command>vi</command> is worth learning. There is an excellent tutorial on vi in @@ -465,7 +457,7 @@ <para>To edit a file, type</para> <informalexample> - <screen>&prompt.root; <userinput>vi <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>vi filename</userinput></screen> </informalexample> <para>Move through the text with the arrow keys. @@ -538,11 +530,11 @@ </varlistentry> <varlistentry> - <term><command>/<replaceable>text</replaceable></command></term> + <term><command>/text</command></term> <listitem> <para>to move the cursor to <replaceable>text</replaceable>; - <command>/<keycap>Enter</keycap></command> (the enter key) + <command>/Enter</command> (the enter key) to find the next instance of <replaceable>text</replaceable>.</para> </listitem> @@ -557,7 +549,7 @@ </varlistentry> <varlistentry> - <term><command><replaceable>n</replaceable>G</command></term> + <term><command>nG</command></term> <listitem> <para>to go to line <replaceable>n</replaceable> in the @@ -587,7 +579,7 @@ <para>Practice with <command>vi</command> in your home directory by creating a new file with <command>vi - <replaceable>filename</replaceable></command> and adding and + filename</command> and adding and deleting text, saving the file, and calling it up again. <command>vi</command> delivers some surprises because it is really quite complex, and sometimes you will inadvertently issue a @@ -601,9 +593,9 @@ <command>:w</command>) when you need to.</para> <para>Now you can <command>cd</command> to - <filename>/etc</filename>, <command>su</command> to <username>root</username>, use + <filename>/etc</filename>, <command>su</command> to <systemitem class="username">root</systemitem>, use <command>vi</command> to edit the file - <filename>/etc/group</filename>, and add a user to <groupname>wheel</groupname> so the + <filename>/etc/group</filename>, and add a user to <systemitem class="groupname">wheel</systemitem> so the user has root privileges. Just add a comma and the user's login name to the end of the first line in the file, press <keycap>Esc</keycap>, and use <command>:wq</command> to write @@ -611,7 +603,7 @@ put a space after the comma, did you?)</para> </sect1> - <sect1 id="printing-files-from-dos"> + <sect1 xml:id="printing-files-from-dos"> <title>Printing Files from DOS</title> <para>At this point you probably do not have the printer working, @@ -628,7 +620,7 @@ <para>will remove formatting codes and send the manual page to the <filename>chmod.txt</filename> file instead of showing it on your screen. Now put a dos-formatted diskette in your floppy - drive <devicename>a</devicename>, <command>su</command> to <username>root</username>, and type</para> + drive <filename>a</filename>, <command>su</command> to <systemitem class="username">root</systemitem>, and type</para> <informalexample> <screen>&prompt.root; <userinput>/sbin/mount -t msdosfs /dev/fd0 /mnt</userinput></screen> @@ -637,7 +629,7 @@ <para>to mount the floppy drive on <filename>/mnt</filename>.</para> - <para>Now (you no longer need to be <username>root</username>, and you can type + <para>Now (you no longer need to be <systemitem class="username">root</systemitem>, and you can type <command>exit</command> to get back to being user jack) you can go to the directory where you created <filename>chmod.txt</filename> and copy the file to the floppy @@ -666,7 +658,7 @@ what do I do?</quote>—people will want to know what <command>dmesg</command> has to say.</para> - <para>You can now unmount the floppy drive (as <username>root</username>) to get the + <para>You can now unmount the floppy drive (as <systemitem class="username">root</systemitem>) to get the disk out with</para> <informalexample> @@ -688,18 +680,17 @@ <filename>/var/spool/output</filename>. If your printer is on <hardware>lpt0</hardware> (what DOS calls <hardware>LPT1</hardware>), you may only need to go to - <filename>/var/spool/output</filename> and (as <username>root</username>) create the + <filename>/var/spool/output</filename> and (as <systemitem class="username">root</systemitem>) create the directory <filename>lpd</filename> by typing: <command>mkdir lpd</command>, if it does not already exist. Then the printer should respond if it is turned on when the system is booted, and <command>lp</command> or <command>lpr</command> should send a file to the printer. Whether or not the file actually prints - depends on configuring it, which is covered in the <ulink - url="&url.books.handbook;/index.html">FreeBSD - handbook.</ulink></para> + depends on configuring it, which is covered in the <link xlink:href="&url.books.handbook;/index.html">FreeBSD + handbook.</link></para> </sect1> - <sect1 id="other-useful-commands"> + <sect1 xml:id="other-useful-commands"> <title>Other Useful Commands</title> <variablelist> @@ -721,7 +712,7 @@ </varlistentry> <varlistentry> - <term><command>rm <replaceable>filename</replaceable></command></term> + <term><command>rm filename</command></term> <listitem> <para>remove <replaceable>filename</replaceable>.</para> @@ -729,7 +720,7 @@ </varlistentry> <varlistentry> - <term><command>rm -R <replaceable>dir</replaceable></command></term> + <term><command>rm -R dir</command></term> <listitem> <para>removes a directory <replaceable>dir</replaceable> and all @@ -754,7 +745,7 @@ <term><command>passwd</command></term> <listitem> - <para>to change user's password (or <username>root</username>'s password)</para> + <para>to change user's password (or <systemitem class="username">root</systemitem>'s password)</para> </listitem> </varlistentry> @@ -772,7 +763,7 @@ with</para> <informalexample> - <screen>&prompt.user; <userinput>find /usr -name "<replaceable>filename</replaceable>"</userinput></screen> + <screen>&prompt.user; <userinput>find /usr -name "filename"</userinput></screen> </informalexample> <para>You can use <literal>*</literal> as a wildcard in @@ -789,18 +780,17 @@ There is also a lot of &unix; information on the Internet.</para> </sect1> - <sect1 id="next-steps"> + <sect1 xml:id="next-steps"> <title>Next Steps</title> <para>You should now have the tools you need to get around and edit files, so you can get everything up and running. There is a great deal of information in the FreeBSD handbook (which is - probably on your hard drive) and <ulink - url="&url.base;/index.html">FreeBSD's web site</ulink>. A + probably on your hard drive) and <link xlink:href="&url.base;/index.html">FreeBSD's web site</link>. A wide variety of packages and ports are on the CDROM as well as the web site. The handbook tells you more about how to use them (get the package if it exists, with <command>pkg_add - /cdrom/packages/All/<replaceable>packagename</replaceable></command>, + /cdrom/packages/All/packagename</command>, where <replaceable>packagename</replaceable> is the filename of the package). The CDROM has lists of the packages and ports with brief descriptions in @@ -880,7 +870,7 @@ space after the slash.)</para> </sect1> - <sect1 id="your-working-environment"> + <sect1 xml:id="your-working-environment"> <title>Your Working Environment</title> <para>Your shell is the most important part of your working @@ -920,7 +910,7 @@ </step> <step> - <para>As <username>root</username>, edit <filename>/etc/shells</filename>, adding a + <para>As <systemitem class="username">root</systemitem>, edit <filename>/etc/shells</filename>, adding a line in the file for the new shell, in this case <filename>/usr/local/bin/tcsh</filename>, and save the file. (Some ports may do this for you.)</para> @@ -935,13 +925,13 @@ </procedure> <note> - <para>It can be dangerous to change <username>root</username>'s shell to something + <para>It can be dangerous to change <systemitem class="username">root</systemitem>'s shell to something other than <command>sh</command> or <command>csh</command> on early versions of FreeBSD and many other versions of &unix;; you may not have a working shell when the system puts you into single user mode. The solution is to use <command>su - -m</command> to become <username>root</username>, which will give you the - <command>tcsh</command> as <username>root</username>, because the shell is part of + -m</command> to become <systemitem class="username">root</systemitem>, which will give you the + <command>tcsh</command> as <systemitem class="username">root</systemitem>, because the shell is part of the environment. You can make this permanent by adding it to your <filename>.tcshrc</filename> file as an alias with:</para> <programlisting>alias su su -m</programlisting> @@ -962,8 +952,8 @@ for <command>tcsh</command>, but here is a line to put in your <filename>.tcshrc</filename> that will tell you how many commands you have typed, what time it is, and what directory you - are in. It also produces a <literal>></literal> if you are an - ordinary user and a <literal>#</literal> if you are <username>root</username>, but + are in. It also produces a <literal>></literal> if you are an + ordinary user and a <literal>#</literal> if you are <systemitem class="username">root</systemitem>, but tsch will do that in any case:</para> <para>set prompt = "%h %t %~ %# "</para> @@ -984,10 +974,10 @@ vt100</command>.</para> </sect1> - <sect1 id="other"> + <sect1 xml:id="other"> <title>Other</title> - <para>As <username>root</username>, you can unmount the CDROM with + <para>As <systemitem class="username">root</systemitem>, you can unmount the CDROM with <command>/sbin/umount /cdrom</command>, take it out of the drive, insert another one, and mount it with <command>/sbin/mount_cd9660 /dev/cd0a /cdrom</command> assuming @@ -1007,7 +997,7 @@ <command>man lndir</command>.</para> </sect1> - <sect1 id="comments-welcome"> + <sect1 xml:id="comments-welcome"> <title>Comments Welcome</title> <para>If you use this guide I would be interested in knowing where it diff --git a/en_US.ISO8859-1/articles/p4-primer/article.xml b/en_US.ISO8859-1/articles/p4-primer/article.xml index d93580c45b..8b9eb87dad 100644 --- a/en_US.ISO8859-1/articles/p4-primer/article.xml +++ b/en_US.ISO8859-1/articles/p4-primer/article.xml @@ -1,24 +1,19 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + -<article lang='en'> - <title>Perforce in &os; Development</title> - - <articleinfo> + <info><title>Perforce in &os; Development</title> <authorgroup> - <author> - <firstname>Scott</firstname> - <surname>Long</surname> - <affiliation> + <author><personname><firstname>Scott</firstname><surname>Long</surname></personname><affiliation> <address><email>scottl@FreeBSD.org</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.general; @@ -27,25 +22,24 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> -<sect1 id="intro"> +<sect1 xml:id="intro"> <title>Introduction</title> <para>The &os; project uses the <application>Perforce</application> version control system to manage experimental projects that are not ready for the main Subversion repository.</para> - <sect2 id="resources"> + <sect2 xml:id="resources"> <title>Availability, Documentation, and Resources</title> <para>While <application>Perforce</application> is a commercial product, the client software for interacting with the server is freely available from Perforce. It can be easily installed on - &os; via the <filename role="package">devel/p4</filename> + &os; via the <package>devel/p4</package> port or can be downloaded from the <application>Perforce</application> - web site at <ulink - url="http://www.perforce.com/perforce/loadprog.html"></ulink>, + web site at <uri xlink:href="http://www.perforce.com/perforce/loadprog.html">http://www.perforce.com/perforce/loadprog.html</uri>, which also offers client applications for other OS's.</para> <para>While there is a GUI client available, most people use the @@ -53,8 +47,7 @@ document is written from the point of view of using this command.</para> - <para>Detailed documentation is available online at <ulink - url="http://www.perforce.com/perforce/technical.html"></ulink>.</para> + <para>Detailed documentation is available online at <uri xlink:href="http://www.perforce.com/perforce/technical.html">http://www.perforce.com/perforce/technical.html</uri>.</para> <para>Reading the <quote>Perforce User's Guide</quote> and <quote>Perforce Command Reference</quote> is highly recommended. @@ -63,28 +56,25 @@ help</command> command.</para> <para>The &os; <application>Perforce</application> server is - hosted on <hostid role="fqdn">perforce.freebsd.org</hostid>, + hosted on <systemitem class="fqdomainname">perforce.freebsd.org</systemitem>, port <literal>1666</literal>. The repository is browsable - online at <ulink url="http://p4web.freebsd.org"></ulink>. + online at <uri xlink:href="http://p4web.freebsd.org">http://p4web.freebsd.org</uri>. Some portions of the repository are also automatically exported to a number of legacy <application>CVSup</application> servers.</para> </sect2> </sect1> -<sect1 id="start"> +<sect1 xml:id="start"> <title>Getting Started</title> <para>The first step to using <application>Perforce</application> is - to obtain an account on the server. If you already have a <hostid - role="domainname">FreeBSD.org</hostid> account, log into <hostid - role="hostname">freefall</hostid>, run the following command, and + to obtain an account on the server. If you already have a <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, log into <systemitem class="fqdomainname">freefall</systemitem>, run the following command, and enter a password that is not the same as your &os; login or any other SSH passphrase:</para> <screen>&prompt.user; <userinput>/usr/local/bin/p4newuser</userinput></screen> - <para>Of course if you do not have a <hostid - role="domainname">FreeBSD.org</hostid> account, you will need to + <para>Of course if you do not have a <systemitem class="fqdomainname">FreeBSD.org</systemitem> account, you will need to coordinate with your sponsor.</para> <warning> @@ -104,8 +94,7 @@ <screen>&prompt.user; <userinput>export P4PORT=perforce.freebsd.org:1666</userinput></screen> <note> - <para>Users with shell access on the <hostid - role="domainname">FreeBSD.org</hostid> cluster may wish to tunnel + <para>Users with shell access on the <systemitem class="fqdomainname">FreeBSD.org</systemitem> cluster may wish to tunnel the <application>Perforce</application> client-server protocol via an SSH tunnel, in which case the above string should be set to <literal>localhost</literal>.</para> @@ -115,8 +104,8 @@ and <envar>P4PASSWD</envar> variables be set. Use the username and password from above, like so:</para> - <screen>&prompt.user; <userinput>export P4USER=<replaceable>username</replaceable></userinput> -&prompt.user; <userinput>export P4PASSWD=<replaceable>password</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>export P4USER=username</userinput> +&prompt.user; <userinput>export P4PASSWD=password</userinput></screen> <para>Test that this works by running the following command:</para> @@ -127,7 +116,7 @@ variable set correctly.</para> </sect1> -<sect1 id="clients"> +<sect1 xml:id="clients"> <title>Clients</title> <para><application>Perforce</application> provides access to the @@ -156,7 +145,7 @@ you want, but it must be unique within the <application>Perforce</application> server. A naming convention that is commonly used is - <literal><replaceable>username</replaceable>_<replaceable>machinename</replaceable></literal>, + <literal>username_machinename</literal>, which makes it easy to identify clients when browsing them. A default name will be filled in that is just the machine name.</para> @@ -217,13 +206,12 @@ <para>This will map the entire <application>Perforce</application> repository to the - <filename class="directory">Root</filename> directory of your + <filename>Root</filename> directory of your client. <emphasis>DO NOT USE THIS DEFAULT!</emphasis> The &os; repo is huge, and trying to map and sync it all will take an enormous amount of resources. Instead, only map the section of the repo that you intend to work on. For - example, there is the smpng project tree at <filename - class="directory">//depot/projects/smpng</filename>. A + example, there is the smpng project tree at <filename>//depot/projects/smpng</filename>. A mapping for this might look like:</para> <programlisting>//depot/projects/smpng/... //<replaceable>client</replaceable>/...</programlisting> @@ -264,14 +252,14 @@ <para>Existing clients can be listed via the <command>p4 clients</command> command. They can be viewed without being modified via the <command>p4 client -o - <replaceable>clientname</replaceable></command> command.</para> + clientname</command> command.</para> <para>Whenever you are interacting with files in <application>Perforce</application>, the <envar>P4CLIENT</envar> environment variable must be set to the name of the client that you are using, like so:</para> - <screen>&prompt.user; <userinput>export P4CLIENT=<replaceable>myclientname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>export P4CLIENT=myclientname</userinput></screen> <para>Note that client mappings in the repository are not exclusive; multiple clients can map in the same part of the repository. This @@ -280,7 +268,7 @@ code.</para> </sect1> -<sect1 id="syncing"> +<sect1 xml:id="syncing"> <title>Syncing</title> <para>Once you have a client specification defined and the @@ -304,18 +292,18 @@ <para>You can sync a subset of your tree or client by specifying a relative path to the sync command. For example, to only sync the - <filename class="directory">ufs</filename> directory of the + <filename>ufs</filename> directory of the <literal>smpng</literal> project, you might do the following:</para> - <screen>&prompt.user; <userinput>cd <replaceable>projectroot</replaceable>/smpng</userinput> + <screen>&prompt.user; <userinput>cd projectroot/smpng</userinput> &prompt.user; <userinput>p4 sync src/sys/ufs/...</userinput></screen> <para>Specifying a local relative path works for many other <command>p4</command> commands.</para> </sect1> -<sect1 id="branches"> +<sect1 xml:id="branches"> <title>Branches</title> <para>One of the strongest features of @@ -335,10 +323,9 @@ <application>Perforce</application> repository (the <quote>depot</quote>) is a single flat tree. Every file, whether a unique creation or a derivative from a branch, is accessible via - a simple path under the server <filename - class="directory">//depot</filename> directory. When you create a + a simple path under the server <filename>//depot</filename> directory. When you create a branch, all you are doing is creating a new path under the - <filename class="directory">//depot</filename>. This is in sharp + <filename>//depot</filename>. This is in sharp contrast to systems like CVS, where each branch lives in the same path as its parent. With <application>Perforce</application>, the server tracks the relationship between the files in the parent and @@ -347,7 +334,7 @@ <para>The first step to creating a branch is to create a branch specification. This is similar to a client specification, but is created via the command <command>p4 branch - <replaceable>branchname</replaceable></command>.</para> + branchname</command>.</para> <para>The following important fields are explained:</para> @@ -411,7 +398,7 @@ command, as described in the next section.</para> </sect1> -<sect1 id="Integrations"> +<sect1 xml:id="Integrations"> <title>Integrations</title> <para><quote>Integration</quote> is the term used by @@ -431,7 +418,7 @@ <para>The common way to do an integration is with the following command:</para> - <screen>&prompt.user; <userinput>p4 integrate -b <replaceable>branchname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 integrate -b branchname</userinput></screen> <para><replaceable>branchname</replaceable> is the name given to a branch spec, as discussed in the previous section. This command @@ -467,7 +454,7 @@ section.</para> </sect1> -<sect1 id="submit"> +<sect1 xml:id="submit"> <title>Submit</title> <para>Changes that are made locally should be committed back to the @@ -521,7 +508,7 @@ case-by-case basis.</para> </sect1> -<sect1 id="editing"> +<sect1 xml:id="editing"> <title>Editing</title> <para>The state of each file in the client is tracked and saved on @@ -534,7 +521,7 @@ <para>To open a file for editing, use the <command>p4 edit</command> command like so:</para> - <screen>&prompt.user; <userinput>p4 edit <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 edit filename</userinput></screen> <para>This marks the file on the server as being in the <emphasis>edit</emphasis> state, which then allows it to be submitted after changes are made, or @@ -558,7 +545,7 @@ your changes and revert it to its original state, run the <command>p4 revert</command> command like so:</para> - <screen>&prompt.user; <userinput>p4 revert <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 revert filename</userinput></screen> <para>This resyncs the file to the contents of the server, and removes the edit attribute from the server. Any local changes @@ -576,7 +563,7 @@ sync</command>.</para> </sect1> -<sect1 id="changes"> +<sect1 xml:id="changes"> <title>Changes, Descriptions, and History</title> <para>Changes to the <application>Perforce</application> depot can @@ -584,7 +571,7 @@ will provide a brief description of each change, who made the change, and what its change number was. A change can be examined in detail via the <command>p4 describe - <replaceable>changenumber</replaceable></command> command. This + changenumber</command> command. This will provide the submit log and the diffs of the actual change.</para> <para>Commonly, the <command>p4 describe</command> command is used in one @@ -592,7 +579,7 @@ <variablelist> <varlistentry> - <term><command>p4 describe -s <replaceable>CHANGE</replaceable></command></term> + <term><command>p4 describe -s CHANGE</command></term> <listitem> <para>List a short description of @@ -602,7 +589,7 @@ </varlistentry> <varlistentry> - <term><command>p4 describe -du <replaceable>CHANGE</replaceable></command></term> + <term><command>p4 describe -du CHANGE</command></term> <listitem> <para>List a description of changeset <emphasis>CHANGE</emphasis>, @@ -614,7 +601,7 @@ </varlistentry> <varlistentry> - <term><command>p4 describe -dc <replaceable>CHANGE</replaceable></command></term> + <term><command>p4 describe -dc CHANGE</command></term> <listitem> <para>List a description of changeset <emphasis>CHANGE</emphasis>, @@ -627,12 +614,12 @@ </variablelist> <para>The <command>p4 filelog - <replaceable>filename</replaceable></command> command will show + filename</command> command will show the history of a file, including all submits, integrations, and branches of it.</para> </sect1> -<sect1 id="diffs"> +<sect1 xml:id="diffs"> <title>Diffs</title> <para>There are two methods of producing file diffs in @@ -667,11 +654,11 @@ <option>-dc</option> flags do work. The two forms of this command are:</para> - <screen>&prompt.user; <userinput>p4 diff2 -b <replaceable>branchname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 diff2 -b branchname</userinput></screen> <para>and</para> - <screen>&prompt.user; <userinput>p4 diff2 //depot/<replaceable>path1</replaceable> //depot/<replaceable>path2</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 diff2 //depot/path1 //depot/path2</userinput></screen> </listitem> </varlistentry> </variablelist> @@ -686,11 +673,10 @@ (the <option>-u</option> flag of <option>diff2</option> will produce unified diffs that are somewhat compatible, but it does not include files that have been added or deleted). There is a - post-processing script at: <ulink - url="http://people.freebsd.org/~scottl/awkdiff"></ulink>.</para> + post-processing script at: <uri xlink:href="http://people.freebsd.org/~scottl/awkdiff">http://people.freebsd.org/~scottl/awkdiff</uri>.</para> </sect1> -<sect1 id="add-rm-files"> +<sect1 xml:id="add-rm-files"> <title>Adding and Removing Files</title> <para>Integrating a branch will bring existing files into your tree, @@ -698,7 +684,7 @@ Adding files is easily done be creating the file and then running the <command>p4 add</command> command like so:</para> - <screen>&prompt.user; <userinput>p4 add <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 add filename</userinput></screen> <para>If you want to add a whole tree of files, run a command like:</para> @@ -723,7 +709,7 @@ <para>Removing a file is just as easy with the <command>p4</command> delete command like so:</para> - <screen>&prompt.user; <userinput>p4 delete <replaceable>filename</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>p4 delete filename</userinput></screen> <para>This will mark the file for deletion from the depot the next time that a submit is run. It will also remove the local copy of @@ -739,7 +725,7 @@ admin access.</para> </sect1> -<sect1 id="working-with-diffs"> +<sect1 xml:id="working-with-diffs"> <title>Working with diffs</title> <para>Sometimes you might need to apply a diff from another source @@ -775,7 +761,7 @@ <para>and just do a <command>p4 submit</command> after that.</para> </sect1> -<sect1 id="renaming-files"> +<sect1 xml:id="renaming-files"> <title>Renaming files</title> <para><application>Perforce</application> does not have a built-in @@ -788,9 +774,9 @@ dealing with this is to do a one-time, in-tree integration, like so:</para> - <screen>&prompt.user; <userinput>p4 integrate -i <replaceable>oldfile</replaceable> <replaceable>newfile</replaceable></userinput> + <screen>&prompt.user; <userinput>p4 integrate -i oldfile newfile</userinput> &prompt.user; <userinput>p4 resolve</userinput> -&prompt.user; <userinput>p4 delete <replaceable>oldfile</replaceable></userinput> +&prompt.user; <userinput>p4 delete oldfile</userinput> &prompt.user; <userinput>p4 submit</userinput></screen> <para>The integration will force <application>Perforce</application> @@ -803,7 +789,7 @@ for normal branch-based integrations.</para> </sect1> -<sect1 id="freebsd-cvs-and-p4"> +<sect1 xml:id="freebsd-cvs-and-p4"> <title>Interactions between &os; Subversion and Perforce</title> <para>The &os; <application>Perforce</application> and <application>Subversion</application> @@ -811,8 +797,7 @@ tracked at near-real-time in <application>Perforce</application>. Every 2 minutes, the Subversion server is polled for updates in the HEAD branch, and those updates are committed to - <application>Perforce</application> in the <filename - class="directory">//depot/vendor/freebsd/...</filename> tree. This + <application>Perforce</application> in the <filename>//depot/vendor/freebsd/...</filename> tree. This tree is then available for branching and integrating to derivative projects. Any project that directly modifies that &os; source code should have this tree as its branch parent (or grandparent, @@ -831,7 +816,7 @@ something that you are interested in.</para> </sect1> -<sect1 id="offline-ops"> +<sect1 xml:id="offline-ops"> <title>Offline Operation</title> <para>One weakness of <application>Perforce</application> is that it @@ -853,7 +838,7 @@ so be extra vigilant with this.</para> </sect1> -<sect1 id="soc"> +<sect1 xml:id="soc"> <title>Notes for Google Summer of Code</title> <para>Most &os; projects under the Google Summer of Code program @@ -862,20 +847,16 @@ <itemizedlist> <listitem> - <para><filename - class="directory">//depot/projects/soc2005/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2005/project-name/...</filename></para> </listitem> <listitem> - <para><filename - class="directory">//depot/projects/soc2006/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2006/project-name/...</filename></para> </listitem> <listitem> - <para><filename - class="directory">//depot/projects/soc2007/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2007/project-name/...</filename></para> </listitem> <listitem> - <para><filename - class="directory">//depot/projects/soc2008/<replaceable>project-name</replaceable>/...</filename></para> + <para><filename>//depot/projects/soc2008/project-name/...</filename></para> </listitem> </itemizedlist> diff --git a/en_US.ISO8859-1/articles/pam/article.xml b/en_US.ISO8859-1/articles/pam/article.xml index 6680a890e7..4755b6bec4 100644 --- a/en_US.ISO8859-1/articles/pam/article.xml +++ b/en_US.ISO8859-1/articles/pam/article.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- - Copyright (c) 2001-2003 Networks Associates Technology, Inc. - All rights reserved. @@ -35,10 +34,9 @@ - OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF - SUCH DAMAGE. --> - -<article xmlns:xi="http://www.w3.org/2001/XInclude" lang='en'> - <articleinfo> - <title>Pluggable Authentication Modules</title> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Pluggable Authentication Modules</title> + <abstract> <para>This article describes the underlying principles and @@ -55,14 +53,10 @@ </copyright> <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <legalnotice id="pam-legalnotice"> + <legalnotice xml:id="pam-legalnotice"> <para>This article was written for the FreeBSD Project by ThinkSec AS and Network Associates Laboratories, the Security Research Division of Network Associates, Inc. under @@ -70,7 +64,7 @@ as part of the DARPA CHATS research program.</para> </legalnotice> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.opengroup; @@ -79,10 +73,10 @@ </legalnotice> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> - <section id="pam-intro"> - <title id="pam-intro.title">Introduction</title> + <section xml:id="pam-intro"> + <title xml:id="pam-intro.title">Introduction</title> <para>The Pluggable Authentication Modules (PAM) library is a generalized API for authentication-related services which allows @@ -104,11 +98,11 @@ Linux and &solaris;.</para> </section> - <section id="pam-terms"> - <title id="pam-terms.title">Terms and conventions</title> + <section xml:id="pam-terms"> + <title xml:id="pam-terms.title">Terms and conventions</title> - <section id="pam-definitions"> - <title id="pam-definitions.title">Definitions</title> + <section xml:id="pam-definitions"> + <title xml:id="pam-definitions.title">Definitions</title> <para>The terminology surrounding PAM is rather confused. Neither Samar and Lai's original paper nor the XSSO @@ -253,8 +247,8 @@ </glosslist> </section> - <section id="pam-usage-examples"> - <title id="pam-usage-examples.title">Usage examples</title> + <section xml:id="pam-usage-examples"> + <title xml:id="pam-usage-examples.title">Usage examples</title> <para>This section aims to illustrate the meanings of some of the terms defined above by way of a handful of simple @@ -392,11 +386,11 @@ sshd password required pam_permit.so</programlisting> --> </section> - <section id="pam-essentials"> - <title id="pam-essentials.title">PAM Essentials</title> + <section xml:id="pam-essentials"> + <title xml:id="pam-essentials.title">PAM Essentials</title> - <section id="pam-facilities-primitives"> - <title id="pam-facilities-primitives.title">Facilities and + <section xml:id="pam-facilities-primitives"> + <title xml:id="pam-facilities-primitives.title">Facilities and primitives</title> <para>The PAM API offers six different authentication primitives @@ -498,8 +492,8 @@ sshd password required pam_permit.so</programlisting> </section> - <section id="pam-modules"> - <title id="pam-modules.title">Modules</title> + <section xml:id="pam-modules"> + <title xml:id="pam-modules.title">Modules</title> <para>Modules are a very central concept in PAM; after all, they are the <quote>M</quote> in <quote>PAM</quote>. A PAM @@ -509,12 +503,12 @@ sshd password required pam_permit.so</programlisting> authentication facility, for instance, include the &unix; password database, NIS, LDAP and Radius.</para> - <section id="pam-module-naming"> - <title id="pam-module-naming.title">Module Naming</title> + <section xml:id="pam-module-naming"> + <title xml:id="pam-module-naming.title">Module Naming</title> <para>FreeBSD implements each mechanism in a single module, named - <literal>pam_<replaceable>mechanism</replaceable>.so</literal> + <literal>pam_mechanism.so</literal> (for instance, <literal>pam_unix.so</literal> for the &unix; mechanism.) Other implementations sometimes have separate modules for separate facilities, and include the facility @@ -524,8 +518,8 @@ sshd password required pam_permit.so</programlisting> commonly used to authenticate dialup users.</para> </section> - <section id="pam-module-versioning"> - <title id="pam-module-versioning.title">Module Versioning</title> + <section xml:id="pam-module-versioning"> + <title xml:id="pam-module-versioning.title">Module Versioning</title> <para>FreeBSD's original PAM implementation, based on Linux-PAM, did not use version numbers for PAM modules. @@ -549,8 +543,8 @@ sshd password required pam_permit.so</programlisting> </section> </section> - <section id="pam-chains-policies"> - <title id="pam-chains-policies.title">Chains and + <section xml:id="pam-chains-policies"> + <title xml:id="pam-chains-policies.title">Chains and policies</title> <para>When a server initiates a PAM transaction, the PAM library @@ -657,8 +651,8 @@ sshd password required pam_permit.so</programlisting> in the same chain as different, unrelated modules.</para> </section> - <section id="pam-transactions"> - <title id="pam-transactions.title">Transactions</title> + <section xml:id="pam-transactions"> + <title xml:id="pam-transactions.title">Transactions</title> <para>The lifecycle of a typical PAM transaction is described below. Note that if any of these steps fails, the server @@ -743,14 +737,14 @@ sshd password required pam_permit.so</programlisting> </section> </section> - <section id="pam-config"> - <title id="pam-config.title">PAM Configuration</title> + <section xml:id="pam-config"> + <title xml:id="pam-config.title">PAM Configuration</title> - <section id="pam-config-file"> - <title id="pam-config-file.title">PAM policy files</title> + <section xml:id="pam-config-file"> + <title xml:id="pam-config-file.title">PAM policy files</title> - <section id="pam-config-pam.conf"> - <title id="pam-config-pam.conf.title">The + <section xml:id="pam-config-pam.conf"> + <title xml:id="pam-config-pam.conf.title">The <filename>/etc/pam.conf</filename> file</title> <para>The traditional PAM policy file is @@ -776,8 +770,8 @@ sshd password required pam_permit.so</programlisting> Either way is fine; either way makes equal sense.</para> </section> - <section id="pam-config-pam.d"> - <title id="pam-config-pam.d.title">The + <section xml:id="pam-config-pam.d"> + <title xml:id="pam-config-pam.d.title">The <filename>/etc/pam.d</filename> directory</title> <para>OpenPAM and Linux-PAM support an alternate configuration @@ -816,8 +810,8 @@ sshd password required pam_permit.so</programlisting> software packages.</para> </section> - <section id="pam-config-file-order"> - <title id="pam-config-file-order.title">The policy search + <section xml:id="pam-config-file-order"> + <title xml:id="pam-config-file-order.title">The policy search order</title> <para>As we have seen above, PAM policies can be found in a @@ -830,8 +824,8 @@ sshd password required pam_permit.so</programlisting> </section> </section> - <section id="pam-config-breakdown"> - <title id="pam-config-breakdown.title">Breakdown of a + <section xml:id="pam-config-breakdown"> + <title xml:id="pam-config-breakdown.title">Breakdown of a configuration line</title> <para>As explained in <xref linkend="pam-config-file"/>, each line in @@ -864,8 +858,8 @@ sshd password required pam_permit.so</programlisting> Unsurprisingly, OpenPAM does not support this syntax.</para> </section> - <section id="pam-policies"> - <title id="pam-policies.title">Policies</title> + <section xml:id="pam-policies"> + <title xml:id="pam-policies.title">Policies</title> <para>To configure PAM correctly, it is essential to understand how policies are interpreted.</para> @@ -896,7 +890,7 @@ sshd password required pam_permit.so</programlisting> <colspec colwidth="1*" colname="other"/> <thead> <row> - <entry colname="type"></entry> + <entry colname="type"/> <entry colname="success"><literal>PAM_SUCCESS</literal></entry> <entry colname="ignore"><literal>PAM_IGNORE</literal></entry> <entry colname="other"><literal>other</literal></entry> @@ -965,11 +959,11 @@ sshd password required pam_permit.so</programlisting> </section> </section> - <section id="pam-freebsd-modules"> - <title id="pam-freebsd-modules.title">FreeBSD PAM Modules</title> + <section xml:id="pam-freebsd-modules"> + <title xml:id="pam-freebsd-modules.title">FreeBSD PAM Modules</title> - <section id="pam-modules-deny"> - <title id="pam-modules-deny.title">&man.pam.deny.8;</title> + <section xml:id="pam-modules-deny"> + <title xml:id="pam-modules-deny.title">&man.pam.deny.8;</title> <para>The &man.pam.deny.8; module is one of the simplest modules available; it responds to any request with @@ -979,8 +973,8 @@ sshd password required pam_permit.so</programlisting> modules.</para> </section> - <section id="pam-modules-echo"> - <title id="pam-modules-echo.title">&man.pam.echo.8;</title> + <section xml:id="pam-modules-echo"> + <title xml:id="pam-modules-echo.title">&man.pam.echo.8;</title> <para>The &man.pam.echo.8; module simply passes its arguments to the conversation function as a @@ -990,8 +984,8 @@ sshd password required pam_permit.so</programlisting> starting the authentication procedure.</para> </section> - <section id="pam-modules-exec"> - <title id="pam-modules-exec.title">&man.pam.exec.8;</title> + <section xml:id="pam-modules-exec"> + <title xml:id="pam-modules-exec.title">&man.pam.exec.8;</title> <para>The &man.pam.exec.8; module takes its first argument to be the name of a program to execute, and the remaining arguments @@ -1000,14 +994,14 @@ sshd password required pam_permit.so</programlisting> time which mounts the user's home directory.</para> </section> - <section id="pam-modules-ftpusers"> - <title id="pam-modules-ftpusers.title">&man.pam.ftpusers.8;</title> + <section xml:id="pam-modules-ftpusers"> + <title xml:id="pam-modules-ftpusers.title">&man.pam.ftpusers.8;</title> <para>The &man.pam.ftpusers.8; module</para> </section> - <section id="pam-modules-group"> - <title id="pam-modules-group.title">&man.pam.group.8;</title> + <section xml:id="pam-modules-group"> + <title xml:id="pam-modules-group.title">&man.pam.group.8;</title> <para>The &man.pam.group.8; module accepts or rejects applicants on the basis of their membership in a particular file group @@ -1017,8 +1011,8 @@ sshd password required pam_permit.so</programlisting> certain groups of users from a particular service.</para> </section> - <section id="pam-modules-guest"> - <title id="pam-modules-guest.title">&man.pam.guest.8;</title> + <section xml:id="pam-modules-guest"> + <title xml:id="pam-modules-guest.title">&man.pam.guest.8;</title> <para>The &man.pam.guest.8; module allows guest logins using fixed login names. Various requirements can be placed on the @@ -1028,26 +1022,26 @@ sshd password required pam_permit.so</programlisting> anonymous FTP logins.</para> </section> - <section id="pam-modules-krb5"> - <title id="pam-modules-krb5.title">&man.pam.krb5.8;</title> + <section xml:id="pam-modules-krb5"> + <title xml:id="pam-modules-krb5.title">&man.pam.krb5.8;</title> <para>The &man.pam.krb5.8; module</para> </section> - <section id="pam-modules-ksu"> - <title id="pam-modules-ksu.title">&man.pam.ksu.8;</title> + <section xml:id="pam-modules-ksu"> + <title xml:id="pam-modules-ksu.title">&man.pam.ksu.8;</title> <para>The &man.pam.ksu.8; module</para> </section> - <section id="pam-modules-lastlog"> - <title id="pam-modules-lastlog.title">&man.pam.lastlog.8;</title> + <section xml:id="pam-modules-lastlog"> + <title xml:id="pam-modules-lastlog.title">&man.pam.lastlog.8;</title> <para>The &man.pam.lastlog.8; module</para> </section> - <section id="pam-modules-login-access"> - <title id="pam-modules-login-access.title">&man.pam.login.access.8;</title> + <section xml:id="pam-modules-login-access"> + <title xml:id="pam-modules-login-access.title">&man.pam.login.access.8;</title> <para>The &man.pam.login.access.8; module provides an implementation of the account management primitive which @@ -1055,8 +1049,8 @@ sshd password required pam_permit.so</programlisting> &man.login.access.5; table.</para> </section> - <section id="pam-modules-nologin"> - <title id="pam-modules-nologin.title">&man.pam.nologin.8;</title> + <section xml:id="pam-modules-nologin"> + <title xml:id="pam-modules-nologin.title">&man.pam.nologin.8;</title> <para>The &man.pam.nologin.8; module refuses non-root logins when <filename>/var/run/nologin</filename> exists. This file @@ -1064,8 +1058,8 @@ sshd password required pam_permit.so</programlisting> minutes remain until the scheduled shutdown time.</para> </section> - <section id="pam-modules-opie"> - <title id="pam-modules-opie.title">&man.pam.opie.8;</title> + <section xml:id="pam-modules-opie"> + <title xml:id="pam-modules-opie.title">&man.pam.opie.8;</title> <para>The &man.pam.opie.8; module implements the &man.opie.4; authentication method. The &man.opie.4; system is a @@ -1078,8 +1072,8 @@ sshd password required pam_permit.so</programlisting> answered, it is not vulnerable to replay attacks.</para> </section> - <section id="pam-modules-opieaccess"> - <title id="pam-modules-opieaccess.title">&man.pam.opieaccess.8;</title> + <section xml:id="pam-modules-opieaccess"> + <title xml:id="pam-modules-opieaccess.title">&man.pam.opieaccess.8;</title> <para>The &man.pam.opieaccess.8; module is a companion module to &man.pam.opie.8;. Its purpose is to enforce the restrictions @@ -1096,14 +1090,14 @@ sshd password required pam_permit.so</programlisting> <literal>auth</literal> chain.</para> </section> - <section id="pam-modules-passwdqc"> - <title id="pam-modules-passwdqc.title">&man.pam.passwdqc.8;</title> + <section xml:id="pam-modules-passwdqc"> + <title xml:id="pam-modules-passwdqc.title">&man.pam.passwdqc.8;</title> <para>The &man.pam.passwdqc.8; module</para> </section> - <section id="pam-modules-permit"> - <title id="pam-modules-permit.title">&man.pam.permit.8;</title> + <section xml:id="pam-modules-permit"> + <title xml:id="pam-modules-permit.title">&man.pam.permit.8;</title> <para>The &man.pam.permit.8; module is one of the simplest modules available; it responds to any request with @@ -1112,20 +1106,20 @@ sshd password required pam_permit.so</programlisting> empty.</para> </section> - <section id="pam-modules-radius"> - <title id="pam-modules-radius.title">&man.pam.radius.8;</title> + <section xml:id="pam-modules-radius"> + <title xml:id="pam-modules-radius.title">&man.pam.radius.8;</title> <para>The &man.pam.radius.8; module</para> </section> - <section id="pam-modules-rhosts"> - <title id="pam-modules-rhosts.title">&man.pam.rhosts.8;</title> + <section xml:id="pam-modules-rhosts"> + <title xml:id="pam-modules-rhosts.title">&man.pam.rhosts.8;</title> <para>The &man.pam.rhosts.8; module</para> </section> - <section id="pam-modules-rootok"> - <title id="pam-modules-rootok.title">&man.pam.rootok.8;</title> + <section xml:id="pam-modules-rootok"> + <title xml:id="pam-modules-rootok.title">&man.pam.rootok.8;</title> <para>The &man.pam.rootok.8; module reports success if and only if the real user id of the process calling it (which is @@ -1135,14 +1129,14 @@ sshd password required pam_permit.so</programlisting> access.</para> </section> - <section id="pam-modules-securetty"> - <title id="pam-modules-securetty.title">&man.pam.securetty.8;</title> + <section xml:id="pam-modules-securetty"> + <title xml:id="pam-modules-securetty.title">&man.pam.securetty.8;</title> <para>The &man.pam.securetty.8; module</para> </section> - <section id="pam-modules-self"> - <title id="pam-modules-self.title">&man.pam.self.8;</title> + <section xml:id="pam-modules-self"> + <title xml:id="pam-modules-self.title">&man.pam.self.8;</title> <para>The &man.pam.self.8; module reports success if and only if the names of the applicant matches that of the target account. @@ -1151,8 +1145,8 @@ sshd password required pam_permit.so</programlisting> verified.</para> </section> - <section id="pam-modules-ssh"> - <title id="pam-modules-ssh.title">&man.pam.ssh.8;</title> + <section xml:id="pam-modules-ssh"> + <title xml:id="pam-modules-ssh.title">&man.pam.ssh.8;</title> <para>The &man.pam.ssh.8; module provides both authentication and session services. The authentication service allows users @@ -1166,14 +1160,14 @@ sshd password required pam_permit.so</programlisting> console.</para> </section> - <section id="pam-modules-tacplus"> - <title id="pam-modules-tacplus.title">&man.pam.tacplus.8;</title> + <section xml:id="pam-modules-tacplus"> + <title xml:id="pam-modules-tacplus.title">&man.pam.tacplus.8;</title> <para>The &man.pam.tacplus.8; module</para> </section> - <section id="pam-modules-unix"> - <title id="pam-modules-unix.title">&man.pam.unix.8;</title> + <section xml:id="pam-modules-unix"> + <title xml:id="pam-modules-unix.title">&man.pam.unix.8;</title> <para>The &man.pam.unix.8; module implements traditional &unix; password authentication, using &man.getpwnam.3; to obtain the @@ -1187,8 +1181,8 @@ sshd password required pam_permit.so</programlisting> </section> </section> - <section id="pam-appl-prog"> - <title id="pam-appl-prog.title">PAM Application Programming</title> + <section xml:id="pam-appl-prog"> + <title xml:id="pam-appl-prog.title">PAM Application Programming</title> <para><!--XXX-->This section has not yet been written.</para> @@ -1207,33 +1201,31 @@ sshd password required pam_permit.so</programlisting> </section> - <section id="pam-module-prog"> - <title id="pam-module-prog.title">PAM Module Programming</title> + <section xml:id="pam-module-prog"> + <title xml:id="pam-module-prog.title">PAM Module Programming</title> <para><!--XXX-->This section has not yet been written.</para> </section> - <appendix id="pam-sample-appl"> - <title id="pam-sample-appl.title">Sample PAM Application</title> + <appendix xml:id="pam-sample-appl"> + <title xml:id="pam-sample-appl.title">Sample PAM Application</title> <para>The following is a minimal implementation of &man.su.1; using PAM. Note that it uses the OpenPAM-specific &man.openpam.ttyconv.3; conversation function, which is - prototyped in <filename - class="headerfile">security/openpam.h</filename>. If you wish + prototyped in <filename>security/openpam.h</filename>. If you wish build this application on a system with a different PAM library, you will have to provide your own conversation function. A robust conversation function is surprisingly difficult to - implement; the one presented in <xref - linkend="pam-sample-conv"/> is a good + implement; the one presented in <xref linkend="pam-sample-conv"/> is a good starting point, but should not be used in real-world applications.</para> -<programlisting><xi:include href="su.c" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="su.c" parse="text"/></programlisting> </appendix> - <appendix id="pam-sample-module"> - <title id="pam-sample-module.title">Sample PAM Module</title> + <appendix xml:id="pam-sample-module"> + <title xml:id="pam-sample-module.title">Sample PAM Module</title> <para>The following is a minimal implementation of &man.pam.unix.8;, offering only authentication services. It @@ -1242,11 +1234,11 @@ sshd password required pam_permit.so</programlisting> &man.pam.get.authtok.3;, which enormously simplifies prompting the user for a password.</para> -<programlisting><xi:include href="pam_unix.c" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="pam_unix.c" parse="text"/></programlisting> </appendix> - <appendix id="pam-sample-conv"> - <title id="pam-sample-conv.title">Sample PAM Conversation + <appendix xml:id="pam-sample-conv"> + <title xml:id="pam-sample-conv.title">Sample PAM Conversation Function</title> <para>The conversation function presented below is a greatly @@ -1258,57 +1250,46 @@ sshd password required pam_permit.so</programlisting> your uses; we believe it to be as robust as a tty-oriented conversation function can reasonably get.</para> -<programlisting><xi:include href="converse.c" parse="text"/></programlisting> +<programlisting><xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="converse.c" parse="text"/></programlisting> </appendix> - <bibliography id="pam-further"> - <title id="pam-further.title">Further Reading</title> + <bibliography xml:id="pam-further"> + <info><title xml:id="pam-further.title">Further Reading</title> + <abstract> <para>This is a list of documents relevant to PAM and related issues. It is by no means complete.</para> </abstract> + </info> <bibliodiv> <title>Papers</title> <biblioentry> - <title><ulink - url="http://www.sun.com/software/solaris/pam/pam.external.pdf"> + <citetitle><link xlink:href="http://www.sun.com/software/solaris/pam/pam.external.pdf"> Making Login Services Independent of Authentication - Technologies</ulink></title> + Technologies</link></citetitle> <authorgroup> - <author> - <surname>Samar</surname> - <firstname>Vipin</firstname> - </author> - <author> - <surname>Lai</surname> - <firstname>Charlie</firstname> - </author> + <author><personname><surname>Samar</surname><firstname>Vipin</firstname></personname></author> + <author><personname><surname>Lai</surname><firstname>Charlie</firstname></personname></author> </authorgroup> <orgname>Sun Microsystems</orgname> </biblioentry> <biblioentry> - <title><ulink - url="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open - Single Sign-on Preliminary Specification</ulink></title> + <citetitle><link xlink:href="http://www.opengroup.org/pubs/catalog/p702.htm">X/Open + Single Sign-on Preliminary Specification</link></citetitle> <orgname>The Open Group</orgname> - <isbn>1-85912-144-6</isbn> + <biblioid class="isbn">1-85912-144-6</biblioid> <pubdate>June 1997</pubdate> </biblioentry> <biblioentry> - <title><ulink - url="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt"> - Pluggable Authentication Modules</ulink></title> - <author> - <surname>Morgan</surname> - <firstname>Andrew</firstname> - <othername role="mi">G.</othername> - </author> - <pubdate>October 6, 1999</pubdate> + <citetitle><link xlink:href="http://www.kernel.org/pub/linux/libs/pam/pre/doc/current-draft.txt"> + Pluggable Authentication Modules</link></citetitle> + <author><personname><surname>Morgan</surname><firstname>Andrew</firstname><othername role="mi">G.</othername></personname></author> + <pubdate>1999-10-06</pubdate> </biblioentry> </bibliodiv> @@ -1316,9 +1297,8 @@ sshd password required pam_permit.so</programlisting> <title>User Manuals</title> <biblioentry> - <title><ulink - url="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM - Administration</ulink></title> + <citetitle><link xlink:href="http://www.sun.com/software/solaris/pam/pam.admin.pdf">PAM + Administration</link></citetitle> <orgname>Sun Microsystems</orgname> </biblioentry> </bibliodiv> @@ -1327,25 +1307,18 @@ sshd password required pam_permit.so</programlisting> <title>Related Web pages</title> <biblioentry> - <title><ulink url="http://openpam.sourceforge.net/">OpenPAM homepage</ulink></title> - <author> - <surname>Smørgrav</surname> - <firstname>Dag-Erling</firstname> - </author> + <citetitle><link xlink:href="http://openpam.sourceforge.net/">OpenPAM homepage</link></citetitle> + <author><personname><surname>Smørgrav</surname><firstname>Dag-Erling</firstname></personname></author> <orgname>ThinkSec AS</orgname> </biblioentry> <biblioentry> - <title><ulink url="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</ulink></title> - <author> - <surname>Morgan</surname> - <firstname>Andrew</firstname> - <othername role="mi">G.</othername> - </author> + <citetitle><link xlink:href="http://www.kernel.org/pub/linux/libs/pam/">Linux-PAM homepage</link></citetitle> + <author><personname><surname>Morgan</surname><firstname>Andrew</firstname><othername role="mi">G.</othername></personname></author> </biblioentry> <biblioentry> - <title><ulink url="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</ulink></title> + <citetitle><link xlink:href="http://wwws.sun.com/software/solaris/pam/">Solaris PAM homepage</link></citetitle> <orgname>Sun Microsystems</orgname> </biblioentry> </bibliodiv> diff --git a/en_US.ISO8859-1/articles/port-mentor-guidelines/article.xml b/en_US.ISO8859-1/articles/port-mentor-guidelines/article.xml index 5d98119f6a..06576422f7 100644 --- a/en_US.ISO8859-1/articles/port-mentor-guidelines/article.xml +++ b/en_US.ISO8859-1/articles/port-mentor-guidelines/article.xml @@ -1,13 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang="en"> - <articleinfo> - <title>Port Mentor Guidelines</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Port Mentor Guidelines</title> + <authorgroup> - <corpauthor>The &os; Ports Management Team</corpauthor> + <author><orgname>The &os; Ports Management Team</orgname></author> </authorgroup> <pubdate>$FreeBSD$</pubdate> @@ -19,9 +18,9 @@ <holder role="mailto:tabthorpe@FreeBSD.org">Thomas Abthorpe</holder> <holder role="mailto:crees@FreeBSD.org">Chris Rees</holder> </copyright> - </articleinfo> + </info> - <sect1 id="port-mentor.guidelines"> + <sect1 xml:id="port-mentor.guidelines"> <title>Guideline for Mentor/Mentee relationships</title> <para>This section is intended to help demystify the @@ -33,7 +32,7 @@ working toward a common goal, maintaining the quality assurance of the product we call the Ports Tree.</para> - <sect2 id="why.mentor"> + <sect2 xml:id="why.mentor"> <title>Why mentor?</title> <itemizedlist> @@ -55,7 +54,7 @@ </itemizedlist> </sect2> - <sect2 id="mentor.comentor"> + <sect2 xml:id="mentor.comentor"> <title>Mentor/Co-Mentor</title> <para>Reasons for a co-mentorship:</para> @@ -109,7 +108,7 @@ </itemizedlist> </sect2> - <sect2 id="mentor.expectations"> + <sect2 xml:id="mentor.expectations"> <title>Expectations</title> <para>We expect mentors to review and test-build all proposed @@ -122,17 +121,16 @@ and implicit.</para> <para>We expect mentors to make sure their mentees read the - <ulink url="&url.books.porters-handbook;">Porter's - Handbook</ulink>, the <ulink - url="&url.articles.pr-guidelines;">PR handling guide</ulink>, and - the <ulink url="&url.articles.committers-guide;">Committer's - Guide</ulink>. While it's not necessary to memorize all the + <link xlink:href="&url.books.porters-handbook;">Porter's + Handbook</link>, the <link xlink:href="&url.articles.pr-guidelines;">PR handling guide</link>, and + the <link xlink:href="&url.articles.committers-guide;">Committer's + Guide</link>. While it's not necessary to memorize all the details, every committer needs to have an overview of these things to be an effective part of the community (and avoid as many rookie mistakes as possible).</para> </sect2> - <sect2 id="mentees"> + <sect2 xml:id="mentees"> <title>Selecting a mentee</title> <para>There is no defined rule for what makes a candidate ready; it @@ -171,15 +169,15 @@ and hope that portmgr agrees.</para> </sect2> - <sect2 id="mentorship.duration"> + <sect2 xml:id="mentorship.duration"> <title>Mentorship duration</title> <para>As the trust level develops and grows, the mentee may be granted <quote>implicit</quote> commit rights. This can include trivial changes to a <filename>Makefile</filename>, <filename>pkg-descr</filename> etc. Similarly, it may include - <makevar>PORTVERSION</makevar> updates that do not include - <makevar>plist</makevar> changes. Other circumstances may be + <varname>PORTVERSION</varname> updates that do not include + <varname>plist</varname> changes. Other circumstances may be formulated at the discretion of the Mentor. However, during the period of mentorship, a port version bump that affects dependent ports should be checked by a mentor.</para> @@ -195,7 +193,7 @@ mistakes, they still require mentor guidance.</para> </sect2> - <sect2 id="mentor.comentor.debate"> + <sect2 xml:id="mentor.comentor.debate"> <title>Mentor/Co-Mentor debate</title> <para>When a request gets to portmgr, it usually reads as, @@ -206,14 +204,14 @@ <quote>first among equals</quote>, the co-mentor is the backup.</para> <para>Some reprobate, whose name shall be withheld, made the - <ulink url="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html"> - first recorded co-mentor commit</ulink>. Similar co-mentor commits + <link xlink:href="http://lists.freebsd.org/pipermail/cvs-ports/2007-September/134614.html"> + first recorded co-mentor commit</link>. Similar co-mentor commits have also been spotted in the src tree. Does this make it right? Does this make it wrong? It seems to be part of the evolution of how things are done.</para> </sect2> - <sect2 id="mentee.expectations"> + <sect2 xml:id="mentee.expectations"> <title>Expectations</title> <para>We expect mentees to be prepared for constructive criticism diff --git a/en_US.ISO8859-1/articles/portbuild/article.xml b/en_US.ISO8859-1/articles/portbuild/article.xml index d882a2ed29..692d23c1e0 100644 --- a/en_US.ISO8859-1/articles/portbuild/article.xml +++ b/en_US.ISO8859-1/articles/portbuild/article.xml @@ -1,13 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Package Building Procedures</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Package Building Procedures</title> + <authorgroup> - <corpauthor>The &os; Ports Management Team</corpauthor> + <author><orgname>The &os; Ports Management Team</orgname></author> </authorgroup> <copyright> @@ -26,7 +25,7 @@ Management Team</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.sparc; @@ -36,27 +35,27 @@ <pubdate>$FreeBSD$</pubdate> <releaseinfo>$FreeBSD$</releaseinfo> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction</title> <para>In order to provide pre-compiled binaries of third-party applications for &os;, the Ports Collection is regularly built on one of the <quote>Package Building Clusters.</quote> Currently, the main cluster in use is at - <ulink url="http://pointyhat.FreeBSD.org"></ulink>.</para> + <uri xlink:href="http://pointyhat.FreeBSD.org">http://pointyhat.FreeBSD.org</uri>.</para> <para>This article documents the internal workings of the cluster.</para> <note> <para>Many of the details in this article will be of interest only to - those on the <ulink url="&url.base;/portmgr/">Ports Management</ulink> + those on the <link xlink:href="&url.base;/portmgr/">Ports Management</link> team.</para> </note> - <sect2 id="codebase"> + <sect2 xml:id="codebase"> <title>The codebase</title> <para>Most of the package building magic occurs under the @@ -67,9 +66,9 @@ (e.g., amd64, arm, &i386;, ia64, powerpc, &sparc64;), and <replaceable>${branch}</replaceable> will be used to specify the build branch (e.g., 7, 7-exp, 8, 8-exp, 9, 9-exp, 10, 10-exp). - The set of branches that <username>portmgr</username> currently + The set of branches that <systemitem class="username">portmgr</systemitem> currently supports is the same as those that the &os; - <ulink url="http://www.freebsd.org/security/index.html#sup">security team</ulink> + <link xlink:href="http://www.freebsd.org/security/index.html#sup">security team</link> supports. </para> @@ -79,12 +78,12 @@ </note> <para>The scripts that control all of this live in either - <filename class="directory">/a/portbuild/scripts/</filename> or. - <filename class="directory">/a/portbuild/admin/scripts/</filename>. + <filename>/a/portbuild/scripts/</filename> or. + <filename>/a/portbuild/admin/scripts/</filename>. These are the checked-out copies from the Subversion repository at - <ulink url="http://svnweb.freebsd.org/base/projects/portbuild/"> - <filename class="directory">base/projects/portbuild/</filename> - </ulink>.</para> + <link xlink:href="http://svnweb.freebsd.org/base/projects/portbuild/"> + <filename>base/projects/portbuild/</filename> + </link>.</para> <para>Typically, incremental builds are done that use previous packages as dependencies; this takes less time, and puts less @@ -109,11 +108,11 @@ <para>Packages from experimental builds are not uploaded.</para> </sect2> - <sect2 id="codebase-notes"> + <sect2 xml:id="codebase-notes"> <title>Historical notes on the codebase</title> <para>Until mid-2010, the scripts were completely specific to - <hostid>pointyhat.FreeBSD.org</hostid> as the head (dispatch) node. During + <systemitem>pointyhat.FreeBSD.org</systemitem> as the head (dispatch) node. During the summer of 2010, a significant rewrite was done in order to allow for other hosts to be head nodes. Among the changes were:</para> @@ -148,15 +147,15 @@ <note> <para>Also during this process, the codebase was migrated to the - <ulink url="http://svnweb.freebsd.org/base/projects/portbuild/scripts/"> - Subversion repository</ulink>. For reference, the previous version + <link xlink:href="http://svnweb.freebsd.org/base/projects/portbuild/scripts/"> + Subversion repository</link>. For reference, the previous version may still be - <ulink url="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Tools/portbuild/scripts/Attic/"> - found in CVS</ulink>.</para> + <link xlink:href="http://www.freebsd.org/cgi/cvsweb.cgi/ports/Tools/portbuild/scripts/Attic/"> + found in CVS</link>.</para> </note> </sect2> - <sect2 id="pointyhat-privsep"> + <sect2 xml:id="pointyhat-privsep"> <title>Notes on privilege separation</title> <para>As of January 2013, a rewrite is in progress to further separate @@ -164,14 +163,14 @@ <itemizedlist> <listitem> - <para>Server-side user <username>portbuild</username> assumes all + <para>Server-side user <systemitem class="username">portbuild</systemitem> assumes all responsiblity for operations involving builds and communicating with the clients. This user no longer has access to <application>sudo</application>.</para> </listitem> <listitem> - <para>Server-side user <username>srcbuild</username> is created + <para>Server-side user <systemitem class="username">srcbuild</systemitem> is created and given responsiblity for operations involving both VCS operations and anything involving src builds for the clients. This user does not have access to @@ -194,7 +193,7 @@ <listitem> <para>The only client-side user is also named - <username>portbuild</username> and still has access to + <systemitem class="username">portbuild</systemitem> and still has access to <application>sudo</application> for the purpose of managing jails.</para> </listitem> @@ -202,7 +201,7 @@ </sect2> </sect1> - <sect1 id="management"> + <sect1 xml:id="management"> <title>Build Client Management</title> <para>You may set up clients to either netboot from the master @@ -220,10 +219,10 @@ nullfs-mounted for jail builds.</para> <para>The - <username>portbuild</username> + <systemitem class="username">portbuild</systemitem> user can &man.ssh.1; to the client nodes to monitor them. Use <command>sudo</command> and check the - <hostid>portbuild.<replaceable>hostname</replaceable>.conf</hostid> + <systemitem>portbuild.<replaceable>hostname</replaceable>.conf</systemitem> for the user and access details.</para> <para>The <command>scripts/allgohans</command> script can @@ -231,35 +230,35 @@ <replaceable>${arch}</replaceable> clients.</para> </sect1> - <sect1 id="setup"> + <sect1 xml:id="setup"> <title>Jail Build Environment Setup</title> <para>Package builds are performed by the clients in a <literal>jail</literal> populated by the <filename>portbuild</filename> script using the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/bindist.tar</filename> + <filename>${arch}/${branch}/builds/${buildid}/bindist.tar</filename> file.</para> <para>On the server, use the <command>makeworld</command> command to build a world from the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src/</filename> + <filename>${arch}/${branch}/builds/${buildid}/src/</filename> tree and install it into - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/bindist.tar</filename>. + <filename>${arch}/${branch}/builds/${buildid}/bindist.tar</filename>. The tree will be updated first unless <literal>-novcs</literal> is specified.</para> - <screen>&prompt.root; <userinput>/a/portbuild/admin/scripts/makeworld <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-novcs]</userinput></screen> + <screen>&prompt.root; <userinput>/a/portbuild/admin/scripts/makeworld ${arch} ${branch} ${buildid} [-novcs]</userinput></screen> <para>Similiarly on the server, the <filename>bindist.tar</filename> tarball is created from the previously installed world by the <command>mkbindist</command> script.</para> - <screen>&prompt.root; <userinput>/a/portbuild/admin/scripts/mkbindist <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>/a/portbuild/admin/scripts/mkbindist ${arch} ${branch} ${buildid}</userinput></screen> <para>The per-machine tarballs are located on the server in - <filename><replaceable>${arch}</replaceable>/clients</filename>.</para> + <filename>${arch}/clients</filename>.</para> <para>The <filename>bindist.tar</filename> file is extracted onto each client at client boot time, and at the start of @@ -272,53 +271,53 @@ <note> <para>Currently the above two scripts must be run as - <username>root</username>; otherwise, the install scripts + <systemitem class="username">root</systemitem>; otherwise, the install scripts lack sufficient permissions. This is undesirable for security reasons. Work is in progress in -HEAD to allow users to do installations; once that is committed, the intention is to use that and run these two commands as - <username>srcbuild</username>.</para> + <systemitem class="username">srcbuild</systemitem>.</para> </note> </sect1> - <sect1 id="customizing"> + <sect1 xml:id="customizing"> <title>Customizing Your Build</title> <para>You can customize your build by providing local versions of <filename>make.conf</filename> and/or <filename>src.conf</filename>, named - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.server</filename> + <filename>${arch}/${branch}/builds/${buildid}/make.conf.server</filename> and - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src.conf.server</filename>, + <filename>${arch}/${branch}/builds/${buildid}/src.conf.server</filename>, respectively. These will be used in lieu of the default-named files on the server side.</para> <para>Similarly, if you wish to also affect the <emphasis>client-side</emphasis> <filename>make.conf</filename>, you may use - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.client</filename>. + <filename>${arch}/${branch}/builds/${buildid}/make.conf.client</filename>. </para> <note> <para>Due to the fact that individual clients may each have their own per-host <filename>make.conf</filename>, the contents of - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.client</filename> + <filename>${arch}/${branch}/builds/${buildid}/make.conf.client</filename> will be <emphasis>appended</emphasis> to that <filename>make.conf</filename>, not supplant it, as is done for - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/make.conf.server</filename>.</para> + <filename>${arch}/${branch}/builds/${buildid}/make.conf.server</filename>.</para> </note> <note> <para>There is no similar functionality for - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/src.conf.client</filename> + <filename>${arch}/${branch}/builds/${buildid}/src.conf.client</filename> (what effect would it have?).</para> </note> <example> <title>Sample - <filename>make.conf.<replaceable>target</replaceable></filename> + <filename>make.conf.target</filename> to test new default <application>ruby</application> version</title> @@ -330,7 +329,7 @@ <example> <title>Sample - <filename>make.conf.<replaceable>target</replaceable></filename> + <filename>make.conf.target</filename> for <application>clang</application> builds</title> <para>(For this case, the contents are also identical for both @@ -373,13 +372,13 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> </example> </sect1> - <sect1 id="starting"> + <sect1 xml:id="starting"> <title>Starting the Build</title> <para>Separate builds for various combinations of architecture and branch are supported. All data private to a build (ports tree, src tree, packages, distfiles, log files, bindist, Makefile, etc) are located under the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/builds/<replaceable>${buildid}</replaceable>/</filename> + <filename>${arch}/${branch}/builds/${buildid}/</filename> directory. The most recently created build can be alternatively referenced using buildid <literal>latest</literal>, and the one before using @@ -388,13 +387,13 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <para>New builds are cloned from the <literal>latest</literal>, which is fast since it uses ZFS.</para> - <sect2 id="build-dopackages"> + <sect2 xml:id="build-dopackages"> <title><command>dopackages</command> scripts</title> <para>The <filename>scripts/dopackages.wrapper</filename> script is used to perform the builds.</para> - <screen>&prompt.root; <userinput>dopackages.wrapper <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> <option>[-options]</option></userinput></screen> + <screen>&prompt.root; <userinput>dopackages.wrapper ${arch} ${branch} ${buildid} [-options]</userinput></screen> <para>Most often, you will be using <literal>latest</literal> for the value of <replaceable>buildid</replaceable>.</para> @@ -456,7 +455,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <listitem> <para><option>-cdrom</option> - This package build is intended to end up on a CD-ROM, so - <makevar>NO_CDROM</makevar> packages and distfiles + <varname>NO_CDROM</varname> packages and distfiles should be deleted in post-processing.</para> </listitem> @@ -475,25 +474,25 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <para><option>-noduds</option> - Do not rebuild the <filename>duds</filename> file (ports that are never built, e.g., those marked <literal>IGNORE</literal>, - <makevar>NO_PACKAGE</makevar>, etc.) during + <varname>NO_PACKAGE</varname>, etc.) during preprocessing.</para> </listitem> <listitem> <para><option>-nochecksubdirs</option> - Do not check the - <makevar>SUBDIRS</makevar> for ports that are not connected + <varname>SUBDIRS</varname> for ports that are not connected to the build.</para> </listitem> <listitem> <para><option>-trybroken</option> - Try to build - <makevar>BROKEN</makevar> ports (off by default + <varname>BROKEN</varname> ports (off by default because the amd64/&i386; clusters are fast enough now that when doing incremental builds, more time was spent rebuilding things that were going to fail anyway. Conversely, the other clusters are slow enough that it would be a waste of time - to try and build <makevar>BROKEN</makevar> ports).</para> + to try and build <varname>BROKEN</varname> ports).</para> <note> <para>With <option>-trybroken</option>, you probably @@ -529,7 +528,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <listitem> <para><option>-norestr</option> - Do not attempt to build - <makevar>RESTRICTED</makevar> ports.</para> + <varname>RESTRICTED</varname> ports.</para> </listitem> <listitem> @@ -540,13 +539,13 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <listitem> <para><option>-nodistfiles</option> - Do not collect distfiles that pass <command>make checksum</command> for later - uploading to <hostid>ftp-master</hostid>.</para> + uploading to <systemitem>ftp-master</systemitem>.</para> </listitem> <listitem> <para><option>-fetch-original</option> - Fetch the - distfile from the original <makevar>MASTER_SITES</makevar> - rather than any cache such as on <hostid>ftp-master</hostid>.</para> + distfile from the original <varname>MASTER_SITES</varname> + rather than any cache such as on <systemitem>ftp-master</systemitem>.</para> </listitem> <listitem> @@ -571,7 +570,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> anything. If it was interrupted, or you selected <option>-nocleanup</option>, you need to clean up clients by running</para> - <screen>&prompt.user; <userinput>build cleanup <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> -full</userinput></screen> + <screen>&prompt.user; <userinput>build cleanup ${arch} ${branch} ${buildid} -full</userinput></screen> <para>When a new build is created, the directories <filename>errors/</filename>, <filename>logs/</filename>, <filename>packages/</filename>, and so @@ -591,7 +590,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> </note> <para>Make sure the <replaceable>${arch}</replaceable> build - is run as the <username>portbuild</username> user + is run as the <systemitem class="username">portbuild</systemitem> user or it will complain loudly.</para> <note> @@ -609,19 +608,19 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> process encounters an empty subdirectory, both package build phases will stop short, and an error similar to the following will be written to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/journal</filename>:</para> + <filename>${arch}/${branch}/journal</filename>:</para> <screen>don't know how to make dns-all(continuing)</screen> <para>To correct this problem, simply comment out or remove - the <makevar>SUBDIR</makevar> entries that point to empty + the <varname>SUBDIR</varname> entries that point to empty subdirectories. After doing this, you can restart the build by running the proper <command>dopackages</command> command with the <option>-restart</option> option.</para> <note> <para>This problem also appears if you create a new category - <filename>Makefile</filename> with no <makevar>SUBDIR</makevar>s + <filename>Makefile</filename> with no <varname>SUBDIR</varname>s in it. This is probably a bug.</para> </note> @@ -647,7 +646,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> command inside of <command>screen(1)</command>.</para> </sect2> - <sect2 id="build-command"> + <sect2 xml:id="build-command"> <title><command>build</command> command</title> <para>You may need to manipulate the build data before starting it, @@ -657,34 +656,34 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <itemizedlist> <listitem> - <para><literal>build create <replaceable>arch</replaceable> - <replaceable>branch</replaceable> - [<replaceable>newid</replaceable>]</literal> - Creates + <para><literal>build create arch + branch + [newid]</literal> - Creates <replaceable>newid</replaceable> (or a datestamp if not specified). Only needed when bringing up a new branch or a new architecture.</para> </listitem> <listitem> - <para><literal>build clone <replaceable>arch</replaceable> - <replaceable>branch</replaceable> <replaceable>oldid</replaceable> - [<replaceable>newid</replaceable>]</literal> - Clones + <para><literal>build clone arch + branch oldid + [newid]</literal> - Clones <replaceable>oldid</replaceable> to <replaceable>newid</replaceable> (or a datestamp if not specified).</para> </listitem> <listitem> - <para><literal>build srcupdate <replaceable>arch</replaceable> - <replaceable>branch</replaceable> - <replaceable>buildid</replaceable></literal> - Replaces the src + <para><literal>build srcupdate arch + branch + buildid</literal> - Replaces the src tree with a new ZFS snapshot. Do not forget to use <literal>-nosrc</literal> flag to <command>dopackages</command> later!</para> </listitem> <listitem> - <para><literal>build portsupdate <replaceable>arch</replaceable> - <replaceable>branch</replaceable> - <replaceable>buildid</replaceable></literal> - Replaces the ports + <para><literal>build portsupdate arch + branch + buildid</literal> - Replaces the ports tree with a new ZFS snapshot. Do not forget to use <literal>-noports</literal> flag to <command>dopackages</command> later!</para> @@ -692,18 +691,18 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> </itemizedlist> </sect2> - <sect2 id="build-one"> + <sect2 xml:id="build-one"> <title>Building a single package</title> <para>Sometimes there is a need to rebuild a single package from the package set. This can be accomplished with the following invocation:</para> - <screen>&prompt.root; <command><replaceable>path</replaceable>/qmanager/packagebuild <replaceable>amd64</replaceable> <replaceable>7-exp</replaceable> <replaceable>20080904212103</replaceable> <replaceable>aclock-0.2.3_2.tbz</replaceable></command></screen> + <screen>&prompt.root; <command>path/qmanager/packagebuild amd64 7-exp 20080904212103 aclock-0.2.3_2.tbz</command></screen> </sect2> </sect1> - <sect1 id="anatomy"> + <sect1 xml:id="anatomy"> <title>Anatomy of a Build</title> <para>A full build without any <literal>-no</literal> @@ -713,67 +712,67 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <orderedlist> <listitem> <para>An update of the current <filename>ports</filename> - tree from the ZFS snapshot<footnote id="footnote-status1"> + tree from the ZFS snapshot<footnote xml:id="footnote-status1"> <para>Status of these steps can be found in - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</filename> + <filename>${arch}/${branch}/build.log</filename> as well as on stderr of the tty running the <command>dopackages</command> command.</para></footnote></para> </listitem> <listitem> <para>An update of the running branch's - <filename>src</filename> tree from the ZFS snapshot<footnoteref linkend='footnote-status1'></footnoteref></para> + <filename>src</filename> tree from the ZFS snapshot<footnoteref linkend="footnote-status1"/></para> </listitem> <listitem> <para>Checks which ports do not have a - <makevar>SUBDIR</makevar> entry in their respective - category's <filename>Makefile</filename><footnoteref linkend='footnote-status1'></footnoteref></para> + <varname>SUBDIR</varname> entry in their respective + category's <filename>Makefile</filename><footnoteref linkend="footnote-status1"/></para> </listitem> <listitem> <para>Creates the <filename>duds</filename> file, which - is a list of ports not to build<footnoteref linkend='footnote-status1'></footnoteref><footnote id="footnote-buildstop"> + is a list of ports not to build<footnoteref linkend="footnote-status1"/><footnote xml:id="footnote-buildstop"> <para>If any of these steps fail, the build will stop cold in its tracks.</para></footnote></para> </listitem> <listitem> <para>Generates a fresh <filename>INDEX</filename> - file<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para> + file<footnoteref linkend="footnote-status1"/><footnoteref linkend="footnote-buildstop"/></para> </listitem> <listitem> <para>Sets up the nodes that will be used in the - build<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para> + build<footnoteref linkend="footnote-status1"/><footnoteref linkend="footnote-buildstop"/></para> </listitem> <listitem> - <para>Builds a list of restricted ports<footnoteref linkend='footnote-status1'></footnoteref><footnoteref linkend='footnote-buildstop'></footnoteref></para> + <para>Builds a list of restricted ports<footnoteref linkend="footnote-status1"/><footnoteref linkend="footnote-buildstop"/></para> </listitem> <listitem> - <para>Builds packages (phase 1)<footnote id="footnote-status2"><para>Status of these steps can be found in - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/journal</filename>. + <para>Builds packages (phase 1)<footnote xml:id="footnote-status2"><para>Status of these steps can be found in + <filename>${arch}/${branch}/journal</filename>. Individual ports will write their build logs to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/logs/</filename> + <filename>${arch}/${branch}/logs/</filename> and their error logs to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/errors/</filename>. + <filename>${arch}/${branch}/errors/</filename>. </para></footnote></para> </listitem> <listitem> - <para>Performs another node setup<footnoteref linkend='footnote-status1'></footnoteref></para> + <para>Performs another node setup<footnoteref linkend="footnote-status1"/></para> </listitem> <listitem> - <para>Builds packages (phase 2)<footnoteref linkend='footnote-status2'></footnoteref></para> + <para>Builds packages (phase 2)<footnoteref linkend="footnote-status2"/></para> </listitem> </orderedlist> </sect1> - <sect1 id="build-maintenance"> + <sect1 xml:id="build-maintenance"> <title>Build Maintenance</title> <para>There are several cases where you will need to manually clean @@ -795,7 +794,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> </listitem> </orderedlist> - <sect2 id="interrupting"> + <sect2 xml:id="interrupting"> <title>Interrupting a Build</title> <para>Manually interrupting a build is a bit messy. First you need to @@ -822,7 +821,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> package.</para> </sect2> - <sect2 id="cleanup"> + <sect2 xml:id="cleanup"> <title>Cleaning up a Build</title> <para>To free up resources, you will need to clean up client machines by @@ -833,7 +832,7 @@ PKG_BIN=/usr/local/sbin/pkg</programlisting> <para>If you forget to do this, then the old build <literal>jail</literal>s will not be cleaned up for 24 hours, and no new jobs will be dispatched in their place since - <hostid>pointyhat</hostid> thinks the job slot is still occupied.</para> + <systemitem>pointyhat</systemitem> thinks the job slot is still occupied.</para> <para>To check, <userinput>cat ~/loads/*</userinput> to display the status of client machines; the first column is the number of jobs @@ -883,7 +882,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! </note> <para>After you have done all the above, remove the - <filename><replaceable>${arch}</replaceable>/lock</filename> + <filename>${arch}/lock</filename> file before trying to restart the build. If you do not, <filename>dopackages</filename> will simply exit.</para> @@ -892,7 +891,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <filename>INDEX</filename>, or both.</para> </sect2> - <sect2 id="build-command-2"> + <sect2 xml:id="build-command-2"> <title>Maintaining builds with the <command>build</command> command</title> @@ -901,31 +900,31 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <itemizedlist> <listitem> - <para><literal>build destroy <replaceable>arch</replaceable> - <replaceable>branch</replaceable></literal> - Destroy the + <para><literal>build destroy arch + branch</literal> - Destroy the build id.</para> </listitem> <listitem> - <para><literal>build list <replaceable>arch</replaceable> - <replaceable>branch</replaceable></literal> - Shows the current set + <para><literal>build list arch + branch</literal> - Shows the current set of build ids.</para> </listitem> </itemizedlist> </sect2> </sect1> - <sect1 id="monitoring"> + <sect1 xml:id="monitoring"> <title>Monitoring the Build</title> <para>You can use <command>qclient</command> command to monitor the status of build nodes, and to list the currently scheduled jobs:</para> - <screen>&prompt.user; <userinput>python <replaceable>path</replaceable>/qmanager/qclient jobs</userinput> -&prompt.user; <userinput>python <replaceable>path</replaceable>/qmanager/qclient status</userinput></screen> + <screen>&prompt.user; <userinput>python path/qmanager/qclient jobs</userinput> +&prompt.user; <userinput>python path/qmanager/qclient status</userinput></screen> <para>The - <userinput>scripts/stats <replaceable>${branch}</replaceable></userinput> + <userinput>scripts/stats ${branch}</userinput> command shows the number of packages already built.</para> <para>Running <userinput>cat /a/portbuild/*/loads/*</userinput> @@ -943,17 +942,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! idle node.</para> </note> - <para>Running <userinput>tail -f <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/build.log</userinput> + <para>Running <userinput>tail -f ${arch}/${branch}/build.log</userinput> shows the overall build progress.</para> <para>If a port build is failing, and it is not immediately obvious from the log as to why, you can preserve the - <makevar>WRKDIR</makevar> for further analysis. To do this, + <varname>WRKDIR</varname> for further analysis. To do this, touch a file called <filename>.keep</filename> in the port's directory. The next time the cluster tries to build this port, - it will tar, compress, and copy the <makevar>WRKDIR</makevar> + it will tar, compress, and copy the <varname>WRKDIR</varname> to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/wrkdirs/</filename>.</para> + <filename>${arch}/${branch}/wrkdirs/</filename>.</para> <para>If you find that the system is looping trying to build the same package over and over again, you may be able to fix the @@ -970,7 +969,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>The status of all current builds is generated periodically into the <filename>packagestats.html</filename> file, e.g., - <ulink url="http://pointyhat.FreeBSD.org/errorlogs/packagestats.html"></ulink>. + <uri xlink:href="http://pointyhat.FreeBSD.org/errorlogs/packagestats.html">http://pointyhat.FreeBSD.org/errorlogs/packagestats.html</uri>. For each <literal>buildenv</literal>, the following is displayed:</para> <itemizedlist> @@ -1021,18 +1020,18 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! </itemizedlist> </sect1> - <sect1 id="errors"> + <sect1 xml:id="errors"> <title>Dealing With Build Errors</title> <para>The easiest way to track build failures is to receive the emailed logs and sort them to a folder, so you can maintain a running list of current failures and detect new ones easily. To do this, add an email address to - <filename><replaceable>${branch}</replaceable>/portbuild.conf</filename>. + <filename>${branch}/portbuild.conf</filename>. You can easily bounce the new ones to maintainers.</para> <para>After a port appears broken on every build combination - multiple times, it is time to mark it <makevar>BROKEN</makevar>. + multiple times, it is time to mark it <varname>BROKEN</varname>. Two weeks' notification for the maintainers seems fair.</para> <note> @@ -1044,7 +1043,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! </note> </sect1> - <sect1 id="release"> + <sect1 xml:id="release"> <title>Release Builds</title> <para>When building packages for a release, it may be @@ -1067,23 +1066,23 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! build is post-processed, take an inventory of the list of files fetched:</para> - <screen>&prompt.user; <userinput>cd <replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable></userinput> -&prompt.user; <userinput>find distfiles > distfiles-<replaceable>${release}</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>cd ${arch}/${branch}</userinput> +&prompt.user; <userinput>find distfiles > distfiles-${release}</userinput></screen> <para>You should use that output to periodically clean out - the distfiles from <hostid>ftp-master</hostid>. When space + the distfiles from <systemitem>ftp-master</systemitem>. When space gets tight, distfiles from recent releases can be kept while others can be thrown away.</para> <para>Once the distfiles have been uploaded (see below), the final release package set must be created. Just to be on the safe side, run the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/cdrom.sh</filename> + <filename>${arch}/${branch}/cdrom.sh</filename> script by hand to make sure all the CD-ROM restricted packages and distfiles have been pruned. Then, copy the - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/packages</filename> + <filename>${arch}/${branch}/packages</filename> directory to - <filename><replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable>/packages-<replaceable>${release}</replaceable></filename>. + <filename>${arch}/${branch}/packages-${release}</filename>. Once the packages are safely moved off, contact the &a.re; and inform them of the release package location.</para> @@ -1091,27 +1090,27 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! and status of the release builds.</para> </sect1> - <sect1 id="uploading"> + <sect1 xml:id="uploading"> <title>Uploading Packages</title> <note> <para>For FreeBSD.org as of 2013, the instructions - about uploading to <hostid>ftp-master</hostid> are obsolete. - In the future, <hostid>ftp-master</hostid> will pull - from <hostid>pointyhat</hostid>, using a mechanism yet + about uploading to <systemitem>ftp-master</systemitem> are obsolete. + In the future, <systemitem>ftp-master</systemitem> will pull + from <systemitem>pointyhat</systemitem>, using a mechanism yet to be implemented. However, the instructions about - <makevar>RESTRICTED</makevar> and <makevar>NO_CDROM</makevar> + <varname>RESTRICTED</varname> and <varname>NO_CDROM</varname> must still be <emphasis>carefully</emphasis> followed.</para> </note> <para>Once a build has completed, packages and/or distfiles - can be transferred to <hostid>ftp-master</hostid> for + can be transferred to <systemitem>ftp-master</systemitem> for propagation to the FTP mirror network. If the build was run with <option>-nofinish</option>, then make sure to follow up with <command>dopackages -finish</command> to post-process the - packages (removes <makevar>RESTRICTED</makevar> and - <makevar>NO_CDROM</makevar> packages where appropriate, + packages (removes <varname>RESTRICTED</varname> and + <varname>NO_CDROM</varname> packages where appropriate, prunes packages not listed in <filename>INDEX</filename>, removes from <filename>INDEX</filename> references to packages not built, and generates a @@ -1119,7 +1118,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! summary); and distfiles (moves them from the temporary <filename>distfiles/.pbtmp</filename> directory into <filename>distfiles/</filename> and removes - <makevar>RESTRICTED</makevar> and <makevar>NO_CDROM</makevar> + <varname>RESTRICTED</varname> and <varname>NO_CDROM</varname> distfiles).</para> <para>It is usually a good idea to run the @@ -1127,7 +1126,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <command>cdrom.sh</command> scripts by hand after <command>dopackages</command> finishes just to be safe. Run the <command>restricted.sh</command> script before - uploading to <hostid>ftp-master</hostid>, then run + uploading to <systemitem>ftp-master</systemitem>, then run <command>cdrom.sh</command> before preparing the final package set for a release.</para> @@ -1159,7 +1158,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <note> <para>Some of the directories on - <hostid>ftp-master</hostid> are, in fact, symlinks. Examples:</para> + <systemitem>ftp-master</systemitem> are, in fact, symlinks. Examples:</para> <itemizedlist> <listitem> @@ -1179,15 +1178,15 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>If you are doing a completely new package set (e.g., for a new release), copy packages to the staging area on - <hostid>ftp-master</hostid> with something like the following:</para> + <systemitem>ftp-master</systemitem> with something like the following:</para> - <screen>&prompt.root; <userinput>cd /a/portbuild/<replaceable>${arch}</replaceable>/<replaceable>${branch}</replaceable></userinput> -&prompt.root; <userinput>tar cfv - packages/ | ssh portmgr@ftp-master tar xfC - w/ports/<replaceable>${arch}</replaceable>/tmp/<replaceable>${subdir}</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cd /a/portbuild/${arch}/${branch}</userinput> +&prompt.root; <userinput>tar cfv - packages/ | ssh portmgr@ftp-master tar xfC - w/ports/${arch}/tmp/${subdir}</userinput></screen> - <para>Then log into <hostid>ftp-master</hostid>, verify that + <para>Then log into <systemitem>ftp-master</systemitem>, verify that the package set was transferred successfully, remove the package set that the new package set is to replace (in - <filename>~/w/ports/<replaceable>${arch}</replaceable></filename>), + <filename>~/w/ports/${arch}</filename>), and move the new set into place. (<filename>w/</filename> is merely a shortcut.)</para> @@ -1204,17 +1203,17 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>Example <command>rsync</command> command for incremental package upload:</para> - <screen>&prompt.root; <userinput>rsync -n -r -v -l -t -p --delete packages/ portmgr@ftp-master:w/ports/<replaceable>${arch}</replaceable>/<replaceable>${subdir}</replaceable>/ | tee log</userinput></screen> + <screen>&prompt.root; <userinput>rsync -n -r -v -l -t -p --delete packages/ portmgr@ftp-master:w/ports/${arch}/${subdir}/ | tee log</userinput></screen> <para>Distfiles should be transferred with the <command>cpdistfiles</command> script:</para> - <screen>&prompt.root; <userinput>/a/portbuild/scripts/cpdistfiles <replaceable>${arch}</replaceable> <replaceable>${branch}</replaceable> <replaceable>${buildid}</replaceable> [-yesreally] | tee log2</userinput></screen> + <screen>&prompt.root; <userinput>/a/portbuild/scripts/cpdistfiles ${arch} ${branch} ${buildid} [-yesreally] | tee log2</userinput></screen> <para>Doing it by hand is deprecated.</para> </sect1> - <sect1 id="expbuilds"> + <sect1 xml:id="expbuilds"> <title>Experimental Patches Builds</title> <note> @@ -1239,8 +1238,8 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>The following example is obsolete</para> </note> - <screen>&prompt.user; <userinput>cvs -R update -dP > update.out</userinput> -&prompt.user; <userinput>date > .updated</userinput></screen> + <screen>&prompt.user; <userinput>cvs -R update -dP > update.out</userinput> +&prompt.user; <userinput>date > .updated</userinput></screen> <para>This will most closely simulate what the <literal>dopackages</literal> script does. (While <filename>.updated</filename> is merely @@ -1258,8 +1257,8 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>Since the machine is shared, someone else may delete your changes by mistake, so keep a copy of them in e.g., your home - directory on <hostid>freefall</hostid>. Do not use - <filename>tmp/</filename>; since <hostid>pointyhat</hostid> + directory on <systemitem>freefall</systemitem>. Do not use + <filename>tmp/</filename>; since <systemitem>pointyhat</systemitem> itself runs some version of <literal>-CURRENT</literal>, you can expect reboots (if nothing else, for updates).</para> @@ -1279,9 +1278,9 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! branch is the experimental patches branch):</para> <screen>&prompt.user; <userinput>cd /a/portbuild/i386/8-exp/errors</userinput> -&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/8-exp-errs</userinput> +&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/8-exp-errs</userinput> &prompt.user; <userinput>cd /a/portbuild/i386/8/errors</userinput> -&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/8-errs</userinput></screen> +&prompt.user; <userinput>find . -name \*.log\* | sort > /tmp/8-errs</userinput></screen> <note> <para>If it has been a long time since one of the builds @@ -1320,11 +1319,11 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! include:</para> <itemizedlist> - <listitem id="broken-by-exp-patches" xreflabel="broken by experimental patches"> + <listitem xml:id="broken-by-exp-patches" xreflabel="broken by experimental patches"> <para>Port was broken by the experimental patches</para> </listitem> - <listitem id="broken-by-upgrading" xreflabel="broken by upgrading"> + <listitem xml:id="broken-by-upgrading" xreflabel="broken by upgrading"> <para>Port was upgraded since the control build and has become broken</para> </listitem> @@ -1337,9 +1336,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>Both columns should be investigated and the reason for the errors understood before committing the experimental patches - set. To differentiate between <xref - linkend="broken-by-exp-patches"></xref> and <xref - linkend="broken-by-upgrading"></xref> above, you can do a + set. To differentiate between <xref linkend="broken-by-exp-patches"/> and <xref linkend="broken-by-upgrading"/> above, you can do a rebuild of the affected packages under the control branch:</para> @@ -1378,7 +1375,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>The list of packages to build should be a list of package names (including versions) as they appear in - <filename>INDEX</filename>. The <makevar>PKGSUFFIX</makevar> + <filename>INDEX</filename>. The <varname>PKGSUFFIX</varname> (i.e., <filename>.tgz</filename> or <filename>.tbz</filename>) is optional.</para> </note> @@ -1391,22 +1388,20 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! <para>Once all the errors have been resolved, you can commit the package set. After committing, it is customary to send a <literal>HEADS - UP</literal> email to <ulink - url="mailto:ports@FreeBSD.org">ports@FreeBSD.org</ulink> and - copy <ulink - url="mailto:ports-developers@FreeBSD.org">ports-developers@FreeBSD.org</ulink> + UP</literal> email to <link xlink:href="mailto:ports@FreeBSD.org">ports@FreeBSD.org</link> and + copy <link xlink:href="mailto:ports-developers@FreeBSD.org">ports-developers@FreeBSD.org</link> informing people of the changes. A summary of all changes should also be committed to <filename>/usr/ports/CHANGES</filename>.</para> </sect1> - <sect1 id="new-node"> + <sect1 xml:id="new-node"> <title>How to configure a new package building node</title> <para>Before following these steps, please coordinate with <literal>portmgr</literal>.</para> - <sect2 id="node-requirements"> + <sect2 xml:id="node-requirements"> <title>Node requirements</title> <note> @@ -1454,7 +1449,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! </itemizedlist> </sect2> - <sect2 id="node-preparation"> + <sect2 xml:id="node-preparation"> <title>Preparation</title> <procedure> @@ -1509,7 +1504,7 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! </procedure> </sect2> - <sect2 id="node-src"> + <sect2 xml:id="node-src"> <title>Configuring <filename>src</filename></title> <procedure> @@ -1528,13 +1523,13 @@ umount: Cleanup of /x/tmp/8-exp/chroot/53837/compat/linux/proc failed! directory to contain the install bits. You will probably want to use a subdirectory of <filename>/pxeroot</filename>, e.g., - <filename>/pxeroot/<replaceable>${arch}</replaceable>-<replaceable>${branch}</replaceable></filename>. - Export that as <makevar>DESTDIR</makevar>.</para> + <filename>/pxeroot/${arch}-${branch}</filename>. + Export that as <varname>DESTDIR</varname>.</para> </step> <step> <para>If you are cross-building, export - <makevar>TARGET_ARCH</makevar>=<replaceable>${arch}</replaceable>.</para> + <varname>TARGET_ARCH</varname>=<replaceable>${arch}</replaceable>.</para> <note> <para>The procedure for cross-building ports is not yet @@ -1589,11 +1584,11 @@ options NFSSERVER # Network Filesystem Server</programlist <para>As root, do the usual build steps, e.g.:</para> <screen>&prompt.root; <userinput>make -j4 buildworld</userinput> -&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput> -&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>${kernconf}</replaceable></userinput> +&prompt.root; <userinput>make buildkernel KERNCONF=${kernconf}</userinput> +&prompt.root; <userinput>make installkernel KERNCONF=${kernconf}</userinput> &prompt.root; <userinput>make installworld</userinput></screen> - <para>The install steps use <makevar>DESTDIR</makevar>.</para> + <para>The install steps use <varname>DESTDIR</varname>.</para> </step> <step> @@ -1604,15 +1599,15 @@ options NFSSERVER # Network Filesystem Server</programlist <para>If you are using <filename>pxeboot</filename>: create a subdirectory of - <filename><replaceable>${DESTDIR}</replaceable></filename> + <filename>${DESTDIR}</filename> called <filename>conf/</filename>. Create one subdirectory <filename>default/etc/</filename>, and (if your site will host multiple nodes), subdirectories - <filename><replaceable>${ip-address}</replaceable>/etc/</filename> + <filename>${ip-address}/etc/</filename> to contain override files for individual hosts. (You may find it handy to symlink each of those directories to a hostname.) Copy the entire contents of - <filename><replaceable>${DESTDIR}</replaceable>/etc/</filename> + <filename>${DESTDIR}/etc/</filename> to <filename>default/etc/</filename>; that is where you will edit your files. The by-ip-address <filename>etc/</filename> directories will probably only need @@ -1707,8 +1702,8 @@ sshd_program="/usr/local/sbin/sshd"</programlisting> cache on the client, add the following</para> <programlisting>squid_enable="YES" -squid_chdir="<filename>/<replaceable>a</replaceable>/squid/logs</filename>" -squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</filename>"</programlisting> +squid_chdir="<filename>/a/squid/logs</filename>" +squid_pidfile="<filename>/a/squid/logs/squid.pid</filename>"</programlisting> <para>Required entries for VMWare-based nodes:</para> <programlisting>vmware_guest_vmmemctl_enable="YES" @@ -1729,8 +1724,8 @@ sshd_program="/usr/local/sbin/sshd" gmond_enable="YES" squid_enable="YES" -squid_chdir="<filename>/<replaceable>a</replaceable>/squid/logs</filename>" -squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</filename>"</programlisting> +squid_chdir="<filename>/a/squid/logs</filename>" +squid_pidfile="<filename>/a/squid/logs/squid.pid</filename>"</programlisting> <para>&man.ntpd.8; should <emphasis>not</emphasis> be enabled for VMWare instances.</para> @@ -1738,7 +1733,7 @@ squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</fil <para>Also, it may be possible to leave <application>squid</application> disabled by default so as to not have - <filename>/<replaceable>a</replaceable></filename> + <filename>/a</filename> persistent (which should save instantiation time.) Work is still ongoing. </para> @@ -1753,27 +1748,27 @@ squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</fil <para>Modify <filename>etc/sysctl.conf</filename>:</para> <screen>9a10,30 -> kern.corefile=<filename>/<replaceable>a</replaceable>/%N.core</filename> -> kern.sugid_coredump=1 -> #debug.witness_ddb=0 -> #debug.witness_watch=0 -> -> # squid needs a lot of fds (leak?) -> kern.maxfiles=40000 -> kern.maxfilesperproc=30000 -> -> # Since the NFS root is static we do not need to check frequently for file changes -> # This saves >75% of NFS traffic -> vfs.nfs.access_cache_timeout=300 -> debug.debugger_on_panic=1 -> -> # For jailing -> security.jail.sysvipc_allowed=1 -> security.jail.allow_raw_sockets=1 -> security.jail.chflags_allowed=1 -> security.jail.enforce_statfs=1 -> -> vfs.lookup_shared=1</screen> +> kern.corefile=<filename>/a/%N.core</filename> +> kern.sugid_coredump=1 +> #debug.witness_ddb=0 +> #debug.witness_watch=0 +> +> # squid needs a lot of fds (leak?) +> kern.maxfiles=40000 +> kern.maxfilesperproc=30000 +> +> # Since the NFS root is static we do not need to check frequently for file changes +> # This saves >75% of NFS traffic +> vfs.nfs.access_cache_timeout=300 +> debug.debugger_on_panic=1 +> +> # For jailing +> security.jail.sysvipc_allowed=1 +> security.jail.allow_raw_sockets=1 +> security.jail.chflags_allowed=1 +> security.jail.enforce_statfs=1 +> +> vfs.lookup_shared=1</screen> </listitem> <listitem> @@ -1786,7 +1781,7 @@ squid_pidfile="<filename>/<replaceable>a</replaceable>/squid/logs/squid.pid</fil </procedure> </sect2> - <sect2 id="node-ports"> + <sect2 xml:id="node-ports"> <title>Configuring <filename>ports</filename></title> <procedure> @@ -1861,7 +1856,7 @@ security/sudo</programlisting> # # Configure a package build system post-boot -scratchdir=<filename>/<replaceable>a</replaceable></filename> +scratchdir=<filename>/a</filename> ln -sf ${scratchdir}/portbuild /var/ @@ -1900,7 +1895,7 @@ touch /tmp/.boot_finished</programlisting> > negative_ttl 0 minutes</screen> <para>Also, change <filename>usr/local</filename> - to <filename><replaceable>usr2</replaceable></filename> in + to <filename>usr2</filename> in <literal>cache_dir</literal>, <literal>access_log</literal>, <literal>cache_log</literal>, @@ -1938,14 +1933,14 @@ portbuild ALL=(ALL) NOPASSWD: ALL</programlisting> </procedure> </sect2> - <sect2 id="node-configuration"> + <sect2 xml:id="node-configuration"> <title>Configuration on the client itself</title> <procedure> <step> <para>Change into the port/package directory you picked above, e.g., - <command>cd <filename>/<replaceable>usr2</replaceable></filename></command>.</para> + <command>cd /usr2</command>.</para> </step> <step> @@ -1989,7 +1984,7 @@ portbuild ALL=(ALL) NOPASSWD: ALL</programlisting> </procedure> </sect2> - <sect2 id="pointyhat-configuration"> + <sect2 xml:id="pointyhat-configuration"> <title>Configuration on the server</title> <para>These steps need to be taken by a <literal>portmgr</literal> @@ -2015,7 +2010,7 @@ portbuild ALL=(ALL) NOPASSWD: ALL</programlisting> <step> <para>Create - <filename>/a/portbuild/<replaceable>${arch}</replaceable>/clients/bindist-<replaceable>${hostname}</replaceable>.tar</filename>.</para> + <filename>/a/portbuild/${arch}/clients/bindist-${hostname}.tar</filename>.</para> <itemizedlist> <listitem> @@ -2031,9 +2026,9 @@ portbuild ALL=(ALL) NOPASSWD: ALL</programlisting> <listitem> <para>Customize <filename>etc/make.conf</filename> for FTP fetches for the local site. Note: the nulling-out - of <makevar>MASTER_SITE_BACKUP</makevar> must be common + of <varname>MASTER_SITE_BACKUP</varname> must be common to all nodes, but the first entry in - <makevar>MASTER_SITE_OVERRIDE</makevar> should be the + <varname>MASTER_SITE_OVERRIDE</varname> should be the nearest local FTP mirror. Example:</para> <programlisting>.if defined(FETCH_ORIGINAL) @@ -2060,15 +2055,15 @@ MASTER_SITE_OVERRIDE= \ <step> <para>Create -<filename>/a/portbuild/<replaceable>${arch}</replaceable>/portbuild-<replaceable>${hostname}</replaceable></filename> +<filename>/a/portbuild/${arch}/portbuild-${hostname}</filename> using one of the existing ones as a guide. This file contains overrides to -<filename>/a/portbuild/<replaceable>${arch}</replaceable>/portbuild.conf</filename>.</para> +<filename>/a/portbuild/${arch}/portbuild.conf</filename>.</para> <para>Suggested values:</para> <programlisting>disconnected=1 -scratchdir=<filename>/<replaceable>usr2</replaceable>/pkgbuild</filename> +scratchdir=<filename>/usr2/pkgbuild</filename> client_user=portbuild sudo_cmd="sudo -H" rsync_gzip=-z @@ -2080,7 +2075,7 @@ infoseek_port=<replaceable>${tunelled-tcp-port}</replaceable></programlisting> on the client:</para> <programlisting>http_proxy="http://localhost:3128/" -squid_dir=<filename>/<replaceable>usr2</replaceable>/squid</filename></programlisting> +squid_dir=<filename>/usr2/squid</filename></programlisting> <para>If, instead, you will be using <application>squid</application> on the server:</para> @@ -2099,7 +2094,7 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> </procedure> <para>These steps need to be taken by a <literal>portmgr</literal> - acting as <literal>root</literal> on <hostid>pointyhat</hostid>.</para> + acting as <literal>root</literal> on <systemitem>pointyhat</systemitem>.</para> <procedure> <step> @@ -2120,7 +2115,7 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> </procedure> </sect2> - <sect2 id="node-enabling"> + <sect2 xml:id="node-enabling"> <title>Enabling the node</title> <para>These steps need to be taken by a <literal>portmgr</literal> @@ -2130,7 +2125,7 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> <step> <para>Ensure that <literal>ssh</literal> to the client is working by executing - <userinput>ssh <replaceable>hostname</replaceable> uname -a</userinput>. + <userinput>ssh hostname uname -a</userinput>. The actual command is not important; what is important is to confirm the setup, and also add an entry into <filename>known_hosts</filename>, once you have confirmed the @@ -2140,13 +2135,13 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> <step> <para>Populate the client's copy of <filename>/var/portbuild/scripts/</filename> by something like - <userinput>/a/portbuild/scripts/dosetupnode <replaceable>arch</replaceable> <replaceable>major</replaceable> latest <replaceable>hostname</replaceable></userinput>. + <userinput>/a/portbuild/scripts/dosetupnode arch major latest hostname</userinput>. Verify that you now have files in that directory.</para> </step> <step> <para>Test the other TCP ports by executing - <userinput>telnet <replaceable>hostname</replaceable> <replaceable>portnumber</replaceable></userinput>. + <userinput>telnet hostname portnumber</userinput>. <literal>414</literal> (or its tunnel) should give you a few lines of status information including <literal>arch</literal> and <literal>osversion</literal>; <literal>8649</literal> should @@ -2162,17 +2157,17 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> <step> <para>Tell <filename>qmanager</filename> about the node. Example:</para> - <para><userinput>python <replaceable>path</replaceable>/qmanager/qclient add - name=<replaceable>uniquename</replaceable> - arch=<replaceable>arch</replaceable> - osversion=<replaceable>osversion</replaceable> - numcpus=<replaceable>number</replaceable> + <para><userinput>python path/qmanager/qclient add + name=uniquename + arch=arch + osversion=osversion + numcpus=number haszfs=0 online=1 - domain=<replaceable>domain</replaceable> + domain=domain primarypool=package pools="package all" maxjobs=1 - acl="ports-<replaceable>arch</replaceable>,deny_all" + acl="ports-arch,deny_all" </userinput></para> </step> </procedure> @@ -2185,16 +2180,16 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> <para>Once you are sure that the client is working, tell <application>pollmachine</application> about it by adding it to - <filename>/a/portbuild/<replaceable>${arch}</replaceable>/mlist</filename>.</para> + <filename>/a/portbuild/${arch}/mlist</filename>.</para> </step> </procedure> </sect2> </sect1> - <sect1 id="new-branch"> + <sect1 xml:id="new-branch"> <title>How to configure a new &os; branch</title> - <sect2 id="new-branch-pre-qmanager"> + <sect2 xml:id="new-branch-pre-qmanager"> <title>Steps necessary before <application>qmanager</application> is started</title> <para>When a new branch is created, some work needs to @@ -2215,19 +2210,19 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> <itemizedlist> <listitem> <para>Add <replaceable>new-branch</replaceable> to - <makevar>SRC_BRANCHES</makevar>.</para> + <varname>SRC_BRANCHES</varname>.</para> </listitem> <listitem> <para>For what was previously head, change - <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> to - <literal>releng/<replaceable>branch</replaceable>.0</literal> + <varname>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</varname> to + <literal>releng/branch.0</literal> (literal zero).</para> </listitem> <listitem> <para>Add - <makevar>SRC_BRANCH_<replaceable>new-branch</replaceable>_SUBDIR</makevar> + <varname>SRC_BRANCH_<replaceable>new-branch</replaceable>_SUBDIR</varname> <literal>=head</literal>.</para> </listitem> </itemizedlist> @@ -2239,7 +2234,7 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> </itemizedlist> </sect2> - <sect2 id="new-branch-post-qmanager"> + <sect2 xml:id="new-branch-post-qmanager"> <title>Steps necessary after <application>qmanager</application> is started</title> <itemizedlist> @@ -2265,7 +2260,7 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> </sect2> </sect1> - <sect1 id="old-branch"> + <sect1 xml:id="old-branch"> <title>How to delete an unsupported &os; branch</title> <para>When an old branch goes out of support, there are some @@ -2279,12 +2274,12 @@ ssh_cmd="/usr/local/bin/ssh"</programlisting> <itemizedlist> <listitem> <para>Delete <replaceable>old-branch</replaceable> from - <makevar>SRC_BRANCHES</makevar>.</para> + <varname>SRC_BRANCHES</varname>.</para> </listitem> <listitem> <para>Delete - <makevar>SRC_BRANCH_<replaceable>old-branch</replaceable>_SUBDIR</makevar><literal>=</literal> + <varname>SRC_BRANCH_<replaceable>old-branch</replaceable>_SUBDIR</varname><literal>=</literal> <replaceable>whatever</replaceable></para> </listitem> </itemizedlist> @@ -2306,29 +2301,29 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> <itemizedlist> <listitem> <para>Files named - <filename>*-<replaceable>old_branch</replaceable>-failure.html</filename></para> + <filename>*-old_branch-failure.html</filename></para> </listitem> <listitem> <para>Files named - <filename>buildlogs_*-<replaceable>old_branch</replaceable>-*-logs.txt</filename></para> + <filename>buildlogs_*-old_branch-*-logs.txt</filename></para> </listitem> <listitem> <para>Symlinks named - <filename>*-<replaceable>old_branch</replaceable>-previous*</filename></para> + <filename>*-old_branch-previous*</filename></para> </listitem> <listitem> <para>Symlinks named - <filename>*-<replaceable>old_branch</replaceable>-latest*</filename></para> + <filename>*-old_branch-latest*</filename></para> </listitem> </itemizedlist> </listitem> </itemizedlist> </sect1> - <sect1 id="rebase-branch"> + <sect1 xml:id="rebase-branch"> <title>How to rebase on a supported &os; branch</title> <para>As of 2011, the philosophy of package building is to build @@ -2338,7 +2333,7 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> <literal>packages-8-stable</literal> should be built from 8.1.</para> <para>As releases go End-Of-Life (see - <ulink url="http://www.freebsd.org/security/index.html#sup">chart</ulink>), + <link xlink:href="http://www.freebsd.org/security/index.html#sup">chart</link>), a full (not incremental!) package build should be done and uploaded.</para> <para>The procedure is as follows:</para> @@ -2351,7 +2346,7 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> <itemizedlist> <listitem> <para>Change the value of - <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> to + <varname>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</varname> to <literal>releng/</literal><replaceable>branch</replaceable>.<replaceable>N</replaceable> where <literal>N</literal> is the newest 'oldest' release for that branch.</para> @@ -2377,10 +2372,10 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> </itemizedlist> </sect1> - <sect1 id="new-arch"> + <sect1 xml:id="new-arch"> <title>How to configure a new architecture</title> - <sect2 id="new-arch-pre-qmanager"> + <sect2 xml:id="new-arch-pre-qmanager"> <title>Steps necessary before <application>qmanager</application> is started</title> <note> @@ -2430,12 +2425,12 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> <note> <para>(Historical note that only applied to the original - <hostid>pointyhat.FreeBSD.org</hostid> installation)</para> + <systemitem>pointyhat.FreeBSD.org</systemitem> installation)</para> <para>It is possible that <filename>/dumpster/pointyhat</filename> will not have enough space. In that case, create the archive directory as - <filename>/dumpster/pointyhat/<replaceable>arch</replaceable>/archive</filename> + <filename>/dumpster/pointyhat/arch/archive</filename> and symlink to that.</para> </note> </listitem> @@ -2453,7 +2448,7 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> <listitem> <para>Create customized - <filename>portbuild.<replaceable>machinename</replaceable>.conf</filename> + <filename>portbuild.machinename.conf</filename> files as appropriate.</para> </listitem> @@ -2481,7 +2476,7 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> <itemizedlist> <listitem> - <para>Add <replaceable>arch</replaceable> to <makevar>SUPPORTED_ARCHS</makevar> in + <para>Add <replaceable>arch</replaceable> to <varname>SUPPORTED_ARCHS</varname> in <filename>/a/portbuild/admin/conf/admin.conf</filename>.</para> </listitem> @@ -2501,7 +2496,7 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> </itemizedlist> </sect2> - <sect2 id="new-arch-post-qmanager"> + <sect2 xml:id="new-arch-post-qmanager"> <title>Steps necessary after <application>qmanager</application> is started</title> <note> @@ -2523,10 +2518,10 @@ zfs destroy -r a/snap/src-<replaceable>old-branch</replaceable></screen> </sect2> </sect1> - <sect1 id="new-head-node"> + <sect1 xml:id="new-head-node"> <title>How to configure a new head node (pointyhat instance)</title> - <sect2 id="pointyhat-basics"> + <sect2 xml:id="pointyhat-basics"> <title>Basic installation</title> <procedure> @@ -2633,14 +2628,14 @@ sysctl vfs.zfs.super_owner=1</programlisting> </procedure> </sect2> - <sect2 id="pointyhat-src"> + <sect2 xml:id="pointyhat-src"> <title>Configuring <filename>src</filename></title> <para>You should be able to install from the most recent release using only the default kernel configuration.</para> </sect2> - <sect2 id="pointyhat-ports"> + <sect2 xml:id="pointyhat-ports"> <title>Configuring <filename>ports</filename></title> <procedure> @@ -2704,7 +2699,7 @@ sysutils/zfs-stats</programlisting> </procedure> </sect2> - <sect2 id="pointyhat-zfs-volume"> + <sect2 xml:id="pointyhat-zfs-volume"> <title>Configuring the zfs volume and setting up the repository</title> <para>The following steps need to be done as euid root.</para> @@ -2748,13 +2743,13 @@ sh -x ./tmp/mkportbuild <procedure> <step> - <para>Export the value of <makevar>PORTBUILD_USER</makevar>:</para> + <para>Export the value of <varname>PORTBUILD_USER</varname>:</para> <screen>&prompt.root; export PORTBUILD_USER=<replaceable>portbuild</replaceable></screen> </step> <step> - <para>Export the value of <makevar>SRCBUILD_USER</makevar>:</para> + <para>Export the value of <varname>SRCBUILD_USER</varname>:</para> <screen>&prompt.root; export SRCBUILD_USER=<replaceable>srcbuild</replaceable></screen> </step> @@ -2768,7 +2763,7 @@ sh -x ./tmp/mkportbuild <step> <para>Pick a mountpoint and export it. We have used - <filename>/<replaceable>a</replaceable></filename> so far to date.</para> + <filename>/a</filename> so far to date.</para> <screen>&prompt.root; export ZFS_MOUNTPOINT=/<replaceable>a</replaceable></screen> </step> @@ -2796,7 +2791,7 @@ sh -x ./tmp/mkportbuild <step> <para>Select an <application>svn</application> repository and export it. See the - <ulink url="&url.books.handbook;/svn-mirrors.html">&os; Handbook</ulink> + <link xlink:href="&url.books.handbook;/svn-mirrors.html">&os; Handbook</link> for the currently supported list.</para> <screen>&prompt.root; export VCS_REPOSITORY=<replaceable>svn://svn0.us-east.FreeBSD.org</replaceable></screen> @@ -2858,42 +2853,42 @@ sh -x ./tmp/mkportbuild </procedure> </sect2> - <sect2 id="srcbuild-user-configuration"> + <sect2 xml:id="srcbuild-user-configuration"> <title>Configuring the <application>srcbuild</application>-owned files</title> <procedure> <step> <para>Configure the server by making the following changes to - <filename>/<replaceable>a</replaceable>/portbuild/admin/conf/admin.conf</filename>:</para> + <filename>/a/portbuild/admin/conf/admin.conf</filename>:</para> <itemizedlist> <listitem> - <para>Set <makevar>SUPPORTED_ARCHS</makevar> to the + <para>Set <varname>SUPPORTED_ARCHS</varname> to the list of architectures you wish to build packages for.</para> </listitem> <listitem> <para>For each source branch you will be building for, set - <makevar>SRC_BRANCHES</makevar> and - <makevar>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</makevar> + <varname>SRC_BRANCHES</varname> and + <varname>SRC_BRANCH_<replaceable>branch</replaceable>_SUBDIR</varname> as detailed in <xref linkend="new-branch-pre-qmanager"/>. You should not need to change - <makevar>SRC_BRANCHES_PATTERN</makevar>.</para> + <varname>SRC_BRANCHES_PATTERN</varname>.</para> </listitem> <listitem> - <para>Set <makevar>ZFS_VOLUME</makevar> and - <makevar>ZFS_MOUNTPOINT</makevar> to whatever you + <para>Set <varname>ZFS_VOLUME</varname> and + <varname>ZFS_MOUNTPOINT</varname> to whatever you chose above.</para> </listitem> <listitem> - <para>Set <makevar>VCS_REPOSITORY</makevar> to whatever + <para>Set <varname>VCS_REPOSITORY</varname> to whatever you chose above.</para> </listitem> <listitem> - <para>Set <makevar>MASTER_URL</makevar> to the http + <para>Set <varname>MASTER_URL</varname> to the http URL of your server. This will be stamped into the package build logs and the indices thereof.</para> </listitem> @@ -2904,30 +2899,30 @@ sh -x ./tmp/mkportbuild </procedure> </sect2> - <sect2 id="portbuild-user-configuration"> + <sect2 xml:id="portbuild-user-configuration"> <title>Configuring the <application>portbuild</application>-owned files</title> <procedure> <step> <para>Configure how build slaves will talk to your server by making the following changes to - <filename>/<replaceable>a</replaceable>/portbuild/conf/client.conf</filename>:</para> + <filename>/a/portbuild/conf/client.conf</filename>:</para> <itemizedlist> <listitem> - <para>Set <makevar>CLIENT_NFS_MASTER</makevar> to wherever + <para>Set <varname>CLIENT_NFS_MASTER</varname> to wherever your build slaves will PXE boot from. (Possibly, the hostname of your server.)</para> </listitem> <listitem> - <para>Set <makevar>CLIENT_BACKUP_FTP_SITE</makevar> + <para>Set <varname>CLIENT_BACKUP_FTP_SITE</varname> to a backup site for FTP fetches; again, possibly the hostname of your server.</para> </listitem> <listitem> - <para>Set <makevar>CLIENT_UPLOAD_HOST</makevar> to + <para>Set <varname>CLIENT_UPLOAD_HOST</varname> to where completed packages will be uploaded.</para> </listitem> </itemizedlist> @@ -2937,14 +2932,14 @@ sh -x ./tmp/mkportbuild <step> <para>Most of the default values in - <filename>/<replaceable>a</replaceable>/portbuild/conf/common.conf</filename> + <filename>/a/portbuild/conf/common.conf</filename> should be fine. This file holds definitions used by both the server and all its clients.</para> </step> <step> <para>Configure the server by making the following changes to - <filename>/<replaceable>a</replaceable>/portbuild/conf/server.conf</filename>:</para> + <filename>/a/portbuild/conf/server.conf</filename>:</para> <itemizedlist> <!-- @@ -2965,9 +2960,9 @@ sh -x ./tmp/mkportbuild --> <listitem> - <para>Set <makevar>UPLOAD_DIRECTORY</makevar>, - <makevar>UPLOAD_TARGET</makevar>, and - <makevar>UPLOAD_USER</makevar> as appropriate + <para>Set <varname>UPLOAD_DIRECTORY</varname>, + <varname>UPLOAD_TARGET</varname>, and + <varname>UPLOAD_USER</varname> as appropriate for your site.</para> </listitem> @@ -2990,7 +2985,7 @@ sh -x ./tmp/mkportbuild </procedure> </sect2> - <sect2 id="pointyhat-pre-qmanager"> + <sect2 xml:id="pointyhat-pre-qmanager"> <title>pre-<application>qmanager</application></title> <procedure> @@ -3001,7 +2996,7 @@ sh -x ./tmp/mkportbuild </procedure> </sect2> - <sect2 id="pointyhat-qmanager"> + <sect2 xml:id="pointyhat-qmanager"> <title><application>qmanager</application></title> <procedure> @@ -3032,7 +3027,7 @@ qmanager</programlisting> </procedure> </sect2> - <sect2 id="pointyhat-src-ports-repos"> + <sect2 xml:id="pointyhat-src-ports-repos"> <title>Creating src and ports repositories</title> <procedure> @@ -3053,7 +3048,7 @@ qmanager</programlisting> </procedure> </sect2> - <sect2 id="pointyhat-other-services"> + <sect2 xml:id="pointyhat-other-services"> <title>Other services</title> <procedure> @@ -3072,7 +3067,7 @@ qmanager</programlisting> <step> <para>Install <filename>/a/portbuild/admin/crontabs/portbuild</filename> as - the <username>portbuild</username> crontab via + the <systemitem class="username">portbuild</systemitem> crontab via <command>crontab -u portbuild -e</command>. If you do not support all the archs listed there, make sure to comment out the appropriate <application>dologs</application> entries.</para> @@ -3080,7 +3075,7 @@ qmanager</programlisting> <step> <para>Install <filename>/a/portbuild/admin/crontabs/srcbuild</filename> as - the <username>srcbuild</username> crontab via + the <systemitem class="username">srcbuild</systemitem> crontab via <command>crontab -u srcbuild -e</command>.</para> </step> @@ -3098,7 +3093,7 @@ qmanager</programlisting> </procedure> </sect2> - <sect2 id="pointyhat-finishing-up"> + <sect2 xml:id="pointyhat-finishing-up"> <title>Finishing up</title> <procedure> @@ -3109,7 +3104,7 @@ qmanager</programlisting> <step> <para>You will probably find it handy to append - the following to the <makevar>PATH</makevar> definition for + the following to the <varname>PATH</varname> definition for the <replaceable>portbuild</replaceable> user:</para> <programlisting>/<replaceable>a</replaceable>/portbuild/scripts:/<replaceable>a</replaceable>/portbuild/tools</programlisting> @@ -3117,7 +3112,7 @@ qmanager</programlisting> <step> <para>You will also probably find it handy to append - the following to the <makevar>PATH</makevar> definition for + the following to the <varname>PATH</varname> definition for the <replaceable>srcbuild</replaceable> user:</para> <programlisting>/<replaceable>a</replaceable>/portbuild/admin/scripts:/<replaceable>a</replaceable>/portbuild/admin/tools</programlisting> @@ -3128,11 +3123,11 @@ qmanager</programlisting> </sect2> </sect1> - <sect1 id="disk-failure"> + <sect1 xml:id="disk-failure"> <title>Procedures for dealing with disk failures</title> <note> - <para>The following section is particular to <hostid>freebsd.org</hostid> + <para>The following section is particular to <systemitem>freebsd.org</systemitem> and is somewhat obsolete.</para> </note> @@ -3143,7 +3138,7 @@ qmanager</programlisting> <listitem> <para>Note the time and failure mode (e.g., paste in the relevant console output) in - <filename>/a/portbuild/<replaceable>${arch}</replaceable>/reboots</filename></para> + <filename>/a/portbuild/${arch}/reboots</filename></para> </listitem> <listitem> diff --git a/en_US.ISO8859-1/articles/pr-guidelines/article.xml b/en_US.ISO8859-1/articles/pr-guidelines/article.xml index 0333091503..083dd0dca5 100644 --- a/en_US.ISO8859-1/articles/pr-guidelines/article.xml +++ b/en_US.ISO8859-1/articles/pr-guidelines/article.xml @@ -1,16 +1,12 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ -<!ENTITY man.edit-pr.1 "<citerefentry><refentrytitle>edit-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> -<!ENTITY man.query-pr.1 "<citerefentry><refentrytitle>query-pr</refentrytitle><manvolnum>1</manvolnum></citerefentry>"> -]> - -<article lang='en'> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> <!-- :START of Article Metadata --> - <articleinfo> - <title>Problem Report Handling Guidelines</title> + <info><title>Problem Report Handling Guidelines</title> + - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; @@ -30,20 +26,14 @@ </abstract> <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - </author> - - <author> - <firstname>Hiten</firstname> - <surname>Pandya</surname> - </author> + <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname></author> + + <author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname></author> </authorgroup> - </articleinfo> + </info> <!-- :END of Article Metadata--> - <section id="intro"> + <section xml:id="intro"> <title>Introduction</title> <para>GNATS is a defect management (bug reporting) system used by @@ -60,7 +50,7 @@ forth.</para> </section> - <section id="pr-lifecycle"> + <section xml:id="pr-lifecycle"> <title>Problem Report Life-cycle</title> <itemizedlist> @@ -133,7 +123,7 @@ </note> </section> - <section id="pr-states"> + <section xml:id="pr-states"> <title>Problem Report State</title> <para>It is important to update the state of a PR when certain @@ -232,7 +222,7 @@ </note> </section> - <section id="pr-types"> + <section xml:id="pr-types"> <title>Types of Problem Reports</title> <para>While handling problem reports, either as a developer who has @@ -263,7 +253,7 @@ PRs is used for, when a PR belongs to one of these types, and what treatment each different type receives.</para> - <section id="pr-unassigned"> + <section xml:id="pr-unassigned"> <title>Unassigned PRs</title> <para>When PRs arrive, they are initially assigned to a generic @@ -273,7 +263,7 @@ specific &os; mailing list. Here is the current list, with the most common ones listed first:</para> - <table id="default-assignees-common"> + <table xml:id="default-assignees-common"> <title>Default Assignees — most common</title> <tgroup cols="3"> <thead> @@ -318,7 +308,7 @@ </tgroup> </table> - <table id="default-assignees-other"> + <table xml:id="default-assignees-other"> <title>Default Assignees — other</title> <tgroup cols="3"> <thead> @@ -385,15 +375,14 @@ <note> <para>Since the list of individuals who have volunteered to be the default assignee for certain types of PRs changes - so often, it is much more suitable for <ulink - url="http://wiki.freebsd.org/AssigningPRs">the FreeBSD wiki</ulink>. + so often, it is much more suitable for <link xlink:href="http://wiki.freebsd.org/AssigningPRs">the FreeBSD wiki</link>. </para> </note> <para>Here is a sample list of such entities; it is probably not complete.</para> - <table id="common-assignees-base"> + <table xml:id="common-assignees-base"> <title>Common Assignees — base system</title> <tgroup cols="4"> <thead> @@ -571,7 +560,7 @@ </tgroup> </table> - <table id="common-assignees-ports"> + <table xml:id="common-assignees-ports"> <title>Common Assignees — Ports Collection</title> <tgroup cols="4"> <thead> @@ -735,7 +724,7 @@ because everyone assumes that the assignee is already working on it.</para> - <table id="common-assignees-other"> + <table xml:id="common-assignees-other"> <title>Common Assignees — Other</title> <tgroup cols="4"> <thead> @@ -767,7 +756,7 @@ </section> - <section id="pr-assigned"> + <section xml:id="pr-assigned"> <title>Assigned PRs</title> <para>If a PR has the <literal>responsible</literal> field set @@ -783,7 +772,7 @@ you please.</para> </section> - <section id="pr-dups"> + <section xml:id="pr-dups"> <title>Duplicate PRs</title> <para>If you find more than one PR that describe the same issue, @@ -795,7 +784,7 @@ the other PRs (which are now completely superseded).</para> </section> - <section id="pr-stale"> + <section xml:id="pr-stale"> <title>Stale PRs</title> <para>A PR is considered stale if it has not been modified in more @@ -847,7 +836,7 @@ </itemizedlist> </section> - <section id="pr-misfiled"> + <section xml:id="pr-misfiled"> <title>Misfiled PRs</title> <para>GNATS is picky about the format of a submitted bug report. @@ -913,7 +902,7 @@ </listitem> </itemizedlist> - <section id="pr-misfiled-followups"> + <section xml:id="pr-misfiled-followups"> <title>Followups misfiled as new PRs</title> <para>The first category of misfiled PRs, the one with the wrong @@ -978,7 +967,7 @@ This was misfiled because the subject did not have the format: avoid the next time a followup to an existing PR is sent.</para> </section> - <section id="pr-misfiled-format"> + <section xml:id="pr-misfiled-format"> <title>PRs misfiled because of missing fields</title> <para>The second type of misfiled PRs is usually the result of a @@ -1001,7 +990,7 @@ This was misfiled because the subject did not have the format: PR, but it is relatively easy to do most of the time.</para> </section> - <section id="pr-misfiled-notpr"> + <section xml:id="pr-misfiled-notpr"> <title>Misfiled PRs that are not really problem reports</title> <para>Sometimes a user wants to submit a report for a problem @@ -1068,7 +1057,7 @@ This was misfiled because the subject did not have the format: </section> </section> - <section id="references"> + <section xml:id="references"> <title>Further Reading</title> <para>This is a list of resources relevant to the proper writing @@ -1076,9 +1065,8 @@ This was misfiled because the subject did not have the format: <itemizedlist> <listitem> - <para><ulink - url="&url.articles.problem-reports;/article.html">How to - Write FreeBSD Problem Reports</ulink>—guidelines + <para><link xlink:href="&url.articles.problem-reports;/article.html">How to + Write FreeBSD Problem Reports</link>—guidelines for PR originators.</para> </listitem> </itemizedlist> diff --git a/en_US.ISO8859-1/articles/problem-reports/article.xml b/en_US.ISO8859-1/articles/problem-reports/article.xml index 61ad4fa589..b7d3dd73a2 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.xml +++ b/en_US.ISO8859-1/articles/problem-reports/article.xml @@ -1,12 +1,11 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Writing &os; Problem Reports</title> + -<article lang='en'> - <articleinfo> - <title>Writing &os; Problem Reports</title> - - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.ibm; &tm-attrib.intel; @@ -25,22 +24,15 @@ </abstract> <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - <contrib>Contributed by </contrib> - </author> - - <author> - <firstname>Mark</firstname> - <surname>Linimon</surname> - </author> + <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Contributed by </contrib></author> + + <author><personname><firstname>Mark</firstname><surname>Linimon</surname></personname></author> </authorgroup> - </articleinfo> + </info> <indexterm><primary>problem reports</primary></indexterm> - <section id="pr-intro"> + <section xml:id="pr-intro"> <title>Introduction</title> <para>One of the most frustrating experiences one can have as a @@ -69,7 +61,7 @@ step-by-step tutorial.</para> </section> - <section id="pr-when"> + <section xml:id="pr-when"> <title>When to submit a problem report</title> <para>There are many types of problems, and not all of them should @@ -107,7 +99,7 @@ system components such as BIND or various GNU utilities).</para> - <para>For unmaintained ports (<makevar>MAINTAINER</makevar> contains + <para>For unmaintained ports (<varname>MAINTAINER</varname> contains <literal>ports@FreeBSD.org</literal>), such update notifications might get picked up by an interested committer, or you might be asked to provide a patch to update @@ -120,12 +112,10 @@ a new version, they have probably worked with the developers on it, they are probably testing to see there is no regression, etc.</para> - <para>In either case, following the process described in <ulink - url="&url.books.porters-handbook;/port-upgrading.html">Porter's - Handbook</ulink> will yield the best results. (You might - also wish to read <ulink - url="&url.articles.contributing-ports;/article.html"> - Contributing to the FreeBSD Ports Collection</ulink>.) + <para>In either case, following the process described in <link xlink:href="&url.books.porters-handbook;/port-upgrading.html">Porter's + Handbook</link> will yield the best results. (You might + also wish to read <link xlink:href="&url.articles.contributing-ports;/article.html"> + Contributing to the FreeBSD Ports Collection</link>.) </para> </listitem> </itemizedlist> @@ -188,16 +178,16 @@ <para>If the problem is in the base system, you should first read the FAQ section on - <ulink url="&url.books.faq;/introduction.html#LATEST-VERSION"> - &os; versions</ulink>, if you are not already familiar with + <link xlink:href="&url.books.faq;/introduction.html#LATEST-VERSION"> + &os; versions</link>, if you are not already familiar with the topic. It is not possible for &os; to fix problems in anything other than certain recent branches of the base system, so filing a bug report about an older version will probably only result in a developer advising you to upgrade to a supported version to see if the problem still recurs. The Security Officer team maintains the - <ulink url="&url.base;/security/">list of supported - versions</ulink>.</para> + <link xlink:href="&url.base;/security/">list of supported + versions</link>.</para> <para>If the problem is in a port, note that you must first upgrade to the latest version of the Ports Collection and see @@ -207,7 +197,7 @@ with older version of applications simply cannot be fixed.</para> </section> - <section id="pr-prep"> + <section xml:id="pr-prep"> <title>Preparations</title> <para>A good rule to follow is to always do a background search @@ -221,26 +211,24 @@ <itemizedlist> <listitem> <para>The &os; - <ulink url="&url.books.faq;/index.html">Frequently Asked - Questions</ulink> (FAQ) list. + <link xlink:href="&url.books.faq;/index.html">Frequently Asked + Questions</link> (FAQ) list. The FAQ attempts to provide answers for a wide range of questions, such as those concerning - <ulink url="&url.books.faq;/hardware.html">hardware - compatibility</ulink>, - <ulink url="&url.books.faq;/applications.html">user - applications</ulink>, - and <ulink url="&url.books.faq;/kernelconfig.html">kernel - configuration</ulink>.</para> + <link xlink:href="&url.books.faq;/hardware.html">hardware + compatibility</link>, + <link xlink:href="&url.books.faq;/applications.html">user + applications</link>, + and <link xlink:href="&url.books.faq;/kernelconfig.html">kernel + configuration</link>.</para> </listitem> <listitem> <para>The - <ulink - url="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing - lists</ulink>—if you are not subscribed, use - <ulink - url="http://www.FreeBSD.org/search/search.html#mailinglists">the - searchable archives</ulink> on the &os; web site. If your + <link xlink:href="&url.books.handbook;/eresources.html#ERESOURCES-MAIL">mailing + lists</link>—if you are not subscribed, use + <link xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">the + searchable archives</link> on the &os; web site. If your problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if someone can spot something you have overlooked.</para> @@ -256,8 +244,8 @@ <listitem> <para>Next, the searchable - <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - &os; PR database</ulink> (GNATS). Unless your problem + <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + &os; PR database</link> (GNATS). Unless your problem is recent or obscure, there is a fair chance it has already been reported.</para> </listitem> @@ -270,7 +258,7 @@ carefully study the contents of the <filename>/usr/src/UPDATING</filename> file on your system or its latest version at - <ulink url="http://svnweb.freebsd.org/base/head/UPDATING?view=log"></ulink>. + <uri xlink:href="http://svnweb.freebsd.org/base/head/UPDATING?view=log">http://svnweb.freebsd.org/base/head/UPDATING?view=log</uri>. (This is vital information if you are upgrading from one version to another—especially if you are upgrading to the @@ -281,15 +269,15 @@ <filename>/usr/ports/UPDATING</filename> (for individual ports) or <filename>/usr/ports/CHANGES</filename> (for changes that affect the entire Ports Collection). - <ulink url="http://svnweb.freebsd.org/ports/head/UPDATING?view=log"></ulink> + <uri xlink:href="http://svnweb.freebsd.org/ports/head/UPDATING?view=log">http://svnweb.freebsd.org/ports/head/UPDATING?view=log</uri> and - <ulink url="http://svnweb.freebsd.org/ports/head/CHANGES?view=log"></ulink> + <uri xlink:href="http://svnweb.freebsd.org/ports/head/CHANGES?view=log">http://svnweb.freebsd.org/ports/head/CHANGES?view=log</uri> are also available via svnweb.</para> </listitem> </itemizedlist> </section> - <section id="pr-writing"> + <section xml:id="pr-writing"> <title>Writing the problem report</title> <para>Now that you have decided that your issue merits a problem @@ -450,7 +438,7 @@ <listitem> <para>any environment variables that override the defaults in <filename>bsd.port.mk</filename>, such - as <makevar>PORTSDIR</makevar></para> + as <varname>PORTSDIR</varname></para> </listitem> <listitem> <para>the fact that you have read @@ -481,7 +469,7 @@ a similar PR.</emphasis> Although this has already been mentioned above, it bears repeating here. It only take a minute or two to use the web-based search engine at - <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"></ulink>. + <uri xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query</uri>. (Of course, everyone is guilty of forgetting to do this now and then.)</para> </listitem> @@ -502,7 +490,7 @@ offer patches, but also justification for why the patches are <quote>The Right Thing To Do</quote>. As noted above, a careful search of the mailing lists using the archives - at <ulink url="http://www.FreeBSD.org/search/search.html#mailinglists"></ulink> + at <uri xlink:href="http://www.FreeBSD.org/search/search.html#mailinglists">http://www.FreeBSD.org/search/search.html#mailinglists</uri> is always good preparation.</para> </listitem> @@ -533,7 +521,7 @@ problem report will not reach the GNATS database. For details on the setup of mail on &os;, see the <quote>Electronic Mail</quote> chapter of the &os; Handbook at - <ulink url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html"></ulink>.</para> + <uri xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html">http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/handbook/mail.html</uri>.</para> <para>Make sure that your mailer will not mangle the message on its way to GNATS. In particular, if your mailer automatically @@ -544,8 +532,8 @@ so that the web display of the PR will be readable.</para> <para>Similar considerations apply if you are using the - <ulink url="&url.base;/send-pr.html"> web-based - PR submission form</ulink> instead of &man.send-pr.1;. Note that + <link xlink:href="&url.base;/send-pr.html"> web-based + PR submission form</link> instead of &man.send-pr.1;. Note that cut-and-paste operations can have their own side-effects on text formatting. In certain cases it may be necessary to use &man.uuencode.1; to ensure that patches arrive unmodified.</para> @@ -553,7 +541,7 @@ <para>Finally, if your submission will be lengthy, you should to prepare your work offline so that nothing will be lost in case there is a problem submitting it. This can especially be a - problem with the <ulink url="&url.base;/send-pr.html">web form</ulink>.</para> + problem with the <link xlink:href="&url.base;/send-pr.html">web form</link>.</para> </section> <section> @@ -680,8 +668,8 @@ <para>Security problems should <emphasis>not</emphasis> be filed in GNATS, because all GNATS information is public knowledge. Please send such problems according to our - <ulink url="http://security.freebsd.org/#how">security - report guidelines</ulink>.</para> + <link xlink:href="http://security.freebsd.org/#how">security + report guidelines</link>.</para> </note> </listitem> @@ -703,7 +691,7 @@ </itemizedlist> <para>The next section describes fields that are common to both - the email interface and the <ulink url="&url.base;/send-pr.html">web interface</ulink>:</para> + the email interface and the <link xlink:href="&url.base;/send-pr.html">web interface</link>:</para> <itemizedlist> @@ -781,18 +769,18 @@ &man.sh.1; or &man.mount.8;, you will first need to determine whether these programs are in the base system or were added via the Ports Collection. If you are unsure, you can do - <command>whereis <replaceable>programname</replaceable></command>. + <command>whereis programname</command>. &os;'s convention for the Ports Collection is to install everything underneath - <filename class="directory">/usr/local</filename>, + <filename>/usr/local</filename>, although this can be overridden by a system administrator. For these, you will use the <literal>ports</literal> category (yes, even if the port's category is <literal>www</literal>; see below). If the location is - <filename class="directory">/bin</filename>, - <filename class="directory">/usr/bin</filename>, - <filename class="directory">/sbin</filename>, or - <filename class="directory">/usr/sbin</filename>, + <filename>/bin</filename>, + <filename>/usr/bin</filename>, + <filename>/sbin</filename>, or + <filename>/usr/sbin</filename>, it is part of the base system, and you should use the <literal>bin</literal> category. (A few programs, such as &man.gcc.1;, actually use the <literal>gnu</literal> category, @@ -816,13 +804,13 @@ <listitem> <para>If you are having a problem with the - <ulink url="http://www.FreeBSD.org">FreeBSD web pages</ulink>, + <link xlink:href="http://www.FreeBSD.org">FreeBSD web pages</link>, the proper choice is <literal>www</literal>.</para> <note> <para>if you are having a problem with something from a port named - <literal>www/<replaceable>someportname</replaceable></literal>, + <literal>www/someportname</literal>, this nevertheless goes in the <literal>ports</literal> category.</para> </note> @@ -913,7 +901,7 @@ </itemizedlist> <para>Here is the current list of categories (taken from - <ulink url="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories"></ulink>):</para> + <uri xlink:href="http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories">http://svnweb.freebsd.org/base/head/gnu/usr.bin/send-pr/categories</uri>):</para> <itemizedlist> <listitem> @@ -1127,7 +1115,7 @@ <para>This will read the specified file, validate the contents, strip comments and send it off.</para> - <para>If you are using the <ulink url="&url.base;/send-pr.html">web form</ulink>:</para> + <para>If you are using the <link xlink:href="&url.base;/send-pr.html">web form</link>:</para> <para>Before you hit <literal>submit</literal>, you will need to fill in a field containing text that is represented in image @@ -1150,7 +1138,7 @@ </section> - <section id="pr-followup"> + <section xml:id="pr-followup"> <title>Follow-up</title> <para>Once your problem report has been filed, you will receive a @@ -1172,8 +1160,8 @@ <listitem> <para>The easiest way is to use the followup link on the individual PR's web page, which you can reach from the - <ulink url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> - PR search page</ulink>. Clicking on this link will bring up an + <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query"> + PR search page</link>. Clicking on this link will bring up an an email window with the correct To: and Subject: lines filled in (if your browser is configured to do this).</para> </listitem> @@ -1210,7 +1198,7 @@ possible, explaining how or when the problem was fixed.</para> </section> - <section id="pr-problems"> + <section xml:id="pr-problems"> <title>If you are having problems</title> <para>Most PRs go through the system and are accepted quickly; @@ -1241,15 +1229,15 @@ may have happened is that the database index has gotten out of synchronization with the database itself. The way that you can test whether this has happened is to pull up the - <ulink url="http://www.FreeBSD.org/cgi/query-pr.cgi"> - view a single PR</ulink> page and see whether the PR shows up. + <link xlink:href="http://www.FreeBSD.org/cgi/query-pr.cgi"> + view a single PR</link> page and see whether the PR shows up. If it does, please notify the GNATS administrators at <email>bugmeister@FreeBSD.org</email>. Note that there is a <literal>cron</literal> job that periodically rebuilds the database, so unless you are in a hurry, no action needs to be taken.</para> </section> - <section id="pr-further"> + <section xml:id="pr-further"> <title>Further Reading</title> <para>This is a list of resources relevant to the proper writing @@ -1257,19 +1245,19 @@ <itemizedlist> <listitem> - <para><ulink - url="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> - How to Report Bugs Effectively</ulink>—an excellent + <para><link xlink:href="http://www.chiark.greenend.org.uk/~sgtatham/bugs.html"> + How to Report Bugs Effectively</link>—an excellent essay by Simon G. Tatham on composing useful (non-&os;-specific) problem reports.</para> </listitem> <listitem> - <para><ulink - url="&url.articles.pr-guidelines;/article.html">Problem - Report Handling Guidelines</ulink>—valuable insight + <para><link xlink:href="&url.articles.pr-guidelines;/article.html">Problem + Report Handling Guidelines</link>—valuable insight into how problem reports are handled by the &os; developers.</para> </listitem> </itemizedlist> </section> + + <index/> </article> diff --git a/en_US.ISO8859-1/articles/rc-scripting/article.xml b/en_US.ISO8859-1/articles/rc-scripting/article.xml index c12a4a58d6..97684cb2d4 100644 --- a/en_US.ISO8859-1/articles/rc-scripting/article.xml +++ b/en_US.ISO8859-1/articles/rc-scripting/article.xml @@ -1,20 +1,13 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Practical rc.d scripting in BSD</title> + -<article lang='en'> - <articleinfo> - <title>Practical rc.d scripting in BSD</title> - - <author> - <firstname>Yar</firstname> - - <surname>Tikhiy</surname> - - <affiliation> + <author><personname><firstname>Yar</firstname><surname>Tikhiy</surname></personname><affiliation> <address><email>yar@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2005</year> @@ -24,7 +17,7 @@ <holder>The FreeBSD Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.netbsd; &tm-attrib.general; @@ -45,9 +38,9 @@ provide reference points for further study of the design and efficient application of <filename>rc.d</filename>.</para> </abstract> - </articleinfo> + </info> - <sect1 id="rcng-intro"> + <sect1 xml:id="rcng-intro"> <title>Introduction</title> <para>The historical BSD had a monolithic startup script, @@ -164,7 +157,7 @@ authors.</para> </sect1> - <sect1 id="rcng-task"> + <sect1 xml:id="rcng-task"> <title>Outlining the task</title> <para>A little consideration before starting @@ -193,28 +186,28 @@ important to know the answers to these questions.</para> </sect1> - <sect1 id="rcng-dummy"> + <sect1 xml:id="rcng-dummy"> <title>A dummy script</title> <para>The following script just emits a message each time the system boots up:</para> <informalexample> - <programlisting>#!/bin/sh<co id="rcng-dummy-shebang"/> + <programlisting>#!/bin/sh<co xml:id="rcng-dummy-shebang"/> -. /etc/rc.subr<co id="rcng-dummy-include"/> +. /etc/rc.subr<co xml:id="rcng-dummy-include"/> -name="dummy"<co id="rcng-dummy-name"/> -start_cmd="${name}_start"<co id="rcng-dummy-startcmd"/> -stop_cmd=":"<co id="rcng-dummy-stopcmd"/> +name="dummy"<co xml:id="rcng-dummy-name"/> +start_cmd="${name}_start"<co xml:id="rcng-dummy-startcmd"/> +stop_cmd=":"<co xml:id="rcng-dummy-stopcmd"/> -dummy_start()<co id="rcng-dummy-startfn"/> +dummy_start()<co xml:id="rcng-dummy-startfn"/> { echo "Nothing started." } -load_rc_config $name<co id="rcng-dummy-loadconfig"/> -run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting> +load_rc_config $name<co xml:id="rcng-dummy-loadconfig"/> +run_rc_command "$1"<co xml:id="rcng-dummy-runcommand"/></programlisting> </informalexample> <para>Things to note are:</para> @@ -283,7 +276,7 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting> </callout> <callout arearefs="rcng-dummy-name"> - <para><anchor id="name-var"/>The mandatory variable + <para><anchor xml:id="name-var"/>The mandatory variable <envar>name</envar> specifies the name of our script. It is required by &man.rc.subr.8;. That is, each <filename>rc.d</filename> script <emphasis>must</emphasis> @@ -369,7 +362,7 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting> </calloutlist> </sect1> - <sect1 id="rcng-confdummy"> + <sect1 xml:id="rcng-confdummy"> <title>A configurable dummy script</title> <para>Now let us add some controls to our dummy script. As you @@ -391,18 +384,18 @@ run_rc_command "$1"<co id="rcng-dummy-runcommand"/></programlisting> . /etc/rc.subr name=dummy -rcvar=dummy_enable<co id="rcng-confdummy-rcvar"/> +rcvar=dummy_enable<co xml:id="rcng-confdummy-rcvar"/> start_cmd="${name}_start" stop_cmd=":" -load_rc_config $name<co id="rcng-confdummy-loadconfig"/> -: ${dummy_enable:=no} <co id="rcng-confdummy-enable"/> -: ${dummy_msg="Nothing started."}<co id="rcng-confdummy-opt"/> +load_rc_config $name<co xml:id="rcng-confdummy-loadconfig"/> +: ${dummy_enable:=no} <co xml:id="rcng-confdummy-enable"/> +: ${dummy_msg="Nothing started."}<co xml:id="rcng-confdummy-opt"/> dummy_start() { - echo "$dummy_msg"<co id="rcng-confdummy-msg"/> + echo "$dummy_msg"<co xml:id="rcng-confdummy-msg"/> } run_rc_command "$1"</programlisting> @@ -509,7 +502,7 @@ run_rc_command "$1"</programlisting> </calloutlist> </sect1> - <sect1 id="rcng-daemon"> + <sect1 xml:id="rcng-daemon"> <title>Startup and shutdown of a simple daemon</title> <para>We said earlier that &man.rc.subr.8; could provide default @@ -527,7 +520,7 @@ run_rc_command "$1"</programlisting> name=mumbled rcvar=mumbled_enable -command="/usr/sbin/${name}"<co id="rcng-daemon-basic-cmd"/> +command="/usr/sbin/${name}"<co xml:id="rcng-daemon-basic-cmd"/> load_rc_config $name run_rc_command "$1"</programlisting> @@ -603,7 +596,7 @@ run_rc_command "$1"</programlisting> </calloutlist> </sect1> - <sect1 id="rcng-daemon-adv"> + <sect1 xml:id="rcng-daemon-adv"> <title>Startup and shutdown of an advanced daemon</title> <para>Let us add some meat onto the bones of the previous @@ -621,26 +614,26 @@ name=mumbled rcvar=mumbled_enable command="/usr/sbin/${name}" -command_args="mock arguments > /dev/null 2>&1"<co id="rcng-daemon-adv-args"/> +command_args="mock arguments > /dev/null 2>&1"<co xml:id="rcng-daemon-adv-args"/> -pidfile="/var/run/${name}.pid"<co id="rcng-daemon-adv-pid"/> +pidfile="/var/run/${name}.pid"<co xml:id="rcng-daemon-adv-pid"/> -required_files="/etc/${name}.conf /usr/share/misc/${name}.rules"<co id="rcng-daemon-adv-reqfiles"/> +required_files="/etc/${name}.conf /usr/share/misc/${name}.rules"<co xml:id="rcng-daemon-adv-reqfiles"/> -sig_reload="USR1"<co id="rcng-daemon-adv-sig"/> +sig_reload="USR1"<co xml:id="rcng-daemon-adv-sig"/> -start_precmd="${name}_prestart"<co id="rcng-daemon-adv-precmd"/> -stop_postcmd="echo Bye-bye"<co id="rcng-daemon-adv-postcmd"/> +start_precmd="${name}_prestart"<co xml:id="rcng-daemon-adv-precmd"/> +stop_postcmd="echo Bye-bye"<co xml:id="rcng-daemon-adv-postcmd"/> -extra_commands="reload plugh xyzzy"<co id="rcng-daemon-adv-extra"/> +extra_commands="reload plugh xyzzy"<co xml:id="rcng-daemon-adv-extra"/> -plugh_cmd="mumbled_plugh"<co id="rcng-daemon-adv-methods"/> +plugh_cmd="mumbled_plugh"<co xml:id="rcng-daemon-adv-methods"/> xyzzy_cmd="echo 'Nothing happens.'" mumbled_prestart() { - if checkyesno mumbled_smart; then<co id="rcng-daemon-adv-yn"/> - rc_flags="-o smart ${rc_flags}"<co id="rcng-daemon-adv-rcflags"/> + if checkyesno mumbled_smart; then<co xml:id="rcng-daemon-adv-yn"/> + rc_flags="-o smart ${rc_flags}"<co xml:id="rcng-daemon-adv-rcflags"/> fi case "$mumbled_mode" in foo) @@ -650,15 +643,15 @@ mumbled_prestart() rc_flags="-baz ${rc_flags}" ;; *) - warn "Invalid value for mumbled_mode"<co id="rcng-daemon-adv-warn"/> - return 1<co id="rcng-daemon-adv-preret"/> + warn "Invalid value for mumbled_mode"<co xml:id="rcng-daemon-adv-warn"/> + return 1<co xml:id="rcng-daemon-adv-preret"/> ;; esac - run_rc_command xyzzy<co id="rcng-daemon-adv-run"/> + run_rc_command xyzzy<co xml:id="rcng-daemon-adv-run"/> return 0 } -mumbled_plugh()<co id="rcng-daemon-adv-plugh"/> +mumbled_plugh()<co xml:id="rcng-daemon-adv-plugh"/> { echo 'A hollow voice says "plugh".' } @@ -688,8 +681,7 @@ run_rc_command "$1"</programlisting> A better way of passing additional options to <envar>$command</envar> is to add them to the beginning of <envar>${name}_flags</envar>. - Another way is to modify <envar>rc_flags</envar> <link - linkend="rc-flags">as shown later</link>.</para> + Another way is to modify <envar>rc_flags</envar> <link linkend="rc-flags">as shown later</link>.</para> </note> </callout> @@ -882,7 +874,7 @@ fi</programlisting> </callout> <callout arearefs="rcng-daemon-adv-rcflags"> - <para><anchor id="rc-flags"/>We can affect the flags to be + <para><anchor xml:id="rc-flags"/>We can affect the flags to be passed to <envar>$command</envar> by modifying <envar>rc_flags</envar> in <envar>$start_precmd</envar>.</para> </callout> @@ -918,7 +910,7 @@ fi</programlisting> </calloutlist> </sect1> - <sect1 id="rcng-hookup"> + <sect1 xml:id="rcng-hookup"> <title>Connecting a script to the rc.d framework</title> <para>After a script has been written, it needs to be integrated @@ -931,9 +923,9 @@ fi</programlisting> the proper ownership and mode. System scripts should be installed from <filename>src/etc/rc.d</filename> through the <filename>Makefile</filename> found there. Port scripts can - be installed using <makevar>USE_RC_SUBR</makevar> as described - <ulink url="&url.books.porters-handbook;/rc-scripts.html">in - the Porter's Handbook</ulink>.</para> + be installed using <varname>USE_RC_SUBR</varname> as described + <link xlink:href="&url.books.porters-handbook;/rc-scripts.html">in + the Porter's Handbook</link>.</para> <para>However, we should consider beforehand the place of our script in the system startup sequence. The service handled @@ -995,10 +987,10 @@ fi</programlisting> <informalexample> <programlisting>#!/bin/sh -# PROVIDE: mumbled oldmumble <co id="rcng-hookup-provide"/> -# REQUIRE: DAEMON cleanvar frotz<co id="rcng-hookup-require"/> -# BEFORE: LOGIN<co id="rcng-hookup-before"/> -# KEYWORD: nojail shutdown<co id="rcng-hookup-keyword"/> +# PROVIDE: mumbled oldmumble <co xml:id="rcng-hookup-provide"/> +# REQUIRE: DAEMON cleanvar frotz<co xml:id="rcng-hookup-require"/> +# BEFORE: LOGIN<co xml:id="rcng-hookup-before"/> +# KEYWORD: nojail shutdown<co xml:id="rcng-hookup-keyword"/> . /etc/rc.subr @@ -1011,8 +1003,8 @@ start_precmd="${name}_prestart" mumbled_prestart() { if ! checkyesno frotz_enable && \ - ! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&1; then - force_depend frotz || return 1<co id="rcng-hookup-force"/> + ! /etc/rc.d/frotz forcestatus 1>/dev/null 2>&1; then + force_depend frotz || return 1<co xml:id="rcng-hookup-force"/> fi return 0 } @@ -1067,7 +1059,7 @@ run_rc_command "$1"</programlisting> <quote>placeholder</quote> scripts used to ensure that certain groups of operations are performed before others. These are denoted by - <filename><replaceable>UPPERCASE</replaceable></filename> + <filename>UPPERCASE</filename> names. Their list and purposes can be found in &man.rc.8;.</para> @@ -1080,13 +1072,12 @@ run_rc_command "$1"</programlisting> will not do that either. Consequently, the application started by our script should be able to cope with any required services being unavailable. In certain cases, - we can help it as discussed <link - linkend="forcedep">below.</link></para> + we can help it as discussed <link linkend="forcedep">below.</link></para> </note> </callout> <callout arearefs="rcng-hookup-keyword"> - <para><anchor id="keywords"/>As we remember from the above text, + <para><anchor xml:id="keywords"/>As we remember from the above text, &man.rcorder.8; keywords can be used to select or leave out some scripts. Namely any &man.rcorder.8; consumer can specify through <option>-k</option> and <option>-s</option> @@ -1173,7 +1164,7 @@ run_rc_command "$1"</programlisting> </callout> <callout arearefs="rcng-hookup-force"> - <para><anchor id="forcedep"/>To begin with, + <para><anchor xml:id="forcedep"/>To begin with, <function>force_depend</function> should be used with much care. It is generally better to revise the hierarchy of configuration variables for your <filename>rc.d</filename> @@ -1200,7 +1191,7 @@ run_rc_command "$1"</programlisting> </calloutlist> </sect1> - <sect1 id="rcng-args"> + <sect1 xml:id="rcng-args"> <title>Giving more flexibility to an rc.d script</title> <para>When invoked during startup or shutdown, an @@ -1261,7 +1252,7 @@ extra_commands="kiss" dummy_start() { - if [ $# -gt 0 ]; then<co id="rcng-args-start"/> + if [ $# -gt 0 ]; then<co xml:id="rcng-args-start"/> echo "Greeting message: $*" else echo "Nothing started." @@ -1271,7 +1262,7 @@ dummy_start() dummy_kiss() { echo -n "A ghost gives you a kiss" - if [ $# -gt 0 ]; then<co id="rcng-args-kiss"/> + if [ $# -gt 0 ]; then<co xml:id="rcng-args-kiss"/> echo -n " and whispers: $*" fi case "$*" in @@ -1285,7 +1276,7 @@ dummy_kiss() } load_rc_config $name -run_rc_command "$@"<co id="rcng-args-all"/></programlisting> +run_rc_command "$@"<co xml:id="rcng-args-all"/></programlisting> </informalexample> <para>What essential changes can we notice in the script?</para> @@ -1347,18 +1338,17 @@ A ghost gives you a kiss and whispers: Once I was Etaoin Shrdlu...</screen> </calloutlist> </sect1> - <sect1 id="rcng-furthur"> + <sect1 xml:id="rcng-furthur"> <title>Further reading</title> - <para><anchor id="lukem"/><ulink - url="http://www.mewburn.net/luke/papers/rc.d.pdf">The original - article by Luke Mewburn</ulink> offers a general overview of + <para><anchor xml:id="lukem"/><link xlink:href="http://www.mewburn.net/luke/papers/rc.d.pdf">The original + article by Luke Mewburn</link> offers a general overview of <filename>rc.d</filename> and detailed rationale for its design decisions. It provides insight on the whole <filename>rc.d</filename> framework and its place in a modern BSD operating system.</para> - <para><anchor id="manpages"/>The manual pages &man.rc.8;, + <para><anchor xml:id="manpages"/>The manual pages &man.rc.8;, &man.rc.subr.8;, and &man.rcorder.8; document the <filename>rc.d</filename> components in great detail. You cannot fully use the <filename>rc.d</filename> power without diff --git a/en_US.ISO8859-1/articles/relaydelay/article.xml b/en_US.ISO8859-1/articles/relaydelay/article.xml index 26cfe3903b..b2e63391f4 100644 --- a/en_US.ISO8859-1/articles/relaydelay/article.xml +++ b/en_US.ISO8859-1/articles/relaydelay/article.xml @@ -1,22 +1,16 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Using Greylist with &os;</title> + -<article lang='en'> - <articleinfo> - <title>Using Greylist with &os;</title> - - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <affiliation> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><affiliation> <address><email>trhodes@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2004</year> @@ -53,14 +47,14 @@ comes into the server. From my personal experience, this really does cut out 90% of the spam.</para> </abstract> - </articleinfo> + </info> <sect1> <title>Basic Configuration</title> <para>We need to install the threaded <command>perl</command>. - Install <filename role="package">lang/perl5.8</filename> - with the <makevar>USE_THREADS=yes</makevar> variable + Install <package>lang/perl5.8</package> + with the <varname>USE_THREADS=yes</varname> variable set. The current version of <command>perl</command> may need to be removed first; errors will be reported by the install process if this is necessary.</para> @@ -68,7 +62,7 @@ <note> <para>This will require all ports which require <command>perl</command> to be rebuilt and reinstalled; - <filename role="package">ports-mgmt/portupgrade</filename> + <package>ports-mgmt/portupgrade</package> is perfect for this. At least it will point out which ports have been removed and which will need to be reinstalled.</para> @@ -77,23 +71,23 @@ <para>Now for the database server; <application>MySQL</application> is perfect for this sort of work. Install the - <filename role="package">databases/mysql40-server</filename> + <package>databases/mysql40-server</package> along with - <filename role="package">databases/p5-DBD-mysql40</filename>. + <package>databases/p5-DBD-mysql40</package>. The previous port should imply the installation of - <filename role="package">databases/p5-DBI-137</filename> + <package>databases/p5-DBI-137</package> so that knocks off another step.</para> <para>Install the <command>perl</command> based portable - server plugin, <filename role="package">net/p5-Net-Daemon</filename> + server plugin, <package>net/p5-Net-Daemon</package> port. Most of these port installations should have been straight forward. The next step will be more involved.</para> <para>Now install the - <filename role="package">mail/p5-Sendmail-Milter</filename> + <package>mail/p5-Sendmail-Milter</package> port. As of this writing the <filename>Makefile</filename> - contains a line beginning with <makevar>BROKEN</makevar>, + contains a line beginning with <varname>BROKEN</varname>, just remove it or comment it out. It is only marked this way because &os; neither has nor installs a threaded <command>perl</command> package by default. Once that @@ -143,7 +137,7 @@ is beyond the scope of this document.</para> <para>Change the working directory to the - <filename class="directory">relaydelay-0.04</filename> + <filename>relaydelay-0.04</filename> directory:</para> <screen>&prompt.root; <userinput>cd relaydelay-0.04</userinput></screen> @@ -166,7 +160,7 @@ <para>If everything worked correctly a new file, <filename>relaydelay.log</filename>, should exist in - <filename class="directory">/var/log</filename>. It should + <filename>/var/log</filename>. It should contain something similar to the following text:</para> <programlisting>Loaded Config File: /etc/mail/relaydelay.conf @@ -188,13 +182,13 @@ Starting Sendmail::Milter 0.18 engine.</programlisting> <para>Rebuild and reinstall the files in the <filename>/etc/mail</filename> directory and restart <command>sendmail</command>. A quick <command>make</command> - <maketarget>restart</maketarget> should do the trick.</para> + <buildtarget>restart</buildtarget> should do the trick.</para> <para>Obtain the <command>perl</command> script located at - <ulink url="http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html"> - http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html</ulink> + <link xlink:href="http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html"> + http://lists.puremagic.com/pipermail/greylist-users/2003-November/000327.html</link> and save it in the - <filename class="directory">relaydelay-0.04</filename> + <filename>relaydelay-0.04</filename> directory. In the following examples this script is referred to as <filename>addlist.pl</filename>.</para> diff --git a/en_US.ISO8859-1/articles/releng-packages/article.xml b/en_US.ISO8859-1/articles/releng-packages/article.xml index ff665828cd..2a22695d71 100644 --- a/en_US.ISO8859-1/articles/releng-packages/article.xml +++ b/en_US.ISO8859-1/articles/releng-packages/article.xml @@ -1,22 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <title>FreeBSD Release Engineering for Third Party Software +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + + <info><title>FreeBSD Release Engineering for Third Party Software Packages</title> - <articleinfo> <authorgroup> - <author> - <firstname>Steve</firstname> - <surname>Price</surname> - <affiliation> + <author><personname><firstname>Steve</firstname><surname>Price</surname></personname><affiliation> <address><email>steve@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.xfree86; @@ -39,7 +34,7 @@ consistent.</para> </abstract> - </articleinfo> + </info> <!-- Introduction @@ -51,11 +46,11 @@ </sect1> --> - <sect1 id="portbuild"> + <sect1 xml:id="portbuild"> <title>Building packages from the Ports Collection</title> - <para>The <ulink url="http://www.FreeBSD.org/ports">FreeBSD Ports - collection</ulink> is a collection of over &os.numports; + <para>The <link xlink:href="http://www.FreeBSD.org/ports">FreeBSD Ports + collection</link> is a collection of over &os.numports; third-party software packages available for FreeBSD. The &a.portmgr; is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany a given FreeBSD diff --git a/en_US.ISO8859-1/articles/releng/article.xml b/en_US.ISO8859-1/articles/releng/article.xml index 58d04fef88..119185d138 100644 --- a/en_US.ISO8859-1/articles/releng/article.xml +++ b/en_US.ISO8859-1/articles/releng/article.xml @@ -1,41 +1,33 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ -<!ENTITY art.re.pkgs '<ulink url="&url.articles.releng-packages;/article.html">The Release Engineering of Third Party Packages</ulink>'> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ +<!ENTITY art.re.pkgs '<link xmlns="http://docbook.org/ns/docbook" xlink:href="{{{url.articles.releng-packages}}}/article.html">The Release Engineering of Third Party Packages</link>'> ]> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + + <info><title>&os; Release Engineering</title> -<article lang='en'> - <title>&os; Release Engineering</title> - <articleinfo> - - <!-- This paper was presented at BSDCon Europe in Brighton, UK on - November 11, 2001. --> - <!-- The content in this paper was updated in March 2013 to - reflect the current FreeBSD Release process. --> + + <confgroup> <confdates>November 2001</confdates> <conftitle>BSDCon Europe</conftitle> </confgroup> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <authorblurb> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><personblurb> <para>I've been involved in the development of &os; based products since 1997 at Walnut Creek CDROM, BSDi, and now Wind River Systems. &os; 4.4 was the first official release of &os; that I played a significant part in.</para> - </authorblurb> - <affiliation> + </personblurb><affiliation> <address><email>murray@FreeBSD.org</email> - <otheraddr><ulink url="http://www.FreeBSD.org/~murray/"></ulink></otheraddr> + <otheraddr xlink:href="http://www.FreeBSD.org/~murray/">http://www.FreeBSD.org/~murray/</otheraddr> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.cvsup; &tm-attrib.intel; @@ -64,10 +56,10 @@ productization.</para> </abstract> - </articleinfo> + </info> <!-- Introduction --> -<sect1 id="introduction"> +<sect1 xml:id="introduction"> <title>Introduction</title> <para>The development of &os; is a very open process. &os; is @@ -76,7 +68,7 @@ Subversion <footnote> <simpara> - Subversion, <ulink url="http://subversion.apache.org"></ulink> + Subversion, <uri xlink:href="http://subversion.apache.org">http://subversion.apache.org</uri> </simpara> </footnote> access to the general public so that @@ -88,22 +80,22 @@ access to the main repository was opened up to everyone on the Internet. Therefore only a <quote>select</quote> group of nearly 300 people are given write access to the Subversion repository. These - <ulink url="&url.articles.contributors;/article.html#staff-committers">committers</ulink> + <link xlink:href="&url.articles.contributors;/article.html#staff-committers">committers</link> <footnote> <simpara> - <ulink url="&url.articles.contributors;/article.html#staff-committers">FreeBSD committers</ulink> + <link xlink:href="&url.articles.contributors;/article.html#staff-committers">FreeBSD committers</link> </simpara> </footnote> are usually the people who do the bulk of &os; development. An elected - <ulink url="&url.base;/administration.html#t-core">Core Team</ulink> + <link xlink:href="&url.base;/administration.html#t-core">Core Team</link> <footnote> <simpara> - <ulink url="&url.base;/administration.html#t-core">&os; Core Team</ulink> + <link xlink:href="&url.base;/administration.html#t-core">&os; Core Team</link> </simpara> </footnote> of developers provide some level of direction over the project.</para> - <para>The rapid pace of <systemitem class="osname">&os;</systemitem> + <para>The rapid pace of <systemitem>&os;</systemitem> development makes the main development branch unsuitable for the everyday use by the general public. In particular, stabilizing efforts are required for polishing the development system into a @@ -137,15 +129,14 @@ <para>In the interim period between releases, weekly snapshots are built automatically by the &os; Project build machines and made - available for download from <systemitem - class="resource">ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/</systemitem>. + available for download from <systemitem>ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/</systemitem>. The widespread availability of binary release snapshots, and the tendency of our user community to keep up with -STABLE development with Subversion and <quote><command>make</command> - <maketarget>buildworld</maketarget></quote> + <buildtarget>buildworld</buildtarget></quote> <footnote> <simpara> - <ulink url="&url.books.handbook;/makeworld.html">Rebuilding "world"</ulink> + <link xlink:href="&url.books.handbook;/makeworld.html">Rebuilding "world"</link> </simpara> </footnote> helps to keep @@ -158,8 +149,7 @@ <application>VirtualBox</application>, <application>qemu</application>, or other popular emulation software. The virtual machine images can be downloaded from - <systemitem - class="resource">ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/VM-IMAGES/</systemitem>.</para> + <systemitem>ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/VM-IMAGES/</systemitem>.</para> <para>The virtual machine images are approximately 150MB &man.xz.1; compressed, and contain a 10GB sparse filesystem when attached to @@ -167,16 +157,15 @@ <para>Bug reports and feature requests are continuously submitted by users throughout the release cycle. Problems reports are entered into our - <application class="software">GNATS</application> database + <application>GNATS</application> database <footnote> <simpara> GNATS: The GNU Bug Tracking System - <ulink url="http://www.gnu.org/software/gnats"></ulink> + <uri xlink:href="http://www.gnu.org/software/gnats">http://www.gnu.org/software/gnats</uri> </simpara> </footnote> through email, the &man.send-pr.1; application, or via the web - interface provided at <ulink - url="http://www.FreeBSD.org/send-pr.html"></ulink>.</para> + interface provided at <uri xlink:href="http://www.FreeBSD.org/send-pr.html">http://www.FreeBSD.org/send-pr.html</uri>.</para> <para>To service our most conservative users, individual release branches were introduced with &os; 4.3. @@ -239,7 +228,7 @@ </sect1> <!-- Release Process --> -<sect1 id="release-proc"> +<sect1 xml:id="release-proc"> <title>Release Process</title> <para>New releases of &os; are released from the -STABLE branch @@ -330,7 +319,7 @@ widespread testing and all major issues have been resolved, the final release <quote>polishing</quote> can begin.</para> - <sect3 id="rel-branch"> + <sect3 xml:id="rel-branch"> <title>Creating the Release Branch</title> <note> @@ -340,10 +329,10 @@ </note> <para>The layout of &os; branches in Subversion is - described in the <ulink url="&url.articles.committers-guide;/subversion-primer.html#subversion-primer-base-layout">Committer's Guide</ulink>. + described in the <link xlink:href="&url.articles.committers-guide;/subversion-primer.html#subversion-primer-base-layout">Committer's Guide</link>. The first step in creating a branch is to identify the revision of the - <literal>stable/<replaceable>X</replaceable></literal> sources + <literal>stable/X</literal> sources that you want to branch <emphasis>from</emphasis>.</para> <screen>&prompt.root; <userinput>svn log -v $FSVN/stable/9</userinput></screen> @@ -359,9 +348,8 @@ <note> <para>Creating the <literal>releng</literal> branch and - <literal>release</literal> tags is done by the <ulink - url="&url.base;/administration.html#t-re">Release - Engineering Team</ulink>. + <literal>release</literal> tags is done by the <link xlink:href="&url.base;/administration.html#t-re">Release + Engineering Team</link>. </para> </note> @@ -446,7 +434,7 @@ </mediaobject> </sect3> - <sect3 id="versionbump"> + <sect3 xml:id="versionbump"> <title>Bumping up the Version Number</title> <para>Before the final release can be tagged, built, and @@ -548,7 +536,7 @@ <footnote> <simpara> &os; Ports Collection - <ulink url="http://www.FreeBSD.org/ports"></ulink> + <uri xlink:href="http://www.FreeBSD.org/ports">http://www.FreeBSD.org/ports</uri> </simpara> </footnote> This information is currently kept in @@ -561,7 +549,7 @@ <itemizedlist> <listitem> - <para><filename>share/images/articles/releng/branches-releng<replaceable>X</replaceable>.pic</filename></para> + <para><filename>share/images/articles/releng/branches-relengX.pic</filename></para> </listitem> <listitem> @@ -621,15 +609,15 @@ </sect1> <!-- Release Building --> -<sect1 id="release-build"> +<sect1 xml:id="release-build"> <title>Release Building</title> <para>&os; <quote>releases</quote> can be built by anyone with a fast machine and access to a source repository. (That should be everyone, since we offer Subversion access ! See the - <ulink url="&url.books.handbook;/svn.html">Subversion section - in the Handbook</ulink> for + <link xlink:href="&url.books.handbook;/svn.html">Subversion section + in the Handbook</link> for details.) The <emphasis>only</emphasis> special requirement is that the &man.md.4; device must be available. If the device is not loaded into your kernel, then the kernel module @@ -666,7 +654,7 @@ <listitem> <para>Creation of a sanitized system environment in a separate directory hierarchy with <quote><command>make - <literal>installworld</literal></command></quote>. + installworld</command></quote>. </para> </listitem> @@ -745,8 +733,8 @@ <sect2> <title>Contributed Software (<quote>ports</quote>)</title> - <para>The <ulink url="http://www.FreeBSD.org/ports">&os; Ports - collection</ulink> is a collection of over &os.numports; + <para>The <link xlink:href="http://www.FreeBSD.org/ports">&os; Ports + collection</link> is a collection of over &os.numports; third-party software packages available for &os;. The &a.portmgr; is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany official &os; @@ -775,7 +763,7 @@ <emphasis>manifest</emphasis> can be created with a simple command:</para> - <screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/^\.\///' | sort > filename.txt</userinput></screen> + <screen>/stage/cdrom&prompt.root; <userinput>find . -type f | sed -e 's/^\.\///' | sort > filename.txt</userinput></screen> <para>The specific requirements of each CD are outlined below.</para> @@ -849,22 +837,22 @@ </sect1> <!-- Distribution --> -<sect1 id="distribution"> +<sect1 xml:id="distribution"> <title>Distribution</title> - <sect2 id="dist-ftp"> + <sect2 xml:id="dist-ftp"> <title>FTP Sites</title> <para>When the release has been thoroughly tested and packaged for distribution, the master FTP site must be updated. The official &os; public FTP sites are all mirrors of a master server that is open only to other FTP sites. This site is known as - <hostid>ftp-master</hostid>. When the release is ready, the - following files must be modified on <hostid>ftp-master</hostid>:</para> + <systemitem>ftp-master</systemitem>. When the release is ready, the + following files must be modified on <systemitem>ftp-master</systemitem>:</para> <variablelist> <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/</filename></term> + <term><filename>/pub/FreeBSD/releases/arch/X.Y-RELEASE/</filename></term> <listitem> <para>The installable FTP directory as output from <command>make release</command>.</para> @@ -872,25 +860,25 @@ </varlistentry> <varlistentry> - <term><filename>/pub/FreeBSD/ports/<replaceable>arch</replaceable>/packages-<replaceable>X.Y</replaceable>-release/</filename></term> + <term><filename>/pub/FreeBSD/ports/arch/packages-X.Y-release/</filename></term> <listitem><para>The complete package build for this release.</para></listitem> </varlistentry> <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/tools</filename></term> + <term><filename>/pub/FreeBSD/releases/arch/X.Y-RELEASE/tools</filename></term> <listitem><para>A symlink to <filename>../../../tools</filename>.</para></listitem> </varlistentry> <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>X.Y</replaceable>-RELEASE/packages</filename></term> + <term><filename>/pub/FreeBSD/releases/arch/X.Y-RELEASE/packages</filename></term> <listitem><para>A symlink to - <filename>../../../ports/<replaceable>arch</replaceable>/packages-<replaceable>X.Y</replaceable>-release</filename>.</para></listitem> + <filename>../../../ports/arch/packages-X.Y-release</filename>.</para></listitem> </varlistentry> <varlistentry> - <term><filename>/pub/FreeBSD/releases/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>X.Y</replaceable>/<replaceable>X.Y</replaceable>-RELEASE-<replaceable>arch</replaceable>-*.iso</filename></term> + <term><filename>/pub/FreeBSD/releases/arch/ISO-IMAGES/X.Y/X.Y-RELEASE-arch-*.iso</filename></term> <listitem><para>The ISO images. The <quote>*</quote> is <filename>disc1</filename>, <filename>disc2</filename>, etc. Only if there is a <filename>disc1</filename> and there is an @@ -902,11 +890,10 @@ </variablelist> <para>For more information about the distribution mirror - architecture of the &os; FTP sites, please see the <ulink - url="&url.articles.hubs;/">Mirroring &os;</ulink> article.</para> + architecture of the &os; FTP sites, please see the <link xlink:href="&url.articles.hubs;/">Mirroring &os;</link> article.</para> <para>It may take many hours to two days after updating - <hostid>ftp-master</hostid> before a majority of the Tier-1 FTP + <systemitem>ftp-master</systemitem> before a majority of the Tier-1 FTP sites have the new software depending on whether or not a package set got loaded at the same time. It is imperative that the release engineers coordinate with the &a.mirror-announce; before announcing the general @@ -924,7 +911,7 @@ time, for example make it relative to GMT.</para> </sect2> - <sect2 id="dist-cdrom"> + <sect2 xml:id="dist-cdrom"> <title>CD-ROM Replication</title> <para>Coming soon: Tips for sending &os; ISOs to a replicator @@ -934,7 +921,7 @@ </sect1> <!-- Extensibility --> -<sect1 id="extensibility"> +<sect1 xml:id="extensibility"> <title>Extensibility</title> <para>Although &os; forms a complete operating system, there is @@ -959,7 +946,7 @@ with &intel; PXE <footnote> <simpara> - <ulink url="&url.books.handbook;/network-pxe-nfs.html"></ulink> + <uri xlink:href="&url.books.handbook;/network-pxe-nfs.html">&url.books.handbook;/network-pxe-nfs.html</uri> </simpara> </footnote> to bootstrap systems from the network. @@ -968,7 +955,7 @@ </sect1> <!-- Lessons Learned --> -<sect1 id="lessons-learned"> +<sect1 xml:id="lessons-learned"> <title>Lessons Learned from &os; 4.4</title> <para>The release engineering process for 4.4 formally began on @@ -993,7 +980,7 @@ </sect1> <!-- Future Directions --> -<sect1 id="future"> +<sect1 xml:id="future"> <title>Future Directions</title> <para>It is imperative for our release engineering activities to @@ -1042,7 +1029,7 @@ </sect1> <!-- Acknowledgements --> -<sect1 id="ackno"> +<sect1 xml:id="ackno"> <title>Acknowledgements</title> <para>I would like to thank Jordan Hubbard for giving me the @@ -1059,8 +1046,8 @@ <footnote> <simpara> Marshall Kirk McKusick, Michael J. Karels, and Keith Bostic: - <ulink url="http://docs.FreeBSD.org/44doc/papers/releng.html"> - <emphasis>The Release Engineering of 4.3BSD</emphasis></ulink> + <link xlink:href="http://docs.FreeBSD.org/44doc/papers/releng.html"> + <emphasis>The Release Engineering of 4.3BSD</emphasis></link> </simpara> </footnote> , @@ -1068,7 +1055,7 @@ <footnote> <simpara> NetBSD Developer Documentation: Release Engineering - <ulink url="http://www.NetBSD.org/developers/releng/index.html"></ulink> + <uri xlink:href="http://www.NetBSD.org/developers/releng/index.html">http://www.NetBSD.org/developers/releng/index.html</uri> </simpara> </footnote> , and John @@ -1076,7 +1063,7 @@ <footnote> <simpara> John Baldwin's &os; Release Engineering Proposal - <ulink url="http://people.FreeBSD.org/~jhb/docs/releng.txt"></ulink> + <uri xlink:href="http://people.FreeBSD.org/~jhb/docs/releng.txt">http://people.FreeBSD.org/~jhb/docs/releng.txt</uri> </simpara> </footnote> </para> diff --git a/en_US.ISO8859-1/articles/remote-install/article.xml b/en_US.ISO8859-1/articles/remote-install/article.xml index 8c520bfa30..e0e3c1280a 100644 --- a/en_US.ISO8859-1/articles/remote-install/article.xml +++ b/en_US.ISO8859-1/articles/remote-install/article.xml @@ -1,22 +1,16 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Remote Installation of the &os; Operating System without a +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Remote Installation of the &os; Operating System without a Remote Console</title> + - <author> - <firstname>Daniel</firstname> - <surname>Gerzo</surname> - <affiliation> + <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><affiliation> <address><email>danger@FreeBSD.org</email></address> - </affiliation> - <!-- 11 April 2008 --> - </author> + </affiliation></author> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -37,9 +31,9 @@ a collaboration with &a.mm.email; with valuable input provided by &a.pjd.email;.</para> </abstract> - </articleinfo> + </info> - <sect1 id="background"> + <sect1 xml:id="background"> <title>Background</title> <para>There are many server hosting providers in the world, but very @@ -58,7 +52,7 @@ RAID-1 and <application>ZFS</application> capabilities.</para> </sect1> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Introduction</title> <para>This section will summarize the purpose of this article and @@ -68,8 +62,7 @@ <procedure> <step> - <para>As we have mentioned in the <link - linkend="background">Background</link> section, many of the + <para>As we have mentioned in the <link linkend="background">Background</link> section, many of the reputable server hosting companies provide some kind of rescue system, which is booted from their <acronym>LAN</acronym> and accessible over <application>SSH</application>. They usually @@ -97,7 +90,7 @@ </step> </procedure> - <sect2 id="requirements"> + <sect2 xml:id="requirements"> <title>Requirements</title> <para>To continue successfully, you must:</para> @@ -124,7 +117,7 @@ </sect2> </sect1> - <sect1 id="preparation"> + <sect1 xml:id="preparation"> <title>Preparation - <application>mfsBSD</application></title> <para>Before &os; may be installed on the target system, it is @@ -140,8 +133,7 @@ entirely from a ramdisk. Thanks to this feature, the manipulation of hard drives will not be limited, therefore it will be possible to install a complete &os; operating system. The home page of - <application>mfsBSD</application>, at <ulink - url="http://people.freebsd.org/~mm/mfsbsd/"></ulink>, includes + <application>mfsBSD</application>, at <uri xlink:href="http://people.freebsd.org/~mm/mfsbsd/">http://people.freebsd.org/~mm/mfsbsd/</uri>, includes pointers to the latest release of the toolset.</para> <para>Please note that the internals of @@ -156,10 +148,10 @@ <application>mfsBSD</application> scripts will reside:</para> <screen>&prompt.root; <userinput>fetch http://people.freebsd.org/~mm/mfsbsd/mfsbsd-latest.tar.gz</userinput> -&prompt.root; <userinput>tar xvzf mfsbsd-<replaceable>1.0-beta1</replaceable>.tar.gz</userinput> -&prompt.root; <userinput>cd <replaceable>mfsbsd-1.0-beta1</replaceable>/</userinput></screen> +&prompt.root; <userinput>tar xvzf mfsbsd-1.0-beta1.tar.gz</userinput> +&prompt.root; <userinput>cd mfsbsd-1.0-beta1/</userinput></screen> - <sect2 id="mfsbsd-config"> + <sect2 xml:id="mfsbsd-config"> <title>Configuration of <application>mfsBSD</application></title> <para>Before booting <application>mfsBSD</application>, a few @@ -173,7 +165,7 @@ case.</para> <para>Another important thing to set is the - <username>root</username> password. This can be done by editing + <systemitem class="username">root</systemitem> password. This can be done by editing the <filename>conf/rootpw.conf</filename> file. Please keep in mind that the file will contain your password in the plain text, thus we do not recommend to use real password here. @@ -221,7 +213,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> </sect3> </sect2> - <sect2 id="mfsbsd-build"> + <sect2 xml:id="mfsbsd-build"> <title>Building an <application>mfsBSD</application> image</title> <para>The process of building an <application>mfsBSD</application> @@ -229,26 +221,24 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> <para>The first step is to mount the &os; installation <acronym>CD</acronym>, or the installation - <acronym>ISO</acronym> image to <filename - class="directory">/cdrom</filename>. For the sake of example, + <acronym>ISO</acronym> image to <filename>/cdrom</filename>. For the sake of example, in this article we will assume that you have downloaded the &os; 7.0-RELEASE <acronym>ISO</acronym>. Mounting this ISO image to - the <filename class="directory">/cdrom</filename> directory is + the <filename>/cdrom</filename> directory is easy with the &man.mdconfig.8; utility:</para> - <screen>&prompt.root; <userinput>mdconfig -a -t vnode -u 10 -f <replaceable>7.0-RELEASE-amd64-disc1.iso</replaceable></userinput> + <screen>&prompt.root; <userinput>mdconfig -a -t vnode -u 10 -f 7.0-RELEASE-amd64-disc1.iso</userinput> &prompt.root; <userinput>mount_cd9660 /dev/md10 /cdrom</userinput></screen> <para>Next, build the bootable <application>mfsBSD</application> image:</para> - <screen>&prompt.root; <userinput>make BASE=/cdrom/<replaceable>7.0-RELEASE</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make BASE=/cdrom/7.0-RELEASE</userinput></screen> <note> <para>The above <command>make</command> command has to be run from the top level of the <application>mfsBSD</application> - directory tree, i.e. <filename - class="directory">~/mfsbsd-1.0-beta1/</filename>.</para> + directory tree, i.e. <filename>~/mfsbsd-1.0-beta1/</filename>.</para> </note> </sect2> @@ -266,7 +256,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> <para>To boot <application>mfsBSD</application> image properly, it must be placed on the first (bootable) device of the given machine. This may be accomplished using this example providing - that <devicename>sda</devicename> is the first bootable disk + that <filename>sda</filename> is the first bootable disk device:</para> <screen>&prompt.root; <userinput>dd if=/root/disk.img of=/dev/sda bs=1m</userinput></screen> @@ -276,11 +266,11 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> be rebooted. Watch for the machine to boot up properly with the &man.ping.8; tool. Once it has came back on-line, it should be possible to access it over &man.ssh.1; as user - <username>root</username> with the configured password.</para> + <systemitem class="username">root</systemitem> with the configured password.</para> </sect2> </sect1> - <sect1 id="installation"> + <sect1 xml:id="installation"> <title>Installation of The &os; Operating System</title> <para>The <application>mfsBSD</application> has been successfully @@ -304,7 +294,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> <para>At the start, mark all system disks as empty. Repeat the following command for each hard drive:</para> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/<replaceable>ad0</replaceable> count=2</userinput></screen> + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/ad0 count=2</userinput></screen> <para>Next, create slices and label them with your preferred tool. While it is considered easier to use @@ -312,15 +302,12 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> probably less buggy method will be to use standard text-based &unix; tools, such as &man.fdisk.8; and &man.bsdlabel.8;, which will also be covered in this section. The former option is well - documented in the <ulink - url="&url.books.handbook;/install-steps.html">Installing &os;</ulink> + documented in the <link xlink:href="&url.books.handbook;/install-steps.html">Installing &os;</link> chapter of the &os; Handbook. As it was mentioned in the introduction, this article will present how to set up a system with RAID-1 and <application>ZFS</application> capabilities. Our set up will consist of a small &man.gmirror.8; mirrored - <filename class="directory">/</filename> (root), <filename - class="directory">/usr</filename> and <filename - class="directory">/var</filename> file systems, and the rest of + <filename>/</filename> (root), <filename>/usr</filename> and <filename>/var</filename> file systems, and the rest of the disk space will be allocated for a &man.zpool.8; mirrored <application>ZFS</application> file system. Please note, that the <application>ZFS</application> file system will be @@ -332,17 +319,17 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> create a <application>UFS2</application> file system in each mirrored partition:</para> - <screen>&prompt.root; <userinput>fdisk -BI /dev/ad0</userinput> <co id="fdisk"/> + <screen>&prompt.root; <userinput>fdisk -BI /dev/ad0</userinput> <co xml:id="fdisk"/> &prompt.root; <userinput>fdisk -BI /dev/ad1</userinput> -&prompt.root; <userinput>bsdlabel -wB /dev/ad0s1</userinput> <co id="bsdlabel-writing"/> +&prompt.root; <userinput>bsdlabel -wB /dev/ad0s1</userinput> <co xml:id="bsdlabel-writing"/> &prompt.root; <userinput>bsdlabel -wB /dev/ad1s1</userinput> -&prompt.root; <userinput>bsdlabel -e /dev/ad0s1</userinput> <co id="bsdlabel-editing"/> -&prompt.root; <userinput>bsdlabel /dev/ad0s1 > /tmp/bsdlabel.txt && bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt</userinput> <co id="bsdlabel-restore"/> -&prompt.root; <userinput>gmirror label root /dev/ad[01]s1a</userinput> <co id="gmirror1"/> +&prompt.root; <userinput>bsdlabel -e /dev/ad0s1</userinput> <co xml:id="bsdlabel-editing"/> +&prompt.root; <userinput>bsdlabel /dev/ad0s1 > /tmp/bsdlabel.txt && bsdlabel -R /dev/ad1s1 /tmp/bsdlabel.txt</userinput> <co xml:id="bsdlabel-restore"/> +&prompt.root; <userinput>gmirror label root /dev/ad[01]s1a</userinput> <co xml:id="gmirror1"/> &prompt.root; <userinput>gmirror label var /dev/ad[01]s1d</userinput> &prompt.root; <userinput>gmirror label usr /dev/ad[01]s1e</userinput> -&prompt.root; <userinput>gmirror label -F swap /dev/ad[01]s1b</userinput> <co id="gmirror2"/> -&prompt.root; <userinput>newfs /dev/mirror/root</userinput> <co id="newfs"/> +&prompt.root; <userinput>gmirror label -F swap /dev/ad[01]s1b</userinput> <co xml:id="gmirror2"/> +&prompt.root; <userinput>newfs /dev/mirror/root</userinput> <co xml:id="newfs"/> &prompt.root; <userinput>newfs /dev/mirror/var</userinput> &prompt.root; <userinput>newfs /dev/mirror/usr</userinput></screen> @@ -363,12 +350,10 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> <para>Now, manually edit the label of the given disk. Refer to the &man.bsdlabel.8; manual page in order to find out how to create partitions. Create partitions - <literal>a</literal> for <filename - class="directory">/</filename> (root) file system, + <literal>a</literal> for <filename>/</filename> (root) file system, <literal>b</literal> for swap, <literal>d</literal> for - <filename class="directory">/var</filename>, - <literal>e</literal> for <filename - class="directory">/usr</filename> and finally + <filename>/var</filename>, + <literal>e</literal> for <filename>/usr</filename> and finally <literal>f</literal> which will later be used for <application>ZFS</application>.</para> </callout> @@ -417,8 +402,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> menu. Select <guimenuitem>Options</guimenuitem> and press <keycap>Enter</keycap>. With the help of arrow keys, move the cursor on the <literal>Install Root</literal> item, press - <keycap>Space</keycap> and change it to <filename - class="directory">/mnt</filename>. Press + <keycap>Space</keycap> and change it to <filename>/mnt</filename>. Press <keycap>Enter</keycap> to submit your changes and exit the <guimenuitem>Options</guimenuitem> menu by pressing <keycap>q</keycap>.</para> @@ -475,7 +459,7 @@ ifconfig_re0="inet 192.168.0.2 netmask 255.255.255.0"</programlisting> <itemizedlist> <listitem> <para>Copy the <literal>GENERIC</literal> kernel to the - <filename class="directory">/boot/kernel</filename> + <filename>/boot/kernel</filename> directory:</para> <screen>&prompt.root; <userinput>cp -Rp /boot/GENERIC/* /boot/kernel</userinput></screen> @@ -512,13 +496,13 @@ zfs_load="YES"</programlisting> <application>ZFS</application> available on the next boot:</para> - <screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' >> /etc/rc.conf </userinput></screen> + <screen>&prompt.root; <userinput>echo 'zfs_enable="YES"' >> /etc/rc.conf </userinput></screen> </listitem> <listitem> <para>Add additional users to the system using the &man.adduser.8; tool. Do not forget to add a user to the - <groupname>wheel</groupname> group so you may obtain root + <systemitem class="groupname">wheel</systemitem> group so you may obtain root access after the reboot.</para> </listitem> @@ -532,7 +516,7 @@ zfs_load="YES"</programlisting> </sect2> </sect1> - <sect1 id="zfs"> + <sect1 xml:id="zfs"> <title>ZFS</title> <para>If your system survived the reboot, it should now be possible @@ -556,8 +540,7 @@ zfs_load="YES"</programlisting> &prompt.root; <userinput>zfs set mountpoint=/usr/src tank/src</userinput></screen> <para>That's all. If you are interested in more details about - <application>ZFS</application> on &os;, please refer to the <ulink - url="http://wiki.freebsd.org/ZFS">ZFS</ulink> section of the &os; + <application>ZFS</application> on &os;, please refer to the <link xlink:href="http://wiki.freebsd.org/ZFS">ZFS</link> section of the &os; Wiki.</para> </sect1> </article> diff --git a/en_US.ISO8859-1/articles/serial-uart/article.xml b/en_US.ISO8859-1/articles/serial-uart/article.xml index 81686f5758..3e590bbcb0 100644 --- a/en_US.ISO8859-1/articles/serial-uart/article.xml +++ b/en_US.ISO8859-1/articles/serial-uart/article.xml @@ -1,23 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - -<article lang='en'> - <articleinfo> - <title>Serial and UART Tutorial</title> +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Serial and UART Tutorial</title> + <authorgroup> - <author> - <firstname>Frank</firstname> - <surname>Durda</surname> - - <affiliation> + <author><personname><firstname>Frank</firstname><surname>Durda</surname></personname><affiliation> <address><email>uhclem@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.microsoft; &tm-attrib.general; @@ -30,9 +24,9 @@ <abstract> <para>This article talks about using serial hardware with FreeBSD.</para> </abstract> - </articleinfo> + </info> - <sect1 id="uart"> + <sect1 xml:id="uart"> <title>The UART: What it is and how it works</title> <para><emphasis>Copyright © 1996 &a.uhclem.email;, All Rights @@ -1151,16 +1145,16 @@ <para>The 8250/16450/16550 UART occupies eight contiguous I/O port addresses. In the IBM PC, there are two defined locations for these eight ports and they are known - collectively as <devicename>COM1</devicename> and <devicename>COM2</devicename>. The makers of PC-clones and - add-on cards have created two additional areas known as <devicename>COM3</devicename> - and <devicename>COM4</devicename>, but these extra COM ports conflict with other + collectively as <filename>COM1</filename> and <filename>COM2</filename>. The makers of PC-clones and + add-on cards have created two additional areas known as <filename>COM3</filename> + and <filename>COM4</filename>, but these extra COM ports conflict with other hardware on some systems. The most common conflict is with video adapters that provide IBM 8514 emulation.</para> - <para><devicename>COM1</devicename> is located from 0x3f8 to 0x3ff and normally uses - IRQ 4. <devicename>COM2</devicename> is located from 0x2f8 to 0x2ff and normally uses - IRQ 3. <devicename>COM3</devicename> is located from 0x3e8 to 0x3ef and has no - standardized IRQ. <devicename>COM4</devicename> is located from 0x2e8 to 0x2ef and has + <para><filename>COM1</filename> is located from 0x3f8 to 0x3ff and normally uses + IRQ 4. <filename>COM2</filename> is located from 0x2f8 to 0x2ff and normally uses + IRQ 3. <filename>COM3</filename> is located from 0x3e8 to 0x3ef and has no + standardized IRQ. <filename>COM4</filename> is located from 0x2e8 to 0x2ef and has no standardized IRQ.</para> <para>A description of the I/O ports of the 8250/16450/16550 @@ -1969,10 +1963,10 @@ </sect2> </sect1> - <sect1 id="sio"> - <title>Configuring the <devicename>sio</devicename> driver</title> + <sect1 xml:id="sio"> + <title>Configuring the <filename>sio</filename> driver</title> - <para>The <devicename>sio</devicename> driver provides support + <para>The <filename>sio</filename> driver provides support for NS8250-, NS16450-, NS16550 and NS16550A-based EIA RS-232C (CCITT V.24) communications interfaces. Several multiport cards are supported as well. See the &man.sio.4; manual page @@ -2039,9 +2033,8 @@ device sio11 at isa? port 0x138 flags 0xb05 irq 9</programlisting> either.</para> <para>If you do not already have a custom kernel - configuration file set up, refer to <ulink - url="&url.books.handbook;/kernelconfig.html">Kernel - Configuration</ulink> chapter of the FreeBSD Handbook for + configuration file set up, refer to <link xlink:href="&url.books.handbook;/kernelconfig.html">Kernel + Configuration</link> chapter of the FreeBSD Handbook for general procedures. The following are the specifics for the Boca 16 board and assume you are using the kernel name MYKERNEL and editing with vi.</para> @@ -2057,7 +2050,7 @@ device sio11 at isa? port 0x138 flags 0xb05 irq 9</programlisting> <step> <para>Where the current <literal>device - sio<replaceable>n</replaceable></literal> lines are, you + sion</literal> lines are, you will need to add 16 more devices. The following example is for a Boca Board with an interrupt of 3, and a base IO address 100h. The IO address for @@ -2147,7 +2140,7 @@ sio16: type 16550A (multiport master)</screen> support compiled in.</para> <para>If you do need to create the <filename>/dev</filename> - entries, run the following as <username>root</username>:</para> + entries, run the following as <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>cd /dev</userinput> &prompt.root; <userinput>./MAKEDEV tty1</userinput> @@ -2187,14 +2180,14 @@ sio16: type 16550A (multiport master)</screen> <para>Usually the only option to support these kind of boards is to use a distinct IRQ for each port. For example, if - your CPU board has an on-board <devicename>COM1</devicename> - port (aka <devicename>sio0</devicename>–I/O address + your CPU board has an on-board <filename>COM1</filename> + port (aka <filename>sio0</filename>–I/O address 0x3F8 and IRQ 4) and you have an extension board with two UARTs, you will commonly need to configure them as - <devicename>COM2</devicename> (aka - <devicename>sio1</devicename>–I/O address 0x2F8 and + <filename>COM2</filename> (aka + <filename>sio1</filename>–I/O address 0x2F8 and IRQ 3), and the third port (aka - <devicename>sio2</devicename>) as I/O 0x3E8 and IRQ 5. + <filename>sio2</filename>) as I/O 0x3E8 and IRQ 5. Obviously this is a waste of IRQ resources, as it should be basically possible to run both extension board ports using a single IRQ with the <literal>COM_MULTIPORT</literal> @@ -2237,7 +2230,7 @@ IRQ 2 3 4 5</programlisting> above:</para> <programlisting> Diode - +---------->|-------+ + +---------->|-------+ / | o * o o | 1 kOhm Port A +----|######|-------+ @@ -2245,7 +2238,7 @@ Port A +----|######|-------+ Port B `-------------------+ ==+== o * o o | Ground \ | - +--------->|-------+ + +--------->|-------+ IRQ 2 3 4 5 Diode</programlisting> <para>The cathodes of the diodes are connected to a common @@ -2264,11 +2257,11 @@ device sio1 at isa? port "IO_COM2" flags 0x205 device sio2 at isa? port "IO_COM3" flags 0x205 irq 3</programlisting> <para>Note that the <literal>flags</literal> setting for - <devicename>sio1</devicename> and - <devicename>sio2</devicename> is truly essential; refer to + <filename>sio1</filename> and + <filename>sio2</filename> is truly essential; refer to &man.sio.4; for details. (Generally, the <literal>2</literal> in the "flags" attribute refers to - <devicename>sio</devicename>2 which holds the IRQ, and you + <filename>sio</filename>2 which holds the IRQ, and you surely want a <literal>5</literal> low nibble.) With kernel verbose mode turned on this should yield something similar to this:</para> @@ -2294,20 +2287,20 @@ sio2: type 16550A (multiport master)</screen> </sect2> </sect1> - <sect1 id="cy"> - <title>Configuring the <devicename>cy</devicename> driver</title> + <sect1 xml:id="cy"> + <title>Configuring the <filename>cy</filename> driver</title> <para><emphasis>Contributed by Alex Nash. 6 June 1996.</emphasis></para> <para>The Cyclades multiport cards are based on the - <devicename>cy</devicename> driver instead of the usual - <devicename>sio</devicename> driver used by other multiport + <filename>cy</filename> driver instead of the usual + <filename>sio</filename> driver used by other multiport cards. Configuration is a simple matter of:</para> <procedure> <step> - <para>Add the <devicename>cy</devicename> device to your + <para>Add the <filename>cy</filename> device to your kernel configuration (note that your irq and iomem settings may differ).</para> @@ -2350,13 +2343,13 @@ ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting> </sect1> <sect1> - <title>Configuring the <devicename>si</devicename> driver</title> + <title>Configuring the <filename>si</filename> driver</title> <para><emphasis>Contributed by &a.nsayer.email;. 25 March 1998.</emphasis></para> <para>The Specialix SI/XIO and SX multiport cards use the - <devicename>si</devicename> driver. A single machine can have + <filename>si</filename> driver. A single machine can have up to 4 host cards. The following host cards are supported:</para> @@ -2420,7 +2413,7 @@ ttyc7 "/usr/libexec/getty std.38400" unknown on insecure</programlisting> you have and type:</para> <screen>&prompt.root; <userinput>cd /dev</userinput> -&prompt.root; <userinput>./MAKEDEV ttyA<replaceable>nn</replaceable> cuaA<replaceable>nn</replaceable></userinput></screen> +&prompt.root; <userinput>./MAKEDEV ttyAnn cuaAnn</userinput></screen> <para>(where <replaceable>nn</replaceable> is the number of ports)</para> diff --git a/en_US.ISO8859-1/articles/solid-state/article.xml b/en_US.ISO8859-1/articles/solid-state/article.xml index 1290cb19cc..b47dd45d06 100644 --- a/en_US.ISO8859-1/articles/solid-state/article.xml +++ b/en_US.ISO8859-1/articles/solid-state/article.xml @@ -1,7 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- Copyright (c) 2001 The FreeBSD Documentation Project Redistribution and use in source (SGML DocBook) and 'compiled' forms @@ -33,20 +32,14 @@ $FreeBSD$ --> - -<article lang='en'> - <articleinfo> - <title>&os; and Solid State Devices</title> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>&os; and Solid State Devices</title> + <authorgroup> - <author> - <firstname>John</firstname> - <surname>Kozubik</surname> - - <affiliation> + <author><personname><firstname>John</firstname><surname>Kozubik</surname></personname><affiliation> <address><email>john@kozubik.com</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> <copyright> @@ -55,7 +48,7 @@ <holder>The FreeBSD Documentation Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.general; </legalnotice> @@ -85,9 +78,9 @@ The article will conclude with some general strategies for small and read-only &os; environments.</para> </abstract> - </articleinfo> + </info> - <sect1 id="intro"> + <sect1 xml:id="intro"> <title>Solid State Disk Devices</title> <para>The scope of this article will be limited to solid state @@ -126,7 +119,7 @@ beyond the scope of this article.</para> </sect1> - <sect1 id="kernel"> + <sect1 xml:id="kernel"> <title>Kernel Options</title> <para>A few kernel options are of specific interest to those @@ -151,7 +144,7 @@ options MD_ROOT # md device usable as a potential root device pseudo-device md # memory disk</programlisting> </sect1> - <sect1 id="ro-fs"> + <sect1 xml:id="ro-fs"> <title>The <literal>rc</literal> Subsystem and Read-Only Filesystems</title> @@ -210,11 +203,11 @@ pseudo-device md # memory disk</programlisting> mounted read-only with <filename>/etc/fstab</filename> can be made read-write at any time by issuing the command:</para> - <screen>&prompt.root; <userinput>/sbin/mount -uw <replaceable>partition</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>/sbin/mount -uw partition</userinput></screen> <para>and can be toggled back to read-only with the command:</para> - <screen>&prompt.root; <userinput>/sbin/mount -ur <replaceable>partition</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>/sbin/mount -ur partition</userinput></screen> </sect1> <sect1> @@ -324,12 +317,12 @@ pseudo-device md # memory disk</programlisting> have the tar file and the tar contents on your disk at the same time:</para> - <screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| tar xvf -"</userinput></screen> + <screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| tar xvf -"</userinput></screen> <para>If your tarfile is gzipped, you can accomplish this as well:</para> - <screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| zcat | tar xvf -"</userinput></screen> + <screen><prompt>ftp></prompt> <userinput>get tarfile.tar "| zcat | tar xvf -"</userinput></screen> <para>After the contents of your tarred filesystem are on your flash memory filesystem, you can unmount the flash memory @@ -348,7 +341,7 @@ pseudo-device md # memory disk</programlisting> </procedure> </sect1> - <sect1 id="strategies"> + <sect1 xml:id="strategies"> <title>System Strategies for Small and Read Only Environments</title> @@ -363,12 +356,10 @@ pseudo-device md # memory disk</programlisting> <sect2> <title>cron</title> - <para>Upon boot, <filename class="directory">/var</filename> + <para>Upon boot, <filename>/var</filename> gets populated by <filename>/etc/rc.d/var</filename> using the list from <filename>/etc/mtree/BSD.var.dist</filename>, so the - <filename class="directory">cron</filename>, <filename - class="directory">cron/tabs</filename>, <filename - class="directory">at</filename>, and a few other standard + <filename>cron</filename>, <filename>cron/tabs</filename>, <filename>at</filename>, and a few other standard directories get created.</para> <para>However, this does not solve the problem of maintaining @@ -411,15 +402,14 @@ pseudo-device md # memory disk</programlisting> use the ports tree, a reminder is necessary regarding the read-only nature of your filesystems on the flash media. Since they are read-only, you will need to temporarily mount - them read-write using the mount syntax shown in <xref - linkend="ro-fs"/>. You should always remount those + them read-write using the mount syntax shown in <xref linkend="ro-fs"/>. You should always remount those filesystems read-only when you are done with any maintenance - unnecessary writes to the flash media could considerably shorten its lifespan.</para> <para>To make it possible to enter a ports directory and successfully run - <command>make</command> <maketarget>install</maketarget>, we + <command>make</command> <buildtarget>install</buildtarget>, we must create a packages directory on a non-memory filesystem that will keep track of our packages across reboots. Because it is necessary to mount your filesystems as read-write for @@ -442,7 +432,7 @@ pseudo-device md # memory disk</programlisting> <para>Now, any time that you mount your filesystems as read-write and install a package, the - <command>make</command> <maketarget>install</maketarget> will + <command>make</command> <buildtarget>install</buildtarget> will work, and package information will be written successfully to <filename>/etc/pkg</filename> (because the filesystem will, at that time, be mounted read-write) which will always be @@ -456,24 +446,20 @@ pseudo-device md # memory disk</programlisting> <note> <para>The steps in this section are only necessary if Apache is set up to write its pid or log information outside of - <filename class="directory">/var</filename>. By default, - Apache keeps its pid file in <filename - class="directory">/var/run/httpd.pid</filename> and its - log files in <filename - class="directory">/var/log</filename>.</para> + <filename>/var</filename>. By default, + Apache keeps its pid file in <filename>/var/run/httpd.pid</filename> and its + log files in <filename>/var/log</filename>.</para> </note> <para>It is now assumed that Apache keeps its log files in a - directory <filename - class="directory"><replaceable>apache_log_dir</replaceable></filename> - outside of <filename class="directory">/var</filename>. + directory <filename>apache_log_dir</filename> + outside of <filename>/var</filename>. When this directory lives on a read-only filesystem, Apache will not be able to save any log files, and may have problems working. If so, it is necessary to add a new directory to the list of directories in <filename>/etc/rc.d/var</filename> to create in <filename>/var</filename>, and to link - <filename - class="directory"><replaceable>apache_log_dir</replaceable></filename> + <filename>apache_log_dir</filename> to <filename>/var/log/apache</filename>. It is also necessary to set permissions and ownership on this new directory.</para> @@ -488,13 +474,11 @@ pseudo-device md # memory disk</programlisting> <screen>&prompt.root; <userinput>chmod 0774 /var/log/apache</userinput> &prompt.root; <userinput>chown nobody:nobody /var/log/apache</userinput></screen> - <para>Finally, remove the existing <filename - class="directory"><replaceable>apache_log_dir</replaceable></filename> + <para>Finally, remove the existing <filename>apache_log_dir</filename> directory, and replace it with a link:</para> - <screen>&prompt.root; <userinput>rm -rf <filename class="directory"><replaceable>apache_log_dir</replaceable></filename></userinput> -&prompt.root; <userinput>ln -s /var/log/apache <filename class="directory"><replaceable>apache_log_dir</replaceable></filename></userinput></screen> + <screen>&prompt.root; <userinput>rm -rf apache_log_dir</userinput> +&prompt.root; <userinput>ln -s /var/log/apache apache_log_dir</userinput></screen> </sect2> </sect1> </article> - diff --git a/en_US.ISO8859-1/articles/vm-design/article.xml b/en_US.ISO8859-1/articles/vm-design/article.xml index d68e2228ca..1dd734c928 100644 --- a/en_US.ISO8859-1/articles/vm-design/article.xml +++ b/en_US.ISO8859-1/articles/vm-design/article.xml @@ -1,29 +1,21 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- FreeBSD Documentation Project --> - -<article lang='en'> - <articleinfo> - <title>Design elements of the &os; VM system</title> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Design elements of the &os; VM system</title> + <authorgroup> - <author> - <firstname>Matthew</firstname> - - <surname>Dillon</surname> - - <affiliation> + <author><personname><firstname>Matthew</firstname><surname>Dillon</surname></personname><affiliation> <address> <email>dillon@apollo.backplane.com</email> </address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.microsoft; @@ -52,15 +44,15 @@ with peoples names, since I will invariably get it wrong.</para> </abstract> - <legalnotice id="legalnotice"> + <legalnotice xml:id="legalnotice"> <para>This article was originally published in the January 2000 issue of - <ulink url="http://www.daemonnews.org/">DaemonNews</ulink>. This + <link xlink:href="http://www.daemonnews.org/">DaemonNews</link>. This version of the article may include updates from Matt and other authors to reflect changes in &os;'s VM implementation.</para> </legalnotice> - </articleinfo> + </info> - <sect1 id="introduction"> + <sect1 xml:id="introduction"> <title>Introduction</title> <para>Before moving along to the actual design let's spend a little time @@ -128,7 +120,7 @@ the parallels to algorithmic design and code generalization.</para> </sect1> - <sect1 id="vm-objects"> + <sect1 xml:id="vm-objects"> <title>VM Objects</title> <para>The best way to begin describing the &os; VM system is to look at @@ -292,10 +284,10 @@ called the <quote>All Shadowed Case</quote>. This case occurs if either C1 or C2 take sufficient COW faults to completely shadow all pages in B. Lets say that C1 achieves this. C1 can now bypass B entirely, so rather - then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But + then have C1->B->A and C2->B->A we now have C1->A and C2->B->A. But look what also happened—now B has only one reference (C2), so we can collapse B and C2 together. The end result is that B is deleted - entirely and we have C1->A and C2->A. It is often the case that B will + entirely and we have C1->A and C2->A. It is often the case that B will contain a large number of pages and neither C1 nor C2 will be able to completely overshadow it. If we fork again and create a set of D layers, however, it is much more likely that one of the D layers will @@ -321,7 +313,7 @@ that they can be ignored, leaving no real disadvantage.</para> </sect1> - <sect1 id="swap-layers"> + <sect1 xml:id="swap-layers"> <title>SWAP Layers</title> <para>Private data pages are initially either copy-on-write or zero-fill @@ -416,7 +408,7 @@ I ensured that such an addition could be made.</para> </sect1> - <sect1 id="freeing-pages"> + <sect1 xml:id="freeing-pages"> <title>When to free a page</title> <para>Since the VM system uses all available memory for disk caching, @@ -501,7 +493,7 @@ pages. I do not know whether this is still true today.</para> </sect1> - <sect1 id="prefault-optimizations"> + <sect1 xml:id="prefault-optimizations"> <title>Pre-Faulting and Zeroing Optimizations</title> <para>Taking a VM fault is not expensive if the underlying page is already @@ -537,7 +529,7 @@ optimize the critical path.</para> </sect1> - <sect1 id="page-table-optimizations"> + <sect1 xml:id="page-table-optimizations"> <title>Page Table Optimizations</title> <para>The page table optimizations make up the most contentious part of @@ -572,7 +564,7 @@ whether a page can be reused or not.</para> </sect1> - <sect1 id="page-coloring-optimizations"> + <sect1 xml:id="page-coloring-optimizations"> <title>Page Coloring</title> <para>We will end with the page coloring optimizations. Page coloring is a @@ -607,7 +599,7 @@ performance.</para> </sect1> - <sect1 id="conclusion"> + <sect1 xml:id="conclusion"> <title>Conclusion</title> <para>Virtual memory in modern operating systems must address a number of @@ -619,7 +611,7 @@ years, and work is ongoing.</para> </sect1> - <sect1 id="allen-briggs-qa"> + <sect1 xml:id="allen-briggs-qa"> <title>Bonus QA session by Allen Briggs <email>briggs@ninthwonder.com</email></title> @@ -713,7 +705,7 @@ <para>What this means is that &os; will not try very hard to separate out dirty pages (inactive queue) from clean pages (cache queue) when the system is not being stressed, nor will it try to - deactivate pages (active queue -> inactive queue) when the system + deactivate pages (active queue -> inactive queue) when the system is not being stressed, even if they are not being used.</para> </answer> </qandaentry> diff --git a/en_US.ISO8859-1/articles/wp-toolbox/article.xml b/en_US.ISO8859-1/articles/wp-toolbox/article.xml index ac6460d6a3..49c83b327f 100644 --- a/en_US.ISO8859-1/articles/wp-toolbox/article.xml +++ b/en_US.ISO8859-1/articles/wp-toolbox/article.xml @@ -1,28 +1,23 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY ports "Ports Collection"> -<!ENTITY os.ports "&os; &ports;"> -<!ENTITY frisbee "<application>Frisbee</application>"> -<!ENTITY ghost "<application>Ghost</application>"> -<!ENTITY nessus "<application>Nessus</application>"> +<!ENTITY os.ports "{{{os}}} {{{ports}}}"> +<!ENTITY frisbee "<application xmlns='http://docbook.org/ns/docbook'>Frisbee</application>"> +<!ENTITY ghost "<application xmlns='http://docbook.org/ns/docbook'>Ghost</application>"> +<!ENTITY nessus "<application xmlns='http://docbook.org/ns/docbook'>Nessus</application>"> ]> - -<article lang='en'> - <title>Creating a Software Testing Environment Using &os;</title> - <articleinfo> +<article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + + <info><title>Creating a Software Testing Environment Using &os;</title> <authorgroup> - <author> - <firstname>Chris</firstname> - <surname>McMahon</surname> - <affiliation> + <author><personname><firstname>Chris</firstname><surname>McMahon</surname></personname><affiliation> <address><email>christopher.mcmahon@gmail.com</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.microsoft; @@ -38,10 +33,10 @@ published in the Pacific Northwest Software Quality Conference Proceedings, 2005.</para></abstract> - </articleinfo> + </info> - <sect1 id="overview"> + <sect1 xml:id="overview"> <title>Overview</title> <para>From late 2003 until early 2005, I was a tester in an @@ -63,7 +58,7 @@ </sect1> - <sect1 id="challenge"> + <sect1 xml:id="challenge"> <title>The Challenge</title> <para>Software testing environments are radically more complex @@ -86,15 +81,14 @@ </sect1> - <sect1 id="freebsd-solution"> + <sect1 xml:id="freebsd-solution"> <title>The &os; Solution</title> - <sect2 id="freebsd-intro"> + <sect2 xml:id="freebsd-intro"> <title>Introduction</title> <para>The set of tools available with the &os; Operating - System is amazing. The &os; <ulink - url="http://www.freebsd.org/ports">&ports;</ulink> + System is amazing. The &os; <link xlink:href="http://www.freebsd.org/ports">&ports;</link> contains more than thirteen thousand separate applications, all of which have a standard installation procedure and conform to a set of guidelines that make them reliable without @@ -121,7 +115,7 @@ </sect2> - <sect2 id="freebsd-ports"> + <sect2 xml:id="freebsd-ports"> <title>How To Use The Ports System</title> <para>Installing an application from the &os.ports; is a simple matter of: </para> @@ -135,7 +129,7 @@ who typically is pressed for time!</para> </sect2> - <sect2 id="freebsd-testing"> + <sect2 xml:id="freebsd-testing"> <title>&os; For Testing</title> <para>The test environment should be more stable than the SUT. @@ -148,8 +142,7 @@ services to be their network-testing person in an all-Windows environment. My first assignment was to replace the obsolete, buggy, disk imaging system. I chose to do that with an Open - Source disk imaging system called <ulink - url="http://www.cs.utah.edu/flux/papers/frisbee-usenix03-base.html">&frisbee;</ulink> + Source disk imaging system called <link xlink:href="http://www.cs.utah.edu/flux/papers/frisbee-usenix03-base.html">&frisbee;</link> which was implemented originally on &os;. I built the system—a feature-for-feature replacement for an expensive proprietary system—but we never actually used it in our @@ -165,12 +158,12 @@ </sect2> - <sect2 id="freebsd-collab"> + <sect2 xml:id="freebsd-collab"> <title>&os; For Collaboration: Twiki</title> <para>A wiki is a simple set of web pages to allow many users to share information and collaborate on any sort of documents. - <ulink url="http://twiki.org">Twiki</ulink> is a wiki fine-tuned for + <link xlink:href="http://twiki.org">Twiki</link> is a wiki fine-tuned for document management. It has built-in version control and security implemented at the user/password level. I used it for requirements management and traceability.</para> @@ -220,7 +213,7 @@ the power of a unified system like &os;.</para> </sect2> - <sect2 id="freebsd-frisbee"> + <sect2 xml:id="freebsd-frisbee"> <title>&os; For Disk Imaging: Frisbee</title> <para>A disk imaging system is a mechanism for saving and @@ -280,13 +273,12 @@ developers or managers.</para> </sect2> - <sect2 id="freebsd-nessus"> + <sect2 xml:id="freebsd-nessus"> <title>&os; Security Testing: &nessus;</title> <para>Whenever you have more than one entity on a network, and whenever you expose a server to the wider Internet, security - of the machine itself is always a concern. <ulink - url="http://www.nessus.org">&nessus;</ulink> is an Open Source + of the machine itself is always a concern. <link xlink:href="http://www.nessus.org">&nessus;</link> is an Open Source remote vulnerability scanner for security and penetration testing that consistently is rated among the top products of its type throughout the security industry.</para> @@ -309,7 +301,7 @@ <application>NeWT</application>, <quote>Nessus on Windows Technology</quote>.</para> </sect2> - <sect2 id="freebsd-network"> + <sect2 xml:id="freebsd-network"> <title>&os; Network Tools</title> <para>&os; is most widely used as a robust server platform. @@ -318,8 +310,7 @@ brief description of network diagnostic tools that I found invaluable in testing in a networked environment.</para> - <para>From the name, one would assume that <ulink - url="http://www.ntop.org">ntop</ulink> emulates the functions of + <para>From the name, one would assume that <link xlink:href="http://www.ntop.org">ntop</link> emulates the functions of the UNIX &man.top.1; command, but for the network rather than for the local machine. Perhaps the first version did; currently, <application>ntop</application> is capable of providing detailed @@ -344,7 +335,7 @@ host, over that port. Often it was a new build with a bug.</para> - <para><ulink url="http://ettercap.sourceforge.net">Ettercap</ulink> is + <para><link xlink:href="http://ettercap.sourceforge.net">Ettercap</link> is a tool for ARP poisoning which can also decipher passwords on the fly and corrupt IP traffic by means of a Man In The Middle (MITM) attack. However, I used <application>Ettercap</application> as a performance tool. @@ -396,7 +387,7 @@ </sect2> </sect1> - <sect1 id="conclusion"> + <sect1 xml:id="conclusion"> <title>Conclusion</title> <para>I used tools from the &os.ports; in four diff --git a/en_US.ISO8859-1/books/arch-handbook/Makefile b/en_US.ISO8859-1/books/arch-handbook/Makefile index 9ad49d0e62..5f933755f9 100644 --- a/en_US.ISO8859-1/books/arch-handbook/Makefile +++ b/en_US.ISO8859-1/books/arch-handbook/Makefile @@ -10,8 +10,6 @@ DOC?= book FORMATS?= html-split -HAS_INDEX= true - INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= diff --git a/en_US.ISO8859-1/books/arch-handbook/book.xml b/en_US.ISO8859-1/books/arch-handbook/book.xml index 61509a2072..2853744df8 100644 --- a/en_US.ISO8859-1/books/arch-handbook/book.xml +++ b/en_US.ISO8859-1/books/arch-handbook/book.xml @@ -1,23 +1,21 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; <!ENTITY % mac-entities SYSTEM "mac.ent"> %mac-entities; ]> - <!-- The FreeBSD Documentation Project $FreeBSD$ --> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>&os; Architecture Handbook</title> + -<book lang='en'> - <bookinfo> - <title>&os; Architecture Handbook</title> - - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> <pubdate>$FreeBSD$</pubdate> @@ -34,7 +32,7 @@ <holder>The FreeBSD Documentation Project</holder> </copyright> - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.unix; &tm-attrib.apple; @@ -55,16 +53,14 @@ helping with this project, send email to the &a.doc;.</para> <para>The latest version of this document is always available - from the <ulink url="&url.base;/index.html">FreeBSD World - Wide Web server</ulink>. It may also be downloaded in a - variety of formats and compression options from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP server</ulink> - or one of the numerous <ulink - url="&url.books.handbook;/mirrors-ftp.html">mirror sites</ulink>.</para> + from the <link xlink:href="&url.base;/index.html">FreeBSD World + Wide Web server</link>. It may also be downloaded in a + variety of formats and compression options from the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP server</link> + or one of the numerous <link xlink:href="&url.books.handbook;/mirrors-ftp.html">mirror sites</link>.</para> </abstract> - </bookinfo> + </info> - <part id="kernel"> + <part xml:id="kernel"> <title>Kernel</title> &chap.boot; @@ -78,7 +74,7 @@ </part> - <part id="devicedrivers"> + <part xml:id="devicedrivers"> <title>Device Drivers</title> &chap.driverbasics; @@ -135,32 +131,17 @@ </part> --> - <part id="appendices"> + <part xml:id="appendices"> <title>Appendices</title> <bibliography> <biblioentry xreflabel="1"> <authorgroup> - <author> - <firstname>Marshall</firstname> - <othername role="Middle">Kirk</othername> - <surname>McKusick</surname> - </author> - <author> - <firstname>Keith</firstname> - <surname>Bostic</surname> - </author> - <author> - <firstname>Michael</firstname> - <othername role="MI">J</othername> - <surname>Karels</surname> - </author> - <author> - <firstname>John</firstname> - <othername role="MI">S</othername> - <surname>Quarterman</surname> - </author> + <author><personname><firstname>Marshall</firstname><othername role="Middle">Kirk</othername><surname>McKusick</surname></personname></author> + <author><personname><firstname>Keith</firstname><surname>Bostic</surname></personname></author> + <author><personname><firstname>Michael</firstname><othername role="MI">J</othername><surname>Karels</surname></personname></author> + <author><personname><firstname>John</firstname><othername role="MI">S</othername><surname>Quarterman</surname></personname></author> </authorgroup> <copyright> @@ -168,13 +149,13 @@ <holder>Addison-Wesley Publishing Company, Inc.</holder> </copyright> - <isbn>0-201-54979-4</isbn> + <biblioid class="isbn">0-201-54979-4</biblioid> <publisher> <publishername>Addison-Wesley Publishing Company, Inc.</publishername> </publisher> - <title>The Design and Implementation of the 4.4 BSD Operating System</title> + <citetitle>The Design and Implementation of the 4.4 BSD Operating System</citetitle> <pagenums>1-2</pagenums> </biblioentry> diff --git a/en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml index 40b71de09c..2aff82083e 100644 --- a/en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/boot/chapter.xml @@ -6,20 +6,15 @@ Copyright (c) 2002 Sergey Lyubka <devnull@uptsoft.com> All rights reserved $FreeBSD$ --> - -<chapter id="boot"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="boot"> + <info><title>Bootstrapping and Kernel Initialization</title> <authorgroup> - <author> - <firstname>Sergey</firstname> - <surname>Lyubka</surname> - <contrib>Contributed by </contrib> - </author> <!-- devnull@uptsoft.com 12 Jun 2002 --> + <author><personname><firstname>Sergey</firstname><surname>Lyubka</surname></personname><contrib>Contributed by </contrib></author> <!-- devnull@uptsoft.com 12 Jun 2002 --> </authorgroup> - </chapterinfo> - <title>Bootstrapping and Kernel Initialization</title> + </info> + - <sect1 id="boot-synopsis"> + <sect1 xml:id="boot-synopsis"> <title>Synopsis</title> <indexterm><primary>BIOS</primary></indexterm> @@ -35,7 +30,7 @@ $FreeBSD$ architecture is used as an example.</para> </sect1> - <sect1 id="boot-overview"> + <sect1 xml:id="boot-overview"> <title>Overview</title> <para>A computer running FreeBSD can boot by several methods, @@ -117,7 +112,7 @@ Timecounter "i8254" frequency 1193182 Hz</screen></para></entry> </informaltable> </sect1> - <sect1 id="boot-bios"> + <sect1 xml:id="boot-bios"> <title>BIOS POST</title> <para>When the PC powers on, the processor's registers are set @@ -173,7 +168,7 @@ Timecounter "i8254" frequency 1193182 Hz</screen></para></entry> sector.</para></footnote>.</para> </sect1> - <sect1 id="boot-boot0"> + <sect1 xml:id="boot-boot0"> <title><literal>boot0</literal> Stage</title> <indexterm><primary>MBR</primary></indexterm> @@ -259,7 +254,7 @@ Timecounter "i8254" frequency 1193182 Hz</screen></para></entry> <filename>boot2</filename>.</para> </sect1> - <sect1 id="boot-boot2"> + <sect1 xml:id="boot-boot2"> <title><literal>boot2</literal> Stage</title> <para>You might wonder, why <literal>boot2</literal> comes after @@ -456,7 +451,7 @@ struct bootinfo { 0, 0, 0, VTOP(&bootinfo));</programlisting> </sect1> - <sect1 id="boot-loader"> + <sect1 xml:id="boot-loader"> <title><application>loader</application> Stage</title> <para><application>loader</application> is a BTX client as well. @@ -473,7 +468,7 @@ struct bootinfo { module_formats[km->m_loader]->l_exec(km);</programlisting> </sect1> - <sect1 id="boot-kernel"> + <sect1 xml:id="boot-kernel"> <title>Kernel Initialization</title> <para>Let us take a look at the command that links the kernel. @@ -840,9 +835,8 @@ struct gate_descriptor *idt = &idt0[0]; /* interrupt descriptor table */ }</programlisting> <para>Although the sysinit framework is described in the - <ulink - url="&url.doc.langbase;/books/developers-handbook">Developers' - Handbook</ulink>, I will discuss the internals of it.</para> + <link xlink:href="&url.doc.langbase;/books/developers-handbook">Developers' + Handbook</link>, I will discuss the internals of it.</para> <indexterm><primary>sysinit objects</primary></indexterm> <para>Every system initialization object (sysinit object) is diff --git a/en_US.ISO8859-1/books/arch-handbook/chapters.ent b/en_US.ISO8859-1/books/arch-handbook/chapters.ent index 7fdd3df4ad..5182a6f8fb 100644 --- a/en_US.ISO8859-1/books/arch-handbook/chapters.ent +++ b/en_US.ISO8859-1/books/arch-handbook/chapters.ent @@ -10,8 +10,6 @@ $FreeBSD$ --> -<!ENTITY % chap.index "IGNORE"> - <!-- Part one - Kernel --> <!ENTITY chap.boot SYSTEM "boot/chapter.xml"> <!ENTITY chap.kobj SYSTEM "kobj/chapter.xml"> @@ -33,7 +31,4 @@ <!ENTITY chap.pccard SYSTEM "pccard/chapter.xml"> <!-- Part three - Appendices --> -<![%chap.index;[ - <!ENTITY chap.index SYSTEM "index.xml"> -]]> -<!ENTITY chap.index ""> +<!ENTITY chap.index "<index xmlns='http://docbook.org/ns/docbook'/>"> diff --git a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml index 2815b30aa8..9105d11730 100644 --- a/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/driverbasics/chapter.xml @@ -4,27 +4,18 @@ $FreeBSD$ --> - -<chapter id="driverbasics"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="driverbasics"> + <info><title>Writing FreeBSD Device Drivers</title> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Jörg</firstname> - <surname>Wunsch</surname> - <contrib>Based on intro(4) manual page by </contrib> - </author> + <author><personname><firstname>Jörg</firstname><surname>Wunsch</surname></personname><contrib>Based on intro(4) manual page by </contrib></author> </authorgroup> - </chapterinfo> - <title>Writing FreeBSD Device Drivers</title> + </info> + - <sect1 id="driverbasics-intro"> + <sect1 xml:id="driverbasics-intro"> <title>Introduction</title> <indexterm><primary>device driver</primary></indexterm> @@ -54,7 +45,7 @@ </sect1> - <sect1 id="driverbasics-kld"> + <sect1 xml:id="driverbasics-kld"> <title>Dynamic Kernel Linker Facility - KLD</title> <indexterm><primary>kernel linking</primary><secondary>dynamic</secondary></indexterm> @@ -154,7 +145,7 @@ KMOD=skeleton </sect2> </sect1> - <sect1 id="driverbasics-char"> + <sect1 xml:id="driverbasics-char"> <title>Character Devices</title> <indexterm><primary>character devices</primary></indexterm> @@ -349,7 +340,7 @@ Closing device "echo".</screen> <para>Real hardware devices are described in the next chapter.</para> </sect1> - <sect1 id="driverbasics-block"> + <sect1 xml:id="driverbasics-block"> <title>Block Devices (Are Gone)</title> <indexterm><primary>block devices</primary></indexterm> @@ -377,7 +368,7 @@ Closing device "echo".</screen> infrastructure.</para> </sect1> - <sect1 id="driverbasics-net"> + <sect1 xml:id="driverbasics-net"> <title>Network Drivers</title> <indexterm><primary>network devices</primary></indexterm> diff --git a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml index f413a0dbb1..97bd2822c5 100644 --- a/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/isa/chapter.xml @@ -4,36 +4,21 @@ $FreeBSD$ --> - -<chapter id="isa-driver"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="isa-driver"> + <info><title>ISA Device Drivers</title> <authorgroup> - <author> - <firstname>Sergey</firstname> - <surname>Babkin</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Sergey</firstname><surname>Babkin</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Modifications for Handbook made by </contrib> - </author> - <author> - <firstname>Valentino</firstname> - <surname>Vaschetto</surname> - </author> - <author> - <firstname>Wylie</firstname> - <surname>Stilwell</surname> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Modifications for Handbook made by </contrib></author> + <author><personname><firstname>Valentino</firstname><surname>Vaschetto</surname></personname></author> + <author><personname><firstname>Wylie</firstname><surname>Stilwell</surname></personname></author> </authorgroup> - </chapterinfo> + </info> - <title>ISA Device Drivers</title> + - <sect1 id="isa-driver-synopsis"> + <sect1 xml:id="isa-driver-synopsis"> <title>Synopsis</title> <indexterm><primary>ISA</primary></indexterm> @@ -48,7 +33,7 @@ <literal>ep</literal> and <literal>aha</literal> are good sources of information.</para> </sect1> - <sect1 id="isa-driver-basics"> + <sect1 xml:id="isa-driver-basics"> <title>Basic Information</title> <para>A typical ISA driver would need the following include @@ -163,7 +148,7 @@ <indexterm><primary>softc</primary></indexterm> - <para>Here struct <structname>xxx_softc</structname> is a + <para>Here struct <varname remap="structname">xxx_softc</varname> is a device-specific structure that contains private driver data and descriptors for the driver's resources. The bus code automatically allocates one softc descriptor per device as @@ -207,10 +192,10 @@ </sect1> - <sect1 id="isa-driver-device-t"> - <title><structname>device_t</structname> Pointer</title> + <sect1 xml:id="isa-driver-device-t"> + <title><varname remap="structname">device_t</varname> Pointer</title> - <para><structname>device_t</structname> is the pointer type for + <para><varname remap="structname">device_t</varname> is the pointer type for the device structure. Here we consider only the methods interesting from the device driver writer's standpoint. The methods to manipulate values in the device structure @@ -257,7 +242,7 @@ <listitem><para><function>void *device_get_softc(dev)</function> Get pointer to the device - descriptor (struct <structname>xxx_softc</structname>) + descriptor (struct <varname remap="structname">xxx_softc</varname>) associated with this device.</para></listitem> <listitem><para><function>u_int32_t @@ -276,7 +261,7 @@ </sect1> - <sect1 id="isa-driver-config"> + <sect1 xml:id="isa-driver-config"> <title>Configuration File and the Order of Identifying and Probing During Auto-Configuration</title> @@ -417,7 +402,7 @@ </sect1> - <sect1 id="isa-driver-resources"> + <sect1 xml:id="isa-driver-resources"> <title>Resources</title> <indexterm><primary>resources</primary></indexterm> @@ -730,7 +715,7 @@ </sect1> - <sect1 id="isa-driver-busmem"> + <sect1 xml:id="isa-driver-busmem"> <title>Bus Memory Mapping</title> <para>In many cases data is exchanged between the driver and the @@ -1510,7 +1495,7 @@ <!--_________________________________________________________________________--> <!--~~~~~~~~~~~~~~~~~~~~END OF SECTION~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~--> - <sect1 id="isa-driver-dma"> + <sect1 xml:id="isa-driver-dma"> <title>DMA</title> <!-- Section Marked up by Wylie --> @@ -1747,7 +1732,7 @@ </itemizedlist> </sect1> - <sect1 id="isa-driver-probe"> + <sect1 xml:id="isa-driver-probe"> <title>xxx_isa_probe</title> <!-- Section marked up by Wylie --> @@ -2177,7 +2162,7 @@ </sect1> - <sect1 id="isa-driver-attach"> + <sect1 xml:id="isa-driver-attach"> <title>xxx_isa_attach</title> <!-- Section Marked up by Wylie --> @@ -2385,7 +2370,7 @@ </sect1> - <sect1 id="isa-driver-detach"> + <sect1 xml:id="isa-driver-detach"> <title>xxx_isa_detach</title> <para> @@ -2448,7 +2433,7 @@ </para> </sect1> - <sect1 id="isa-driver-shutdown"> + <sect1 xml:id="isa-driver-shutdown"> <title>xxx_isa_shutdown</title> <para> @@ -2468,7 +2453,7 @@ </para> </sect1> - <sect1 id="isa-driver-intr"> + <sect1 xml:id="isa-driver-intr"> <title>xxx_intr</title> <indexterm><primary>interrupt handler</primary></indexterm> diff --git a/en_US.ISO8859-1/books/arch-handbook/jail/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/jail/chapter.xml index f6d6e404da..7269fdefbe 100644 --- a/en_US.ISO8859-1/books/arch-handbook/jail/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/jail/chapter.xml @@ -4,22 +4,17 @@ $FreeBSD$ --> - -<chapter id="jail"> - <chapterinfo> - <author> - <firstname>Evan</firstname> - <surname>Sarmiento</surname> - <affiliation> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="jail"> + <info><title>The Jail Subsystem</title> + <author><personname><firstname>Evan</firstname><surname>Sarmiento</surname></personname><affiliation> <address><email>evms@cs.bu.edu</email></address> - </affiliation> - </author> + </affiliation></author> <copyright> <year>2001</year> <holder role="mailto:evms@cs.bu.edu">Evan Sarmiento</holder> </copyright> - </chapterinfo> - <title>The Jail Subsystem</title> + </info> + <indexterm><primary>security</primary></indexterm> <indexterm><primary>Jail</primary></indexterm> @@ -46,10 +41,9 @@ gains <literal>root</literal> within the <application>jail</application>, it is only an annoyance, and not a devastation. This article mainly focuses on the internals (source code) of <application>jail</application>. - For information on how to set up a jail see the <ulink - url="&url.books.handbook;/jails.html">handbook entry on jails</ulink>.</para> + For information on how to set up a jail see the <link xlink:href="&url.books.handbook;/jails.html">handbook entry on jails</link>.</para> - <sect1 id="jail-arch"> + <sect1 xml:id="jail-arch"> <title>Architecture</title> <para> @@ -422,7 +416,7 @@ td2->td_ucred = crhold(p2->p_ucred);</programlisting> </sect2> </sect1> - <sect1 id="jail-restrictions"> + <sect1 xml:id="jail-restrictions"> <title>Restrictions</title> <para>Throughout the kernel there are access restrictions relating @@ -751,4 +745,3 @@ prison_priv_check(struct ucred *cred, int priv) </sect1> </chapter> - diff --git a/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.xml index f08b847166..e52d1603d4 100644 --- a/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/kobj/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="kernel-objects"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="kernel-objects"> <title>Kernel Objects</title> <indexterm><primary>Kernel Objects</primary></indexterm> @@ -18,7 +17,7 @@ interface at run time and without breaking binary compatibility.</para> - <sect1 id="kernel-objects-term"> + <sect1 xml:id="kernel-objects-term"> <title>Terminology</title> <indexterm><primary>object</primary></indexterm> @@ -54,7 +53,7 @@ </variablelist> </sect1> - <sect1 id="kernel-objects-operation"> + <sect1 xml:id="kernel-objects-operation"> <title>Kobj Operation</title> <para>Kobj works by generating descriptions of methods. Each @@ -86,7 +85,7 @@ </sect1> - <sect1 id="kernel-objects-using"> + <sect1 xml:id="kernel-objects-using"> <title>Using Kobj</title> <sect2> @@ -118,8 +117,8 @@ KOBJMETHOD(NAME, FUNC)</programlisting> <sect2> <title>Headers</title> - <programlisting><sys/param.h> -<sys/kobj.h></programlisting> + <programlisting><sys/param.h> +<sys/kobj.h></programlisting> </sect2> <sect2> @@ -147,7 +146,7 @@ KOBJMETHOD(NAME, FUNC)</programlisting> <para>For example:</para> - <programlisting>#include <sys/foo.h></programlisting> + <programlisting>#include <sys/foo.h></programlisting> <para>The <literal>INTERFACE</literal> keyword is used to define the interface name. This name is concatenated with each method @@ -242,7 +241,7 @@ kobj_method_t foomethods[] = { the state of the system at the time that the class is to be initialized a statically allocated cache, <quote>ops table</quote> have to be used. This can be accomplished by - declaring a <structname>struct kobj_ops</structname> and using + declaring a <varname remap="structname">struct kobj_ops</varname> and using <function>kobj_class_compile_static();</function> otherwise, <function>kobj_class_compile()</function> should be used.</para> </sect2> diff --git a/en_US.ISO8859-1/books/arch-handbook/locking/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/locking/chapter.xml index 4486cfb648..47ec5236ba 100644 --- a/en_US.ISO8859-1/books/arch-handbook/locking/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/locking/chapter.xml @@ -5,8 +5,7 @@ $FreeBSD$ --> - -<chapter id="locking"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="locking"> <title>Locking Notes</title> <indexterm><primary>SMP Next Generation Project</primary></indexterm> @@ -25,7 +24,7 @@ are protected simply by always using atomic operations to access them.</para> - <sect1 id="locking-mutexes"> + <sect1 xml:id="locking-mutexes"> <title>Mutexes</title> <para>A mutex is simply a lock used to guarantee mutual exclusion. @@ -99,7 +98,7 @@ <para>A list of data structures or data structure members that this entry protects. For data structure members, the name will be in the form of - <structname>structure name</structname>.<structfield>member name</structfield>.</para> + <varname remap="structname">structure name</varname>.<varname remap="structfield">member name</varname>.</para> </listitem> </varlistentry> @@ -152,38 +151,38 @@ <varname>cnt.v_swtch</varname>, <varname>cp_time</varname>, <varname>curpriority</varname>, - <structname>mtx</structname>.<structfield>mtx_blocked</structfield>, - <structname>mtx</structname>.<structfield>mtx_contested</structfield>, - <structname>proc</structname>.<structfield>p_procq</structfield>, - <structname>proc</structname>.<structfield>p_slpq</structfield>, - <structname>proc</structname>.<structfield>p_sflag</structfield>, - <structname>proc</structname>.<structfield>p_stat</structfield>, - <structname>proc</structname>.<structfield>p_estcpu</structfield>, - <structname>proc</structname>.<structfield>p_cpticks</structfield> - <structname>proc</structname>.<structfield>p_pctcpu</structfield>, - <structname>proc</structname>.<structfield>p_wchan</structfield>, - <structname>proc</structname>.<structfield>p_wmesg</structfield>, - <structname>proc</structname>.<structfield>p_swtime</structfield>, - <structname>proc</structname>.<structfield>p_slptime</structfield>, - <structname>proc</structname>.<structfield>p_runtime</structfield>, - <structname>proc</structname>.<structfield>p_uu</structfield>, - <structname>proc</structname>.<structfield>p_su</structfield>, - <structname>proc</structname>.<structfield>p_iu</structfield>, - <structname>proc</structname>.<structfield>p_uticks</structfield>, - <structname>proc</structname>.<structfield>p_sticks</structfield>, - <structname>proc</structname>.<structfield>p_iticks</structfield>, - <structname>proc</structname>.<structfield>p_oncpu</structfield>, - <structname>proc</structname>.<structfield>p_lastcpu</structfield>, - <structname>proc</structname>.<structfield>p_rqindex</structfield>, - <structname>proc</structname>.<structfield>p_heldmtx</structfield>, - <structname>proc</structname>.<structfield>p_blocked</structfield>, - <structname>proc</structname>.<structfield>p_mtxname</structfield>, - <structname>proc</structname>.<structfield>p_contested</structfield>, - <structname>proc</structname>.<structfield>p_priority</structfield>, - <structname>proc</structname>.<structfield>p_usrpri</structfield>, - <structname>proc</structname>.<structfield>p_nativepri</structfield>, - <structname>proc</structname>.<structfield>p_nice</structfield>, - <structname>proc</structname>.<structfield>p_rtprio</structfield>, + <varname remap="structname">mtx</varname>.<varname remap="structfield">mtx_blocked</varname>, + <varname remap="structname">mtx</varname>.<varname remap="structfield">mtx_contested</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_procq</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_slpq</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_sflag</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_stat</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_estcpu</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_cpticks</varname> + <varname remap="structname">proc</varname>.<varname remap="structfield">p_pctcpu</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_wchan</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_wmesg</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_swtime</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_slptime</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_runtime</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_uu</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_su</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_iu</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_uticks</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_sticks</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_iticks</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_oncpu</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_lastcpu</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_rqindex</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_heldmtx</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_blocked</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_mtxname</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_contested</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_priority</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_usrpri</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_nativepri</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_nice</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_rtprio</varname>, <varname>pscnt</varname>, <varname>slpque</varname>, <varname>itqueuebits</varname>, @@ -258,8 +257,8 @@ <varname>callfree</varname>, <varname>callwheel</varname>, <varname>nextsoftcheck</varname>, - <structname>proc</structname>.<structfield>p_itcallout</structfield>, - <structname>proc</structname>.<structfield>p_slpcallout</structfield>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_itcallout</varname>, + <varname remap="structname">proc</varname>.<varname remap="structfield">p_slpcallout</varname>, <varname>softticks</varname>, <varname>ticks</varname> </entry> @@ -271,7 +270,7 @@ </table> </sect1> - <sect1 id="locking-sx"> + <sect1 xml:id="locking-sx"> <title>Shared Exclusive Locks</title> <para>These locks provide basic reader-writer type functionality @@ -301,16 +300,16 @@ <varname>allproc</varname> <varname>zombproc</varname> <varname>pidhashtbl</varname> - <structname>proc</structname>.<structfield>p_list</structfield> - <structname>proc</structname>.<structfield>p_hash</structfield> + <varname remap="structname">proc</varname>.<varname remap="structfield">p_list</varname> + <varname remap="structname">proc</varname>.<varname remap="structfield">p_hash</varname> <varname>nextpid</varname> </entry> </row> <row> <entry><varname>proctree_lock</varname></entry> <entry> - <structname>proc</structname>.<structfield>p_children</structfield> - <structname>proc</structname>.<structfield>p_sibling</structfield> + <varname remap="structname">proc</varname>.<varname remap="structfield">p_children</varname> + <varname remap="structname">proc</varname>.<varname remap="structfield">p_sibling</varname> </entry> </row> </tbody> @@ -318,7 +317,7 @@ </table> </sect1> - <sect1 id="locking-atomic"> + <sect1 xml:id="locking-atomic"> <title>Atomically Protected Variables</title> <indexterm><primary>atomically protected variables</primary></indexterm> @@ -333,7 +332,7 @@ <itemizedlist> <listitem> - <para><structname>mtx</structname>.<structfield>mtx_lock</structfield></para> + <para><varname remap="structname">mtx</varname>.<varname remap="structfield">mtx_lock</varname></para> </listitem> </itemizedlist> </sect1> diff --git a/en_US.ISO8859-1/books/arch-handbook/mac.ent b/en_US.ISO8859-1/books/arch-handbook/mac.ent index e05ac48e87..76a5938a76 100644 --- a/en_US.ISO8859-1/books/arch-handbook/mac.ent +++ b/en_US.ISO8859-1/books/arch-handbook/mac.ent @@ -3,11 +3,11 @@ <!ENTITY mac.mpo "mpo"> <!ENTITY mac.thead ' - <colspec colname="first" colwidth="0"/> - <colspec colwidth="0"/> - <colspec colname="last" colwidth="0"/> + <colspec xmlns="http://docbook.org/ns/docbook" colname="first" colwidth="0"/> + <colspec xmlns="http://docbook.org/ns/docbook" colwidth="0"/> + <colspec xmlns="http://docbook.org/ns/docbook" colname="last" colwidth="0"/> - <thead> + <thead xmlns="http://docbook.org/ns/docbook"> <row> <entry>Parameter</entry> <entry>Description</entry> @@ -17,14 +17,14 @@ '> <!ENTITY mac.externalize.paramdefs ' - <paramdef>struct label *<parameter>label</parameter></paramdef> - <paramdef>char *<parameter>element_name</parameter></paramdef> - <paramdef>struct sbuf *<parameter>sb</parameter></paramdef> - <paramdef>int <parameter>*claimed</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">struct label *<parameter>label</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">char *<parameter>element_name</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">struct sbuf *<parameter>sb</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">int <parameter>*claimed</parameter></paramdef> '> <!ENTITY mac.externalize.tbody ' - <tbody> + <tbody xmlns="http://docbook.org/ns/docbook"> <row> <entry><parameter>label</parameter></entry> <entry>Label to be externalized</entry> @@ -49,11 +49,11 @@ </tbody> '> -<!ENTITY mac.externalize.para " - <para>Produce an externalized label based on the label structure passed. +<!ENTITY mac.externalize.para ' + <para xmlns="http://docbook.org/ns/docbook">Produce an externalized label based on the label structure passed. An externalized label consists of a text representation of the label contents that can be used with userland applications and read by the - user. Currently, all policies' <function>externalize</function> entry + user. Currently, all policies' <function>externalize</function> entry points will be called, so the implementation should check the contents of <parameter>element_name</parameter> before attempting to fill in <parameter>sb</parameter>. If @@ -62,17 +62,17 @@ if an error occurs while externalizing the label data. Once the policy fills in <parameter>element_data</parameter>, <varname>*claimed</varname> should be incremented.</para> -"> +'> <!ENTITY mac.internalize.paramdefs ' - <paramdef>struct label *<parameter>label</parameter></paramdef> - <paramdef>char *<parameter>element_name</parameter></paramdef> - <paramdef>char *<parameter>element_data</parameter></paramdef> - <paramdef>int *<parameter>claimed</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">struct label *<parameter>label</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">char *<parameter>element_name</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">char *<parameter>element_data</parameter></paramdef> + <paramdef xmlns="http://docbook.org/ns/docbook">int *<parameter>claimed</parameter></paramdef> '> <!ENTITY mac.internalize.tbody ' - <tbody> + <tbody xmlns="http://docbook.org/ns/docbook"> <row> <entry><parameter>label</parameter></entry> <entry>Label to be filled in</entry> @@ -96,9 +96,9 @@ </tbody> '> -<!ENTITY mac.internalize.para " - <para>Produce an internal label structure based on externalized label data - in text format. Currently, all policies' <function>internalize</function> +<!ENTITY mac.internalize.para ' + <para xmlns="http://docbook.org/ns/docbook">Produce an internal label structure based on externalized label data + in text format. Currently, all policies' <function>internalize</function> entry points are called when internalization is requested, so the implementation should compare the contents of <parameter>element_name</parameter> to its own name in order to be sure @@ -108,4 +108,4 @@ <parameter>element_name</parameter> does not match its own name, or when data can successfully be internalized, in which case <varname>*claimed</varname> should be incremented.</para> -"> +'> diff --git a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml index 923dd53eb6..215b9557de 100644 --- a/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/mac/chapter.xml @@ -32,35 +32,24 @@ $FreeBSD$ --> - -<chapter id="mac"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="mac"> + <info><title>The TrustedBSD MAC Framework</title> <authorgroup> - <author> - <firstname>Chris</firstname> - <surname>Costello</surname> - - <affiliation> + <author><personname><firstname>Chris</firstname><surname>Costello</surname></personname><affiliation> <orgname>TrustedBSD Project</orgname> <address><email>chris@FreeBSD.org</email></address> - </affiliation> - </author> - - <author> - <firstname>Robert</firstname> - <surname>Watson</surname> + </affiliation></author> - <affiliation> + <author><personname><firstname>Robert</firstname><surname>Watson</surname></personname><affiliation> <orgname>TrustedBSD Project</orgname> <address><email>rwatson@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - </chapterinfo> + </info> - <title>The TrustedBSD MAC Framework</title> + - <sect1 id="mac-copyright"> + <sect1 xml:id="mac-copyright"> <title>MAC Documentation Copyright</title> <para>This documentation was developed for the FreeBSD Project by @@ -110,7 +99,7 @@ </important> </sect1> - <sect1 id="mac-synopsis"> + <sect1 xml:id="mac-synopsis"> <title>Synopsis</title> <para>FreeBSD includes experimental support for several @@ -129,7 +118,7 @@ </sect1> - <sect1 id="mac-introduction"> + <sect1 xml:id="mac-introduction"> <title>Introduction</title> <para>The TrustedBSD MAC framework provides a mechanism to allow @@ -148,7 +137,7 @@ access control extension of the kernel.</para> </sect1> - <sect1 id="mac-background"> + <sect1 xml:id="mac-background"> <title>Policy Background</title> <para>Mandatory Access Control (MAC), refers to a set of @@ -180,7 +169,7 @@ flexibility in how they authorize protections.</para> </sect1> - <sect1 id="mac-framework-kernel-arch"> + <sect1 xml:id="mac-framework-kernel-arch"> <title>MAC Framework Kernel Architecture</title> <para>The TrustedBSD MAC Framework permits kernel modules to @@ -191,7 +180,7 @@ some definition of useful) compose the results of the policies.</para> - <sect2 id="mac-framework-kernel-arch-elements"> + <sect2 xml:id="mac-framework-kernel-arch-elements"> <title>Kernel Elements</title> <para>The MAC Framework contains a number of kernel elements:</para> @@ -221,7 +210,7 @@ </itemizedlist> </sect2> - <sect2 id="mac-framework-kernel-arch-management"> + <sect2 xml:id="mac-framework-kernel-arch-management"> <title>Framework Management Interfaces</title> <para>The TrustedBSD MAC Framework may be directly managed using @@ -247,7 +236,7 @@ events, including preventing undesired unloading of the policy.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-synchronization"> + <sect2 xml:id="mac-framework-kernel-arch-synchronization"> <title>Policy List Concurrency and Synchronization</title> <para>As the set of active policies may change at run-time, @@ -286,7 +275,7 @@ framework to become idle.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-label-synchronization"> + <sect2 xml:id="mac-framework-kernel-arch-label-synchronization"> <title>Label Synchronization</title> <para>As kernel objects of interest may generally be accessed from @@ -311,7 +300,7 @@ the label state attached to the credential.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-policy-synchronization"> + <sect2 xml:id="mac-framework-kernel-arch-policy-synchronization"> <title>Policy Synchronization and Concurrency</title> <para>Policy modules must be written to assume that many @@ -338,7 +327,7 @@ locks in the global lock order, helping to avoid deadlock.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-registration"> + <sect2 xml:id="mac-framework-kernel-arch-registration"> <title>Policy Registration</title> <para>The MAC Framework maintains two lists of active @@ -361,7 +350,7 @@ not unloadable.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-entrypoints"> + <sect2 xml:id="mac-framework-kernel-arch-entrypoints"> <title>Entry Points</title> <para>Kernel services interact with the MAC Framework in two ways: @@ -385,7 +374,7 @@ sockets and label transition at program execution.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-composition"> + <sect2 xml:id="mac-framework-kernel-arch-composition"> <title>Policy Composition</title> <para>When more than one policy module is loaded into the kernel @@ -406,7 +395,7 @@ composition.</para> </sect2> - <sect2 id="mac-framework-kernel-arch-labels"> + <sect2 xml:id="mac-framework-kernel-arch-labels"> <title>Labeling Support</title> <para>As many interesting access control extensions rely on @@ -422,8 +411,8 @@ of string-based labels provides by user applications, and can expose multiple label elements to applications if desired.</para> - <para>In-memory labels are stored in slab-allocated <structname>struct - label</structname>, which consists of a fixed-length array + <para>In-memory labels are stored in slab-allocated <varname remap="structname">struct + label</varname>, which consists of a fixed-length array of unions, each holding a <literal>void *</literal> pointer and a <literal>long</literal>. Policies registering for label storage will be assigned a "slot" identifier, which @@ -483,7 +472,7 @@ unload-reload operations for labeled policies.</para></note> </sect2> - <sect2 id="mac-framework-kernel-arch-syscalls"> + <sect2 xml:id="mac-framework-kernel-arch-syscalls"> <title>System Calls</title> <para>The MAC Framework implements a number of system calls: @@ -492,7 +481,7 @@ applications.</para> <para>The label management calls accept a label description - structure, <structname>struct mac</structname>, which + structure, <varname remap="structname">struct mac</varname>, which contains a series of MAC label elements. Each element contains a character string name, and character string value. Each policy will be given the chance to claim a @@ -590,7 +579,7 @@ </sect2> </sect1> - <sect1 id="mac-policy-architecture"> + <sect1 xml:id="mac-policy-architecture"> <title>MAC Policy Architecture</title> <para>Security policies are either linked directly into the kernel, @@ -618,7 +607,7 @@ points, and policy properties.</para></listitem> </itemizedlist> - <sect2 id="mac-policy-declaration"> + <sect2 xml:id="mac-policy-declaration"> <title>Policy Declaration</title> <para>Modules may be declared using the @@ -670,7 +659,7 @@ processes.</para> </sect2> - <sect2 id="mac-policy-flags"> + <sect2 xml:id="mac-policy-flags"> <title>Policy Flags</title> <para>The policy declaration flags field permits the module to @@ -737,7 +726,7 @@ to have label storage.</para></note> </sect2> - <sect2 id="mac-policy-entry-points"> + <sect2 xml:id="mac-policy-entry-points"> <title>Policy Entry Points</title> <para>Four classes of entry points are offered to policies @@ -772,13 +761,13 @@ </sect2> </sect1> - <sect1 id="mac-entry-point-reference"> + <sect1 xml:id="mac-entry-point-reference"> <title>MAC Policy Entry Point Reference</title> - <sect2 id="mac-mpo-general"> + <sect2 xml:id="mac-mpo-general"> <title>General-Purpose Module Entry Points</title> - <sect3 id="mac-mpo-init"> + <sect3 xml:id="mac-mpo-init"> <title><function>&mac.mpo;_init</function></title> <funcsynopsis> @@ -812,7 +801,7 @@ SYSINIT().</para> </sect3> - <sect3 id="mpo-destroy"> + <sect3 xml:id="mpo-destroy"> <title><function>&mac.mpo;_destroy</function></title> <funcsynopsis> @@ -842,7 +831,7 @@ caution should be applied.</para> </sect3> - <sect3 id="mac-mpo-syscall"> + <sect3 xml:id="mac-mpo-syscall"> <title><function>&mac.mpo;_syscall</function></title> <funcsynopsis> @@ -898,7 +887,7 @@ own.</para></note> </sect3> - <sect3 id="mac-mpo-thread-userret"> + <sect3 xml:id="mac-mpo-thread-userret"> <title><function>&mac.mpo;_thread_userret</function></title> <funcsynopsis> @@ -948,10 +937,10 @@ </sect3> </sect2> - <sect2 id="mac-label-ops"> + <sect2 xml:id="mac-label-ops"> <title>Label Operations</title> - <sect3 id="mac-mpo-init-bpfdesc"> + <sect3 xml:id="mac-mpo-init-bpfdesc"> <title><function>&mac.mpo;_init_bpfdesc_label</function></title> <funcsynopsis> @@ -981,7 +970,7 @@ descriptor). Sleeping is permitted.</para> </sect3> - <sect3 id="mac-mpo-init-cred-label"> + <sect3 xml:id="mac-mpo-init-cred-label"> <title><function>&mac.mpo;_init_cred_label</function></title> <funcsynopsis> @@ -1011,7 +1000,7 @@ user credential. Sleeping is permitted.</para> </sect3> - <sect3 id="mac-mpo-init-devfsdirent"> + <sect3 xml:id="mac-mpo-init-devfsdirent"> <title><function>&mac.mpo;_init_devfsdirent_label</function></title> <funcsynopsis> @@ -1041,7 +1030,7 @@ entry. Sleeping is permitted.</para> </sect3> - <sect3 id="mac-mpo-init-ifnet"> + <sect3 xml:id="mac-mpo-init-ifnet"> <title><function>&mac.mpo;_init_ifnet_label</function></title> <funcsynopsis> @@ -1071,7 +1060,7 @@ interface. Sleeping is permitted.</para> </sect3> - <sect3 id="mac-mpo-init-ipq"> + <sect3 xml:id="mac-mpo-init-ipq"> <title><function>&mac.mpo;_init_ipq_label</function></title> <funcsynopsis> @@ -1116,7 +1105,7 @@ the IP fragment reassembly queue.</para> </sect3> - <sect3 id="mac-mpo-init-mbuf"> + <sect3 xml:id="mac-mpo-init-mbuf"> <title><function>&mac.mpo;_init_mbuf_label</function></title> <funcsynopsis> @@ -1162,7 +1151,7 @@ the mbuf header.</para> </sect3> - <sect3 id="mac-mpo-init-mount"> + <sect3 xml:id="mac-mpo-init-mount"> <title><function>&mac.mpo;_init_mount_label</function></title> <funcsynopsis> @@ -1202,7 +1191,7 @@ point. Sleeping is permitted.</para> </sect3> - <sect3 id="mac-mpo-init-mount-fs-label"> + <sect3 xml:id="mac-mpo-init-mount-fs-label"> <title><function>&mac.mpo;_init_mount_fs_label</function></title> <funcsynopsis> @@ -1232,7 +1221,7 @@ system. Sleeping is permitted</para> </sect3> - <sect3 id="mac-mpo-init-pipe-label"> + <sect3 xml:id="mac-mpo-init-pipe-label"> <title><function>&mac.mpo;_init_pipe_label</function></title> <funcsynopsis> @@ -1262,7 +1251,7 @@ is permitted.</para> </sect3> - <sect3 id="mac-mpo-init-socket"> + <sect3 xml:id="mac-mpo-init-socket"> <title><function>&mac.mpo;_init_socket_label</function></title> <funcsynopsis> @@ -1301,7 +1290,7 @@ during this initialization call.</para> </sect3> - <sect3 id="mac-mpo-init-socket-peer-label"> + <sect3 xml:id="mac-mpo-init-socket-peer-label"> <title><function>&mac.mpo;_init_socket_peer_label</function></title> <funcsynopsis> @@ -1340,7 +1329,7 @@ during this initialization call.</para> </sect3> - <sect3 id="mac-mpo-init-proc-label"> + <sect3 xml:id="mac-mpo-init-proc-label"> <title><function>&mac.mpo;_init_proc_label</function></title> <funcsynopsis> @@ -1371,7 +1360,7 @@ </sect3> - <sect3 id="mac-mpo-init-vnode"> + <sect3 xml:id="mac-mpo-init-vnode"> <title><function>&mac.mpo;_init_vnode_label</function></title> <funcsynopsis> @@ -1400,7 +1389,7 @@ <para>Initialize the label on a newly instantiated vnode. Sleeping is permitted.</para> </sect3> - <sect3 id="mac-mpo-destroy-bpfdesc"> + <sect3 xml:id="mac-mpo-destroy-bpfdesc"> <title><function>&mac.mpo;_destroy_bpfdesc_label</function></title> <funcsynopsis> @@ -1432,7 +1421,7 @@ destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-cred"> + <sect3 xml:id="mac-mpo-destroy-cred"> <title><function>&mac.mpo;_destroy_cred_label</function></title> <funcsynopsis> @@ -1465,7 +1454,7 @@ </sect3> - <sect3 id="mac-mpo-destroy-devfsdirent"> + <sect3 xml:id="mac-mpo-destroy-devfsdirent"> <title><function>&mac.mpo;_destroy_devfsdirent_label</function></title> <funcsynopsis> @@ -1497,7 +1486,7 @@ be destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-ifnet-label"> + <sect3 xml:id="mac-mpo-destroy-ifnet-label"> <title><function>&mac.mpo;_destroy_ifnet_label</function></title> <funcsynopsis> @@ -1529,7 +1518,7 @@ be destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-ipq-label"> + <sect3 xml:id="mac-mpo-destroy-ipq-label"> <title><function>&mac.mpo;_destroy_ipq_label</function></title> <funcsynopsis> @@ -1561,7 +1550,7 @@ it may be destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-mbuf-label"> + <sect3 xml:id="mac-mpo-destroy-mbuf-label"> <title><function>&mac.mpo;_destroy_mbuf_label</function></title> <funcsynopsis> @@ -1593,7 +1582,7 @@ be destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-mount-label"> + <sect3 xml:id="mac-mpo-destroy-mount-label"> <title><function>&mac.mpo;_destroy_mount_label</function></title> <funcsynopsis> @@ -1625,7 +1614,7 @@ may be destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-mount"> + <sect3 xml:id="mac-mpo-destroy-mount"> <title><function>&mac.mpo;_destroy_mount_label</function></title> <funcsynopsis> @@ -1652,7 +1641,7 @@ <row> <entry><parameter>fslabel</parameter></entry> - <entry>File system label being destroyed></entry> + <entry>File system label being destroyed></entry> </row> </tbody> </tgroup> @@ -1665,7 +1654,7 @@ destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-socket"> + <sect3 xml:id="mac-mpo-destroy-socket"> <title><function>&mac.mpo;_destroy_socket_label</function></title> <funcsynopsis> @@ -1699,7 +1688,7 @@ destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-socket-peer-label"> + <sect3 xml:id="mac-mpo-destroy-socket-peer-label"> <title><function>&mac.mpo;_destroy_socket_peer_label</function></title> <funcsynopsis> @@ -1731,7 +1720,7 @@ be destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-pipe-label"> + <sect3 xml:id="mac-mpo-destroy-pipe-label"> <title><function>&mac.mpo;_destroy_pipe_label</function></title> <funcsynopsis> @@ -1763,7 +1752,7 @@ destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-proc-label"> + <sect3 xml:id="mac-mpo-destroy-proc-label"> <title><function>&mac.mpo;_destroy_proc_label</function></title> <funcsynopsis> @@ -1794,7 +1783,7 @@ destroyed.</para> </sect3> - <sect3 id="mac-mpo-destroy-vnode-label"> + <sect3 xml:id="mac-mpo-destroy-vnode-label"> <title><function>&mac.mpo;_destroy_vnode_label</function></title> <funcsynopsis> @@ -1825,7 +1814,7 @@ destroyed.</para> </sect3> - <sect3 id="mac-mpo-copy-mbuf-label"> + <sect3 xml:id="mac-mpo-copy-mbuf-label"> <title><function>&mac.mpo;_copy_mbuf_label</function></title> <funcsynopsis> @@ -1863,7 +1852,7 @@ <parameter>dest</parameter>.</para> </sect3> - <sect3 id="mac-mpo-copy-pipe-label"> + <sect3 xml:id="mac-mpo-copy-pipe-label"> <title><function>&mac.mpo;_copy_pipe_label</function></title> <funcsynopsis> @@ -1901,7 +1890,7 @@ <parameter>dest</parameter>.</para> </sect3> - <sect3 id="mac-mpo-copy-vnode-label"> + <sect3 xml:id="mac-mpo-copy-vnode-label"> <title><function>&mac.mpo;_copy_vnode_label</function></title> <funcsynopsis> @@ -1939,7 +1928,7 @@ <parameter>dest</parameter>.</para> </sect3> - <sect3 id="mac-mpo-externalize-cred-label"> + <sect3 xml:id="mac-mpo-externalize-cred-label"> <title><function>&mac.mpo;_externalize_cred_label</function></title> <funcsynopsis> @@ -1962,7 +1951,7 @@ &mac.externalize.para; </sect3> - <sect3 id="mac-mpo-externalize-ifnet-label"> + <sect3 xml:id="mac-mpo-externalize-ifnet-label"> <title><function>&mac.mpo;_externalize_ifnet_label</function></title> <funcsynopsis> @@ -1985,7 +1974,7 @@ &mac.externalize.para; </sect3> - <sect3 id="mac-mpo-externalize-pipe-label"> + <sect3 xml:id="mac-mpo-externalize-pipe-label"> <title><function>&mac.mpo;_externalize_pipe_label</function></title> <funcsynopsis> @@ -2008,7 +1997,7 @@ &mac.externalize.para; </sect3> - <sect3 id="mac-mpo-externalize-socket-label"> + <sect3 xml:id="mac-mpo-externalize-socket-label"> <title><function>&mac.mpo;_externalize_socket_label</function></title> <funcsynopsis> @@ -2031,7 +2020,7 @@ &mac.externalize.para; </sect3> - <sect3 id="mac-mpo-externalize-socket-peer-label"> + <sect3 xml:id="mac-mpo-externalize-socket-peer-label"> <title><function>&mac.mpo;_externalize_socket_peer_label</function></title> <funcsynopsis> @@ -2054,7 +2043,7 @@ &mac.externalize.para; </sect3> - <sect3 id="mac-mpo-externalize-vnode-label"> + <sect3 xml:id="mac-mpo-externalize-vnode-label"> <title><function>&mac.mpo;_externalize_vnode_label</function></title> <funcsynopsis> @@ -2077,7 +2066,7 @@ &mac.externalize.para; </sect3> - <sect3 id="mac-mpo-internalize-cred-label"> + <sect3 xml:id="mac-mpo-internalize-cred-label"> <title><function>&mac.mpo;_internalize_cred_label</function></title> <funcsynopsis> @@ -2100,7 +2089,7 @@ &mac.internalize.para; </sect3> - <sect3 id="mac-mpo-internalize-ifnet-label"> + <sect3 xml:id="mac-mpo-internalize-ifnet-label"> <title><function>&mac.mpo;_internalize_ifnet_label</function></title> <funcsynopsis> @@ -2123,7 +2112,7 @@ &mac.internalize.para; </sect3> - <sect3 id="mac-mpo-internalize-pipe-label"> + <sect3 xml:id="mac-mpo-internalize-pipe-label"> <title><function>&mac.mpo;_internalize_pipe_label</function></title> <funcsynopsis> @@ -2146,7 +2135,7 @@ &mac.internalize.para; </sect3> - <sect3 id="mac-mpo-internalize-socket-label"> + <sect3 xml:id="mac-mpo-internalize-socket-label"> <title><function>&mac.mpo;_internalize_socket_label</function></title> <funcsynopsis> @@ -2169,7 +2158,7 @@ &mac.internalize.para; </sect3> - <sect3 id="mac-mpo-internalize-vnode-label"> + <sect3 xml:id="mac-mpo-internalize-vnode-label"> <title><function>&mac.mpo;_internalize_vnode_label</function></title> <funcsynopsis> @@ -2193,7 +2182,7 @@ </sect3> </sect2> - <sect2 id="mac-label-events"> + <sect2 xml:id="mac-label-events"> <title>Label Events</title> <para>This class of entry points is used by the MAC framework to @@ -2264,10 +2253,10 @@ Label destruction o</programlisting> <symbol>MAC_INTERNALIZE</symbol>, which accepts a user label to be converted to an in-kernel representation.</para> - <sect3 id="mac-fs-label-event-ops"> + <sect3 xml:id="mac-fs-label-event-ops"> <title>File System Object Labeling Event Operations</title> - <sect4 id="mac-mpo-associate-vnode-devfs"> + <sect4 xml:id="mac-mpo-associate-vnode-devfs"> <title><function>&mac.mpo;_associate_vnode_devfs</function></title> <funcsynopsis> @@ -2338,7 +2327,7 @@ Label destruction o</programlisting> label.</para> </sect4> - <sect4 id="mac-mpo-associate-vnode-extattr"> + <sect4 xml:id="mac-mpo-associate-vnode-extattr"> <title><function>&mac.mpo;_associate_vnode_extattr</function></title> <funcsynopsis> @@ -2397,7 +2386,7 @@ Label destruction o</programlisting> be returned.</para> </sect4> - <sect4 id="mac-mpo-associate-vnode-singlelabel"> + <sect4 xml:id="mac-mpo-associate-vnode-singlelabel"> <title><function>&mac.mpo;_associate_vnode_singlelabel</function></title> <funcsynopsis> @@ -2452,7 +2441,7 @@ Label destruction o</programlisting> </sect4> - <sect4 id="mac-mpo-create-devfs-device"> + <sect4 xml:id="mac-mpo-create-devfs-device"> <title><function>&mac.mpo;_create_devfs_device</function></title> <funcsynopsis> @@ -2499,7 +2488,7 @@ Label destruction o</programlisting> available.</para> </sect4> - <sect4 id="mac-mpo-create-devfs-directory"> + <sect4 xml:id="mac-mpo-create-devfs-directory"> <title><function>&mac.mpo;_create_devfs_directory</function></title> <funcsynopsis> @@ -2548,7 +2537,7 @@ Label destruction o</programlisting> available.</para> </sect4> - <sect4 id="mac-mpo-create-devfs-symlink"> + <sect4 xml:id="mac-mpo-create-devfs-symlink"> <title><function>&mac.mpo;_create_devfs_symlink</function></title> <funcsynopsis> @@ -2615,7 +2604,7 @@ Label destruction o</programlisting> a newly created &man.devfs.5; symbolic link entry.</para> </sect4> - <sect4 id="mac-mpo-create-vnode-extattr"> + <sect4 xml:id="mac-mpo-create-vnode-extattr"> <title><function>&mac.mpo;_create_vnode_extattr</function></title> <funcsynopsis> @@ -2700,7 +2689,7 @@ Label destruction o</programlisting> return an appropriate error.</para> </sect4> - <sect4 id="mac-mpo-create-mount"> + <sect4 xml:id="mac-mpo-create-mount"> <title><function>&mac.mpo;_create_mount</function></title> <funcsynopsis> @@ -2754,7 +2743,7 @@ Label destruction o</programlisting> a new file system is mounted.</para> </sect4> - <sect4 id="mac-mpo-create-root-mount"> + <sect4 xml:id="mac-mpo-create-root-mount"> <title><function>&mac.mpo;_create_root_mount</function></title> <funcsynopsis> @@ -2779,8 +2768,7 @@ Label destruction o</programlisting> <tbody> <row> - <entry namest="first" nameend="last">See <xref - linkend="mac-mpo-create-mount"/>.</entry> + <entry namest="first" nameend="last">See <xref linkend="mac-mpo-create-mount"/>.</entry> </row> </tbody> </tgroup> @@ -2792,7 +2780,7 @@ Label destruction o</programlisting> &mac.mpo;_create_mount;.</para> </sect4> - <sect4 id="mac-mpo-relabel-vnode"> + <sect4 xml:id="mac-mpo-relabel-vnode"> <title><function>&mac.mpo;_relabel_vnode</function></title> <funcsynopsis> @@ -2845,7 +2833,7 @@ Label destruction o</programlisting> update vnode label and the passed subject credential.</para> </sect4> - <sect4 id="mac-mpo-setlabel-vnode-extattr"> + <sect4 xml:id="mac-mpo-setlabel-vnode-extattr"> <title><function>&mac.mpo;_setlabel_vnode_extattr</function></title> <funcsynopsis> @@ -2900,7 +2888,7 @@ Label destruction o</programlisting> <function>vop_stdcreatevnode_ea</function>.</para> </sect4> - <sect4 id="mac-mpo-update-devfsdirent"> + <sect4 xml:id="mac-mpo-update-devfsdirent"> <title><function>&mac.mpo;_update_devfsdirent</function></title> <funcsynopsis> <funcprototype> @@ -2961,11 +2949,11 @@ Label destruction o</programlisting> </sect4> </sect3> - <sect3 id="mac-ipc-label-ops"> + <sect3 xml:id="mac-ipc-label-ops"> <title>IPC Object Labeling Event Operations</title> - <sect4 id="mac-mpo-create-mbuf-from-socket"> + <sect4 xml:id="mac-mpo-create-mbuf-from-socket"> <title><function>&mac.mpo;_create_mbuf_from_socket</function></title> <funcsynopsis> @@ -3020,7 +3008,7 @@ Label destruction o</programlisting> passed mbuf.</para> </sect4> - <sect4 id="mac-mpo-create-pipe"> + <sect4 xml:id="mac-mpo-create-pipe"> <title><function>&mac.mpo;_create_pipe</function></title> <funcsynopsis> @@ -3066,7 +3054,7 @@ Label destruction o</programlisting> created.</para> </sect4> - <sect4 id="mac-mpo-create-socket"> + <sect4 xml:id="mac-mpo-create-socket"> <title><function>&mac.mpo;_create_socket</function></title> <funcsynopsis> @@ -3113,7 +3101,7 @@ Label destruction o</programlisting> created.</para> </sect4> - <sect4 id="mac-mpo-create-socket-from-socket"> + <sect4 xml:id="mac-mpo-create-socket-from-socket"> <title><function>&mac.mpo;_create_socket_from_socket</function></title> <funcsynopsis> @@ -3167,7 +3155,7 @@ Label destruction o</programlisting> socket, <parameter>oldsocket</parameter>.</para> </sect4> - <sect4 id="mac-mpo-relabel-pipe"> + <sect4 xml:id="mac-mpo-relabel-pipe"> <title><function>&mac.mpo;_relabel_pipe</function></title> <funcsynopsis> @@ -3220,7 +3208,7 @@ Label destruction o</programlisting> <parameter>pipe</parameter>.</para> </sect4> - <sect4 id="mac-mpo-relabel-socket"> + <sect4 xml:id="mac-mpo-relabel-socket"> <title><function>&mac.mpo;_relabel_socket</function></title> <funcsynopsis> @@ -3274,7 +3262,7 @@ Label destruction o</programlisting> label update.</para> </sect4> - <sect4 id="mpo-set-socket-peer-from-mbuf"> + <sect4 xml:id="mpo-set-socket-peer-from-mbuf"> <title><function>&mac.mpo;_set_socket_peer_from_mbuf</function></title> <funcsynopsis> @@ -3328,7 +3316,7 @@ Label destruction o</programlisting> domain sockets.</para> </sect4> - <sect4 id="mac-mpo-set-socket-peer-from-socket"> + <sect4 xml:id="mac-mpo-set-socket-peer-from-socket"> <title><function>&mac.mpo;_set_socket_peer_from_socket</function></title> <funcsynopsis> @@ -3385,10 +3373,10 @@ Label destruction o</programlisting> </sect4> </sect3> - <sect3 id="mac-net-labeling-event-ops"> + <sect3 xml:id="mac-net-labeling-event-ops"> <title>Network Object Labeling Event Operations</title> - <sect4 id="mac-mpo-create-bpfdesc"> + <sect4 xml:id="mac-mpo-create-bpfdesc"> <title><function>&mac.mpo;_create_bpfdesc</function></title> <funcsynopsis> @@ -3436,7 +3424,7 @@ Label destruction o</programlisting> subject credential.</para> </sect4> - <sect4 id="mac-mpo-create-ifnet"> + <sect4 xml:id="mac-mpo-create-ifnet"> <title><function>&mac.mpo;_create_ifnet</function></title> <funcsynopsis> @@ -3476,7 +3464,7 @@ Label destruction o</programlisting> during the boot or as a result of a user action.</para> </sect4> - <sect4 id="mac-mpo-create-ipq"> + <sect4 xml:id="mac-mpo-create-ipq"> <title><function>&mac.mpo;_create_ipq</function></title> <funcsynopsis> @@ -3530,7 +3518,7 @@ Label destruction o</programlisting> fragment.</para> </sect4> - <sect4 id="mac-mpo-create-datagram-from-ipq"> + <sect4 xml:id="mac-mpo-create-datagram-from-ipq"> <title><function>&mac.mpo;_create_datagram_from_ipq</function></title> <funcsynopsis> @@ -3584,7 +3572,7 @@ Label destruction o</programlisting> generated.</para> </sect4> - <sect4 id="mac-mpo-create-fragment"> + <sect4 xml:id="mac-mpo-create-fragment"> <title><function>&mac.mpo;_create_fragment</function></title> <funcsynopsis> @@ -3638,7 +3626,7 @@ Label destruction o</programlisting> it was generate from.</para> </sect4> - <sect4 id="mac-mpo-create-mbuf-from-mbuf"> + <sect4 xml:id="mac-mpo-create-mbuf-from-mbuf"> <title><function>&mac.mpo;_create_mbuf_from_mbuf</function></title> <funcsynopsis> @@ -3693,7 +3681,7 @@ Label destruction o</programlisting> an mbuf is re-allocated for alignment purposes.</para> </sect4> - <sect4 id="mac-mpo-create-mbuf-linklayer"> + <sect4 xml:id="mac-mpo-create-mbuf-linklayer"> <title><function>&mac.mpo;_create_mbuf_linklayer</function></title> <funcsynopsis> @@ -3749,7 +3737,7 @@ Label destruction o</programlisting> IPv4 and IPv6 stacks.</para> </sect4> - <sect4 id="mac-mpo-create-mbuf-from-bpfdesc"> + <sect4 xml:id="mac-mpo-create-mbuf-from-bpfdesc"> <title><function>&mac.mpo;_create_mbuf_from_bpfdesc</function></title> <funcsynopsis> @@ -3804,7 +3792,7 @@ Label destruction o</programlisting> associated with the passed BPF descriptor.</para> </sect4> - <sect4 id="mac-mpo-create-mbuf-from-ifnet"> + <sect4 xml:id="mac-mpo-create-mbuf-from-ifnet"> <title><function>&mac.mpo;_create_mbuf_from_ifnet</function></title> <funcsynopsis> @@ -3857,7 +3845,7 @@ Label destruction o</programlisting> datagram generated from the passed network interface.</para> </sect4> - <sect4 id="mac-mpo-create-mbuf-multicast-encap"> + <sect4 xml:id="mac-mpo-create-mbuf-multicast-encap"> <title><function>&mac.mpo;_create_mbuf_multicast_encap</function></title> <funcsynopsis> @@ -3929,7 +3917,7 @@ Label destruction o</programlisting> delivered using the virtual interface.</para> </sect4> - <sect4 id="mac-mpo-create-mbuf-netlayer"> + <sect4 xml:id="mac-mpo-create-mbuf-netlayer"> <title><function>&mac.mpo;_create_mbuf_netlayer</function></title> <funcsynopsis> @@ -3985,7 +3973,7 @@ Label destruction o</programlisting> when responding to ICMP request datagrams.</para> </sect4> - <sect4 id="mac-mpo-fragment-match"> + <sect4 xml:id="mac-mpo-fragment-match"> <title><function>&mac.mpo;_fragment_match</function></title> <funcsynopsis> @@ -4049,7 +4037,7 @@ Label destruction o</programlisting> label or other information.</para> </sect4> - <sect4 id="mac-mpo-ifnet-relabel"> + <sect4 xml:id="mac-mpo-ifnet-relabel"> <title><function>&mac.mpo;_relabel_ifnet</function></title> <funcsynopsis> @@ -4104,7 +4092,7 @@ Label destruction o</programlisting> subject credential, <parameter>cred</parameter>.</para> </sect4> - <sect4 id="mac-mpo-update-ipq"> + <sect4 xml:id="mac-mpo-update-ipq"> <title><function>&mac.mpo;_update_ipq</function></title> <funcsynopsis> @@ -4160,10 +4148,10 @@ Label destruction o</programlisting> </sect4> </sect3> - <sect3 id="mac-proc-labeling-event-ops"> + <sect3 xml:id="mac-proc-labeling-event-ops"> <title>Process Labeling Event Operations</title> - <sect4 id="mac-mpo-create-cred"> + <sect4 xml:id="mac-mpo-create-cred"> <title><function>&mac.mpo;_create_cred</function></title> <funcsynopsis> @@ -4203,7 +4191,7 @@ Label destruction o</programlisting> process forking or creation event.</para> </sect4> - <sect4 id="mac-mpo-execve-transition"> + <sect4 xml:id="mac-mpo-execve-transition"> <title><function>&mac.mpo;_execve_transition</function></title> <funcsynopsis> @@ -4271,7 +4259,7 @@ Label destruction o</programlisting> <function>mpo_execve_will_transition</function>.</para> </sect4> - <sect4 id="mac-mpo-execve-will-transition"> + <sect4 xml:id="mac-mpo-execve-will-transition"> <title><function>&mac.mpo;_execve_will_transition</function></title> <funcsynopsis> @@ -4326,7 +4314,7 @@ Label destruction o</programlisting> transition.</para> </sect4> - <sect4 id="mac-mpo-create-proc0"> + <sect4 xml:id="mac-mpo-create-proc0"> <title><function>&mac.mpo;_create_proc0</function></title> <funcsynopsis> @@ -4356,7 +4344,7 @@ Label destruction o</programlisting> of all kernel processes.</para> </sect4> - <sect4 id="mac-mpo-create-proc1"> + <sect4 xml:id="mac-mpo-create-proc1"> <title><function>&mac.mpo;_create_proc1</function></title> <funcsynopsis> @@ -4386,7 +4374,7 @@ Label destruction o</programlisting> of all user processes.</para> </sect4> - <sect4 id="mac-mpo-relabel-cred"> + <sect4 xml:id="mac-mpo-relabel-cred"> <title><function>&mac.mpo;_relabel_cred</function></title> <funcsynopsis> @@ -4427,7 +4415,7 @@ Label destruction o</programlisting> </sect3> </sect2> - <sect2 id="mac-access-control-checks"> + <sect2 xml:id="mac-access-control-checks"> <title>Access Control Checks</title> <para>Access control entry points permit policy modules to @@ -4455,15 +4443,15 @@ Label destruction o</programlisting> <entry><errorcode>EDEADLK</errorcode></entry></row> <row> - <entry></entry> + <entry/> <entry><errorcode>EINVAL</errorcode></entry> </row> <row> - <entry></entry> + <entry/> <entry><errorcode>ESRCH</errorcode></entry> </row> <row> - <entry></entry> + <entry/> <entry>EACCES</entry> </row> <row> @@ -4481,7 +4469,7 @@ Label destruction o</programlisting> failures, invalid arguments, object not present, access not permitted, other.</para> - <sect3 id="mac-mpo-bpfdesc-check-receive-from-ifnet"> + <sect3 xml:id="mac-mpo-bpfdesc-check-receive-from-ifnet"> <title><function>&mac.mpo;_check_bpfdesc_receive</function></title> <funcsynopsis> @@ -4539,7 +4527,7 @@ Label destruction o</programlisting> <errorcode>EPERM</errorcode> for lack of privilege.</para> </sect3> - <sect3 id="mac-mpo-check-kenv-dump"> + <sect3 xml:id="mac-mpo-check-kenv-dump"> <title><function>&mac.mpo;_check_kenv_dump</function></title> <funcsynopsis> @@ -4569,7 +4557,7 @@ Label destruction o</programlisting> retrieve the kernel environment (see &man.kenv.2;).</para> </sect3> - <sect3 id="mac-mpo-check-kenv-get"> + <sect3 xml:id="mac-mpo-check-kenv-get"> <title><function>&mac.mpo;_check_kenv_get</function></title> <funcsynopsis> @@ -4606,7 +4594,7 @@ Label destruction o</programlisting> variable.</para> </sect3> - <sect3 id="mac-mpo-check-kenv-set"> + <sect3 xml:id="mac-mpo-check-kenv-set"> <title><function>&mac.mpo;_check_kenv_set</function></title> <funcsynopsis> @@ -4642,7 +4630,7 @@ Label destruction o</programlisting> the specified kernel environment variable.</para> </sect3> - <sect3 id="mac-mpo-check-kenv-unset"> + <sect3 xml:id="mac-mpo-check-kenv-unset"> <title><function>&mac.mpo;_check_kenv_unset</function></title> <funcsynopsis> @@ -4678,7 +4666,7 @@ Label destruction o</programlisting> the specified kernel environment variable.</para> </sect3> - <sect3 id="mac-mpo-check-kld-load"> + <sect3 xml:id="mac-mpo-check-kld-load"> <title><function>&mac.mpo;_check_kld_load</function></title> <funcsynopsis> @@ -4723,7 +4711,7 @@ Label destruction o</programlisting> the specified module file.</para> </sect3> - <sect3 id="mac-mpo-check-kld-stat"> + <sect3 xml:id="mac-mpo-check-kld-stat"> <title><function>&mac.mpo;_check_kld_stat</function></title> <funcsynopsis> @@ -4754,7 +4742,7 @@ Label destruction o</programlisting> statistics.</para> </sect3> - <sect3 id="mac-mpo-check-kld-unload"> + <sect3 xml:id="mac-mpo-check-kld-unload"> <title><function>&mac.mpo;_check_kld_unload</function></title> <funcsynopsis> @@ -4784,7 +4772,7 @@ Label destruction o</programlisting> unload a kernel module.</para> </sect3> - <sect3 id="mac-mpo-check-pipe-ioctl"> + <sect3 xml:id="mac-mpo-check-pipe-ioctl"> <title><function>&mac.mpo;_check_pipe_ioctl</function></title> <funcsynopsis> @@ -4842,7 +4830,7 @@ Label destruction o</programlisting> the specified &man.ioctl.2; call.</para> </sect3> - <sect3 id="mac-mpo-check-pipe-poll"> + <sect3 xml:id="mac-mpo-check-pipe-poll"> <title><function>&mac.mpo;_check_pipe_poll</function></title> <funcsynopsis> @@ -4887,7 +4875,7 @@ Label destruction o</programlisting> <parameter>pipe</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-pipe-read"> + <sect3 xml:id="mac-mpo-check-pipe-read"> <title><function>&mac.mpo;_check_pipe_read</function></title> <funcsynopsis> @@ -4932,7 +4920,7 @@ Label destruction o</programlisting> access to <parameter>pipe</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-pipe-relabel"> + <sect3 xml:id="mac-mpo-check-pipe-relabel"> <title><function>&mac.mpo;_check_pipe_relabel</function></title> <funcsynopsis> @@ -4985,7 +4973,7 @@ Label destruction o</programlisting> relabel <parameter>pipe</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-pipe-stat"> + <sect3 xml:id="mac-mpo-check-pipe-stat"> <title><function>&mac.mpo;_check_pipe_stat</function></title> <funcsynopsis> @@ -5031,7 +5019,7 @@ Label destruction o</programlisting> <parameter>pipe</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-pipe-write"> + <sect3 xml:id="mac-mpo-check-pipe-write"> <title><function>&mac.mpo;_check_pipe_write</function></title> <funcsynopsis> @@ -5076,7 +5064,7 @@ Label destruction o</programlisting> to <parameter>pipe</parameter>.</para> </sect3> - <sect3 id="mac-mpo-cred-check-socket-bind"> + <sect3 xml:id="mac-mpo-cred-check-socket-bind"> <title><function>&mac.mpo;_check_socket_bind</function></title> <funcsynopsis> @@ -5128,7 +5116,7 @@ Label destruction o</programlisting> </sect3> - <sect3 id="mac-mpo-cred-check-socket-connect"> + <sect3 xml:id="mac-mpo-cred-check-socket-connect"> <title><function>&mac.mpo;_check_socket_connect</function></title> <funcsynopsis> @@ -5187,7 +5175,7 @@ Label destruction o</programlisting> <errorcode>EPERM</errorcode> for lack of privilege.</para> </sect3> - <sect3 id="mac-mpo-check-socket-receive"> + <sect3 xml:id="mac-mpo-check-socket-receive"> <title><function>&mac.mpo;_check_socket_receive</function></title> <funcsynopsis> @@ -5233,7 +5221,7 @@ Label destruction o</programlisting> <parameter>so</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-socket-send"> + <sect3 xml:id="mac-mpo-check-socket-send"> <title><function>&mac.mpo;_check_socket_send</function></title> <funcsynopsis> @@ -5279,7 +5267,7 @@ Label destruction o</programlisting> <parameter>so</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-cred-visible"> + <sect3 xml:id="mac-mpo-check-cred-visible"> <title><function>&mac.mpo;_check_cred_visible</function></title> <funcsynopsis> @@ -5326,7 +5314,7 @@ Label destruction o</programlisting> and in procfs lookups.</para> </sect3> - <sect3 id="mac-mpo-cred-check-socket-visible"> + <sect3 xml:id="mac-mpo-cred-check-socket-visible"> <title><function>&mac.mpo;_check_socket_visible</function></title> <funcsynopsis> @@ -5369,7 +5357,7 @@ Label destruction o</programlisting> </sect3> - <sect3 id="mac-mpo-cred-check-ifnet-relabel"> + <sect3 xml:id="mac-mpo-cred-check-ifnet-relabel"> <title><function>&mac.mpo;_check_ifnet_relabel</function></title> <funcsynopsis> @@ -5422,7 +5410,7 @@ Label destruction o</programlisting> passed network interface to the passed label update.</para> </sect3> - <sect3 id="mac-mpo-cred-check-socket-relabel"> + <sect3 xml:id="mac-mpo-cred-check-socket-relabel"> <title><function>&mac.mpo;_check_socket_relabel</function></title> <funcsynopsis> @@ -5475,7 +5463,7 @@ Label destruction o</programlisting> passed socket to the passed label update.</para> </sect3> - <sect3 id="mac-mpo-cred-check-cred-relabel"> + <sect3 xml:id="mac-mpo-cred-check-cred-relabel"> <title><function>&mac.mpo;_check_cred_relabel</function></title> <funcsynopsis> @@ -5514,7 +5502,7 @@ Label destruction o</programlisting> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-relabel"> + <sect3 xml:id="mac-mpo-cred-check-vnode-relabel"> <title><function>&mac.mpo;_check_vnode_relabel</function></title> <funcsynopsis> @@ -5569,7 +5557,7 @@ Label destruction o</programlisting> passed vnode to the passed label update.</para> </sect3> - <sect3 id="mpo-cred-check-mount-stat"> + <sect3 xml:id="mpo-cred-check-mount-stat"> <title><function>&mac.mpo;_check_mount_stat</function></title> <funcsynopsis> @@ -5622,7 +5610,7 @@ Label destruction o</programlisting> systems, such as when &man.getfsstat.2; is invoked. </para> </sect3> - <sect3 id="mac-mpo-cred-check-proc-debug"> + <sect3 xml:id="mac-mpo-cred-check-proc-debug"> <title><function>&mac.mpo;_check_proc_debug</function></title> <funcsynopsis> @@ -5668,7 +5656,7 @@ Label destruction o</programlisting> operations.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-access"> + <sect3 xml:id="mac-mpo-cred-check-vnode-access"> <title><function>&mac.mpo;_check_vnode_access</function></title> <funcsynopsis> @@ -5727,7 +5715,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-chdir"> + <sect3 xml:id="mac-mpo-cred-check-vnode-chdir"> <title><function>&mac.mpo;_check_vnode_chdir</function></title> <funcsynopsis> @@ -5777,7 +5765,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-chroot"> + <sect3 xml:id="mac-mpo-check-vnode-chroot"> <title><function>&mac.mpo;_check_vnode_chroot</function></title> <funcsynopsis> @@ -5823,7 +5811,7 @@ Label destruction o</programlisting> (<parameter>dvp</parameter>).</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-create"> + <sect3 xml:id="mac-mpo-cred-check-vnode-create"> <title><function>&mac.mpo;_check_vnode_create</function></title> <funcsynopsis> @@ -5892,7 +5880,7 @@ Label destruction o</programlisting> others.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-delete"> + <sect3 xml:id="mac-mpo-cred-check-vnode-delete"> <title><function>&mac.mpo;_check_vnode_delete</function></title> <funcsynopsis> @@ -5970,7 +5958,7 @@ Label destruction o</programlisting> rename.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-deleteacl"> + <sect3 xml:id="mac-mpo-cred-check-vnode-deleteacl"> <title><function>&mac.mpo;_check_vnode_deleteacl</function></title> <funcsynopsis> @@ -6025,7 +6013,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-exec"> + <sect3 xml:id="mac-mpo-cred-check-vnode-exec"> <title><function>&mac.mpo;_check_vnode_exec</function></title> <funcsynopsis> @@ -6076,7 +6064,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mpo-cred-check-vnode-getacl"> + <sect3 xml:id="mpo-cred-check-vnode-getacl"> <title><function>&mac.mpo;_check_vnode_getacl</function></title> <funcsynopsis> @@ -6133,7 +6121,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-getextattr"> + <sect3 xml:id="mac-mpo-cred-check-vnode-getextattr"> <title><function>&mac.mpo;_check_vnode_getextattr</function></title> <funcsynopsis> @@ -6207,7 +6195,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-link"> + <sect3 xml:id="mac-mpo-check-vnode-link"> <title><function>&mac.mpo;_check_vnode_link</function></title> <funcsynopsis> @@ -6275,7 +6263,7 @@ Label destruction o</programlisting> the name specified by <parameter>cnp</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-mmap"> + <sect3 xml:id="mac-mpo-check-vnode-mmap"> <title><function>&mac.mpo;_check_vnode_mmap</function></title> <funcsynopsis> @@ -6327,7 +6315,7 @@ Label destruction o</programlisting> specified in <parameter>prot</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-mmap-downgrade"> + <sect3 xml:id="mac-mpo-check-vnode-mmap-downgrade"> <title><function>&mac.mpo;_check_vnode_mmap_downgrade</function></title> <funcsynopsis> @@ -6376,7 +6364,7 @@ Label destruction o</programlisting> object labels.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-mprotect"> + <sect3 xml:id="mac-mpo-check-vnode-mprotect"> <title><function>&mac.mpo;_check_vnode_mprotect</function></title> <funcsynopsis> @@ -6422,7 +6410,7 @@ Label destruction o</programlisting> the vnode <parameter>vp</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-poll"> + <sect3 xml:id="mac-mpo-check-vnode-poll"> <title><function>&mac.mpo;_check_vnode_poll</function></title> <funcsynopsis> @@ -6475,7 +6463,7 @@ Label destruction o</programlisting> the vnode <parameter>vp</parameter>.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-rename-from"> + <sect3 xml:id="mac-mpo-check-vnode-rename-from"> <title><function>&mac.mpo;_check_vnode_rename_from</function></title> <funcsynopsis> @@ -6544,7 +6532,7 @@ Label destruction o</programlisting> else.</para> </sect3> - <sect3 id="mac-mpo-check-vnode-rename-to"> + <sect3 xml:id="mac-mpo-check-vnode-rename-to"> <title><function>&mac.mpo;_check_vnode_rename_to</function></title> <funcsynopsis> @@ -6622,7 +6610,7 @@ Label destruction o</programlisting> <parameter>label</parameter> will be NULL.</para> </sect3> - <sect3 id="mac-mpo-cred-check-socket-listen"> + <sect3 xml:id="mac-mpo-cred-check-socket-listen"> <title><function>&mac.mpo;_check_socket_listen</function></title> <funcsynopsis> @@ -6671,7 +6659,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-lookup"> + <sect3 xml:id="mac-mpo-cred-check-vnode-lookup"> <title><function>&mac.mpo;_check_vnode_lookup</function></title> <funcsynopsis> @@ -6680,11 +6668,11 @@ Label destruction o</programlisting> <function>&mac.mpo;_check_vnode_lookup</function></funcdef> <paramdef>struct ucred - *<parameter></parameter>cred</paramdef> + *<parameter/>cred</paramdef> <paramdef>struct vnode - *<parameter></parameter>dvp</paramdef> + *<parameter/>dvp</paramdef> <paramdef>struct label - *<parameter></parameter>dlabel</paramdef> + *<parameter/>dlabel</paramdef> <paramdef>struct componentname *<parameter>cnp</parameter></paramdef> </funcprototype> @@ -6728,7 +6716,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-open"> + <sect3 xml:id="mac-mpo-cred-check-vnode-open"> <title><function>&mac.mpo;_check_vnode_open</function></title> <funcsynopsis> @@ -6784,7 +6772,7 @@ Label destruction o</programlisting> <errorcode>EPERM</errorcode> for lack of privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-readdir"> + <sect3 xml:id="mac-mpo-cred-check-vnode-readdir"> <title><function>&mac.mpo;_check_vnode_readdir</function></title> <funcsynopsis> @@ -6793,11 +6781,11 @@ Label destruction o</programlisting> <function>&mac.mpo;_check_vnode_readdir</function></funcdef> <paramdef>struct ucred - *<parameter></parameter>cred</paramdef> + *<parameter/>cred</paramdef> <paramdef>struct vnode - *<parameter></parameter>dvp</paramdef> + *<parameter/>dvp</paramdef> <paramdef>struct label - *<parameter></parameter>dlabel</paramdef> + *<parameter/>dlabel</paramdef> </funcprototype> </funcsynopsis> @@ -6834,7 +6822,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-readlink"> + <sect3 xml:id="mac-mpo-cred-check-vnode-readlink"> <title><function>&mac.mpo;_check_vnode_readlink</function></title> <funcsynopsis> @@ -6888,7 +6876,7 @@ Label destruction o</programlisting> process.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-revoke"> + <sect3 xml:id="mac-mpo-cred-check-vnode-revoke"> <title><function>&mac.mpo;_check_vnode_revoke</function></title> <funcsynopsis> @@ -6938,7 +6926,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-setacl"> + <sect3 xml:id="mac-mpo-cred-check-vnode-setacl"> <title><function>&mac.mpo;_check_vnode_setacl</function></title> <funcsynopsis> @@ -7002,7 +6990,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-setextattr"> + <sect3 xml:id="mac-mpo-cred-check-vnode-setextattr"> <title><function>&mac.mpo;_check_vnode_setextattr</function></title> <funcsynopsis> @@ -7080,7 +7068,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-setflags"> + <sect3 xml:id="mac-mpo-cred-check-vnode-setflags"> <title><function>&mac.mpo;_check_vnode_setflags</function></title> <funcsynopsis> @@ -7136,7 +7124,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-setmode"> + <sect3 xml:id="mac-mpo-cred-check-vnode-setmode"> <title><function>&mac.mpo;_check_vnode_setmode</function></title> <funcsynopsis> @@ -7191,7 +7179,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-setowner"> + <sect3 xml:id="mac-mpo-cred-check-vnode-setowner"> <title><function>&mac.mpo;_check_vnode_setowner</function></title> <funcsynopsis> @@ -7253,7 +7241,7 @@ Label destruction o</programlisting> of privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-setutimes"> + <sect3 xml:id="mac-mpo-cred-check-vnode-setutimes"> <title><function>&mac.mpo;_check_vnode_setutimes</function></title> <funcsynopsis> @@ -7262,15 +7250,15 @@ Label destruction o</programlisting> <function>&mac.mpo;_check_vnode_setutimes</function></funcdef> <paramdef>struct ucred - *<parameter></parameter>cred</paramdef> + *<parameter/>cred</paramdef> <paramdef>struct vnode - *<parameter></parameter>vp</paramdef> + *<parameter/>vp</paramdef> <paramdef>struct label - *<parameter></parameter>label</paramdef> + *<parameter/>label</paramdef> <paramdef>struct timespec - <parameter></parameter>atime</paramdef> + <parameter/>atime</paramdef> <paramdef>struct timespec - <parameter></parameter>mtime</paramdef> + <parameter/>mtime</paramdef> </funcprototype> </funcsynopsis> @@ -7317,7 +7305,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-proc-sched"> + <sect3 xml:id="mac-mpo-cred-check-proc-sched"> <title><function>&mac.mpo;_check_proc_sched</function></title> <funcsynopsis> @@ -7361,7 +7349,7 @@ Label destruction o</programlisting> <para>See &man.setpriority.2; for more information.</para> </sect3> - <sect3 id="mac-mpo-cred-check-proc-signal"> + <sect3 xml:id="mac-mpo-cred-check-proc-signal"> <title><function>&mac.mpo;_check_proc_signal</function></title> <funcsynopsis> @@ -7409,7 +7397,7 @@ Label destruction o</programlisting> <errorcode>ESRCH</errorcode> to limit visibility.</para> </sect3> - <sect3 id="mac-mpo-cred-check-vnode-stat"> + <sect3 xml:id="mac-mpo-cred-check-vnode-stat"> <title><function>&mac.mpo;_check_vnode_stat</function></title> <funcsynopsis> @@ -7461,7 +7449,7 @@ Label destruction o</programlisting> <para>See &man.stat.2; for more information.</para> </sect3> - <sect3 id="mac-mpo-cred-check-ifnet-transmit"> + <sect3 xml:id="mac-mpo-cred-check-ifnet-transmit"> <title><function>&mac.mpo;_check_ifnet_transmit</function></title> <funcsynopsis> @@ -7525,7 +7513,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-cred-check-socket-deliver"> + <sect3 xml:id="mac-mpo-cred-check-socket-deliver"> <title><function>&mac.mpo;_check_socket_deliver</function></title> <funcsynopsis> @@ -7590,7 +7578,7 @@ Label destruction o</programlisting> privilege.</para> </sect3> - <sect3 id="mac-mpo-check-socket-visible"> + <sect3 xml:id="mac-mpo-check-socket-visible"> <title><function>&mac.mpo;_check_socket_visible</function></title> <funcsynopsis> @@ -7643,7 +7631,7 @@ Label destruction o</programlisting> <errorcode>ESRCH</errorcode> to hide visibility.</para> </sect3> - <sect3 id="mac-mpo-check-system-acct"> + <sect3 xml:id="mac-mpo-check-system-acct"> <title><function>&mac.mpo;_check_system_acct</function></title> <funcsynopsis> @@ -7689,7 +7677,7 @@ Label destruction o</programlisting> accounting log file.</para> </sect3> - <sect3 id="mac-mpo-check-system-nfsd"> + <sect3 xml:id="mac-mpo-check-system-nfsd"> <title><function>&mac.mpo;_check_system_nfsd</function></title> <funcsynopsis> @@ -7719,7 +7707,7 @@ Label destruction o</programlisting> &man.nfssvc.2;.</para> </sect3> - <sect3 id="mac-mpo-check-system-reboot"> + <sect3 xml:id="mac-mpo-check-system-reboot"> <title><function>&mac.mpo;_check_system_reboot</function></title> <funcsynopsis> @@ -7756,7 +7744,7 @@ Label destruction o</programlisting> reboot the system in the specified manner.</para> </sect3> - <sect3 id="mac-mpo-check-system-settime"> + <sect3 xml:id="mac-mpo-check-system-settime"> <title><function>&mac.mpo;_check_system_settime</function></title> <funcsynopsis> @@ -7786,7 +7774,7 @@ Label destruction o</programlisting> system clock.</para> </sect3> - <sect3 id="mac-mpo-check-system-swapon"> + <sect3 xml:id="mac-mpo-check-system-swapon"> <title><function>&mac.mpo;_check_system_swapon</function></title> <funcsynopsis> @@ -7831,7 +7819,7 @@ Label destruction o</programlisting> <parameter>vp</parameter> as a swap device.</para> </sect3> - <sect3 id="mac-mpo-check-system-sysctl"> + <sect3 xml:id="mac-mpo-check-system-sysctl"> <title><function>&mac.mpo;_check_system_sysctl</function></title> <funcsynopsis> @@ -7902,7 +7890,7 @@ Label destruction o</programlisting> </sect3> </sect2> - <sect2 id="mac-label-management"> + <sect2 xml:id="mac-label-management"> <title>Label Management Calls</title> <para>Relabel events occur when a user process has requested @@ -7919,7 +7907,7 @@ Label destruction o</programlisting> </sect2> </sect1> - <sect1 id="mac-userland-arch"> + <sect1 xml:id="mac-userland-arch"> <title>Userland Architecture</title> <para>The TrustedBSD MAC Framework includes a number of @@ -7931,7 +7919,7 @@ Label destruction o</programlisting> interfaces. More details on the user architecture will be added to this section in the near future.</para> - <sect2 id="mac-userland-labels"> + <sect2 xml:id="mac-userland-labels"> <title>APIs for Policy-Agnostic Label Management</title> <para>The TrustedBSD MAC Framework provides a number of @@ -7980,7 +7968,7 @@ Label destruction o</programlisting> writers.</para></note> </sect2> - <sect2 id="mac-userland-credentials"> + <sect2 xml:id="mac-userland-credentials"> <title>Binding of Labels to Users</title> <para>The standard user context management interface, @@ -8001,7 +7989,7 @@ Label destruction o</programlisting> </sect2> </sect1> - <sect1 id="mac-conclusion"> + <sect1 xml:id="mac-conclusion"> <title>Conclusion</title> <para>The TrustedBSD MAC framework permits kernel modules to diff --git a/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.xml index 48df641aa6..e038e49f2f 100644 --- a/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/newbus/chapter.xml @@ -22,27 +22,18 @@ Provided under the FreeBSD Documentation License. --> -<chapter id="newbus"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="newbus"> + <info><title>Newbus</title> <authorgroup> - <author> - <firstname>Jeroen</firstname> - <surname>Ruigrok van der Werven (asmodai)</surname> - <affiliation> + <author><personname><firstname>Jeroen</firstname><surname>Ruigrok van der Werven (asmodai)</surname></personname><affiliation> <address><email>asmodai@FreeBSD.org</email></address> - </affiliation> - <contrib>Written by </contrib> - </author> - <author> - <firstname>Hiten</firstname> - <surname>Pandya</surname> - <affiliation> + </affiliation><contrib>Written by </contrib></author> + <author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname><affiliation> <address><email>hiten@uk.FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - </chapterinfo> - <title>Newbus</title> + </info> + <para><emphasis>Special thanks to Matthew N. Dodd, Warner Losh, Bill Paul, Doug Rabson, Mike Smith, Peter Wemm and Scott @@ -51,7 +42,7 @@ <para>This chapter explains the Newbus device framework in detail.</para> - <sect1 id="newbus-devdrivers"> + <sect1 xml:id="newbus-devdrivers"> <title>Device Drivers</title> <sect2> @@ -106,7 +97,7 @@ </sect2> </sect1> - <sect1 id="newbus-overview"> + <sect1 xml:id="newbus-overview"> <!-- Real title: Newbus, Busspace and the Resource Manager, an Explanation of the Possibilities @@ -161,9 +152,9 @@ device, which normally has one child for the attached bus. An example of this is a <emphasis>PCI-to-PCI bridge</emphasis> which is represented by a device - <emphasis><devicename>pcibN</devicename></emphasis> on the + <emphasis><filename>pcibN</filename></emphasis> on the parent PCI bus and has a child - <emphasis><devicename>pciN</devicename></emphasis> for the + <emphasis><filename>pciN</filename></emphasis> for the attached bus. This layout simplifies the implementation of the PCI bus tree, allowing common code to be used for both top-level and bridged busses.</para> @@ -203,8 +194,8 @@ <para>This support is integrated into the resource allocation mechanism. When a resource is allocated, a driver can retrieve - the associated <structfield>bus_space_tag_t</structfield> and - <structfield>bus_space_handle_t</structfield> from the + the associated <varname remap="structfield">bus_space_tag_t</varname> and + <varname remap="structfield">bus_space_handle_t</varname> from the resource.</para> <para>Newbus also allows for definitions of interface methods in @@ -319,7 +310,7 @@ accessing the configuration registers of a PCI device.</para> </sect1> - <sect1 id="newbus-api"> + <sect1 xml:id="newbus-api"> <title>Newbus API</title> <para>As the Newbus API is huge, this section makes some effort at diff --git a/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.xml index b894c1e68e..a9a2753d9a 100644 --- a/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/pccard/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="pccard"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="pccard"> <title>PC Card</title> <indexterm><primary>PC Card</primary></indexterm> @@ -16,14 +15,14 @@ at present it just documents how to add a new device to an existing pccard driver.</para> - <sect1 id="pccard-adddev"> + <sect1 xml:id="pccard-adddev"> <title>Adding a Device</title> <para>Device drivers know what devices they support. There is a table of supported devices in the kernel that drivers use to attach to a device.</para> - <sect2 id="pccard-overview"> + <sect2 xml:id="pccard-overview"> <title>Overview</title> <indexterm><primary>CIS</primary></indexterm> @@ -85,7 +84,7 @@ adding new devices, prefer using the numeric method.</para> </sect2> - <sect2 id="pccard-pccarddevs"> + <sect2 xml:id="pccard-pccarddevs"> <title>Format of <filename>pccarddevs</filename></title> <para>There are four sections in the @@ -199,7 +198,7 @@ product ALLIEDTELESIS WR211PCM { "Allied&spTelesis&spK.K.", "WR211PCM", available at this time.</para> </sect2> - <sect2 id="pccard-probe"> + <sect2 xml:id="pccard-probe"> <title>Sample Probe Routine</title> <indexterm> @@ -248,11 +247,11 @@ wi_pccard_probe(dev) the rest of the driver, so there may be some variance in the table. The only requirement is that each row of the table must have a <function>struct</function> - <structname>pccard_product</structname> as the first + <varname remap="structname">pccard_product</varname> as the first element.</para> <para>Looking at the table - <structname>wi_pccard_products</structname>, one notices that + <varname remap="structname">wi_pccard_products</varname>, one notices that all the entries are of the form <function>PCMCIA_CARD(<replaceable>foo</replaceable>, <replaceable>bar</replaceable>, @@ -273,7 +272,7 @@ wi_pccard_probe(dev) description from pccarddevs</quote> flavors.</para> </sect2> - <sect2 id="pccard-add"> + <sect2 xml:id="pccard-add"> <title>Putting it All Together</title> <para>To add a new device, one must first obtain the @@ -348,7 +347,7 @@ product BUFFALO WLI_CF_S11G 0x030b BUFFALO AirStation 11Mbps CF WLAN</programlis Finally, commit the additions to the driver.</para> </sect2> - <sect2 id="pccard-pr"> + <sect2 xml:id="pccard-pr"> <title>Submitting a New Device</title> <para>Please do not send entries for new devices to the author diff --git a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml index 15a70da312..592096c867 100644 --- a/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/pci/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="pci"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="pci"> <title>PCI Devices</title> <indexterm><primary>PCI bus</primary></indexterm> @@ -13,7 +12,7 @@ <para>This chapter will talk about the FreeBSD mechanisms for writing a device driver for a device on a PCI bus.</para> - <sect1 id="pci-probe"> + <sect1 xml:id="pci-probe"> <title>Probe and Attach</title> <para>Information here about how the PCI bus code iterates through @@ -253,8 +252,8 @@ SRCS+= device_if.h bus_if.h pci_if.h <sect2> <title>Additional Resources</title> <itemizedlist> - <listitem><simpara><ulink url="http://www.pcisig.org/">PCI - Special Interest Group</ulink></simpara></listitem> + <listitem><simpara><link xlink:href="http://www.pcisig.org/">PCI + Special Interest Group</link></simpara></listitem> <listitem><simpara>PCI System Architecture, Fourth Edition by Tom Shanley, et al.</simpara></listitem> @@ -263,7 +262,7 @@ SRCS+= device_if.h bus_if.h pci_if.h </sect2> </sect1> - <sect1 id="pci-bus"> + <sect1 xml:id="pci-bus"> <title>Bus Resources</title> <indexterm><primary>PCI bus</primary><secondary>resources</secondary></indexterm> @@ -310,7 +309,7 @@ SRCS+= device_if.h bus_if.h pci_if.h sc->bar1_bh = rman_get_bushandle(sc->bar1res);</programlisting> <para>Handles for each base address register are kept in the - <structname>softc</structname> structure so that they can be + <varname remap="structname">softc</varname> structure so that they can be used to write to the device later.</para> <para>These handles can then be used to read or write from the @@ -346,7 +345,7 @@ board_write(struct ni_softc *sc, uint16_t address, uint16_t value) <function>bus_*</function> functions take a <type>struct resource *</type> pointer instead of a bus tag and handle. Thus, you could drop the bus tag and bus handle members from - the <structname>softc</structname> and rewrite the + the <varname remap="structname">softc</varname> and rewrite the <function>board_read()</function> function as:</para> <programlisting>uint16_t diff --git a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml index 8e94b8904e..f29a4c88cd 100644 --- a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml @@ -4,28 +4,19 @@ $FreeBSD$ --> - -<chapter id="scsi"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="scsi"> + <info><title>Common Access Method SCSI Controllers</title> <authorgroup> - <author> - <firstname>Sergey</firstname> - <surname>Babkin</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Sergey</firstname><surname>Babkin</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Modifications for Handbook made by </contrib> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Modifications for Handbook made by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Common Access Method SCSI Controllers</title> + - <sect1 id="scsi-synopsis"> + <sect1 xml:id="scsi-synopsis"> <title>Synopsis</title> <indexterm><primary>SCSI</primary></indexterm> @@ -71,7 +62,7 @@ can be found in the real drivers.</para> </sect1> - <sect1 id="scsi-general"> + <sect1 xml:id="scsi-general"> <title>General Architecture</title> <indexterm> @@ -163,17 +154,17 @@ }</programlisting> <para>Note that if we are not able to create a SIM descriptor we - free the <structname>devq</structname> also because we can do + free the <varname remap="structname">devq</varname> also because we can do nothing else with it and we want to conserve memory.</para> <para>If a SCSI card has multiple SCSI buses<indexterm><primary>SCSI</primary><secondary>bus</secondary></indexterm> on it then each bus requires its own - <structname>cam_sim</structname> structure.</para> + <varname remap="structname">cam_sim</varname> structure.</para> <para>An interesting question is what to do if a SCSI card has more than one SCSI bus, do we need one - <structname>devq</structname> structure per card or per SCSI + <varname remap="structname">devq</varname> structure per card or per SCSI bus? The answer given in the comments to the CAM code is: either way, as the driver's author prefers.</para> @@ -218,7 +209,7 @@ </listitem> <listitem> - <para><structname>softc</structname> - pointer to the driver's + <para><varname remap="structname">softc</varname> - pointer to the driver's internal descriptor for this SCSI card. This pointer will be used by the driver in future to get private data.</para> @@ -262,7 +253,7 @@ error; /* some code to handle the error */ }</programlisting> - <para>If there is one <structname>devq</structname> structure per + <para>If there is one <varname remap="structname">devq</varname> structure per SCSI bus (i.e., we consider a card with multiple buses as multiple cards with one bus each) then the bus number will always be 0, otherwise each bus on the SCSI card should be get a @@ -270,7 +261,7 @@ cam_sim.</para> <para>After that our controller is completely hooked to the CAM - system. The value of <structname>devq</structname> can be + system. The value of <varname remap="structname">devq</varname> can be discarded now: sim will be passed as an argument in all further calls from CAM and devq can be derived from it.</para> @@ -339,7 +330,7 @@ bus.</para> <para>And we save the path pointer in the - <structname>softc</structname> structure for future use. After + <varname remap="structname">softc</varname> structure for future use. After that we save the value of sim (or we can also discard it on the exit from <function>xxx_probe()</function> if we wish).</para> @@ -426,7 +417,7 @@ these functions.</para> <para>The type of request is stored in - <structfield>ccb->ccb_h.func_code</structfield>. So + <varname remap="structfield">ccb->ccb_h.func_code</varname>. So generally <function>xxx_action()</function> consists of a big switch:</para> @@ -446,7 +437,7 @@ <para>As can be seen from the default case (if an unknown command was received) the return code of the command is set into - <structfield>ccb->ccb_h.status</structfield> and the + <varname remap="structfield">ccb->ccb_h.status</varname> and the completed CCB is returned back to CAM by calling <function>xpt_done(ccb)</function>.</para> @@ -1626,7 +1617,7 @@ </itemizedlist> </sect1> - <sect1 id="scsi-polling"> + <sect1 xml:id="scsi-polling"> <title>Polling</title> <funcsynopsis> @@ -1652,7 +1643,7 @@ <function>xxx_poll</function> routine gets the struct cam_sim pointer as its argument when the PCI interrupt routine by common convention gets pointer to the struct - <structname>xxx_softc</structname> and the ISA interrupt routine + <varname remap="structname">xxx_softc</varname> and the ISA interrupt routine gets just the device unit number. So the poll routine would normally look as:</para> @@ -1671,7 +1662,7 @@ xxx_poll(struct cam_sim *sim) }</programlisting> </sect1> - <sect1 id="scsi-async"> + <sect1 xml:id="scsi-async"> <title>Asynchronous Events</title> <para>If an asynchronous event callback has been set up then the @@ -1728,7 +1719,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< }</programlisting> </sect1> - <sect1 id="scsi-interrupts"> + <sect1 xml:id="scsi-interrupts"> <title>Interrupts</title> <indexterm><primary>SCSI</primary><secondary>interrupts</secondary></indexterm> @@ -2093,7 +2084,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< specific controllers may require some additions.</para> </sect1> - <sect1 id="scsi-errors"> + <sect1 xml:id="scsi-errors"> <title>Errors Summary</title> <indexterm><primary>SCSI</primary><secondary>errors</secondary></indexterm> @@ -2208,7 +2199,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< </itemizedlist> </sect1> - <sect1 id="scsi-timeout"> + <sect1 xml:id="scsi-timeout"> <title>Timeout Handling</title> <para>When the timeout for an HCB expires that request should be diff --git a/en_US.ISO8859-1/books/arch-handbook/smp/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/smp/chapter.xml index f6ab5e9985..6c1256b045 100644 --- a/en_US.ISO8859-1/books/arch-handbook/smp/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/smp/chapter.xml @@ -5,18 +5,11 @@ $FreeBSD$ --> -<chapter id="smp"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="smp"> + <info><title>SMPng Design Document</title> <authorgroup> - <author> - <firstname>John</firstname> - <surname>Baldwin</surname> - <contrib>Written by </contrib> - </author> - <author> - <firstname>Robert</firstname> - <surname>Watson</surname> - </author> + <author><personname><firstname>John</firstname><surname>Baldwin</surname></personname><contrib>Written by </contrib></author> + <author><personname><firstname>Robert</firstname><surname>Watson</surname></personname></author> </authorgroup> <copyright> @@ -26,11 +19,11 @@ <holder>John Baldwin</holder> <holder>Robert Watson</holder> </copyright> - </chapterinfo> + </info> - <title>SMPng Design Document</title> + - <sect1 id="smp-intro"> + <sect1 xml:id="smp-intro"> <title>Introduction</title> <indexterm><primary>SMP Next Generation</primary></indexterm> @@ -64,7 +57,7 @@ the <xref linkend="smp-glossary"/> section of this article.</para> </sect1> - <sect1 id="smp-lock-fundamentals"> + <sect1 xml:id="smp-lock-fundamentals"> <title>Basic Tools and Locking Fundamentals</title> <sect2> @@ -105,7 +98,7 @@ <function>atomic_cmpset</function> rather than an <function>atomic_set</function> to turn on the <constant>MTX_CONTESTED</constant> bit. The reason is that we - read the value of <structfield>mtx_lock</structfield> into a + read the value of <varname remap="structfield">mtx_lock</varname> into a variable and then make a decision based on that read. However, the value we read may be stale, or it may change while we are making our decision. Thus, when the @@ -172,7 +165,7 @@ </sect2> </sect1> - <sect1 id="smp-design"> + <sect1 xml:id="smp-design"> <title>General Architecture and Design</title> <sect2> @@ -498,7 +491,7 @@ </sect2> </sect1> - <sect1 id="smp-lock-strategies"> + <sect1 xml:id="smp-lock-strategies"> <title>Specific Locking Strategies</title> <sect2> @@ -506,7 +499,7 @@ <indexterm><primary>credentials</primary></indexterm> - <para><structname>struct ucred</structname> is the kernel's + <para><varname remap="structname">struct ucred</varname> is the kernel's internal credential structure, and is generally used as the basis for process-driven access control within the kernel. BSD-derived systems use a <quote>copy-on-write</quote> model @@ -524,35 +517,35 @@ <para>Credential structures with a single reference are considered mutable; shared credential structures must not be modified or a race condition is risked. A mutex, - <structfield>cr_mtxp</structfield> protects the reference - count of <structname>struct ucred</structname> so as to + <varname remap="structfield">cr_mtxp</varname> protects the reference + count of <varname remap="structname">struct ucred</varname> so as to maintain consistency. Any use of the structure requires a valid reference for the duration of the use, or the structure may be released out from under the illegitimate consumer.</para> - <para>The <structname>struct ucred</structname> mutex is a leaf + <para>The <varname remap="structname">struct ucred</varname> mutex is a leaf mutex and is implemented via a mutex pool for performance reasons.</para> <para>Usually, credentials are used in a read-only manner for access control decisions, and in this case - <structfield>td_ucred</structfield> is generally preferred + <varname remap="structfield">td_ucred</varname> is generally preferred because it requires no locking. When a process' credential is updated the <literal>proc</literal> lock must be held across the check and update operations thus avoid races. The process - credential <structfield>p_ucred</structfield> must be used for + credential <varname remap="structfield">p_ucred</varname> must be used for check and update operations to prevent time-of-check, time-of-use races.</para> <para>If system call invocations will perform access control after an update to the process credential, the value of - <structfield>td_ucred</structfield> must also be refreshed to + <varname remap="structfield">td_ucred</varname> must also be refreshed to the current process value. This will prevent use of a stale credential following a change. The kernel automatically - refreshes the <structfield>td_ucred</structfield> pointer in + refreshes the <varname remap="structfield">td_ucred</varname> pointer in the thread structure from the process - <structfield>p_ucred</structfield> whenever a process enters + <varname remap="structfield">p_ucred</varname> whenever a process enters the kernel, permitting use of a fresh credential for kernel access control.</para> </sect2> @@ -568,17 +561,17 @@ <indexterm><primary>Jail</primary></indexterm> - <para><structname>struct prison</structname> stores + <para><varname remap="structname">struct prison</varname> stores administrative details pertinent to the maintenance of jails created using the &man.jail.2; API. This includes the per-jail hostname, IP address, and related settings. This structure is reference-counted since pointers to instances of the structure are shared by many credential structures. A - single mutex, <structfield>pr_mtx</structfield> protects read + single mutex, <varname remap="structfield">pr_mtx</varname> protects read and write access to the reference count and all mutable variables inside the struct jail. Some variables are set only when the jail is created, and a valid reference to the - <structname>struct prison</structname> is sufficient to read + <varname remap="structname">struct prison</varname> is sufficient to read these values. The precise locking of each entry is documented via comments in <filename>sys/jail.h</filename>.</para> </sect2> @@ -589,11 +582,11 @@ <indexterm><primary>MAC</primary></indexterm> <para>The TrustedBSD MAC Framework maintains data in a variety - of kernel objects, in the form of <structname>struct - label</structname>. In general, labels in kernel objects + of kernel objects, in the form of <varname remap="structname">struct + label</varname>. In general, labels in kernel objects are protected by the same lock as the remainder of the kernel - object. For example, the <structfield>v_label</structfield> - label in <structname>struct vnode</structname> is protected + object. For example, the <varname remap="structfield">v_label</varname> + label in <varname remap="structname">struct vnode</varname> is protected by the vnode lock on the vnode.</para> <para>In addition to labels maintained in standard kernel objects, @@ -636,8 +629,8 @@ added to make access to the lock more easy. These macros can be located in <filename>sys/module.h</filename> and are quite basic in terms of usage. The main structures protected under this lock - are the <structname>module_t</structname> structures (when shared) - and the global <structname>modulelist_t</structname> structure, + are the <varname remap="structname">module_t</varname> structures (when shared) + and the global <varname remap="structname">modulelist_t</varname> structure, modules. One should review the related source code in <filename>kern/kern_module.c</filename> to further understand the locking strategy.</para> @@ -710,27 +703,27 @@ referred to as the owner. Each object supporting SIGIO registration contains pointer field that is <constant>NULL</constant> if the object is not registered, or - points to a <structname>struct sigio</structname> describing + points to a <varname remap="structname">struct sigio</varname> describing the registration. This field is protected by a global mutex, <varname>sigio_lock</varname>. Callers to SIGIO maintenance functions must pass in this field <quote>by reference</quote> so that local register copies of the field are not made when unprotected by the lock.</para> - <para>One <structname>struct sigio</structname> is allocated for + <para>One <varname remap="structname">struct sigio</varname> is allocated for each registered object associated with any process or process group, and contains back-pointers to the object, owner, signal information, a credential, and the general disposition of the registration. Each process or progress group contains a list of - registered <structname>struct sigio</structname> structures, - <structfield>p_sigiolst</structfield> for processes, and - <structfield>pg_sigiolst</structfield> for process groups. + registered <varname remap="structname">struct sigio</varname> structures, + <varname remap="structfield">p_sigiolst</varname> for processes, and + <varname remap="structfield">pg_sigiolst</varname> for process groups. These lists are protected by the process or process group - locks respectively. Most fields in each <structname>struct - sigio</structname> are constant for the duration of the + locks respectively. Most fields in each <varname remap="structname">struct + sigio</varname> are constant for the duration of the registration, with the exception of the - <structfield>sio_pgsigio</structfield> field which links the - <structname>struct sigio</structname> into the process or + <varname remap="structfield">sio_pgsigio</varname> field which links the + <varname remap="structname">struct sigio</varname> into the process or process group list. Developers implementing new kernel objects supporting SIGIO will, in general, want to avoid holding structure locks while invoking SIGIO supporting @@ -786,17 +779,17 @@ <varname>taskqueue_queues_mutex</varname> is meant to serve as a lock to protect the <varname>taskqueue_queues</varname> TAILQ. The other mutex lock associated with this system is the one in the - <structname>struct taskqueue</structname> data structure. The + <varname remap="structname">struct taskqueue</varname> data structure. The use of the synchronization primitive here is to protect the - integrity of the data in the <structname>struct - taskqueue</structname>. It should be noted that there are no + integrity of the data in the <varname remap="structname">struct + taskqueue</varname>. It should be noted that there are no separate macros to assist the user in locking down his/her own work since these locks are most likely not going to be used outside of <filename>kern/subr_taskqueue.c</filename>.</para> </sect2> </sect1> - <sect1 id="smp-implementation-notes"> + <sect1 xml:id="smp-implementation-notes"> <title>Implementation Notes</title> <sect2> @@ -1004,7 +997,7 @@ </sect2> </sect1> - <sect1 id="smp-misc"> + <sect1 xml:id="smp-misc"> <title>Miscellaneous Topics</title> <sect2> @@ -1027,10 +1020,10 @@ </sect2> </sect1> - <glossary id="smp-glossary"> + <glossary xml:id="smp-glossary"> <title>Glossary</title> - <glossentry id="smp-glossary-atomic"> + <glossentry xml:id="smp-glossary-atomic"> <glossterm>atomic</glossterm> <glossdef> <para>An operation is atomic if all of its effects are visible @@ -1046,7 +1039,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-block"> + <glossentry xml:id="smp-glossary-block"> <glossterm>block</glossterm> <glossdef> <para>A thread is blocked when it is waiting on a lock, @@ -1057,7 +1050,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-critical-section"> + <glossentry xml:id="smp-glossary-critical-section"> <glossterm>critical section</glossterm> <glossdef> <para>A section of code that is not allowed to be preempted. @@ -1066,7 +1059,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-MD"> + <glossentry xml:id="smp-glossary-MD"> <glossterm>MD</glossterm> <glossdef> <para>Machine dependent.</para> @@ -1075,7 +1068,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-memory-operation"> + <glossentry xml:id="smp-glossary-memory-operation"> <glossterm>memory operation</glossterm> <glossdef> <para>A memory operation reads and/or writes to a memory @@ -1083,7 +1076,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-MI"> + <glossentry xml:id="smp-glossary-MI"> <glossterm>MI</glossterm> <glossdef> <para>Machine independent.</para> @@ -1092,12 +1085,12 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-operation"> + <glossentry xml:id="smp-glossary-operation"> <glossterm>operation</glossterm> <glosssee>memory operation</glosssee> </glossentry> - <glossentry id="smp-glossary-primary-interrupt-context"> + <glossentry xml:id="smp-glossary-primary-interrupt-context"> <glossterm>primary interrupt context</glossterm> <glossdef> <para>Primary interrupt context refers to the code that runs @@ -1118,7 +1111,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-sleep"> + <glossentry xml:id="smp-glossary-sleep"> <glossterm>sleep</glossterm> <glossdef> <para>A thread is asleep when it is blocked on a condition @@ -1129,7 +1122,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-sleepable-lock"> + <glossentry xml:id="smp-glossary-sleepable-lock"> <glossterm>sleepable lock</glossterm> <glossdef> <para>A sleepable lock is a lock that can be held by a thread @@ -1142,7 +1135,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-thread"> + <glossentry xml:id="smp-glossary-thread"> <glossterm>thread</glossterm> <glossdef> <para>A kernel thread represented by a struct thread. Threads own @@ -1150,7 +1143,7 @@ </glossdef> </glossentry> - <glossentry id="smp-glossary-wait-channel"> + <glossentry xml:id="smp-glossary-wait-channel"> <glossterm>wait channel</glossterm> <glossdef> <para>A kernel virtual address that threads may sleep on.</para> diff --git a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml index aca69c4450..488e437f64 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml @@ -4,22 +4,17 @@ $FreeBSD$ --> - -<chapter id="oss"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="oss"> + <info><title>Sound Subsystem</title> <authorgroup> - <author> - <firstname>Jean-Francois</firstname> - <surname>Dockes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Jean-Francois</firstname><surname>Dockes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- 23 November 2001 --> - </chapterinfo> + + </info> - <title>Sound Subsystem</title> + - <sect1 id="oss-intro"> + <sect1 xml:id="oss-intro"> <title>Introduction</title> <indexterm><primary>sound subsystem</primary></indexterm> @@ -62,10 +57,10 @@ <para>The support for specific sound cards is implemented by hardware-specific drivers, which provide channel and mixer - interfaces to plug into the generic <devicename>pcm</devicename> + interfaces to plug into the generic <filename>pcm</filename> code.</para> - <para>In this chapter, the term <devicename>pcm</devicename> will + <para>In this chapter, the term <filename>pcm</filename> will refer to the central, common part of the sound driver, as opposed to the hardware-specific modules.</para> @@ -78,11 +73,11 @@ <para>As an alternative, or in addition to starting from a working example, you can find a commented driver template at - <ulink url="http://people.FreeBSD.org/~cg/template.c"> - http://people.FreeBSD.org/~cg/template.c</ulink></para> + <link xlink:href="http://people.FreeBSD.org/~cg/template.c"> + http://people.FreeBSD.org/~cg/template.c</link></para> </sect1> - <sect1 id="oss-files"> + <sect1 xml:id="oss-files"> <title>Files</title> <para>All the relevant code lives in @@ -97,22 +92,20 @@ for PCI and ISA boards, and for USB audio devices.</para> </sect1> - <sect1 id="pcm-probe-and-attach"> + <sect1 xml:id="pcm-probe-and-attach"> <title>Probing, Attaching, etc.</title> <para>Sound drivers probe and attach in almost the same way as any - hardware driver module. You might want to look at the <link - linkend="isa-driver"> ISA</link> or <link - linkend="pci">PCI</link> specific sections of the handbook for + hardware driver module. You might want to look at the <link linkend="isa-driver"> ISA</link> or <link linkend="pci">PCI</link> specific sections of the handbook for more information.</para> <para>However, sound drivers differ in some ways:</para> <itemizedlist> <listitem> - <para>They declare themselves as <devicename>pcm</devicename> + <para>They declare themselves as <filename>pcm</filename> class devices, with a - <structname>struct snddev_info</structname> device private + <varname remap="structname">struct snddev_info</varname> device private structure:</para> <programlisting> static driver_t xxx_driver = { @@ -129,29 +122,28 @@ need to store additional private information about their device. A private data structure is usually allocated in the attach routine. Its address is passed to - <devicename>pcm</devicename> by the calls to + <filename>pcm</filename> by the calls to <function>pcm_register()</function> and <function>mixer_init()</function>. - <devicename>pcm</devicename> later passes back this address + <filename>pcm</filename> later passes back this address as a parameter in calls to the sound driver interfaces.</para> </listitem> <listitem> <para>The sound driver attach routine should declare its MIXER - or AC97 interface to <devicename>pcm</devicename> by calling + or AC97 interface to <filename>pcm</filename> by calling <function>mixer_init()</function>. For a MIXER interface, - this causes in turn a call to <link - linkend="xxxmixer-init"><function>xxxmixer_init()</function></link>.</para> + this causes in turn a call to <link linkend="xxxmixer-init"><function>xxxmixer_init()</function></link>.</para> </listitem> <listitem> <para>The sound driver attach routine declares its general - CHANNEL configuration to <devicename>pcm</devicename> by + CHANNEL configuration to <filename>pcm</filename> by calling <function>pcm_register(dev, sc, nplay, nrec)</function>, where <varname>sc</varname> is the address for the device data structure, used in further calls from - <devicename>pcm</devicename>, and <varname>nplay</varname> + <filename>pcm</filename>, and <varname>nplay</varname> and <varname>nrec</varname> are the number of play and record channels.</para> </listitem> @@ -160,7 +152,7 @@ <para>The sound driver attach routine declares each of its channel objects by calls to <function>pcm_addchan()</function>. This sets up the - channel glue in <devicename>pcm</devicename> and causes in + channel glue in <filename>pcm</filename> and causes in turn a call to <link linkend="xxxchannel-init"> <function>xxxchannel_init()</function></link>.</para> @@ -193,19 +185,18 @@ </listitem> </itemizedlist> - <para><devicename>pcm</devicename> drivers should implement + <para><filename>pcm</filename> drivers should implement <function>device_suspend</function>, <function>device_resume</function> and <function>device_shutdown</function> routines, so that power management and module unloading function correctly.</para> </sect1> - <sect1 id="oss-interfaces"> + <sect1 xml:id="oss-interfaces"> <title>Interfaces</title> - <para>The interface between the <devicename>pcm</devicename> core - and the sound drivers is defined in terms of <link - linkend="kernel-objects">kernel objects</link>.</para> + <para>The interface between the <filename>pcm</filename> core + and the sound drivers is defined in terms of <link linkend="kernel-objects">kernel objects</link>.</para> <para>There are two main interfaces that a sound driver will usually provide: <emphasis>CHANNEL</emphasis> and either @@ -215,7 +206,7 @@ hardware access (register read/write) interface, implemented by drivers for hardware with an AC97 codec. In this case, the actual MIXER interface is provided by the shared AC97 code in - <devicename>pcm</devicename>.</para> + <filename>pcm</filename>.</para> <sect2> <title>The CHANNEL Interface</title> @@ -235,19 +226,19 @@ <function>channel_init()</function> which has a pointer to the private device structure (and returns the channel pointer for further use by - <devicename>pcm</devicename>).</para> + <filename>pcm</filename>).</para> </sect3> <sect3> <title>Overview of Data Transfer Operations</title> <para>For sound data transfers, the - <devicename>pcm</devicename> core and the sound drivers + <filename>pcm</filename> core and the sound drivers communicate through a shared memory area, described by a - <structname>struct snd_dbuf</structname>.</para> + <varname remap="structname">struct snd_dbuf</varname>.</para> - <para><structname>struct snd_dbuf</structname> is private to - <devicename>pcm</devicename>, and sound drivers obtain + <para><varname remap="structname">struct snd_dbuf</varname> is private to + <filename>pcm</filename>, and sound drivers obtain values of interest by calls to accessor functions (<function>sndbuf_getxxx()</function>).</para> @@ -261,9 +252,8 @@ <itemizedlist> <listitem> - <para><devicename>pcm</devicename> initially fills up the - buffer, then calls the sound driver's <link - linkend="channel-trigger"> + <para><filename>pcm</filename> initially fills up the + buffer, then calls the sound driver's <link linkend="channel-trigger"> <function>xxxchannel_trigger()</function></link> function with a parameter of PCMTRIG_START.</para> </listitem> @@ -275,7 +265,7 @@ <function>sndbuf_getsize()</function>) to the device, in blocks of <function>sndbuf_getblksz()</function> bytes. It calls back the <function>chn_intr()</function> - <devicename>pcm</devicename> function for each + <filename>pcm</filename> function for each transferred block (this will typically happen at interrupt time).</para> </listitem> @@ -284,12 +274,12 @@ <para><function>chn_intr()</function> arranges to copy new data to the area that was transferred to the device (now free), and make appropriate updates to the - <structname>snd_dbuf</structname> structure.</para> + <varname remap="structname">snd_dbuf</varname> structure.</para> </listitem> </itemizedlist> </sect3> - <sect3 id="xxxchannel-init"> + <sect3 xml:id="xxxchannel-init"> <title>channel_init</title> <para><function>xxxchannel_init()</function> is called to @@ -300,28 +290,28 @@ <programlisting> static void * xxxchannel_init(kobj_t obj, void *data, - struct snd_dbuf *b, struct pcm_channel *c, int dir)<co id="co-chinit-params"/> + struct snd_dbuf *b, struct pcm_channel *c, int dir)<co xml:id="co-chinit-params"/> { struct xxx_info *sc = data; struct xxx_chinfo *ch; ... - return ch;<co id="co-chinit-return"/> + return ch;<co xml:id="co-chinit-return"/> }</programlisting> <calloutlist> <callout arearefs="co-chinit-params"> <para><varname>b</varname> is the address for the channel - <structname>struct snd_dbuf</structname>. It should be + <varname remap="structname">struct snd_dbuf</varname>. It should be initialized in the function by calling <function>sndbuf_alloc()</function>. The buffer size to use is normally a small multiple of the 'typical' unit transfer size for your device.</para> <para><varname>c</varname> is the - <devicename>pcm</devicename> channel control structure + <filename>pcm</filename> channel control structure pointer. This is an opaque object. The function should store it in the local channel structure, to be used in - later calls to <devicename>pcm</devicename> (ie: + later calls to <filename>pcm</filename> (ie: <function>chn_intr(c)</function>).</para> <para><varname>dir</varname> indicates the channel @@ -345,7 +335,7 @@ sound format.</para> <programlisting> static int - xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co id="co-chsetformat-params"/> + xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co xml:id="co-chsetformat-params"/> { struct xxx_chinfo *ch = data; ... @@ -382,11 +372,11 @@ <para><function>xxxchannel_setblocksize()</function> sets the block size, which is the size of unit transactions between - <devicename>pcm</devicename> and the sound driver, and + <filename>pcm</filename> and the sound driver, and between the sound driver and the device. Typically, this would be the number of bytes transferred before an interrupt occurs. During a transfer, the sound driver should call - <devicename>pcm</devicename>'s + <filename>pcm</filename>'s <function>chn_intr()</function> every time this size has been transferred.</para> @@ -399,7 +389,7 @@ { struct xxx_chinfo *ch = data; ... - return blocksize;<co id="co-chsetblocksize-return"/> + return blocksize;<co xml:id="co-chsetblocksize-return"/> }</programlisting> <calloutlist> @@ -412,15 +402,15 @@ </calloutlist> </sect3> - <sect3 id="channel-trigger"> + <sect3 xml:id="channel-trigger"> <title>channel_trigger</title> <para><function>xxxchannel_trigger()</function> is called by - <devicename>pcm</devicename> to control data transfer + <filename>pcm</filename> to control data transfer operations in the driver.</para> <programlisting> static int - xxxchannel_trigger(kobj_t obj, void *data, int go)<co id="co-chtrigger-params"/> + xxxchannel_trigger(kobj_t obj, void *data, int go)<co xml:id="co-chtrigger-params"/> { struct xxx_chinfo *ch = data; ... @@ -473,7 +463,7 @@ <para><function>xxxchannel_getptr()</function> returns the current offset in the transfer buffer. This will typically be called by <function>chn_intr()</function>, and this is - how <devicename>pcm</devicename> knows where it can transfer + how <filename>pcm</filename> knows where it can transfer new data.</para> </sect3> @@ -494,7 +484,7 @@ <programlisting> struct pcmchan_caps * xxxchannel_getcaps(kobj_t obj, void *data) { - return &xxx_caps;<co id="co-chgetcaps-return"/> + return &xxx_caps;<co xml:id="co-chgetcaps-return"/> }</programlisting> <calloutlist> @@ -502,7 +492,7 @@ <callout arearefs="co-chgetcaps-return"> <para>The routine returns a pointer to a (usually statically-defined) - <structname>pcmchan_caps</structname> structure (defined + <varname remap="structname">pcmchan_caps</varname> structure (defined in <filename>sound/pcm/channel.h</filename>. The structure holds the minimum and maximum sampling frequencies, and the accepted sound formats. Look at @@ -528,11 +518,11 @@ <sect2> <title>The MIXER Interface</title> - <sect3 id="xxxmixer-init"> + <sect3 xml:id="xxxmixer-init"> <title>mixer_init</title> <para><function>xxxmixer_init()</function> initializes the - hardware and tells <devicename>pcm</devicename> what mixer + hardware and tells <filename>pcm</filename> what mixer devices are available for playing and recording</para> <programlisting> static int @@ -543,7 +533,7 @@ [Initialize hardware] - [Set appropriate bits in v for play mixers]<co id="co-mxini-sd"/> + [Set appropriate bits in v for play mixers]<co xml:id="co-mxini-sd"/> mix_setdevs(m, v); [Set appropriate bits in v for record mixers] mix_setrecdevs(m, v) @@ -556,7 +546,7 @@ <para>Set bits in an integer value and call <function>mix_setdevs()</function> and <function>mix_setrecdevs()</function> to tell - <devicename>pcm</devicename> what devices exist.</para> + <filename>pcm</filename> what devices exist.</para> </callout> </calloutlist> @@ -574,11 +564,11 @@ <programlisting> static int xxxmixer_set(struct snd_mixer *m, unsigned dev, - unsigned left, unsigned right)<co id="co-mxset-params"/> + unsigned left, unsigned right)<co xml:id="co-mxset-params"/> { struct sc_info *sc = mix_getdevinfo(m); [set volume level] - return left | (right << 8);<co id="co-mxset-return"/> + return left | (right << 8);<co xml:id="co-mxset-return"/> }</programlisting> <calloutlist> @@ -607,14 +597,14 @@ recording source device.</para> <programlisting> static int - xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co id="co-mxsr-params"/> + xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co xml:id="co-mxsr-params"/> { struct xxx_info *sc = mix_getdevinfo(m); [look for non zero bit(s) in src, set up hardware] [update src to reflect actual action] - return src;<co id="co-mxsr-return"/> + return src;<co xml:id="co-mxsr-return"/> }</programlisting> <calloutlist> @@ -668,7 +658,7 @@ </itemizedlist> <para>The <emphasis>AC97</emphasis> interface is used by the - AC97 code in <devicename>pcm</devicename> to perform higher + AC97 code in <filename>pcm</filename> to perform higher level operations. Look at <filename>sound/pci/maestro3.c</filename> or many others under <filename>sound/pci/</filename> for an example.</para> diff --git a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.xml index 7898ee7e2e..66a61dce18 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/sysinit/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="sysinit"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sysinit"> <title>The SYSINIT Framework</title> <indexterm><primary>SYSINIT</primary></indexterm> @@ -28,7 +27,7 @@ using the <quote>kernel linker</quote> and <quote>linker sets</quote>.</para> - <sect1 id="sysinit-term"> + <sect1 xml:id="sysinit-term"> <title>Terminology</title> <variablelist> @@ -44,7 +43,7 @@ </variablelist> </sect1> - <sect1 id="sysinit-operation"> + <sect1 xml:id="sysinit-operation"> <title>SYSINIT Operation</title> <indexterm><primary>linker sets</primary></indexterm> @@ -86,7 +85,7 @@ </sect1> - <sect1 id="sysinit-using"> + <sect1 xml:id="sysinit-using"> <title>Using SYSINIT</title> <sect2> diff --git a/en_US.ISO8859-1/books/arch-handbook/usb/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/usb/chapter.xml index 61c244bf8b..8cf67b0500 100644 --- a/en_US.ISO8859-1/books/arch-handbook/usb/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/usb/chapter.xml @@ -4,28 +4,19 @@ $FreeBSD$ --> - -<chapter id="usb"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="usb"> + <info><title>USB Devices</title> <authorgroup> - <author> - <firstname>Nick</firstname> - <surname>Hibma</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Nick</firstname><surname>Hibma</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Modifications for Handbook made by </contrib> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Modifications for Handbook made by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>USB Devices</title> + - <sect1 id="usb-intro"> + <sect1 xml:id="usb-intro"> <title>Introduction</title> <indexterm><primary>Universal Serial Bus (USB)</primary></indexterm> @@ -123,7 +114,7 @@ </sect2> </sect1> - <sect1 id="usb-hc"> + <sect1 xml:id="usb-hc"> <title>Host Controllers</title> <indexterm><primary>USB</primary><secondary>host controllers</secondary></indexterm> @@ -141,9 +132,8 @@ which the recipient of the data can return either ACK (acknowledge reception), NAK (retry), STALL (error condition) or nothing (garbled data stage, device not available or - disconnected). Section 8.5 of the <ulink - url="http://www.usb.org/developers/docs.html">USB - specification</ulink> explains the details of packets in more + disconnected). Section 8.5 of the <link xlink:href="http://www.usb.org/developers/docs.html">USB + specification</link> explains the details of packets in more detail. Four different types of transfers can occur on a USB bus: control, bulk, interrupt and isochronous. The types of transfers and their characteristics are described below (`Pipes' @@ -170,11 +160,9 @@ to it. It returns the standard andhub class specific set of descriptors. It should also provide an interrupt pipe that reports changes happening at its ports. There are currently two - specifications for host controllers available: <ulink - url="http://developer.intel.com/design/USB/UHCI11D.htm">Universal - Host Controller Interface</ulink> (UHCI; Intel) and <ulink - url="http://www.compaq.com/productinfo/development/openhci.html">Open - Host Controller Interface</ulink> (OHCI; Compaq, Microsoft, + specifications for host controllers available: <link xlink:href="http://developer.intel.com/design/USB/UHCI11D.htm">Universal + Host Controller Interface</link> (UHCI; Intel) and <link xlink:href="http://www.compaq.com/productinfo/development/openhci.html">Open + Host Controller Interface</link> (OHCI; Compaq, Microsoft, National Semiconductor). The UHCI specification has been designed to reduce hardware complexity by requiring the host controller driver to supply a complete schedule of the transfers @@ -232,9 +220,8 @@ service routine will locate all the finished transfers and call their callbacks.</para> - <para>See for a more elaborate description the <ulink - url="http://developer.intel.com/design/USB/UHCI11D.htm">UHCI - specification.</ulink></para> + <para>See for a more elaborate description the <link xlink:href="http://developer.intel.com/design/USB/UHCI11D.htm">UHCI + specification.</link></para> </sect2> @@ -276,9 +263,8 @@ transfer and reschedule interrupt and isochronous endpoints.</para> - <para>See for a more elaborate description the <ulink - url="http://www.compaq.com/productinfo/development/openhci.html"> - OHCI specification</ulink>. Services layer The middle layer + <para>See for a more elaborate description the <link xlink:href="http://www.compaq.com/productinfo/development/openhci.html"> + OHCI specification</link>. Services layer The middle layer provides access to the device in a controlled way and maintains resources in use by the different drivers and the services layer. The layer takes care of the following @@ -296,7 +282,7 @@ </sect2> </sect1> - <sect1 id="usb-dev"> + <sect1 xml:id="usb-dev"> <title>USB Device Information</title> <sect2> @@ -465,7 +451,7 @@ </sect2> </sect1> - <sect1 id="usb-devprobe"> + <sect1 xml:id="usb-devprobe"> <title>Device Probe and Attach</title> <indexterm><primary>USB</primary><secondary>probe</secondary></indexterm> @@ -536,7 +522,7 @@ </sect2> </sect1> - <sect1 id="usb-protocol"> + <sect1 xml:id="usb-protocol"> <title>USB Drivers Protocol Information</title> <para>The protocol used over pipes other than the default pipe is diff --git a/en_US.ISO8859-1/books/arch-handbook/vm/chapter.xml b/en_US.ISO8859-1/books/arch-handbook/vm/chapter.xml index 39ec4fba3c..52c44fca29 100644 --- a/en_US.ISO8859-1/books/arch-handbook/vm/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/vm/chapter.xml @@ -4,22 +4,17 @@ $FreeBSD$ --> - -<chapter id="vm"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="vm"> + <info><title>Virtual Memory System</title> <authorgroup> - <author> - <firstname>Matthew</firstname> - <surname>Dillon</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Matthew</firstname><surname>Dillon</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- 6 Feb 1999 --> - </chapterinfo> + + </info> - <title>Virtual Memory System</title> + - <sect1 id="vm-physmem"> + <sect1 xml:id="vm-physmem"> <title>Management of Physical Memory—<literal>vm_page_t</literal></title> @@ -86,7 +81,7 @@ launder or swap-out a page.</para> </sect1> - <sect1 id="vm-cache"> + <sect1 xml:id="vm-cache"> <title>The Unified Buffer Cache—<literal>vm_object_t</literal></title> @@ -113,7 +108,7 @@ instances.</para> </sect1> - <sect1 id="vm-fileio"> + <sect1 xml:id="vm-fileio"> <title>Filesystem I/O—<literal>struct buf</literal></title> <indexterm><primary>vnode</primary></indexterm> @@ -149,7 +144,7 @@ problem.</para> </sect1> - <sect1 id="vm-pagetables"> + <sect1 xml:id="vm-pagetables"> <title>Mapping Page Tables—<literal>vm_map_t, vm_entry_t</literal></title> <indexterm><primary>page tables</primary></indexterm> @@ -176,7 +171,7 @@ across the board.</para> </sect1> - <sect1 id="vm-kvm"> + <sect1 xml:id="vm-kvm"> <title>KVM Memory Mapping</title> <para>FreeBSD uses KVM to hold various kernel structures. The single @@ -198,7 +193,7 @@ overview of current KVM utilization broken down by zone.</para> </sect1> - <sect1 id="vm-tuning"> + <sect1 xml:id="vm-tuning"> <title>Tuning the FreeBSD VM System</title> <para>A concerted effort has been made to make the FreeBSD kernel @@ -206,7 +201,7 @@ anything beyond the <option>maxusers</option> and <option>NMBCLUSTERS</option> kernel config options. That is, kernel compilation options specified in (typically) - <filename>/usr/src/sys/i386/conf/<replaceable>CONFIG_FILE</replaceable></filename>. + <filename>/usr/src/sys/i386/conf/CONFIG_FILE</filename>. A description of all available kernel configuration options can be found in <filename>/usr/src/sys/i386/conf/LINT</filename>.</para> diff --git a/en_US.ISO8859-1/books/bibliography/book.xml b/en_US.ISO8859-1/books/bibliography/book.xml index 778160a2be..c9b97ef1bf 100644 --- a/en_US.ISO8859-1/books/bibliography/book.xml +++ b/en_US.ISO8859-1/books/bibliography/book.xml @@ -1,20 +1,17 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "../../../share/xml/freebsd50.dtd" [ <!ENTITY bibliography SYSTEM "../../../share/xml/bibliography.xml"> ]> - <!-- The FreeBSD Documentation Project $FreeBSD$ --> - -<book lang='en'> - <bookinfo> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info> <title>FreeBSD Bibliography</title> - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> <pubdate>February 1999</pubdate> @@ -24,7 +21,7 @@ </copyright> <releaseinfo>$FreeBSD$</releaseinfo> - </bookinfo> + </info> &bibliography; </book> diff --git a/en_US.ISO8859-1/books/design-44bsd/book.xml b/en_US.ISO8859-1/books/design-44bsd/book.xml index 04637580a8..7de5641d8e 100644 --- a/en_US.ISO8859-1/books/design-44bsd/book.xml +++ b/en_US.ISO8859-1/books/design-44bsd/book.xml @@ -1,37 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd"> - +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd"> <!-- $FreeBSD$ --> <!-- FreeBSD Documentation Project --> - -<book lang='en'> - <bookinfo> - <title>The Design and Implementation of the 4.4BSD Operating System</title> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>The Design and Implementation of the 4.4BSD Operating System</title> + <authorgroup> - <author> - <firstname>Marshall</firstname> - <othername>Kirk</othername> - <surname>McKusick</surname> - </author> - - <author> - <firstname>Keith</firstname> - <surname>Bostic</surname> - </author> - - <author> - <firstname>Michael</firstname> - <othername>J.</othername> - <surname>Karels</surname> - </author> - - <author> - <firstname>John</firstname> - <othername>S.</othername> - <surname>Quarterman</surname> - </author> + <author><personname><firstname>Marshall</firstname><othername>Kirk</othername><surname>McKusick</surname></personname></author> + + <author><personname><firstname>Keith</firstname><surname>Bostic</surname></personname></author> + + <author><personname><firstname>Michael</firstname><othername>J.</othername><surname>Karels</surname></personname></author> + + <author><personname><firstname>John</firstname><othername>S.</othername><surname>Quarterman</surname></personname></author> </authorgroup> <copyright> @@ -39,34 +22,33 @@ <holder>Addison-Wesley Longman, Inc</holder> </copyright> -<!-- I seem to recall the editor wanting this notice to be bold. In html, I'd - use the _strong_ tag. What should I use instead? --> - <legalnotice id="legalnotice"> + + <legalnotice xml:id="legalnotice"> <para>The second chapter of the book, <citetitle>The Design and Implementation of the 4.4BSD Operating System</citetitle> is excerpted here with the permission of the publisher. No part of it may be further reproduced or distributed without the publisher's express written - <ulink url="mailto:peter.gordon@awl.com">permission</ulink>. The + <link xlink:href="mailto:peter.gordon@awl.com">permission</link>. The rest of - <ulink url="http://cseng.aw.com/catalog/academic/product/0,1144,0201549794,00.html">the - book</ulink> explores the concepts introduced in this chapter in + <link xlink:href="http://cseng.aw.com/catalog/academic/product/0,1144,0201549794,00.html">the + book</link> explores the concepts introduced in this chapter in incredible detail and is an excellent reference for anyone with an interest in BSD UNIX. More information about this book is available from the publisher, with whom you can also sign up to receive news - of <ulink url="mailto:curt.johnson@awl.com">related titles</ulink>. - Information about <ulink url="http://www.mckusick.com/courses/">BSD - courses</ulink> is available from Kirk McKusick.</para> + of <link xlink:href="mailto:curt.johnson@awl.com">related titles</link>. + Information about <link xlink:href="http://www.mckusick.com/courses/">BSD + courses</link> is available from Kirk McKusick.</para> </legalnotice> <releaseinfo>$FreeBSD$</releaseinfo> - </bookinfo> + </info> - <chapter id="overview" label="2"> + <chapter xml:id="overview" label="2"> <title>Design Overview of 4.4BSD</title> - <sect1 id="overview-facilities"> + <sect1 xml:id="overview-facilities"> <title>4.4BSD Facilities and the Kernel</title> <para>The 4.4BSD kernel provides four basic facilities: @@ -223,7 +205,7 @@ </sect2> </sect1> - <sect1 id="overview-kernel-organization"> + <sect1 xml:id="overview-kernel-organization"> <title>Kernel Organization</title> <para>In this section, we view the organization of the 4.4BSD @@ -288,7 +270,7 @@ </listitem> </itemizedlist> - <table frame="none" id="table-mach-indep"> + <table frame="none" xml:id="table-mach-indep"> <title>Machine-independent software in the 4.4BSD kernel</title> <tgroup cols="3"> <thead> @@ -466,7 +448,7 @@ </listitem> </itemizedlist> - <table frame="none" id="table-mach-dep"> + <table frame="none" xml:id="table-mach-dep"> <title>Machine-dependent software for the HP300 in the 4.4BSD kernel</title> @@ -568,7 +550,7 @@ in places logically associated with what is being initialized.</para> </sect1> - <sect1 id="overview-kernel-service"> + <sect1 xml:id="overview-kernel-service"> <title>Kernel Services</title> <para>The boundary between the kernel- and user-level code is enforced by @@ -635,7 +617,7 @@ invisible to the processes involved.</para> </sect1> - <sect1 id="overview-process-management"> + <sect1 xml:id="overview-process-management"> <title>Process Management</title> <para>4.4BSD supports a multitasking environment. @@ -672,7 +654,7 @@ Important components of the kernel state are described in Chapter 4.</para> - <figure id="fig-process-lifecycle"> + <figure xml:id="fig-process-lifecycle"> <title>Process lifecycle</title> <mediaobject> @@ -682,13 +664,13 @@ <textobject> <literallayout class="monospaced">+----------------+ wait +----------------+ -| parent process |--------------------------------->| parent process |---> +| parent process |--------------------------------->| parent process |---> +----------------+ +----------------+ | ^ | fork | V | +----------------+ execve +----------------+ wait +----------------+ -| child process |------->| child process |------->| zombie process | +| child process |------->| child process |------->| zombie process | +----------------+ +----------------+ +----------------+</literallayout> </textobject> @@ -899,7 +881,7 @@ </sect2> </sect1> - <sect1 id="overview-memory-management"> + <sect1 xml:id="overview-memory-management"> <title>Memory Management</title> <para>Each process has its own private address space. @@ -1120,7 +1102,7 @@ </sect2> </sect1> - <sect1 id="overview-io-system"> + <sect1 xml:id="overview-io-system"> <title>I/O System</title> <para>The basic model of the UNIX @@ -1633,7 +1615,7 @@ </sect2> </sect1> - <sect1 id="overview-filesystem"> + <sect1 xml:id="overview-filesystem"> <title>Filesystems</title> <para>A regular file is a linear array of bytes, @@ -1658,7 +1640,7 @@ A hierarchy of directories and files is thus formed, and is called a <emphasis>filesystem</emphasis>;</para> - <figure id="fig-small-fs"> + <figure xml:id="fig-small-fs"> <title>A small filesystem</title> <mediaobject> @@ -1979,7 +1961,7 @@ in addition to the natural desire of users to give files long descriptive names, a common way of forming filenames is as - <filename><replaceable>basename</replaceable>.<replaceable>extension</replaceable></filename>, + <filename>basename.extension</filename>, where the extension (indicating the kind of file, such as <literal>.c</literal> for C source or @@ -2019,7 +2001,7 @@ first introduced in 4.2BSD practically eliminate it.</para> </sect1> - <sect1 id="overview-filestore"> + <sect1 xml:id="overview-filestore"> <title>Filestores</title> <para>The operations defined for local filesystems are divided into two parts. @@ -2078,7 +2060,7 @@ the usage of virtual-memory resources.</para> </sect1> - <sect1 id="overview-nfs"> + <sect1 xml:id="overview-nfs"> <title>Network Filesystem</title> <para>Initially, networking was used @@ -2136,7 +2118,7 @@ </para> </sect1> - <sect1 id="overview-terminal"> + <sect1 xml:id="overview-terminal"> <title>Terminals</title> <para>Terminals support the standard system I/O operations, as well @@ -2221,7 +2203,7 @@ </sect1> - <sect1 id="overview-ipc"> + <sect1 xml:id="overview-ipc"> <title>Interprocess Communication</title> <para>Interprocess communication in 4.4BSD is organized in @@ -2315,7 +2297,7 @@ Microsoft's Winsock networking interface for Windows.</para> </sect1> - <sect1 id="overview-network-communication"> + <sect1 xml:id="overview-network-communication"> <title>Network Communication</title> <para>Some of the communication domains supported by the @@ -2350,7 +2332,7 @@ running with a newer network protocol.</para> </sect1> - <sect1 id="overview-network-implementation"> + <sect1 xml:id="overview-network-implementation"> <title>Network Implementation</title> <para>The first protocol suite implemented in 4.2BSD was @@ -2408,7 +2390,7 @@ network masks.</para> </sect1> - <sect1 id="overview-operation"> + <sect1 xml:id="overview-operation"> <title>System Operation</title> <para>Bootstrapping mechanisms are used to start the system running. @@ -2435,163 +2417,112 @@ the user can run additional processes.</para> </sect1> - <bibliography id="references"> + <bibliography xml:id="references"> <title>References</title> - <biblioentry id="biblio-accetta"> + <biblioentry xml:id="biblio-accetta"> <abbrev>Accetta et al, 1986</abbrev> <biblioset relation="article"> - <title>Mach: A New Kernel Foundation for UNIX Development"</title> + <citetitle>Mach: A New Kernel Foundation for UNIX Development"</citetitle> <authorgroup> - <author> - <firstname>M. </firstname> - <surname>Accetta</surname> - </author> - <author> - <firstname>R.</firstname> - <surname>Baron</surname> - </author> - <author> - <firstname>W.</firstname> - <surname>Bolosky</surname> - </author> - <author> - <firstname>D.</firstname> - <surname>Golub</surname> - </author> - <author> - <firstname>R.</firstname> - <surname>Rashid</surname> - </author> - <author> - <firstname>A.</firstname> - <surname>Tevanian</surname> - </author> - <author> - <firstname>M.</firstname> - <surname>Young</surname> - </author> + <author><personname><firstname>M. </firstname><surname>Accetta</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Baron</surname></personname></author> + <author><personname><firstname>W.</firstname><surname>Bolosky</surname></personname></author> + <author><personname><firstname>D.</firstname><surname>Golub</surname></personname></author> + <author><personname><firstname>R.</firstname><surname>Rashid</surname></personname></author> + <author><personname><firstname>A.</firstname><surname>Tevanian</surname></personname></author> + <author><personname><firstname>M.</firstname><surname>Young</surname></personname></author> </authorgroup> <pagenums>93-113</pagenums> </biblioset> <biblioset relation="journal"> - <title>USENIX Association Conference Proceedings</title> + <citetitle>USENIX Association Conference Proceedings</citetitle> <publishername>USENIX Association</publishername> <pubdate>June 1986</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-cheriton"> + <biblioentry xml:id="biblio-cheriton"> <abbrev>Cheriton, 1988</abbrev> <biblioset relation="article"> - <title>The V Distributed System</title> + <citetitle>The V Distributed System</citetitle> - <author> - <firstname>D. R.</firstname> - <surname>Cheriton</surname> - </author> + <author><personname><firstname>D. R.</firstname><surname>Cheriton</surname></personname></author> <pagenums>314-333</pagenums> </biblioset> <biblioset relation="journal"> - <title>Comm ACM, 31, 3</title> + <citetitle>Comm ACM, 31, 3</citetitle> <pubdate>March 1988</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-ewens"> + <biblioentry xml:id="biblio-ewens"> <abbrev>Ewens et al, 1985</abbrev> <biblioset relation="article"> - <title>Tunis: A Distributed Multiprocessor Operating System</title> + <citetitle>Tunis: A Distributed Multiprocessor Operating System</citetitle> <authorgroup> - <author> - <firstname>P.</firstname> - <surname>Ewens</surname> - </author> - - <author> - <firstname>D. R.</firstname> - <surname>Blythe</surname> - </author> - - <author> - <firstname>M.</firstname> - <surname>Funkenhauser</surname> - </author> - - <author> - <firstname>R. C.</firstname> - <surname>Holt</surname> - </author> + <author><personname><firstname>P.</firstname><surname>Ewens</surname></personname></author> + + <author><personname><firstname>D. R.</firstname><surname>Blythe</surname></personname></author> + + <author><personname><firstname>M.</firstname><surname>Funkenhauser</surname></personname></author> + + <author><personname><firstname>R. C.</firstname><surname>Holt</surname></personname></author> </authorgroup> <pagenums>247-254</pagenums> </biblioset> <biblioset relation="journal"> - <title>USENIX Assocation Conference Proceedings</title> + <citetitle>USENIX Assocation Conference Proceedings</citetitle> <publishername>USENIX Association</publishername> <pubdate>June 1985</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-gingell"> + <biblioentry xml:id="biblio-gingell"> <abbrev>Gingell et al, 1987</abbrev> <biblioset relation="article"> - <title>Virtual Memory Architecture in SunOS</title> + <citetitle>Virtual Memory Architecture in SunOS</citetitle> <authorgroup> - <author> - <firstname>R.</firstname> - <surname>Gingell</surname> - </author> - - <author> - <firstname>J.</firstname> - <surname>Moran</surname> - </author> - - <author> - <firstname>W.</firstname> - <surname>Shannon</surname> - </author> + <author><personname><firstname>R.</firstname><surname>Gingell</surname></personname></author> + + <author><personname><firstname>J.</firstname><surname>Moran</surname></personname></author> + + <author><personname><firstname>W.</firstname><surname>Shannon</surname></personname></author> </authorgroup> <pagenums>81-94</pagenums> </biblioset> <biblioset relation="journal"> - <title>USENIX Association Conference Proceedings</title> + <citetitle>USENIX Association Conference Proceedings</citetitle> <publishername>USENIX Association</publishername> <pubdate>June 1987</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-kernighan"> + <biblioentry xml:id="biblio-kernighan"> <abbrev>Kernighan & Pike, 1984</abbrev> - <title>The UNIX Programming Environment</title> + <citetitle>The UNIX Programming Environment</citetitle> <authorgroup> - <author> - <firstname>B. W.</firstname> - <surname>Kernighan</surname> - </author> - - <author> - <firstname>R.</firstname> - <surname>Pike</surname> - </author> + <author><personname><firstname>B. W.</firstname><surname>Kernighan</surname></personname></author> + + <author><personname><firstname>R.</firstname><surname>Pike</surname></personname></author> </authorgroup> <publisher> @@ -2605,22 +2536,19 @@ <pubdate>1984</pubdate> </biblioentry> - <biblioentry id="biblio-macklem"> + <biblioentry xml:id="biblio-macklem"> <abbrev>Macklem, 1994</abbrev> <biblioset relation="chapter"> - <title>The 4.4BSD NFS Implementation</title> + <citetitle>The 4.4BSD NFS Implementation</citetitle> - <author> - <firstname>R.</firstname> - <surname>Macklem</surname> - </author> + <author><personname><firstname>R.</firstname><surname>Macklem</surname></personname></author> <pagenums>6:1-14</pagenums> </biblioset> <biblioset relation="book"> - <title>4.4BSD System Manager's Manual</title> + <citetitle>4.4BSD System Manager's Manual</citetitle> <publisher> <publishername>O'Reilly & Associates, Inc.</publishername> @@ -2634,73 +2562,52 @@ </biblioset> </biblioentry> - <biblioentry id="biblio-mckusick-2"> + <biblioentry xml:id="biblio-mckusick-2"> <abbrev>McKusick & Karels, 1988</abbrev> <biblioset relation="article"> - <title>Design of a General Purpose Memory Allocator for the 4.3BSD - UNIX Kernel</title> + <citetitle>Design of a General Purpose Memory Allocator for the 4.3BSD + UNIX Kernel</citetitle> <authorgroup> - <author> - <firstname>M. K.</firstname> - <surname>McKusick</surname> - </author> - - <author> - <firstname>M. J.</firstname> - <surname>Karels</surname> - </author> + <author><personname><firstname>M. K.</firstname><surname>McKusick</surname></personname></author> + + <author><personname><firstname>M. J.</firstname><surname>Karels</surname></personname></author> </authorgroup> <pagenums>295-304</pagenums> </biblioset> <biblioset relation="journal"> - <title>USENIX Assocation Conference Proceedings</title> + <citetitle>USENIX Assocation Conference Proceedings</citetitle> <publishername>USENIX Assocation</publishername> <pubdate>June 1998</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-mckusick-1"> + <biblioentry xml:id="biblio-mckusick-1"> <abbrev>McKusick et al, 1994</abbrev> <biblioset relation="manual"> - <title>Berkeley Software Architecture Manual, 4.4BSD Edition</title> + <citetitle>Berkeley Software Architecture Manual, 4.4BSD Edition</citetitle> <authorgroup> - <author> - <firstname>M. K.</firstname> - <surname>McKusick</surname> - </author> - - <author> - <firstname>M. J.</firstname> - <surname>Karels</surname> - </author> - - <author> - <firstname>S. J.</firstname> - <surname>Leffler</surname> - </author> - - <author> - <firstname>W. N.</firstname> - <surname>Joy</surname> - </author> - - <author> - <firstname>R. S.</firstname> - <surname>Faber</surname> - </author> + <author><personname><firstname>M. K.</firstname><surname>McKusick</surname></personname></author> + + <author><personname><firstname>M. J.</firstname><surname>Karels</surname></personname></author> + + <author><personname><firstname>S. J.</firstname><surname>Leffler</surname></personname></author> + + <author><personname><firstname>W. N.</firstname><surname>Joy</surname></personname></author> + + <author><personname><firstname>R. S.</firstname><surname>Faber</surname></personname></author> </authorgroup> <pagenums>5:1-42</pagenums> </biblioset> <biblioset relation="book"> - <title>4.4BSD Programmer's Supplementary Documents</title> + <citetitle>4.4BSD Programmer's Supplementary Documents</citetitle> <publisher> <publishername>O'Reilly & Associates, Inc.</publishername> @@ -2714,133 +2621,88 @@ </biblioset> </biblioentry> - <biblioentry id="biblio-ritchie"> + <biblioentry xml:id="biblio-ritchie"> <abbrev>Ritchie, 1988</abbrev> - <title>Early Kernel Design</title> + <citetitle>Early Kernel Design</citetitle> <subtitle>private communication</subtitle> - <author> - <firstname>D. M.</firstname> - <surname>Ritchie</surname> - </author> + <author><personname><firstname>D. M.</firstname><surname>Ritchie</surname></personname></author> <pubdate>March 1988</pubdate> </biblioentry> - <biblioentry id="biblio-rosenblum"> + <biblioentry xml:id="biblio-rosenblum"> <abbrev>Rosenblum & Ousterhout, 1992</abbrev> <biblioset relation="article"> - <title>The Design and Implementation of a Log-Structured File - System</title> + <citetitle>The Design and Implementation of a Log-Structured File + System</citetitle> <authorgroup> - <author> - <firstname>M.</firstname> - <surname>Rosenblum</surname> - </author> - - <author> - <firstname>K.</firstname> - <surname>Ousterhout</surname> - </author> + <author><personname><firstname>M.</firstname><surname>Rosenblum</surname></personname></author> + + <author><personname><firstname>K.</firstname><surname>Ousterhout</surname></personname></author> </authorgroup> <pagenums>26-52</pagenums> </biblioset> <biblioset relation="journal"> - <title>ACM Transactions on Computer Systems, 10, 1</title> + <citetitle>ACM Transactions on Computer Systems, 10, 1</citetitle> <publishername>Association for Computing Machinery</publishername> <pubdate>February 1992</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-rozier"> + <biblioentry xml:id="biblio-rozier"> <abbrev>Rozier et al, 1988</abbrev> <biblioset relation="article"> - <title>Chorus Distributed Operating Systems</title> + <citetitle>Chorus Distributed Operating Systems</citetitle> <authorgroup> - <author> - <firstname>M.</firstname> - <surname>Rozier</surname> - </author> - - <author> - <firstname>V.</firstname> - <surname>Abrossimov</surname> - </author> - - <author> - <firstname>F.</firstname> - <surname>Armand</surname> - </author> - - <author> - <firstname>I.</firstname> - <surname>Boule</surname> - </author> - - <author> - <firstname>M.</firstname> - <surname>Gien</surname> - </author> - - <author> - <firstname>M.</firstname> - <surname>Guillemont</surname> - </author> - - <author> - <firstname>F.</firstname> - <surname>Herrmann</surname> - </author> - - <author> - <firstname>C.</firstname> - <surname>Kaiser</surname> - </author> - - <author> - <firstname>S.</firstname> - <surname>Langlois</surname> - </author> - - <author> - <firstname>P.</firstname> - <surname>Leonard</surname> - </author> - - <author> - <firstname>W.</firstname> - <surname>Neuhauser</surname> - </author> + <author><personname><firstname>M.</firstname><surname>Rozier</surname></personname></author> + + <author><personname><firstname>V.</firstname><surname>Abrossimov</surname></personname></author> + + <author><personname><firstname>F.</firstname><surname>Armand</surname></personname></author> + + <author><personname><firstname>I.</firstname><surname>Boule</surname></personname></author> + + <author><personname><firstname>M.</firstname><surname>Gien</surname></personname></author> + + <author><personname><firstname>M.</firstname><surname>Guillemont</surname></personname></author> + + <author><personname><firstname>F.</firstname><surname>Herrmann</surname></personname></author> + + <author><personname><firstname>C.</firstname><surname>Kaiser</surname></personname></author> + + <author><personname><firstname>S.</firstname><surname>Langlois</surname></personname></author> + + <author><personname><firstname>P.</firstname><surname>Leonard</surname></personname></author> + + <author><personname><firstname>W.</firstname><surname>Neuhauser</surname></personname></author> </authorgroup> <pagenums>305-370</pagenums> </biblioset> <biblioset relation="journal"> - <title>USENIX Computing Systems, 1, 4</title> + <citetitle>USENIX Computing Systems, 1, 4</citetitle> <pubdate>Fall 1988</pubdate> </biblioset> </biblioentry> - <biblioentry id="biblio-tevanian"> + <biblioentry xml:id="biblio-tevanian"> <abbrev>Tevanian, 1987</abbrev> - <title>Architecture-Independent Virtual Memory Management for Parallel - and Distributed Environments: The Mach Approach</title> + <citetitle>Architecture-Independent Virtual Memory Management for Parallel + and Distributed Environments: The Mach Approach</citetitle> <subtitle>Technical Report CMU-CS-88-106,</subtitle> - <author> - <firstname>A.</firstname> - <surname>Tevanian</surname> - </author> + <author><personname><firstname>A.</firstname><surname>Tevanian</surname></personname></author> <publisher> <publishername>Department of Computer Science, Carnegie-Mellon diff --git a/en_US.ISO8859-1/books/dev-model/book.xml b/en_US.ISO8859-1/books/dev-model/book.xml index 91f3e6b981..593b777d26 100644 --- a/en_US.ISO8859-1/books/dev-model/book.xml +++ b/en_US.ISO8859-1/books/dev-model/book.xml @@ -1,10 +1,9 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; ]> - <!-- - Copyright (c) 2002-2005 Niklas Saers - All rights reserved. @@ -32,14 +31,10 @@ - - $FreeBSD$ --> - -<book lang='en'> - <bookinfo> - <title>A project model for the FreeBSD Project</title> - <author> - <firstname>Niklas</firstname> - <surname>Saers</surname> - </author> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>A project model for the FreeBSD Project</title> + + <author><personname><firstname>Niklas</firstname><surname>Saers</surname></personname></author> <copyright> <year>2002-2005</year> <holder>Niklas Saers</holder> @@ -91,8 +86,8 @@ </revhistory> <releaseinfo>$FreeBSD$</releaseinfo> - </bookinfo> - <preface id="foreword"> + </info> + <preface xml:id="foreword"> <title>Foreword</title> <para> @@ -140,7 +135,7 @@ </preface> - <chapter id="overview"> + <chapter xml:id="overview"> <title>Overview</title> @@ -193,8 +188,7 @@ </para> <para> - <citation><xref - linkend="freebsd-developer-handbook"/>, Section 1.2 and 1.3</citation> + <citation><xref linkend="freebsd-developer-handbook"/>, Section 1.2 and 1.3</citation> give the vision and the architectural guidelines for the project. The vision is <quote>To produce the best UNIX-like operating system package possible, with due respect to the @@ -205,10 +199,10 @@ </para> </chapter> - <chapter id="definitions"> + <chapter xml:id="definitions"> <title>Definitions</title> - <section id="ref-activity" xreflabel=""> + <section xml:id="ref-activity" xreflabel=""> <title>Activity</title> <para> @@ -223,7 +217,7 @@ </section> - <section id="def-process" xreflabel=""> + <section xml:id="def-process" xreflabel=""> <title>Process</title> <para> @@ -235,7 +229,7 @@ </section> - <section id="ref-hat" xreflabel="Hat"> + <section xml:id="ref-hat" xreflabel="Hat"> <title>Hat</title> <para> @@ -248,7 +242,7 @@ </section> - <section id="ref-outcome" xreflabel="Outcome"> + <section xml:id="ref-outcome" xreflabel="Outcome"> <title>Outcome</title> <para> @@ -258,8 +252,7 @@ item that must be produced to complete a project or part of a project. Often used more narrowly in reference to an external deliverable, which is a deliverable that is subject to approval - by the project sponsor or customer</quote> by <citation><xref - linkend="ref-pmbok"/></citation>. + by the project sponsor or customer</quote> by <citation><xref linkend="ref-pmbok"/></citation>. Examples of outcomes are a piece of software, a decision made or a report written. @@ -268,7 +261,7 @@ </section> - <section id="ref-freebsd" xreflabel=""> + <section xml:id="ref-freebsd" xreflabel=""> <title>FreeBSD</title> <para> @@ -280,7 +273,7 @@ </section> </chapter> - <chapter id="model-orgstruct"> + <chapter xml:id="model-orgstruct"> <title>Organisational structure</title> <para> @@ -292,7 +285,7 @@ <para> <figure> <title>The FreeBSD Project's structure</title> - <graphic fileref="orghierarchy"/> + <mediaobject><imageobject><imagedata fileref="orghierarchy"/></imageobject></mediaobject> </figure> </para> @@ -350,7 +343,7 @@ <para> <figure> <title>The FreeBSD Project's structure with committers in categories</title> - <graphic fileref="orghierarchy2"/> + <mediaobject><imageobject><imagedata fileref="orghierarchy2"/></imageobject></mediaobject> </figure> </para> <para> @@ -430,10 +423,10 @@ </chapter> - <chapter id="methodology-model"> + <chapter xml:id="methodology-model"> <title>Methodology model</title> - <section id="development-model"><title>Development model</title> + <section xml:id="development-model"><title>Development model</title> <para> There is no defined model for how people write code in @@ -444,7 +437,7 @@ <para> <figure> <title>Jørgenssen's model for change integration</title> - <graphic fileref="maintenance"/> + <mediaobject><imageobject><imagedata fileref="maintenance"/></imageobject></mediaobject> </figure> </para> @@ -581,7 +574,7 @@ </section> - <section id="release-branches"> + <section xml:id="release-branches"> <title>Release branches</title> <para> @@ -609,7 +602,7 @@ <para> <figure> <title>The FreeBSD release tree</title> - <graphic fileref="branches"/> + <mediaobject><imageobject><imagedata fileref="branches"/></imageobject></mediaobject> </figure> </para> <para> @@ -679,7 +672,7 @@ </section> - <section id="model-summary"> + <section xml:id="model-summary"> <title>Model summary</title> <para> @@ -690,7 +683,7 @@ <para> <figure> <title>The overall development model</title> - <graphic fileref="freebsd-code-model"/> + <mediaobject><imageobject><imagedata fileref="freebsd-code-model"/></imageobject></mediaobject> </figure> </para> <para> @@ -719,7 +712,7 @@ </chapter> - <chapter id="sect-hats"> + <chapter xml:id="sect-hats"> <title>Hats</title> <para> @@ -747,10 +740,10 @@ </para> - <section id="general-hats"> + <section xml:id="general-hats"> <title>General Hats</title> - <section id="role-contributor" xreflabel="Contributor"> + <section xml:id="role-contributor" xreflabel="Contributor"> <title>Contributor</title> <para> A Contributor contributes to the FreeBSD project either as a @@ -761,7 +754,7 @@ </para> </section> - <section id="role-committer" xreflabel="Committer"> + <section xml:id="role-committer" xreflabel="Committer"> <title>Committer</title> <para> A person who has the required privileges to add his code or documentation to the @@ -799,7 +792,7 @@ </para> </section> - <section id="role-core" xreflabel="Core team"> + <section xml:id="role-core" xreflabel="Core team"> <title>Core Team</title> @@ -816,7 +809,7 @@ </section> - <section id="role-maintainer" xreflabel="Maintainership"> + <section xml:id="role-maintainer" xreflabel="Maintainership"> <title>Maintainership</title> <para> @@ -856,7 +849,7 @@ </section> - <section id="official-hats"> + <section xml:id="official-hats"> <title>Official Hats</title> <para> @@ -870,7 +863,7 @@ <para> <figure> <title>Overview of official hats</title> - <graphic fileref="hats-overview"/> + <mediaobject><imageobject><imagedata fileref="hats-overview"/></imageobject></mediaobject> </figure> </para> @@ -883,8 +876,7 @@ - <section id="role-doc-manager" xreflabel="Documentation - project architect"> + <section xml:id="role-doc-manager" xreflabel="Documentation project architect"> <title>Documentation project manager</title> <para> <xref linkend="sub-project-documentation"/> @@ -897,12 +889,12 @@ Hat held by: The DocEng team <email>doceng@FreeBSD.org</email>. The - <ulink url="http://www.freebsd.org/internal/doceng.html"> - DocEng Charter</ulink>. + <link xlink:href="http://www.freebsd.org/internal/doceng.html"> + DocEng Charter</link>. </para> </section> - <section id="role-postmaster" xreflabel="Postmaster"> + <section xml:id="role-postmaster" xreflabel="Postmaster"> <title>Postmaster</title> <para> The Postmaster is responsible for mail being correctly @@ -917,7 +909,7 @@ </para> </section> - <section id="role-release-coordination" xreflabel="Release Coordination"> + <section xml:id="role-release-coordination" xreflabel="Release Coordination"> <title>Release Coordination</title> <para> @@ -948,16 +940,16 @@ available in the <xref linkend="process-release-engineering"/> section. </para> - <para id="role-releng" xreflabel="Release Engineering Team"> + <para xml:id="role-releng" xreflabel="Release Engineering Team"> Hat held by: the Release Engineering team <email>re@FreeBSD.org</email>. The - <ulink url="http://www.freebsd.org/releng/charter.html"> - Release Engineering Charter</ulink>. + <link xlink:href="http://www.freebsd.org/releng/charter.html"> + Release Engineering Charter</link>. </para> </section> - <section id="role-pr-cr" xreflabel="Public Relations & Corporate Liaison"> + <section xml:id="role-pr-cr" xreflabel="Public Relations & Corporate Liaison"> <title>Public Relations & Corporate Liaison</title> <para> The Public Relations & Corporate Liaison's @@ -986,7 +978,7 @@ </para> </section> - <section id="role-security-officer" xreflabel="Security Officer"> + <section xml:id="role-security-officer" xreflabel="Security Officer"> <title>Security Officer</title> <para> The Security Officer's main responsibility is to @@ -1010,7 +1002,7 @@ </para> </section> - <section id="role-repo-manager" xreflabel="Source Repository Manager"> + <section xml:id="role-repo-manager" xreflabel="Source Repository Manager"> <title>Source Repository Manager</title> <para> The Source Repository Manager is the only one who is allowed @@ -1028,7 +1020,7 @@ </para> </section> - <section id="role-election-manager" xreflabel="Election Manager"> + <section xml:id="role-election-manager" xreflabel="Election Manager"> <title>Election Manager</title> <para> The Election Manager is responsible for the @@ -1043,7 +1035,7 @@ </para> </section> - <section id="role-webmaster" xreflabel="Web site Management"> + <section xml:id="role-webmaster" xreflabel="Web site Management"> <title>Web site Management</title> <para> The Web site Management hat is responsible for coordinating @@ -1061,7 +1053,7 @@ </para> </section> - <section id="role-ports-manager" xreflabel="Ports Manager"> + <section xml:id="role-ports-manager" xreflabel="Ports Manager"> <title>Ports Manager</title> <para> The Ports Manager acts as a liaison between @@ -1075,12 +1067,12 @@ Hat held by: the Ports Management Team <email>portmgr@FreeBSD.org</email>. The - <ulink url="http://www.freebsd.org/portmgr/charter.html"> - Portmgr charter</ulink>. + <link xlink:href="http://www.freebsd.org/portmgr/charter.html"> + Portmgr charter</link>. </para> </section> - <section id="role-standards" xreflabel="Standards"> + <section xml:id="role-standards" xreflabel="Standards"> <title>Standards</title> <para> The Standards hat is responsible for ensuring that FreeBSD @@ -1098,7 +1090,7 @@ </para> </section> - <section id="role-core-secretary" xreflabel="Core Secretary"> + <section xml:id="role-core-secretary" xreflabel="Core Secretary"> <title>Core Secretary</title> <para> The Core Secretary's main responsibility is to write drafts to @@ -1111,7 +1103,7 @@ </para> </section> - <section id="role-gnats" xreflabel="GNATS Administrator"> + <section xml:id="role-gnats" xreflabel="GNATS Administrator"> <title>GNATS Administrator</title> <para> The GNATS Administrator is responsible for ensuring that the @@ -1124,7 +1116,7 @@ </para> </section> - <section id="role-bugmeister" xreflabel="Bugmeister"> + <section xml:id="role-bugmeister" xreflabel="Bugmeister"> <title>Bugmeister</title> <para> The Bugmeister is the person in charge of the problem report @@ -1137,7 +1129,7 @@ </para> </section> - <section id="role-donations" xreflabel="Donations Liaison Officer"> + <section xml:id="role-donations" xreflabel="Donations Liaison Officer"> <title>Donations Liaison Officer</title> <para> The task of @@ -1146,7 +1138,7 @@ organisations willing to make a donation. The Donations Liaison Charter is available - <ulink url="http://www.freebsd.org/donations/">here</ulink> + <link xlink:href="http://www.freebsd.org/donations/">here</link> </para> <para> Hat held by: @@ -1154,7 +1146,7 @@ </para> </section> - <section id="role-admin" xreflabel="Admin"> + <section xml:id="role-admin" xreflabel="Admin"> <title>Admin</title> <para> (Also called <quote>FreeBSD Cluster Admin</quote>) @@ -1181,10 +1173,10 @@ </section> - <section id="proc-depend-hats"> + <section xml:id="proc-depend-hats"> <title>Process dependent hats</title> - <section id="role-problem-originator" xreflabel="Report originator"> + <section xml:id="role-problem-originator" xreflabel="Report originator"> <title>Report originator</title> <para> The person originally responsible for @@ -1193,7 +1185,7 @@ </section> - <section id="role-bugbuster" xreflabel="Bugbuster"> + <section xml:id="role-bugbuster" xreflabel="Bugbuster"> <title>Bugbuster</title> <para> A person who will either find the right @@ -1203,7 +1195,7 @@ </para> </section> - <section id="role-mentor" xreflabel="Mentor"> + <section xml:id="role-mentor" xreflabel="Mentor"> <title>Mentor</title> <para> A mentor is a committer who takes it upon him/her to @@ -1215,7 +1207,7 @@ behaviour. </para> </section> - <section id="role-vendor" xreflabel="Vendor"> + <section xml:id="role-vendor" xreflabel="Vendor"> <title>Vendor</title> <para> The person(s) or organisation whom @@ -1223,7 +1215,7 @@ </para> </section> - <section id="role-reviewer" xreflabel="Reviewer"> + <section xml:id="role-reviewer" xreflabel="Reviewer"> <title>Reviewers</title> <para> People on the mailing list where the request @@ -1235,7 +1227,7 @@ </chapter> - <chapter id="model-processes" xreflabel="processes"> + <chapter xml:id="model-processes" xreflabel="processes"> <title>Processes</title> <para> @@ -1245,7 +1237,7 @@ similar cases. </para> - <section id="proc-addrem-committer"> + <section xml:id="proc-addrem-committer"> <title>Adding new and removing old committers</title> <para> @@ -1289,8 +1281,7 @@ admins@freebsd.org, the assigned mentor, the new committer and core confirming the approval of a new account. The mentor then gathers a password line, <xref linkend="tool-ssh2"/> public key and PGP key from the - new committer and sends them to <xref - linkend="role-admin"/>. When the new account is created, the + new committer and sends them to <xref linkend="role-admin"/>. When the new account is created, the mentor activates the commit bit and guides the new committer through the rest of the initial process. </para> @@ -1298,7 +1289,7 @@ <para> <figure> <title>Process summary: adding a new committer</title> - <graphic fileref="proc-add-committer"/> + <mediaobject><imageobject><imagedata fileref="proc-add-committer"/></imageobject></mediaobject> </figure> </para> @@ -1330,7 +1321,7 @@ <para> <figure> <title>Process summary: removing a committer</title> - <graphic fileref="proc-rm-committer"/> + <mediaobject><imageobject><imagedata fileref="proc-rm-committer"/></imageobject></mediaobject> </figure> </para> @@ -1378,7 +1369,7 @@ </section> - <section id="committing"> + <section xml:id="committing"> <title>Committing code</title> <para> @@ -1441,7 +1432,7 @@ <para> <figure> <title>Process summary: A committer commits code</title> - <graphic fileref="proc-commit"/> + <mediaobject><imageobject><imagedata fileref="proc-commit"/></imageobject></mediaobject> </figure> </para> @@ -1465,7 +1456,7 @@ <para> <figure> <title>Process summary: A contributor commits code</title> - <graphic fileref="proc-contrib"/> + <mediaobject><imageobject><imagedata fileref="proc-contrib"/></imageobject></mediaobject> </figure> </para> @@ -1501,7 +1492,7 @@ </section> - <section id="process-core-election" xreflabel="Core election"> + <section xml:id="process-core-election" xreflabel="Core election"> <title>Core election</title> <para> @@ -1526,9 +1517,8 @@ to submit their candidacy at least one week before the election starts, but can refine their statements until the voting starts. They are - presented in the <ulink - url="http://election.uk.freebsd.org/candidates.html">candidates - list</ulink>. When writing their election statements, the candidates + presented in the <link xlink:href="http://election.uk.freebsd.org/candidates.html">candidates + list</link>. When writing their election statements, the candidates must answer a few standard questions submitted by the election manager. </para> @@ -1565,7 +1555,7 @@ <para> <figure> <title>Process summary: Core elections</title> - <graphic fileref="proc-elections"/> + <mediaobject><imageobject><imagedata fileref="proc-elections"/></imageobject></mediaobject> </figure> </para> @@ -1603,7 +1593,7 @@ </para> </section> - <section id="new-features"> + <section xml:id="new-features"> <title>Development of new features</title> <para> @@ -1686,7 +1676,7 @@ </section> - <section id="model-maintenance" xreflabel="maintenance"> + <section xml:id="model-maintenance" xreflabel="maintenance"> <title>Maintenance</title> <para> @@ -1718,8 +1708,7 @@ <para> The main bulk of work that is put into the FreeBSD project is - maintenance. <citation><xref - linkend="jorgensen2001"/></citation> + maintenance. <citation><xref linkend="jorgensen2001"/></citation> has made a figure showing the life cycle of changes. </para> @@ -1727,7 +1716,7 @@ <para> <figure> <title>Jørgenssen's model for change integration</title> - <graphic fileref="maintenance"/> + <mediaobject><imageobject><imagedata fileref="maintenance"/></imageobject></mediaobject> </figure> </para> @@ -1769,7 +1758,7 @@ </section> - <section id="model-pr"> + <section xml:id="model-pr"> <title>Problem reporting</title> <para> @@ -1807,7 +1796,7 @@ <para> <figure> <title>Process summary: problem reporting</title> - <graphic fileref="proc-pr"/> + <mediaobject><imageobject><imagedata fileref="proc-pr"/></imageobject></mediaobject> </figure> </para> @@ -1843,7 +1832,7 @@ </section> - <section id="process-reactions" xreflabel="Reacting to misbehaviour"> + <section xml:id="process-reactions" xreflabel="Reacting to misbehaviour"> <title>Reacting to misbehaviour</title> <para> @@ -1904,7 +1893,7 @@ </section> - <section id="process-release-engineering" xreflabel="release engineering"> + <section xml:id="process-release-engineering" xreflabel="release engineering"> <title>Release engineering</title> <para> @@ -2044,7 +2033,7 @@ <para> <figure> <title>Process summary: release engineering</title> - <graphic fileref="proc-releng"/> + <mediaobject><imageobject><imagedata fileref="proc-releng"/></imageobject></mediaobject> </figure> </para> @@ -2067,7 +2056,7 @@ - <chapter id="tools"> + <chapter xml:id="tools"> <title>Tools</title> <para> @@ -2076,7 +2065,7 @@ developed tools and are commonly used in the open source world. </para> - <section id="tool-svn" xreflabel="SVN"> + <section xml:id="tool-svn" xreflabel="SVN"> <title>Subversion (SVN)</title> <para>Subversion (<quote>SVN</quote>) is a system to handle multiple versions of text files and @@ -2086,7 +2075,7 @@ </para> </section> - <section id="tool-gnats" xreflabel="GNATS"> + <section xml:id="tool-gnats" xreflabel="GNATS"> <title>GNATS</title> <para> GNATS is a maintenance database consisting of a set of tools to track bugs at a @@ -2100,7 +2089,7 @@ </para> </section> - <section id="model-mailman" xreflabel="[model, Mailman]"> + <section xml:id="model-mailman" xreflabel="[model, Mailman]"> <title>Mailman</title> <para> Mailman is a program that automates the @@ -2119,7 +2108,7 @@ </para> </section> - <section id="tool-perforce" xreflabel="Perforce"> + <section xml:id="tool-perforce" xreflabel="Perforce"> <title>Perforce</title> <para> Perforce is a commercial software configuration management @@ -2137,7 +2126,7 @@ </section> - <section id="tool-pgp" xreflabel="PGP"> + <section xml:id="tool-pgp" xreflabel="PGP"> <title>Pretty Good Privacy</title> <para> Pretty Good Privacy, better known as PGP, is a cryptosystem @@ -2152,7 +2141,7 @@ </para> </section> - <section id="tool-ssh2" xreflabel="SSH 2"> + <section xml:id="tool-ssh2" xreflabel="SSH 2"> <title>Secure Shell</title> <para> Secure Shell is a standard for securely logging into a remote system @@ -2169,7 +2158,7 @@ </chapter> - <chapter id="sub-projects"> + <chapter xml:id="sub-projects"> <title>Sub-projects</title> <para> @@ -2182,7 +2171,7 @@ </para> - <section id="sub-project-ports" xreflabel="The Ports Subproject"> + <section xml:id="sub-project-ports" xreflabel="The Ports Subproject"> <title>The Ports Subproject</title> <para> @@ -2193,16 +2182,16 @@ </para> <para> - <figure id="fig-ports"> + <figure xml:id="fig-ports"> <title>Number of ports added between 1996 and 2005</title> - <graphic fileref="portsstatus"/> + <mediaobject><imageobject><imagedata fileref="portsstatus"/></imageobject></mediaobject> </figure> </para> <para> <xref linkend="fig-ports"/> is taken from - <ulink url="http://www.freebsd.org/ports/growth/status.png"> - the FreeBSD web site</ulink>. It shows the number of ports + <link xlink:href="http://www.freebsd.org/ports/growth/status.png"> + the FreeBSD web site</link>. It shows the number of ports available to FreeBSD in the period 1995 to 2005. It looks like the curve has first grown exponentionally, and then since the middle of 2001 grown linearly. @@ -2252,8 +2241,7 @@ </section> - <section id="sub-project-documentation" xreflabel="The FreeBSD - Documentation Project"> + <section xml:id="sub-project-documentation" xreflabel="The FreeBSD Documentation Project"> <title>The FreeBSD Documentation Project</title> <para> @@ -2303,57 +2291,57 @@ </chapter> -<bibliography id="bibliography"> +<bibliography xml:id="bibliography"> <title>References</title> - <biblioentry id="brooks" xreflabel="Brooks, 1995"> + <biblioentry xml:id="brooks" xreflabel="Brooks, 1995"> <authorgroup> - <author><firstname>Frederick P.</firstname><surname>Brooks</surname></author> + <author><personname><firstname>Frederick P.</firstname><surname>Brooks</surname></personname></author> </authorgroup> <copyright><year>1975</year><year>1995</year> <holder>Pearson Education Limited</holder> </copyright> - <isbn>0201835959</isbn> + <biblioid class="isbn">0201835959</biblioid> <publisher> <publishername>Addison-Wesley Pub Co</publishername> </publisher> - <title>The Mythical Man-Month</title> + <citetitle>The Mythical Man-Month</citetitle> <subtitle>Essays on Software Engineering, Anniversary Edition (2nd Edition)</subtitle> </biblioentry> - <biblioentry id="thesis" xreflabel="Saers, 2003"> + <biblioentry xml:id="thesis" xreflabel="Saers, 2003"> <authorgroup> - <author><firstname>Niklas</firstname><surname>Saers</surname></author> + <author><personname><firstname>Niklas</firstname><surname>Saers</surname></personname></author> </authorgroup> <copyright> <year>2003</year> </copyright> - <title>A project model for the FreeBSD Project</title> + <citetitle>A project model for the FreeBSD Project</citetitle> <subtitle>Candidatus Scientiarum thesis</subtitle> - <bibliomisc role="url"><ulink url="http://niklas.saers.com/thesis"></ulink></bibliomisc> + <bibliomisc xlink:href="http://niklas.saers.com/thesis">http://niklas.saers.com/thesis</bibliomisc> </biblioentry> - <biblioentry id="jorgensen2001" xreflabel="Jørgensen, 2001"> + <biblioentry xml:id="jorgensen2001" xreflabel="Jørgensen, 2001"> <authorgroup> - <author><firstname>Niels</firstname><surname>Jørgensen</surname></author> + <author><personname><firstname>Niels</firstname><surname>Jørgensen</surname></personname></author> </authorgroup> <copyright> <year>2001</year> </copyright> - <title>Putting it All in the Trunk</title> + <citetitle>Putting it All in the Trunk</citetitle> <subtitle>Incremental Software Development in the FreeBSD Open Source Project</subtitle> - <bibliomisc role="url"><ulink url="http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf"></ulink></bibliomisc> + <bibliomisc xlink:href="http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf">http://www.dat.ruc.dk/~nielsj/research/papers/freebsd.pdf</bibliomisc> </biblioentry> - <biblioentry id="ref-pmbok" xreflabel="PMI, 2000"> + <biblioentry xml:id="ref-pmbok" xreflabel="PMI, 2000"> <authorgroup> - <author><surname>Project Management Institute</surname></author> + <author><personname><surname>Project Management Institute</surname></personname></author> </authorgroup> <copyright><year>1996</year><year>2000</year> <holder>Project Management Institute</holder> </copyright> - <isbn>1-880410-23-0</isbn> + <biblioid class="isbn">1-880410-23-0</biblioid> <publisher> <publishername>Project Management Institute</publishername> <address> @@ -2362,41 +2350,41 @@ <country>USA</country> </address> </publisher> - <title>PMBOK Guide</title> + <citetitle>PMBOK Guide</citetitle> <subtitle>A Guide to the Project Management Body of Knowledge, 2000 Edition</subtitle> </biblioentry> - <biblioentry id="freebsd-bylaws" xreflabel="FreeBSD, 2000A"> + <biblioentry xml:id="freebsd-bylaws" xreflabel="FreeBSD, 2000A"> <copyright><year>2002</year> <holder>The FreeBSD Project</holder> </copyright> - <title>Core Bylaws</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/bylaws.html"></ulink></bibliomisc> + <citetitle>Core Bylaws</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/internal/bylaws.html">http://www.freebsd.org/internal/bylaws.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-developer-handbook" xreflabel="FreeBSD, 2002A"> + <biblioentry xml:id="freebsd-developer-handbook" xreflabel="FreeBSD, 2002A"> <copyright><year>2002</year> <holder>The FreeBSD Documentation Project</holder> </copyright> - <title>FreeBSD Developer's Handbook</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/"></ulink></bibliomisc> + <citetitle>FreeBSD Developer's Handbook</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/">http://www.freebsd.org/doc/en_US.ISO8859-1/books/developers-handbook/</bibliomisc> </biblioentry> - <biblioentry id="bsd-election2002" xreflabel="FreeBSD, 2002B"> + <biblioentry xml:id="bsd-election2002" xreflabel="FreeBSD, 2002B"> <copyright><year>2002</year> <holder>The FreeBSD Project</holder> </copyright> - <title>Core team election 2002</title> - <bibliomisc role="url"><ulink url="http://election.uk.freebsd.org/candidates.html"></ulink></bibliomisc> + <citetitle>Core team election 2002</citetitle> + <bibliomisc xlink:href="http://election.uk.freebsd.org/candidates.html">http://election.uk.freebsd.org/candidates.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-handle-pr" xreflabel="FreeBSD, 2002C"> + <biblioentry xml:id="freebsd-handle-pr" xreflabel="FreeBSD, 2002C"> <authorgroup> - <author><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></author> - <author><firstname>Hiten</firstname><surname>Pandya</surname></author> + <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname></author> + <author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname></author> </authorgroup> <copyright><year>2002</year> <holder>The FreeBSD Documentation Project</holder> @@ -2404,13 +2392,13 @@ <publisher> <publishername>The FreeBSD Documentation Project</publishername> </publisher> - <title>Problem Report Handling Guidelines</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html"></ulink></bibliomisc> + <citetitle>Problem Report Handling Guidelines</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html">http://www.freebsd.org/doc/en/articles/pr-guidelines/article.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-send-pr" xreflabel="FreeBSD, 2002D"> + <biblioentry xml:id="freebsd-send-pr" xreflabel="FreeBSD, 2002D"> <authorgroup> - <author><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></author> + <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname></author> </authorgroup> <copyright><year>2002</year> <holder>The FreeBSD Documentation Project</holder> @@ -2418,11 +2406,11 @@ <publisher> <publishername>The FreeBSD Documentation Project</publishername> </publisher> - <title>Writing FreeBSD Problem Reports</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/problem-reports/article.html"></ulink></bibliomisc> + <citetitle>Writing FreeBSD Problem Reports</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en/articles/problem-reports/article.html">http://www.freebsd.org/doc/en/articles/problem-reports/article.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-committer" xreflabel="FreeBSD, 2001"> + <biblioentry xml:id="freebsd-committer" xreflabel="FreeBSD, 2001"> <copyright><year>2001</year> <holder>The FreeBSD Documentation Project</holder> </copyright> @@ -2430,13 +2418,13 @@ <publishername>The FreeBSD Documentation Project</publishername> </publisher> <!-- Version 1.146 --> - <title>Committers Guide</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en/articles/committers-guide/article.html"></ulink></bibliomisc> + <citetitle>Committers Guide</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en/articles/committers-guide/article.html">http://www.freebsd.org/doc/en/articles/committers-guide/article.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-releng" xreflabel="FreeBSD, 2002E"> + <biblioentry xml:id="freebsd-releng" xreflabel="FreeBSD, 2002E"> <authorgroup> - <author><firstname>Murray</firstname><surname>Stokely</surname></author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> </authorgroup> <copyright><year>2002</year> <holder>The FreeBSD Documentation Project</holder> @@ -2445,79 +2433,79 @@ <publisher> <publishername>The FreeBSD Documentation Project</publishername> </publisher> - <title>FreeBSD Release Engineering</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/article.html"></ulink></bibliomisc> + <citetitle>FreeBSD Release Engineering</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/article.html">http://www.freebsd.org/doc/en_US.ISO8859-1/articles/releng/article.html</bibliomisc> </biblioentry> - <biblioentry id="ref-bsd-handbook" xreflabel="FreeBSD, 2003A"> + <biblioentry xml:id="ref-bsd-handbook" xreflabel="FreeBSD, 2003A"> <authorgroup> - <author><surname>The FreeBSD Documentation Project</surname></author> + <author><personname><surname>The FreeBSD Documentation Project</surname></personname></author> </authorgroup> - <title>FreeBSD Handbook</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook"></ulink></bibliomisc> + <citetitle>FreeBSD Handbook</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook">http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook</bibliomisc> </biblioentry> - <biblioentry id="freebsd-contributors" xreflabel="FreeBSD, 2002F"> + <biblioentry xml:id="freebsd-contributors" xreflabel="FreeBSD, 2002F"> <copyright><year>2002</year> <holder>The FreeBSD Documentation Project</holder> </copyright> <publisher> <publishername>The FreeBSD Documentation Project</publishername> </publisher> - <title>Contributors to FreeBSD</title> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/article.html"></ulink></bibliomisc> + <citetitle>Contributors to FreeBSD</citetitle> + <bibliomisc xlink:href="http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/article.html">http://www.freebsd.org/doc/en_US.ISO8859-1/articles/contributors/article.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-election" xreflabel="FreeBSD, 2002G"> + <biblioentry xml:id="freebsd-election" xreflabel="FreeBSD, 2002G"> <copyright><year>2002</year> <holder>The FreeBSD Project</holder> </copyright> <publisher> <publishername>The FreeBSD Project</publishername> </publisher> - <title>Core team elections 2002</title> - <bibliomisc role="url"><ulink url="http://election.uk.freebsd.org"></ulink></bibliomisc> + <citetitle>Core team elections 2002</citetitle> + <bibliomisc xlink:href="http://election.uk.freebsd.org">http://election.uk.freebsd.org</bibliomisc> </biblioentry> - <biblioentry id="freebsd-expiration-policy" xreflabel="FreeBSD, 2002H"> + <biblioentry xml:id="freebsd-expiration-policy" xreflabel="FreeBSD, 2002H"> <copyright><year>2002</year> <holder>The FreeBSD Project</holder> </copyright> <publisher> <publishername>The FreeBSD Project</publishername> </publisher> - <title>Commit Bit Expiration Policy</title> + <citetitle>Commit Bit Expiration Policy</citetitle> <subtitle>2002/04/06 15:35:30</subtitle> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/expire-bits.html"></ulink></bibliomisc> + <bibliomisc xlink:href="http://www.freebsd.org/internal/expire-bits.html">http://www.freebsd.org/internal/expire-bits.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-new-account" xreflabel="FreeBSD, 2002I"> + <biblioentry xml:id="freebsd-new-account" xreflabel="FreeBSD, 2002I"> <copyright><year>2002</year> <holder>The FreeBSD Project</holder> </copyright> <publisher> <publishername>The FreeBSD Project</publishername> </publisher> - <title>New Account Creation Procedure</title> + <citetitle>New Account Creation Procedure</citetitle> <subtitle>2002/08/19 17:11:27</subtitle> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/new-account.html"></ulink></bibliomisc> + <bibliomisc xlink:href="http://www.freebsd.org/internal/new-account.html">http://www.freebsd.org/internal/new-account.html</bibliomisc> </biblioentry> - <biblioentry id="freebsd-doceng-charter" xreflabel="FreeBSD, 2003B"> + <biblioentry xml:id="freebsd-doceng-charter" xreflabel="FreeBSD, 2003B"> <copyright><year>2002</year> <holder>The FreeBSD Documentation Project</holder> </copyright> <publisher> <publishername>The FreeBSD Documentation Project</publishername> </publisher> - <title>FreeBSD DocEng Team Charter</title> + <citetitle>FreeBSD DocEng Team Charter</citetitle> <subtitle>2003/03/16 12:17</subtitle> - <bibliomisc role="url"><ulink url="http://www.freebsd.org/internal/doceng.html"></ulink></bibliomisc> + <bibliomisc xlink:href="http://www.freebsd.org/internal/doceng.html">http://www.freebsd.org/internal/doceng.html</bibliomisc> </biblioentry> - <biblioentry id="ref-freebsd-trenches" xreflabel="Lehey, 2002"> + <biblioentry xml:id="ref-freebsd-trenches" xreflabel="Lehey, 2002"> <authorgroup> - <author><firstname>Greg</firstname><surname>Lehey</surname></author> + <author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname></author> </authorgroup> <copyright><year>2002</year> <holder>Greg Lehey</holder> @@ -2525,9 +2513,9 @@ <publisher> <publishername>Greg Lehey</publishername> </publisher> - <title>Two years in the trenches</title> + <citetitle>Two years in the trenches</citetitle> <subtitle>The evolution of a software project</subtitle> - <bibliomisc role="url"><ulink url="http://www.lemis.com/grog/In-the-trenches.pdf"></ulink></bibliomisc> + <bibliomisc xlink:href="http://www.lemis.com/grog/In-the-trenches.pdf">http://www.lemis.com/grog/In-the-trenches.pdf</bibliomisc> </biblioentry> </bibliography> diff --git a/en_US.ISO8859-1/books/developers-handbook/Makefile b/en_US.ISO8859-1/books/developers-handbook/Makefile index 2d673e307e..8c5bb2209c 100644 --- a/en_US.ISO8859-1/books/developers-handbook/Makefile +++ b/en_US.ISO8859-1/books/developers-handbook/Makefile @@ -10,8 +10,6 @@ DOC?= book FORMATS?= html-split -HAS_INDEX= true - INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= diff --git a/en_US.ISO8859-1/books/developers-handbook/book.xml b/en_US.ISO8859-1/books/developers-handbook/book.xml index 622e745d64..941e222568 100644 --- a/en_US.ISO8859-1/books/developers-handbook/book.xml +++ b/en_US.ISO8859-1/books/developers-handbook/book.xml @@ -1,20 +1,18 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; ]> - <!-- The FreeBSD Documentation Project $FreeBSD$ --> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD Developers' Handbook</title> + -<book lang='en'> - <bookinfo> - <title>FreeBSD Developers' Handbook</title> - - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> <pubdate>$FreeBSD$</pubdate> @@ -38,7 +36,7 @@ &legalnotice; - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.apple; &tm-attrib.ibm; @@ -61,17 +59,15 @@ helping with this project, send email to the &a.doc;.</para> <para>The latest version of this document is always available - from the <ulink url="&url.base;/index.html">FreeBSD World - Wide Web server</ulink>. It may also be downloaded in a - variety of formats and compression options from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP - server</ulink> or one of the numerous <ulink - url="&url.books.handbook;/mirrors-ftp.html">mirror - sites</ulink>.</para> + from the <link xlink:href="&url.base;/index.html">FreeBSD World + Wide Web server</link>. It may also be downloaded in a + variety of formats and compression options from the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD FTP + server</link> or one of the numerous <link xlink:href="&url.books.handbook;/mirrors-ftp.html">mirror + sites</link>.</para> </abstract> - </bookinfo> + </info> - <part id="Basics"> + <part xml:id="Basics"> <title>Basics</title> &chap.introduction; @@ -82,7 +78,7 @@ &chap.testing; </part> - <part id="ipc"> + <part xml:id="ipc"> <title>Interprocess Communication</title> &chap.sockets; @@ -90,7 +86,7 @@ </part> - <part id="kernel"> + <part xml:id="kernel"> <title>Kernel</title> &chap.kernelbuild; @@ -98,123 +94,86 @@ </part> - <part id="architectures"> + <part xml:id="architectures"> <title>Architectures</title> &chap.x86; </part> - <part id="appendices"> + <part xml:id="appendices"> <title>Appendices</title> <bibliography> - <biblioentry id="COD" xreflabel="1"> + <biblioentry xml:id="COD" xreflabel="1"> <authorgroup> - <author> - <firstname>Dave</firstname> - <othername role="MI">A</othername> - <surname>Patterson</surname> - </author> - <author> - <firstname>John</firstname> - <othername role="MI">L</othername> - <surname>Hennessy</surname> - </author> + <author><personname><firstname>Dave</firstname><othername role="MI">A</othername><surname>Patterson</surname></personname></author> + <author><personname><firstname>John</firstname><othername role="MI">L</othername><surname>Hennessy</surname></personname></author> </authorgroup> <copyright><year>1998</year><holder>Morgan Kaufmann Publishers, Inc.</holder></copyright> - <isbn>1-55860-428-6</isbn> + <biblioid class="isbn">1-55860-428-6</biblioid> <publisher> <publishername>Morgan Kaufmann Publishers, Inc.</publishername> </publisher> - <title>Computer Organization and Design</title> + <citetitle>Computer Organization and Design</citetitle> <subtitle>The Hardware / Software Interface</subtitle> <pagenums>1-2</pagenums> </biblioentry> <biblioentry xreflabel="2"> <authorgroup> - <author> - <firstname>W.</firstname> - <othername role="Middle">Richard</othername> - <surname>Stevens</surname> - </author> + <author><personname><firstname>W.</firstname><othername role="Middle">Richard</othername><surname>Stevens</surname></personname></author> </authorgroup> <copyright><year>1993</year><holder>Addison Wesley Longman, Inc.</holder></copyright> - <isbn>0-201-56317-7</isbn> + <biblioid class="isbn">0-201-56317-7</biblioid> <publisher> <publishername>Addison Wesley Longman, Inc.</publishername> </publisher> - <title>Advanced Programming in the Unix Environment</title> + <citetitle>Advanced Programming in the Unix Environment</citetitle> <pagenums>1-2</pagenums> </biblioentry> <biblioentry xreflabel="3"> <authorgroup> - <author> - <firstname>Marshall</firstname> - <othername role="Middle">Kirk</othername> - <surname>McKusick</surname> - </author> - <author> - <firstname>George</firstname> - <surname>Neville-Neil</surname> - </author> + <author><personname><firstname>Marshall</firstname><othername role="Middle">Kirk</othername><surname>McKusick</surname></personname></author> + <author><personname><firstname>George</firstname><surname>Neville-Neil</surname></personname></author> </authorgroup> <copyright><year>2004</year><holder>Addison-Wesley</holder></copyright> - <isbn>0-201-70245-2</isbn> + <biblioid class="isbn">0-201-70245-2</biblioid> <publisher> <publishername>Addison-Wesley</publishername> </publisher> - <title>The Design and Implementation of the FreeBSD Operating System</title> + <citetitle>The Design and Implementation of the FreeBSD Operating System</citetitle> <pagenums>1-2</pagenums> </biblioentry> - <biblioentry id="Phrack" xreflabel="4"> + <biblioentry xml:id="Phrack" xreflabel="4"> <authorgroup> - <author> - <firstname>Aleph</firstname> - <surname>One</surname> - </author> + <author><personname><firstname>Aleph</firstname><surname>One</surname></personname></author> </authorgroup> - <title>Phrack 49; "Smashing the Stack for Fun and Profit"</title> + <citetitle>Phrack 49; "Smashing the Stack for Fun and Profit"</citetitle> </biblioentry> - <biblioentry id="StackGuard" xreflabel="5"> + <biblioentry xml:id="StackGuard" xreflabel="5"> <authorgroup> - <author> - <firstname>Chrispin</firstname> - <surname>Cowan</surname> - </author> - <author> - <firstname>Calton</firstname> - <surname>Pu</surname> - </author> - <author> - <firstname>Dave</firstname> - <surname>Maier</surname> - </author> + <author><personname><firstname>Chrispin</firstname><surname>Cowan</surname></personname></author> + <author><personname><firstname>Calton</firstname><surname>Pu</surname></personname></author> + <author><personname><firstname>Dave</firstname><surname>Maier</surname></personname></author> </authorgroup> - <title>StackGuard; Automatic Adaptive Detection and Prevention of - Buffer-Overflow Attacks</title> + <citetitle>StackGuard; Automatic Adaptive Detection and Prevention of + Buffer-Overflow Attacks</citetitle> </biblioentry> - <biblioentry id="OpenBSD" xreflabel="6"> + <biblioentry xml:id="OpenBSD" xreflabel="6"> <authorgroup> - <author> - <firstname>Todd</firstname> - <surname>Miller</surname> - </author> - <author> - <firstname>Theo</firstname> - <surname>de Raadt</surname> - </author> + <author><personname><firstname>Todd</firstname><surname>Miller</surname></personname></author> + <author><personname><firstname>Theo</firstname><surname>de Raadt</surname></personname></author> </authorgroup> - <title>strlcpy and strlcat -- consistent, safe string copy and - concatenation.</title> + <citetitle>strlcpy and strlcat -- consistent, safe string copy and + concatenation.</citetitle> </biblioentry> </bibliography> diff --git a/en_US.ISO8859-1/books/developers-handbook/chapters.ent b/en_US.ISO8859-1/books/developers-handbook/chapters.ent index 555d115d40..795553bda9 100644 --- a/en_US.ISO8859-1/books/developers-handbook/chapters.ent +++ b/en_US.ISO8859-1/books/developers-handbook/chapters.ent @@ -10,8 +10,6 @@ $FreeBSD$ --> -<!ENTITY % chap.index "IGNORE"> - <!-- Part one --> <!ENTITY chap.introduction SYSTEM "introduction/chapter.xml"> <!ENTITY chap.tools SYSTEM "tools/chapter.xml"> @@ -32,7 +30,4 @@ <!ENTITY chap.x86 SYSTEM "x86/chapter.xml"> <!-- Part six - Appendices --> -<![%chap.index;[ - <!ENTITY chap.index SYSTEM "index.xml"> -]]> -<!ENTITY chap.index ""> +<!ENTITY chap.index "<index xmlns='http://docbook.org/ns/docbook'/>"> diff --git a/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.xml index 0f7e8270b7..899c0bc0a3 100644 --- a/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/introduction/chapter.xml @@ -4,24 +4,16 @@ $FreeBSD$ --> - -<chapter id="introduction"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="introduction"> + <info><title>Introduction</title> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>Jeroen</firstname> - <surname>Ruigrok van der Werven</surname> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Contributed by </contrib></author> + <author><personname><firstname>Jeroen</firstname><surname>Ruigrok van der Werven</surname></personname></author> </authorgroup> - </chapterinfo> - <title>Introduction</title> + </info> + - <sect1 id="introduction-devel"> + <sect1 xml:id="introduction-devel"> <title>Developing on FreeBSD</title> <para>So here we are. System all installed and you are ready to @@ -36,7 +28,7 @@ for the programmer unfamiliar with the &os; platform.</para> </sect1> - <sect1 id="introduction-bsdvision"> + <sect1 xml:id="introduction-bsdvision"> <title>The BSD Vision</title> <para>To produce the best &unix; like operating system package @@ -45,7 +37,7 @@ stability.</para> </sect1> - <sect1 id="introduction-archguide"> + <sect1 xml:id="introduction-archguide"> <title>Architectural Guidelines</title> <para>Our ideology can be described by the following @@ -94,13 +86,13 @@ <para>From Scheifler & Gettys: "X Window System"</para> </sect1> - <sect1 id="introduction-layout"> + <sect1 xml:id="introduction-layout"> <title>The Layout of - <filename class="directory">/usr/src</filename></title> + <filename>/usr/src</filename></title> <para>The complete source code to FreeBSD is available from our public repository. The source code is normally installed in - <filename class="directory">/usr/src</filename> which contains + <filename>/usr/src</filename> which contains the following subdirectories:</para> <para> @@ -115,140 +107,111 @@ <tbody> <row> - <entry><filename - class="directory">bin/</filename></entry> + <entry><filename>bin/</filename></entry> <entry>Source for files in <filename>/bin</filename></entry> </row> <row> - <entry><filename - class="directory">cddl/</filename></entry> + <entry><filename>cddl/</filename></entry> <entry>Utilities covered by the Common Development and Distribution License</entry> </row> <row> - <entry><filename - class="directory">contrib/</filename></entry> + <entry><filename>contrib/</filename></entry> <entry>Source for files from contributed software.</entry> </row> <row> - <entry><filename - class="directory">crypto/</filename></entry> + <entry><filename>crypto/</filename></entry> <entry>Cryptographical sources</entry> </row> <row> - <entry><filename - class="directory">etc/</filename></entry> - <entry>Source for files in <filename - class="directory">/etc</filename></entry> + <entry><filename>etc/</filename></entry> + <entry>Source for files in <filename>/etc</filename></entry> </row> <row> - <entry><filename - class="directory">games/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/games</filename></entry> + <entry><filename>games/</filename></entry> + <entry>Source for files in <filename>/usr/games</filename></entry> </row> <row> - <entry><filename - class="directory">gnu/</filename></entry> + <entry><filename>gnu/</filename></entry> <entry>Utilities covered by the GNU Public License</entry> </row> <row> - <entry><filename - class="directory">include/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/include</filename></entry> + <entry><filename>include/</filename></entry> + <entry>Source for files in <filename>/usr/include</filename></entry> </row> <row> - <entry><filename - class="directory">kerberos5/</filename></entry> + <entry><filename>kerberos5/</filename></entry> <entry>Source for Kerberos version 5</entry> </row> <row> - <entry><filename - class="directory">lib/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/lib</filename></entry> + <entry><filename>lib/</filename></entry> + <entry>Source for files in <filename>/usr/lib</filename></entry> </row> <row> - <entry><filename - class="directory">libexec/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/libexec</filename></entry> + <entry><filename>libexec/</filename></entry> + <entry>Source for files in <filename>/usr/libexec</filename></entry> </row> <row> - <entry><filename - class="directory">release/</filename></entry> + <entry><filename>release/</filename></entry> <entry>Files required to produce a FreeBSD release</entry> </row> <row> - <entry><filename - class="directory">rescue/</filename></entry> + <entry><filename>rescue/</filename></entry> <entry>Build system for the - <filename class="directory">/rescue</filename> + <filename>/rescue</filename> utilities</entry> </row> <row> - <entry><filename - class="directory">sbin/</filename></entry> - <entry>Source for files in <filename - class="directory">/sbin</filename></entry> + <entry><filename>sbin/</filename></entry> + <entry>Source for files in <filename>/sbin</filename></entry> </row> <row> - <entry><filename - class="directory">secure/</filename></entry> + <entry><filename>secure/</filename></entry> <entry>FreeSec sources</entry> </row> <row> - <entry><filename - class="directory">share/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/share</filename></entry> + <entry><filename>share/</filename></entry> + <entry>Source for files in <filename>/usr/share</filename></entry> </row> <row> - <entry><filename - class="directory">sys/</filename></entry> + <entry><filename>sys/</filename></entry> <entry>Kernel source files</entry> </row> <row> - <entry><filename - class="directory">tools/</filename></entry> + <entry><filename>tools/</filename></entry> <entry>Tools used for maintenance and testing of FreeBSD</entry> </row> <row> - <entry><filename - class="directory">usr.bin/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/bin</filename></entry> + <entry><filename>usr.bin/</filename></entry> + <entry>Source for files in <filename>/usr/bin</filename></entry> </row> <row> - <entry><filename - class="directory">usr.sbin/</filename></entry> - <entry>Source for files in <filename - class="directory">/usr/sbin</filename></entry> + <entry><filename>usr.sbin/</filename></entry> + <entry>Source for files in <filename>/usr/sbin</filename></entry> </row> </tbody> </tgroup> diff --git a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml index 66c0ff75b9..1ec2147461 100644 --- a/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/ipv6/chapter.xml @@ -4,29 +4,23 @@ $FreeBSD$ --> - -<chapter id="ipv6"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ipv6"> <title>IPv6 Internals</title> - <sect1 id="ipv6-implementation"> - <sect1info> + <sect1 xml:id="ipv6-implementation"> + <info><title>IPv6/IPsec Implementation</title> <authorgroup> - <author> - <firstname>Yoshinobu</firstname> - <surname>Inoue</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Yoshinobu</firstname><surname>Inoue</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- March 2000 --> - </sect1info> + + </info> - <title>IPv6/IPsec Implementation</title> + <para>This section should explain IPv6 and IPsec related implementation - internals. These functionalities are derived from <ulink - url="http://www.kame.net/">KAME project</ulink></para> + internals. These functionalities are derived from <link xlink:href="http://www.kame.net/">KAME project</link></para> - <sect2 id="ipv6details"> + <sect2 xml:id="ipv6details"> <title>IPv6</title> <sect3> @@ -42,9 +36,9 @@ <para>Conformance tests have been performed on the KAME STABLE kit at TAHI project. Results can be viewed at - <ulink url="http://www.tahi.org/report/KAME/"></ulink>. + <uri xlink:href="http://www.tahi.org/report/KAME/">http://www.tahi.org/report/KAME/</uri>. We also attended Univ. of New Hampshire IOL tests - (<ulink url="http://www.iol.unh.edu/"></ulink>) in the + (<uri xlink:href="http://www.iol.unh.edu/">http://www.iol.unh.edu/</uri>) in the past, with our past snapshots.</para> <itemizedlist> @@ -233,8 +227,7 @@ <itemizedlist> <listitem> <para>IPv4 mapped address (3.7) and special behavior of IPv6 - wildcard bind socket (3.8) are supported. See <link - linkend="ipv6-wildcard-socket">23.5.1.12</link> + wildcard bind socket (3.8) are supported. See <link linkend="ipv6-wildcard-socket">23.5.1.12</link> in this document for details.</para> </listitem> </itemizedlist> @@ -308,7 +301,7 @@ </itemizedlist> </sect3> - <sect3 id="neighbor-discovery"> + <sect3 xml:id="neighbor-discovery"> <title>Neighbor Discovery</title> <para>Neighbor Discovery is fairly stable. Currently Address @@ -367,7 +360,7 @@ we may provide sysctl knob for the variable.</para> </sect3> - <sect3 id="ipv6-scope-index"> + <sect3 xml:id="ipv6-scope-index"> <title>Scope Index</title> <para>IPv6 uses scoped addresses. Therefore, it is very important to @@ -430,7 +423,7 @@ link and an interface, which is stronger than what specs say.</para> </sect3> - <sect3 id="ipv6-pnp"> + <sect3 xml:id="ipv6-pnp"> <title>Plug and Play</title> <para>Most of the IPv6 stateless address autoconfiguration is implemented @@ -549,7 +542,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> </sect4> </sect3> - <sect3 id="gif"> + <sect3 xml:id="gif"> <title>Generic tunnel interface</title> <para>GIF (Generic InterFace) is a pseudo interface for configured @@ -577,8 +570,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> routing tables to perform infinite level of tunneling. <emphasis>Please be warned</emphasis>.</para> - <para>gif can be configured to be ECN-friendly. See <link - linkend="ipsec-ecn">23.5.4.5</link> for ECN-friendliness of + <para>gif can be configured to be ECN-friendly. See <link linkend="ipsec-ecn">23.5.4.5</link> for ECN-friendliness of tunnels, and &man.gif.4; for how to configure.</para> <para>If you would like to configure an IPv4-in-IPv6 tunnel with gif @@ -587,7 +579,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> interface.</para> </sect3> - <sect3 id="ipv6-sas"> + <sect3 xml:id="ipv6-sas"> <title>Source Address Selection</title> <para>Current source selection rule is scope oriented (there are some @@ -633,8 +625,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> <para>For instance, ::1 is selected for ff01::1, fe80:1::200:f8ff:fe01:6317 for fe80:1::2a0:24ff:feab:839b (note - that embedded interface index - described in <link - linkend="ipv6-scope-index">23.5.1.3</link> - helps us + that embedded interface index - described in <link linkend="ipv6-scope-index">23.5.1.3</link> - helps us choose the right source address. Those embedded indices will not be on the wire). If the outgoing interface has multiple address for the scope, a source is selected longest match basis (rule 3). Suppose @@ -664,7 +655,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> address).</para> </sect3> - <sect3 id="ipv6-jumbo"> + <sect3 xml:id="ipv6-jumbo"> <title>Jumbo Payload</title> <para>The Jumbo Payload hop-by-hop option is implemented and can @@ -782,7 +773,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> attack.)</para> </sect3> - <sect3 id="icmpv6"> + <sect3 xml:id="icmpv6"> <title>ICMPv6</title> <para>After RFC2463 was published, IETF ipngwg has decided to @@ -853,7 +844,7 @@ fe80:2::%ep0/64 link#2 UC ep0</screen> <para>Both IP and IP6 reassemble functions never call m_pullup().</para> </sect3> - <sect3 id="ipv6-wildcard-socket"> + <sect3 xml:id="ipv6-wildcard-socket"> <title>IPv4 mapped address and IPv6 wildcard socket</title> <para>RFC2553 describes IPv4 mapped address (3.7) and special behavior @@ -1217,7 +1208,7 @@ FreeBSD 4.x configurable supported </sect3> </sect2> - <sect2 id="ipsec-implementation"> + <sect2 xml:id="ipsec-implementation"> <title>IPsec</title> <para>IPsec is mainly organized by three components.</para> @@ -1327,9 +1318,8 @@ FreeBSD 4.x configurable supported <filename>rfc240[1-6].txt</filename>, <filename>rfc241[01].txt</filename>, <filename>rfc2451.txt</filename> and <filename>draft-mcdonald-simple-ipsec-api-01.txt</filename> - (draft expired, but you can take from <ulink - url="ftp://ftp.kame.net/pub/internet-drafts/"> - ftp://ftp.kame.net/pub/internet-drafts/</ulink>). + (draft expired, but you can take from <link xlink:href="ftp://ftp.kame.net/pub/internet-drafts/"> + ftp://ftp.kame.net/pub/internet-drafts/</link>). (NOTE: IKE specifications, <filename>rfc241[7-9].txt</filename> are implemented in userland, as "racoon" IKE daemon)</para> @@ -1475,7 +1465,7 @@ FreeBSD 4.x configurable supported property issues only).</para> </sect3> - <sect3 id="ipsec-ecn"> + <sect3 xml:id="ipsec-ecn"> <title>ECN consideration on IPsec tunnels</title> <para>ECN-friendly IPsec tunnel is supported as described in @@ -1489,9 +1479,8 @@ FreeBSD 4.x configurable supported lost.</para> <para>To make IPsec tunnel ECN-friendly, we should modify encapsulation - and decapsulation procedure. This is described in <ulink - url="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt"> - http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</ulink>, + and decapsulation procedure. This is described in <link xlink:href="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt"> + http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</link>, chapter 3.</para> <para>IPsec tunnel implementation can give you three behaviors, by @@ -1554,9 +1543,8 @@ ECN allowed copy TOS bits except for ECN use inner TOS bits with some <para>For more information, please refer to:</para> - <para><ulink - url="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt"> - http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</ulink>, + <para><link xlink:href="http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt"> + http://www.aciri.org/floyd/papers/draft-ipsec-ecn-00.txt</link>, RFC2481 (Explicit Congestion Notification), src/sys/netinet6/{ah,esp}_input.c</para> diff --git a/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml index 0c147b8eb6..9b3420b8ab 100644 --- a/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/kernelbuild/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="kernelbuild"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="kernelbuild"> <title>Building and Installing a &os; Kernel</title> <para>Being a kernel developer requires understanding of the kernel @@ -24,21 +23,20 @@ <note> <para>It is supposed that the reader of this chapter is familiar - with the information described in the <ulink - url="../handbook/kernelconfig-building.html">Building and - Installing a Custom Kernel</ulink> chapter of the &os; + with the information described in the <link xlink:href="../handbook/kernelconfig-building.html">Building and + Installing a Custom Kernel</link> chapter of the &os; Handbook. If this is not the case, please read through the above mentioned chapter to understand how the build process works.</para> </note> - <sect1 id="kernelbuild-traditional"> + <sect1 xml:id="kernelbuild-traditional"> <title>Building a Kernel the <quote>Traditional</quote> Way</title> <para>Up to version 4.X of &os; this was the recommended way to build a new kernel. It can still be used on newer versions (instead of the <quote>buildkernel</quote> target of the toplevel - <filename class="directory">/usr/src/</filename> makefiles). + <filename>/usr/src/</filename> makefiles). Building the kernel this way may be useful when working on the kernel code and it may actually be faster than the <quote>New</quote> procedure when only a single option or two were @@ -51,7 +49,7 @@ <para>Run &man.config.8; to generate the kernel source code:</para> - <screen>&prompt.root; <userinput>/usr/sbin/config <replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>/usr/sbin/config MYKERNEL</userinput></screen> </step> <step> @@ -59,7 +57,7 @@ print the name of this directory after being run as above.</para> - <screen>&prompt.root; <userinput>cd ../compile/<replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cd ../compile/MYKERNEL</userinput></screen> </step> <step> @@ -77,13 +75,12 @@ </procedure> </sect1> - <sect1 id="kernelbuild-new"> + <sect1 xml:id="kernelbuild-new"> <title>Building a Kernel the <quote>New</quote> Way</title> <para>This procedure is well supported and recommended under the - latest &os; releases and is documented in the <ulink - url="../handbook/kernelconfig-building.html">Building and - Installing a Custom Kernel</ulink> chapter of the &os; + latest &os; releases and is documented in the <link xlink:href="../handbook/kernelconfig-building.html">Building and + Installing a Custom Kernel</link> chapter of the &os; Handbook.</para> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml index b901c833e4..cc5b911182 100644 --- a/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/kerneldebug/chapter.xml @@ -4,29 +4,18 @@ $FreeBSD$ --> - -<chapter id="kerneldebug"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="kerneldebug"> + <info><title>Kernel Debugging</title> <authorgroup> - <author> - <firstname>Paul</firstname> - <surname>Richards</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>Jörg</firstname> - <surname>Wunsch</surname> - </author> - <author> - <firstname>Robert</firstname> - <surname>Watson</surname> - </author> + <author><personname><firstname>Paul</firstname><surname>Richards</surname></personname><contrib>Contributed by </contrib></author> + <author><personname><firstname>Jörg</firstname><surname>Wunsch</surname></personname></author> + <author><personname><firstname>Robert</firstname><surname>Watson</surname></personname></author> </authorgroup> - </chapterinfo> + </info> - <title>Kernel Debugging</title> + - <sect1 id="kerneldebug-obtain"> + <sect1 xml:id="kerneldebug-obtain"> <title>Obtaining a Kernel Crash Dump</title> <para>When running a development kernel (e.g., &os.current;), such as a @@ -64,7 +53,7 @@ memory dump, as most problems can be isolated only using kernel state.</para> - <sect2 id="config-dumpdev"> + <sect2 xml:id="config-dumpdev"> <title>Configuring the Dump Device</title> <para>Before the kernel will dump the contents of its physical @@ -101,7 +90,7 @@ </important> </sect2> - <sect2 id="extract-dump"> + <sect2 xml:id="extract-dump"> <title>Extracting a Kernel Dump</title> <para>Once a dump has been written to a dump device, the dump @@ -149,7 +138,7 @@ </sect2> </sect1> - <sect1 id="kerneldebug-gdb"> + <sect1 xml:id="kerneldebug-gdb"> <title>Debugging a Kernel Crash Dump with <command>kgdb</command></title> <note> @@ -164,8 +153,8 @@ the crash dump, locate the debug version of your kernel (normally called <filename>kernel.debug</filename>) and the path to the source files used to build your kernel (normally - <filename>/usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></filename>, - where <filename><replaceable>KERNCONF</replaceable></filename> + <filename>/usr/obj/usr/src/sys/KERNCONF</filename>, + where <filename>KERNCONF</filename> is the <varname>ident</varname> specified in a kernel &man.config.5;). With those two pieces of info, let the debugging commence!</para> @@ -173,7 +162,7 @@ <para>To enter into the debugger and begin getting information from the dump, the following steps are required at a minimum:</para> - <screen>&prompt.root; <userinput>cd /usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></userinput> + <screen>&prompt.root; <userinput>cd /usr/obj/usr/src/sys/KERNCONF</userinput> &prompt.root; <userinput>kgdb kernel.debug /var/crash/vmcore.0</userinput></screen> <para>You can debug the crash dump using the kernel sources just like @@ -191,7 +180,7 @@ your patch winds its way into the source tree via a problem report, mailing lists, or by being able to commit it!</para> - <screen> 1:&prompt.root; <userinput>cd /usr/obj/usr/src/sys/<replaceable>KERNCONF</replaceable></userinput> + <screen> 1:&prompt.root; <userinput>cd /usr/obj/usr/src/sys/KERNCONF</userinput> 2:&prompt.root; <userinput>kgdb kernel.debug /var/crash/vmcore.0</userinput> 3:GNU gdb 5.2.1 (FreeBSD) 4:Copyright 2002 Free Software Foundation, Inc. @@ -432,12 +421,12 @@ considerable amount of disk space!</para></tip> </sect1> - <sect1 id="kerneldebug-ddd"> + <sect1 xml:id="kerneldebug-ddd"> <title>Debugging a Crash Dump with DDD</title> <para>Examining a kernel crash dump with a graphical debugger like <command>ddd</command> is also possible (you will need to install - the <filename role="package">devel/ddd</filename> port in order to use the + the <package>devel/ddd</package> port in order to use the <command>ddd</command> debugger). Add the <option>-k</option> option to the <command>ddd</command> command line you would use normally. For example;</para> @@ -448,7 +437,7 @@ <command>ddd</command>'s graphical interface.</para> </sect1> - <sect1 id="kerneldebug-online-ddb"> + <sect1 xml:id="kerneldebug-online-ddb"> <title>On-Line Kernel Debugging Using DDB</title> <para>While <command>kgdb</command> as an off-line debugger provides a very @@ -468,8 +457,7 @@ <programlisting>options KDB</programlisting> <programlisting>options DDB</programlisting> - to your config file, and rebuild. (See <ulink - url="&url.books.handbook;/index.html">The FreeBSD Handbook</ulink> for details on + to your config file, and rebuild. (See <link xlink:href="&url.books.handbook;/index.html">The FreeBSD Handbook</link> for details on configuring the FreeBSD kernel).</para> <note> @@ -671,7 +659,7 @@ single-stepping the kernel.</para> </sect1> - <sect1 id="kerneldebug-online-gdb"> + <sect1 xml:id="kerneldebug-online-gdb"> <title>On-Line Kernel Debugging Using Remote GDB</title> <para>This feature has been supported since FreeBSD 2.2, and it is @@ -741,7 +729,7 @@ Debugger (msg=0xf01b0383 "Boot flags requested debugger") window), etc.</para> </sect1> - <sect1 id="kerneldebug-console"> + <sect1 xml:id="kerneldebug-console"> <title>Debugging a Console Driver</title> <para>Since you need a console driver to run DDB on, things are more @@ -753,7 +741,7 @@ Debugger (msg=0xf01b0383 "Boot flags requested debugger") console.</para> </sect1> - <sect1 id="kerneldebug-deadlocks"> + <sect1 xml:id="kerneldebug-deadlocks"> <title>Debugging Deadlocks</title> <para>You may experience so called deadlocks, the situation where @@ -786,7 +774,7 @@ Debugger (msg=0xf01b0383 "Boot flags requested debugger") stack, and do a backtrace with <command>where</command>.</para> </sect1> - <sect1 id="kerneldebug-dcons"> + <sect1 xml:id="kerneldebug-dcons"> <title>Kernel debugging with Dcons</title> <para>&man.dcons.4; is a very simple console driver that is @@ -912,7 +900,7 @@ hw.firewire.dcons_crom.force_console=1</screen> <para>Run &man.dconschat.8;, with:</para> - <screen>&prompt.root; <userinput>dconschat -e \# -br -G 12345 -t <replaceable>00-11-22-33-44-55-66-77</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dconschat -e \# -br -G 12345 -t 00-11-22-33-44-55-66-77</userinput></screen> <para>The following key combinations can be used once &man.dconschat.8; is running:</para> @@ -1034,7 +1022,7 @@ LANG=C ddd --debugger kgdb kernel /dev/fwmem0.2</screen> </sect2> </sect1> - <sect1 id="kerneldebug-options"> + <sect1 xml:id="kerneldebug-options"> <title>Glossary of Kernel Options for Debugging</title> <para>This section provides a brief glossary of compile-time kernel diff --git a/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml index 1dbc259899..7a30e9b404 100644 --- a/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/l10n/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - - <chapter id="l10n"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="l10n"> <title>Localization and Internationalization - L10N and I18N</title> - <sect1 id="l10n-programming"> + <sect1 xml:id="l10n-programming"> <title>Programming I18N Compliant Applications</title> <indexterm><primary>Qt</primary></indexterm> <indexterm><primary>GTK</primary></indexterm> @@ -60,18 +59,14 @@ </sect2> </sect1> - <sect1 id="posix-nls"> - <sect1info> + <sect1 xml:id="posix-nls"> + <info><title>Localized Messages with POSIX.1 Native Language Support (NLS)</title> <authorgroup> - <author> - <firstname>Gábor</firstname> - <surname>Kövesdán</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Gábor</firstname><surname>Kövesdán</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Localized Messages with POSIX.1 Native Language Support (NLS)</title> + <para>Beyond the basic I18N functions, like supporting various input encodings or supporting national conventions, such as the different @@ -80,7 +75,7 @@ this is using the POSIX.1 NLS functions, which are provided as a part of the &os; base system.</para> - <sect2 id="nls-catalogs"> + <sect2 xml:id="nls-catalogs"> <title>Organizing Localized Messages into Catalog Files</title> <para>POSIX.1 NLS is based on catalog files, which contain the @@ -116,22 +111,19 @@ &man.gencat.1;.</para> </sect2> - <sect2 id="nls-using"> + <sect2 xml:id="nls-using"> <title>Using the Catalog Files from the Source Code</title> <para>Using the catalog files is simple. To use - the related functions, <filename - class="headerfile">nl_types.h</filename> must be included. Before + the related functions, <filename>nl_types.h</filename> must be included. Before using a catalog, it has to be opened with &man.catopen.3;. The function takes two arguments. The first parameter is the name of the installed and compiled catalog. Usually, the name of the program is used, such as <application>grep</application>. This name will be used when looking for the compiled catalog file. The &man.catopen.3; call looks for this file - in <filename - class="directory">/usr/share/nls/<replaceable>locale</replaceable>/<replaceable>catname</replaceable></filename> - and in <filename - class="directory">/usr/local/share/nls/<replaceable>locale</replaceable>/<replaceable>catname</replaceable></filename>, + in <filename>/usr/share/nls/locale/catname</filename> + and in <filename>/usr/local/share/nls/locale/catname</filename>, where <literal>locale</literal> is the locale set and <literal>catname</literal> is the catalog name being discussed. The second parameter is a constant, which can have @@ -165,7 +157,7 @@ &man.catclose.3;, which has one argument, the catalog id.</para> </sect2> - <sect2 id="nls-example"> + <sect2 xml:id="nls-example"> <title>A Practical Example</title> <para>The following example will demonstrate an easy solution on how to @@ -262,8 +254,7 @@ if (!S_ISDIR(st.st_mode)) { and users will see the usual <quote>Not a directory</quote> error message when they encounter this error. This message will probably seem more familiar to them. Please note that - it was necessary to include <filename - class="headerfile">errno.h</filename> in order to directly + it was necessary to include <filename>errno.h</filename> in order to directly access <varname>errno</varname>.</para> <para>It is worth to note that there are cases when @@ -279,7 +270,7 @@ if ((p = malloc(size)) == NULL) </sect3> </sect2> - <sect2 id="nls-mk"> + <sect2 xml:id="nls-mk"> <title>Making use of <filename>bsd.nls.mk</filename></title> <para>Using the catalog files requires few repeatable steps, @@ -291,13 +282,13 @@ if ((p = malloc(size)) == NULL) such as <filename>bsd.prog.mk</filename> or <filename>bsd.lib.mk</filename>.</para> - <para>Usually it is enough to define <makevar>NLSNAME</makevar>, + <para>Usually it is enough to define <varname>NLSNAME</varname>, which should have the catalog name mentioned as the first argument of &man.catopen.3; and list the catalog files in - <makevar>NLS</makevar> without their <literal>.msg</literal> + <varname>NLS</varname> without their <literal>.msg</literal> extension. Here is an example, which makes it possible to to disable NLS when used with the code examples before. - The <makevar>WITHOUT_NLS</makevar> &man.make.1; variable has + The <varname>WITHOUT_NLS</varname> &man.make.1; variable has to be defined in order to build the program without NLS support.</para> @@ -311,13 +302,13 @@ CFLAGS+= -DWITHOUT_NLS .endif</programlisting> <para>Conventionally, the catalog files are placed under the - <filename class="directory">nls</filename> subdirectory and + <filename>nls</filename> subdirectory and this is the default behaviour of <filename>bsd.nls.mk</filename>. It is possible, though to override the location of the - catalogs with the <makevar>NLSSRCDIR</makevar> &man.make.1; + catalogs with the <varname>NLSSRCDIR</varname> &man.make.1; variable. The default name of the precompiled catalog files also follow the naming convention mentioned before. It can be - overridden by setting the <makevar>NLSNAME</makevar> variable. + overridden by setting the <varname>NLSNAME</varname> variable. There are other options to fine tune the processing of the catalog files but usually it is not needed, thus they are not described here. For further information on <filename>bsd.nls.mk</filename>, diff --git a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml index 7da8cc7186..fc94e3ae5b 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml @@ -4,29 +4,21 @@ $FreeBSD$ --> - -<chapter id="policies"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="policies"> + <info><title>Source Tree Guidelines and Policies</title> <authorgroup> - <author> - <firstname>Poul-Henning</firstname> - <surname>Kamp</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>Giorgos</firstname> - <surname>Keramidas</surname> - </author> + <author><personname><firstname>Poul-Henning</firstname><surname>Kamp</surname></personname><contrib>Contributed by </contrib></author> + <author><personname><firstname>Giorgos</firstname><surname>Keramidas</surname></personname></author> </authorgroup> - <!-- June 1996 --> - </chapterinfo> + + </info> - <title>Source Tree Guidelines and Policies</title> + <para>This chapter documents various guidelines and policies in force for the FreeBSD source tree.</para> - <sect1 id="policies-style"> + <sect1 xml:id="policies-style"> <title>Style Guidelines</title> <indexterm><primary>style</primary></indexterm> @@ -37,8 +29,8 @@ &man.style.Makefile.5;.</para> </sect1> - <sect1 id="policies-maintainer"> - <title><makevar>MAINTAINER</makevar> on Makefiles</title> + <sect1 xml:id="policies-maintainer"> + <title><varname>MAINTAINER</varname> on Makefiles</title> <indexterm><primary>ports maintainer</primary></indexterm> @@ -48,10 +40,10 @@ entry in the <filename>src/MAINTAINERS</filename> file. Maintainers of ports within the Ports Collection express their maintainership to the world by adding a - <makevar>MAINTAINER</makevar> line to the + <varname>MAINTAINER</varname> line to the <filename>Makefile</filename> of the port in question:</para> - <programlisting><makevar>MAINTAINER</makevar>= <replaceable>email-addresses</replaceable></programlisting> + <programlisting><varname>MAINTAINER</varname>= <replaceable>email-addresses</replaceable></programlisting> <tip> <para>For other parts of the repository, or for sections not @@ -97,27 +89,17 @@ </itemizedlist> </sect1> - <sect1 id="policies-contributed"> - <sect1info> + <sect1 xml:id="policies-contributed"> + <info><title>Contributed Software</title> <authorgroup> - <author> - <firstname>Poul-Henning</firstname> - <surname>Kamp</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>David</firstname> - <surname>O'Brien</surname> - </author> - <author> - <firstname>Gavin</firstname> - <surname>Atkinson</surname> - </author> + <author><personname><firstname>Poul-Henning</firstname><surname>Kamp</surname></personname><contrib>Contributed by </contrib></author> + <author><personname><firstname>David</firstname><surname>O'Brien</surname></personname></author> + <author><personname><firstname>Gavin</firstname><surname>Atkinson</surname></personname></author> </authorgroup> - <!-- June 1996 --> - </sect1info> + + </info> - <title>Contributed Software</title> + <indexterm><primary>contributed software</primary></indexterm> @@ -161,17 +143,13 @@ still tracking the vendor branch.</para> </note> - <sect2 id="vendor-import-svn"> - <sect2info> + <sect2 xml:id="vendor-import-svn"> + <info><title>Vendor Imports with SVN</title> <authorgroup> - <author> - <firstname>Dag-Erling</firstname> - <surname>Smørgrav</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Dag-Erling</firstname><surname>Smørgrav</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> - <title>Vendor Imports with SVN</title> + </info> + <para>This section describes the vendor import procedure with <application>Subversion</application> in details.</para> @@ -189,18 +167,18 @@ <acronym>SVN</acronym>, vendor branches were imported with the same layout as the main tree. For example, the <application>foo</application> vendor sources ended up in - <filename>vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename>, + <filename>vendor/foo/dist/contrib/foo</filename>, but it is pointless and rather inconvenient. What we really want is to have the vendor source directly in - <filename>vendor/<replaceable>foo</replaceable>/dist</filename>, + <filename>vendor/foo/dist</filename>, like this:</para> - <screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">vendor/<replaceable>foo</replaceable>/dist/contrib/<replaceable>foo</replaceable></filename></userinput> -&prompt.user; <userinput><command>svn move</command> $(svn list) <filename>../..</filename></userinput> -&prompt.user; <userinput><command>cd</command> <filename>../..</filename></userinput> -&prompt.user; <userinput><command>svn remove</command> <filename>contrib</filename></userinput> -&prompt.user; <userinput><command>svn propdel</command> <option>-R</option> svn:mergeinfo</userinput> -&prompt.user; <userinput><command>svn commit</command></userinput></screen> + <screen>&prompt.user; <userinput>cd vendor/foo/dist/contrib/foo</userinput> +&prompt.user; <userinput>svn move $(svn list) ../..</userinput> +&prompt.user; <userinput>cd ../..</userinput> +&prompt.user; <userinput>svn remove contrib</userinput> +&prompt.user; <userinput>svn propdel -R svn:mergeinfo</userinput> +&prompt.user; <userinput>svn commit</userinput></screen> <para>Note that, the <literal>propdel</literal> bit is necessary because starting with 1.5, Subversion will @@ -221,17 +199,17 @@ unmodified vendor code. In some cases, it can be even be harmful.</para> - <screen>&prompt.user; <userinput><command>svn propdel</command> svn:keywords <option>-R</option> <filename>.</filename></userinput> -&prompt.user; <userinput><command>svn commit</command></userinput></screen> + <screen>&prompt.user; <userinput>svn propdel svn:keywords -R .</userinput> +&prompt.user; <userinput>svn commit</userinput></screen> <para>Bootstrapping of <literal>svn:mergeinfo</literal> on the target directory (in the main tree) to the revision that corresponds to the last change was made to the vendor tree prior to importing new sources is also needed:</para> - <screen>&prompt.user; <userinput><command>cd</command> <filename>head/contrib/<replaceable>foo</replaceable></filename></userinput> -&prompt.user; <userinput><command>svn merge</command> <option>--record-only</option> <replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist@<replaceable>12345678</replaceable> <filename>.</filename></userinput> -&prompt.user; <userinput><command>svn commit</command></userinput></screen> + <screen>&prompt.user; <userinput>cd head/contrib/foo</userinput> +&prompt.user; <userinput>svn merge --record-only svn_base/vendor/foo/dist@12345678 .</userinput> +&prompt.user; <userinput>svn commit</userinput></screen> <para>where <replaceable>svn_base</replaceable> is the base directory of your <acronym>SVN</acronym> repository, e.g. @@ -253,30 +231,30 @@ sorted lists of the contents of the vendor tree and of the sources you are about to import:</para> - <screen>&prompt.user; <userinput><command>cd</command> <filename>vendor/<replaceable>foo</replaceable>/dist</filename></userinput> -&prompt.user; <userinput><command>svn list</command> <option>-R</option> | <command>grep</command> <option>-v</option> '/$' | <command>sort</command> > <filename>../<replaceable>old</replaceable></filename></userinput> -&prompt.user; <userinput><command>cd</command> <filename>../<replaceable>foo-9.9</replaceable></filename></userinput> -&prompt.user; <userinput><command>find</command> <filename>.</filename> <option>-type</option> f | <command>cut</command> <option>-c</option> 3- | <command>sort</command> > <filename>../<replaceable>new</replaceable></filename></userinput></screen> + <screen>&prompt.user; <userinput>cd vendor/foo/dist</userinput> +&prompt.user; <userinput>svn list -R | grep -v '/$' | sort > ../old</userinput> +&prompt.user; <userinput>cd ../foo-9.9</userinput> +&prompt.user; <userinput>find . -type f | cut -c 3- | sort > ../new</userinput></screen> <para>With these two files, the following command will list list removed files (files only in - <filename><replaceable>old</replaceable></filename>):</para> + <filename>old</filename>):</para> - <screen>&prompt.user; <userinput><command>comm <option>-23</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>comm -23 ../old ../new</userinput></screen> <para>While the command below will list added files (files only in - <filename><replaceable>new</replaceable></filename>):</para> + <filename>new</filename>):</para> - <screen>&prompt.user; <userinput><command>comm <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>comm -13 ../old ../new</userinput></screen> <para>Let's put this together:</para> - <screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">vendor/<replaceable>foo</replaceable>/<replaceable>foo-9.9</replaceable></filename></userinput> -&prompt.user; <userinput><command>tar</command> cf - <filename>.</filename> | <command>tar</command> xf - <option>-C</option> <filename>../dist</filename></userinput> -&prompt.user; <userinput><command>cd</command> <filename class="directory">../dist</filename></userinput> -&prompt.user; <userinput><command>comm</command> <option>-23</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn remove</userinput> -&prompt.user; <userinput><command>comm</command> <option>-13</option> <filename>../<replaceable>old</replaceable></filename> <filename>../<replaceable>new</replaceable></filename> | <command>xargs</command> svn add</userinput></screen> + <screen>&prompt.user; <userinput>cd vendor/foo/foo-9.9</userinput> +&prompt.user; <userinput>tar cf - . | tar xf - -C ../dist</userinput> +&prompt.user; <userinput>cd ../dist</userinput> +&prompt.user; <userinput>comm -23 ../old ../new | xargs svn remove</userinput> +&prompt.user; <userinput>comm -13 ../old ../new | xargs svn add</userinput></screen> <warning> <para>If there are new directories in the new @@ -325,11 +303,11 @@ should tag it for future reference. The best and quickest way is to do it directly in the repository:</para> - <screen>&prompt.user; <userinput><command>svn copy</command> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/<replaceable>9.9</replaceable></filename></userinput></screen> + <screen>&prompt.user; <userinput>svn copy svn_base/vendor/foo/dist svn_base/vendor/foo/9.9</userinput></screen> <para>To get the new tag, you can update your working copy of - <filename>vendor/<replaceable>foo</replaceable></filename>.</para> + <filename>vendor/foo</filename>.</para> <note> <para>If you choose to do the copy in the checkout @@ -347,9 +325,9 @@ <acronym>SVN</acronym> not to handle merge conflicts yet, because they will be taken care of manually:</para> - <screen>&prompt.user; <userinput><command>cd</command> <filename class="directory">head/contrib/<replaceable>foo</replaceable></filename></userinput> -&prompt.user; <userinput><command>svn update</command></userinput> -&prompt.user; <userinput><command>svn merge</command> <option>--accept=postpone</option> <filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename></userinput></screen> + <screen>&prompt.user; <userinput>cd head/contrib/foo</userinput> +&prompt.user; <userinput>svn update</userinput> +&prompt.user; <userinput>svn merge --accept=postpone svn_base/vendor/foo/dist</userinput></screen> <para>Resolve any conflicts, and make sure that any files that were added or removed in the vendor tree have been @@ -357,7 +335,7 @@ a good idea to check differences against the vendor branch:</para> - <screen>&prompt.user; <userinput><command>svn diff</command> <option>--no-diff-deleted</option> <option>--old=</option><filename><replaceable>svn_base</replaceable>/vendor/<replaceable>foo</replaceable>/dist</filename> <option>--new=</option><filename>.</filename></userinput></screen> + <screen>&prompt.user; <userinput>svn diff --no-diff-deleted --old=svn_base/vendor/foo/dist --new=.</userinput></screen> <para>The <option>--no-diff-deleted</option> option tells <acronym>SVN</acronym> not to check files that are in the @@ -392,7 +370,7 @@ </sect2> </sect1> - <sect1 id="policies-encumbered"> + <sect1 xml:id="policies-encumbered"> <title>Encumbered Files</title> <para>It might occasionally be necessary to include an encumbered @@ -423,8 +401,8 @@ <listitem> <para>Any encumbered file requires specific approval from the - <ulink url="&url.base;/administration.html#t-core">Core - Team</ulink> before it is added to the repository.</para> + <link xlink:href="&url.base;/administration.html#t-core">Core + Team</link> before it is added to the repository.</para> </listitem> <listitem> @@ -440,7 +418,7 @@ <listitem> <para>Object files are named - <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> + <filename>arch/filename.o.uu></filename>.</para> </listitem> <listitem> @@ -455,12 +433,10 @@ <listitem> <para>Should always be in <filename>LINT</filename>, but - the <ulink - url="&url.base;/administration.html#t-core">Core - Team</ulink> decides per case if it should be - commented out or not. The <ulink - url="&url.base;/administration.html#t-core">Core - Team</ulink> can, of course, change their minds later + the <link xlink:href="&url.base;/administration.html#t-core">Core + Team</link> decides per case if it should be + commented out or not. The <link xlink:href="&url.base;/administration.html#t-core">Core + Team</link> can, of course, change their minds later on.</para> </listitem> @@ -476,18 +452,16 @@ <orderedlist> <listitem> - <para>The <ulink - url="&url.base;/administration.html#t-core">Core - team</ulink><indexterm><primary>core + <para>The <link xlink:href="&url.base;/administration.html#t-core">Core + team</link><indexterm><primary>core team</primary></indexterm> decides if the code should be part of <command>make world</command>.</para> </listitem> <listitem> - <para>The <ulink - url="&url.base;/administration.html#t-re">Release - Engineering</ulink><indexterm><primary>release + <para>The <link xlink:href="&url.base;/administration.html#t-re">Release + Engineering</link><indexterm><primary>release engineering</primary></indexterm> decides if it goes into the release.</para> </listitem> @@ -496,27 +470,17 @@ </orderedlist> </sect1> - <sect1 id="policies-shlib"> - <sect1info> + <sect1 xml:id="policies-shlib"> + <info><title>Shared Libraries</title> <authorgroup> - <author> - <firstname>Satoshi</firstname> - <surname>Asami</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>Peter</firstname> - <surname>Wemm</surname> - </author> - <author> - <firstname>David</firstname> - <surname>O'Brien</surname> - </author> + <author><personname><firstname>Satoshi</firstname><surname>Asami</surname></personname><contrib>Contributed by </contrib></author> + <author><personname><firstname>Peter</firstname><surname>Wemm</surname></personname></author> + <author><personname><firstname>David</firstname><surname>O'Brien</surname></personname></author> </authorgroup> - <!-- 9 Dec 1996 --> - </sect1info> + + </info> - <title>Shared Libraries</title> + <para>If you are adding shared library support to a port or other piece of software that does not have one, the version numbers diff --git a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.xml index 4a655c189c..eb5d53b7a2 100644 --- a/en_US.ISO8859-1/books/developers-handbook/secure/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/secure/chapter.xml @@ -4,21 +4,16 @@ $FreeBSD$ --> - - <chapter id="secure"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="secure"> + <info><title>Secure Programming</title> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Secure Programming</title> + - <sect1 id="secure-synopsis"><title>Synopsis</title> + <sect1 xml:id="secure-synopsis"><title>Synopsis</title> <para>This chapter describes some of the security issues that have plagued &unix; programmers for decades and some of the new @@ -26,7 +21,7 @@ code.</para> </sect1> - <sect1 id="secure-philosophy"><title>Secure Design + <sect1 xml:id="secure-philosophy"><title>Secure Design Methodology</title> <para>Writing secure applications takes a very scrutinous and @@ -45,7 +40,7 @@ operations are rarely atomic.</para> </sect1> - <sect1 id="secure-bufferov"><title>Buffer Overflows</title> + <sect1 xml:id="secure-bufferov"><title>Buffer Overflows</title> <para>Buffer Overflows have been around since the very beginnings of the Von-Neuman <xref linkend="COD"/> architecture. @@ -230,8 +225,7 @@ int main() { <function>strlcpy</function> and <function>strlcat</function> functions guarantee that they will always null terminate the destination string when given a non-zero length argument. For - more information about these functions see <xref - linkend="OpenBSD"/>. The OpenBSD <function>strlcpy</function> and + more information about these functions see <xref linkend="OpenBSD"/>. The OpenBSD <function>strlcpy</function> and <function>strlcat</function> instructions have been in FreeBSD since 3.3.</para> @@ -317,7 +311,7 @@ int main() { </sect2> </sect1> - <sect1 id="secure-setuid"><title>SetUID issues</title> + <sect1 xml:id="secure-setuid"><title>SetUID issues</title> <indexterm><primary>seteuid</primary></indexterm> @@ -350,7 +344,7 @@ int main() { </sect1> - <sect1 id="secure-chroot"><title>Limiting your program's environment</title> + <sect1 xml:id="secure-chroot"><title>Limiting your program's environment</title> <indexterm><primary>chroot()</primary></indexterm> @@ -438,8 +432,7 @@ int main() { <para>&posix; has released a working draft that adds event auditing, access control lists, fine grained privileges, information labeling, and mandatory access control.</para> - <para>This is a work in progress and is the focus of the <ulink - url="http://www.trustedbsd.org/">TrustedBSD</ulink> project. Some + <para>This is a work in progress and is the focus of the <link xlink:href="http://www.trustedbsd.org/">TrustedBSD</link> project. Some of the initial work has been committed to &os.current; (cap_set_proc(3)).</para> @@ -447,7 +440,7 @@ int main() { </sect1> - <sect1 id="secure-trust"><title>Trust</title> + <sect1 xml:id="secure-trust"><title>Trust</title> <para>An application should never assume that anything about the users environment is sane. This includes (but is certainly not @@ -479,7 +472,7 @@ int main() { </sect1> - <sect1 id="secure-race-conditions"> + <sect1 xml:id="secure-race-conditions"> <title>Race Conditions</title> <para>A race condition is anomalous behavior caused by the diff --git a/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml index 7cb263be69..c6c76fcf24 100644 --- a/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/sockets/chapter.xml @@ -4,21 +4,16 @@ $FreeBSD$ --> - -<chapter id="sockets"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="sockets"> + <info><title>Sockets</title> <authorgroup> - <author> - <firstname>G. Adam</firstname> - <surname>Stanislav</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>G. Adam</firstname><surname>Stanislav</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Sockets</title> + - <sect1 id="sockets-synopsis"> + <sect1 xml:id="sockets-synopsis"> <title>Synopsis</title> <para><acronym>BSD</acronym> sockets take interprocess @@ -45,7 +40,7 @@ </sect1> - <sect1 id="sockets-diversity"> + <sect1 xml:id="sockets-diversity"> <title>Networking and Diversity</title> <para>We have already hinted on the <emphasis>diversity</emphasis> @@ -85,7 +80,7 @@ </para> </sect1> - <sect1 id="sockets-protocols"> + <sect1 xml:id="sockets-protocols"> <title>Protocols</title> <para>While various programming languages tend to have complex @@ -324,7 +319,7 @@ </sect1> - <sect1 id="sockets-model"> + <sect1 xml:id="sockets-model"> <title>The Sockets Model</title> <para><acronym>BSD</acronym> sockets are built on the basic &unix; @@ -349,7 +344,7 @@ </sect1> - <sect1 id="sockets-essential-functions"> + <sect1 xml:id="sockets-essential-functions"> <title>Essential Socket Functions</title> <para>While FreeBSD offers different functions to work with @@ -357,17 +352,17 @@ <quote>open</quote> a socket. And in some cases we only need two.</para> - <sect2 id="sockets-client-server"> + <sect2 xml:id="sockets-client-server"> <title>The Client-Server Difference</title> <para>Typically, one of the ends of a socket-based data communication is a <emphasis>server</emphasis>, the other is a <emphasis>client</emphasis>.</para> - <sect3 id="sockets-common-elements"> + <sect3 xml:id="sockets-common-elements"> <title>The Common Elements</title> - <sect4 id="sockets-socket"> + <sect4 xml:id="sockets-socket"> <title><function>socket</function></title> <para>The one function used by both, clients and servers, is @@ -418,7 +413,7 @@ int socket(int domain, int type, int protocol); meaningful. In that case, use <constant>0</constant> for its value.</para> - <note id="sockets-unconnected"> + <note xml:id="sockets-unconnected"> <title>The Unconnected Socket</title> <para>Nowhere, in the <function>socket</function> function @@ -434,7 +429,7 @@ int socket(int domain, int type, int protocol); </sect4> - <sect4 id="sockets-sockaddr"> + <sect4 xml:id="sockets-sockaddr"> <title><varname>sockaddr</varname></title> <para>Various functions of the sockets family expect the @@ -598,10 +593,8 @@ struct sockaddr_in { <constant>AF_INET</constant> in the address family field. <constant>AF_INET</constant> is defined as <constant>2</constant>. Let us use the - <acronym>IP</acronym> address of <hostid - role="ipaddr">192.43.244.18</hostid>, which is the time - server of US federal government (<hostid - role="domainname">time.nist.gov</hostid>).</para> + <acronym>IP</acronym> address of <systemitem class="ipaddress">192.43.244.18</systemitem>, which is the time + server of US federal government (<systemitem class="fqdomainname">time.nist.gov</systemitem>).</para> <mediaobject> <imageobject> @@ -643,7 +636,7 @@ struct in_addr { <para>In addition, <varname>in_addr_t</varname> is a 32-bit integer.</para> - <para>The <hostid role="ipaddr">192.43.244.18</hostid> is + <para>The <systemitem class="ipaddress">192.43.244.18</systemitem> is just a convenient notation of expressing a 32-bit integer by listing all of its 8-bit bytes, starting with the <emphasis>most significant</emphasis> one.</para> @@ -905,7 +898,7 @@ struct in_addr { </sect3> - <sect3 id="sockets-client-functions"> + <sect3 xml:id="sockets-client-functions"> <title>Client Functions</title> <para>Typically, the client initiates the connection to the @@ -917,7 +910,7 @@ struct in_addr { asking for the person in charge of wingdings (the <emphasis>port</emphasis>).</para> - <sect4 id="sockets-connect"> + <sect4 xml:id="sockets-connect"> <title><function>connect</function></title> <para>Once a client has created a socket, it needs to @@ -952,13 +945,12 @@ int connect(int s, const struct sockaddr *name, socklen_t namelen); </sect4> - <sect4 id="sockets-first-client"> + <sect4 xml:id="sockets-first-client"> <title>Our First Client</title> <para>We now know enough to write a very simple client, one - that will get current time from <hostid - role="ipaddr">192.43.244.18</hostid> and print it to - <devicename>stdout</devicename>.</para> + that will get current time from <systemitem class="ipaddress">192.43.244.18</systemitem> and print it to + <filename>stdout</filename>.</para> <programlisting> /* @@ -1020,7 +1012,7 @@ int main() { </sect3> - <sect3 id="sockets-server-functions"> + <sect3 xml:id="sockets-server-functions"> <title>Server Functions</title> <para>The typical server does not initiate the @@ -1034,7 +1026,7 @@ int main() { <para>The sockets interface offers three basic functions to handle this.</para> - <sect4 id="sockets-bind"> + <sect4 xml:id="sockets-bind"> <title><function>bind</function></title> <para>Ports are like extensions to a phone line: After you @@ -1095,7 +1087,7 @@ int bind(int s, const struct sockaddr *addr, socklen_t addrlen); </mediaobject> </sect4> - <sect4 id="sockets-listen"> + <sect4 xml:id="sockets-listen"> <title><function>listen</function></title> <para>To continue our office phone analogy, after you have @@ -1120,7 +1112,7 @@ int listen(int s, int backlog); </sect4> - <sect4 id="sockets-accept"> + <sect4 xml:id="sockets-accept"> <title><function>accept</function></title> <para>After you hear the phone ringing, you accept the call @@ -1157,7 +1149,7 @@ int accept(int s, struct sockaddr *addr, socklen_t *addrlen); </sect4> - <sect4 id="sockets-first-server"> + <sect4 xml:id="sockets-first-server"> <title>Our First Server</title> <para>Our first server will be somewhat more complex than @@ -1514,19 +1506,19 @@ Connection closed by foreign host. </sect1> - <sect1 id="sockets-helper-functions"> + <sect1 xml:id="sockets-helper-functions"> <title>Helper Functions</title> <para>FreeBSD C library contains many helper functions for sockets programming. For example, in our sample client we hard coded - the <hostid role="domainname">time.nist.gov</hostid> + the <systemitem class="fqdomainname">time.nist.gov</systemitem> <acronym>IP</acronym> address. But we do not always know the <acronym>IP</acronym> address. Even if we do, our software is more flexible if it allows the user to enter the <acronym>IP</acronym> address, or even the domain name. </para> - <sect2 id="sockets-gethostbyname"> + <sect2 xml:id="sockets-gethostbyname"> <title><function>gethostbyname</function></title> <para>While there is no way to pass the domain name directly to @@ -1608,18 +1600,15 @@ int main(int argc, char *argv[]) { address, it works both ways) on the command line, and the program will try to connect to its <emphasis>daytime</emphasis> server. Otherwise, it will still - default to <hostid - role="domainname">time.nist.gov</hostid>. However, even in + default to <systemitem class="fqdomainname">time.nist.gov</systemitem>. However, even in this case we will use <function>gethostbyname</function> - rather than hard coding <hostid - role="ipaddr">192.43.244.18</hostid>. That way, even if its + rather than hard coding <systemitem class="ipaddress">192.43.244.18</systemitem>. That way, even if its <acronym>IP</acronym> address changes in the future, we will still find it.</para> <para>Since it takes virtually no time to get the time from your local server, you could run <application>daytime</application> - twice in a row: First to get the time from <hostid - role="domainname">time.nist.gov</hostid>, the second time from + twice in a row: First to get the time from <systemitem class="fqdomainname">time.nist.gov</systemitem>, the second time from your own system. You can then compare the results and see how exact your system clock is:</para> @@ -1635,7 +1624,7 @@ int main(int argc, char *argv[]) { </sect2> - <sect2 id="sockets-getservbyname"> + <sect2 xml:id="sockets-getservbyname"> <title><function>getservbyname</function></title> <para>Sometimes you may not be sure what port a certain service @@ -1680,7 +1669,7 @@ struct servent * getservbyname(const char *name, const char *proto); </sect1> - <sect1 id="sockets-concurrent-servers"> + <sect1 xml:id="sockets-concurrent-servers"> <title>Concurrent Servers</title> <para>Unlike a sequential server, a <emphasis>concurrent diff --git a/en_US.ISO8859-1/books/developers-handbook/testing/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/testing/chapter.xml index 1f0150ea6f..99c2148356 100644 --- a/en_US.ISO8859-1/books/developers-handbook/testing/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/testing/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="testing"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="testing"> <title>Regression and Performance Testing</title> <para>Regression tests are used to exercise a particular bit of the @@ -13,10 +12,9 @@ old bugs are not reintroduced.</para> <para>The &os; regression testing tools can be found in the &os; - source tree in the directory <filename - class="directory">src/tools/regression</filename>.</para> + source tree in the directory <filename>src/tools/regression</filename>.</para> - <section id="testing-micro-benchmark"> + <section xml:id="testing-micro-benchmark"> <title>Micro Benchmark Checklist</title> <para>This section contains hints for doing proper @@ -61,8 +59,8 @@ </listitem> <listitem> - <para>Mount <filename class="directory">/</filename>, - <filename class="directory">/usr</filename>, and any other + <para>Mount <filename>/</filename>, + <filename>/usr</filename>, and any other file system as read-only if possible. This removes atime updates to disk (etc.) from the I/O picture.</para> </listitem> @@ -73,12 +71,11 @@ &man.dump.8; file before every run. Unmount and mount it before starting the test. This results in a consistent file system layout. For a worldstone test this would apply to - <filename class="directory">/usr/obj</filename> (just + <filename>/usr/obj</filename> (just reinitialize with <command>newfs</command> and mount). To get 100% reproducibility, populate the file system from a &man.dd.1; file (i.e.: <command>dd - if=<filename>myimage</filename> of=<filename - class="devicefile">/dev/ad0s1h</filename> + if=myimage of=/dev/ad0s1h bs=1m</command>)</para> </listitem> @@ -215,7 +212,7 @@ </itemizedlist> </section> - <section id="testing-tinderbox"> + <section xml:id="testing-tinderbox"> <title>The &os; Source Tinderbox</title> <para>The source Tinderbox consists of:</para> @@ -250,8 +247,7 @@ <para>The scripts are maintained and were developed by &a.des.email;, and are now written in Perl, a move on from their original incarnation as shell scripts. All scripts and configuration - files are kept in <ulink - url="http://www.freebsd.org/cgi/cvsweb.cgi/projects/tinderbox/">/projects/tinderbox/</ulink>.</para> + files are kept in <link xlink:href="http://www.freebsd.org/cgi/cvsweb.cgi/projects/tinderbox/">/projects/tinderbox/</link>.</para> <para>For more information about the tinderbox and tbmaster scripts at this stage, see their respective man pages: @@ -367,11 +363,11 @@ have rank 9999.</para> </listitem> <listitem> - <para><literal>RELENG_<replaceable>x</replaceable></literal> + <para><literal>RELENG_x</literal> has rank <replaceable>xx</replaceable>99.</para> </listitem> <listitem> - <para><literal>RELENG_<replaceable>x</replaceable>_<replaceable>y</replaceable></literal> + <para><literal>RELENG_x_y</literal> has rank <replaceable>xxyy</replaceable>.</para> </listitem> </itemizedlist> @@ -416,11 +412,9 @@ <section> <title>Official Build Servers</title> - <para>The official Tinderbox build servers are hosted by <ulink - url="http://www.sentex.ca">Sentex Data - Communications</ulink>, who also host the <ulink - url="http://www.freebsd.org/projects/netperf/cluster.html">&os; - Netperf Cluster</ulink>.</para> + <para>The official Tinderbox build servers are hosted by <link xlink:href="http://www.sentex.ca">Sentex Data + Communications</link>, who also host the <link xlink:href="http://www.freebsd.org/projects/netperf/cluster.html">&os; + Netperf Cluster</link>.</para> <para>Three build servers currently exist:</para> @@ -468,8 +462,7 @@ <title>Official Summary Site</title> <para>Summaries and logs from the official build servers are - available online at <ulink - url="http://tinderbox.FreeBSD.org">http://tinderbox.FreeBSD.org</ulink>, + available online at <link xlink:href="http://tinderbox.FreeBSD.org">http://tinderbox.FreeBSD.org</link>, hosted by &a.des.email; and set up as follows:</para> <itemizedlist> diff --git a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml index 890979af7d..8f50cdf03f 100644 --- a/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/tools/chapter.xml @@ -4,24 +4,16 @@ $FreeBSD$ --> - -<chapter id="tools"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools"> + <info><title>Programming Tools</title> <authorgroup> - <author> - <firstname>James</firstname> - <surname>Raynard</surname> - <contrib>Contributed by </contrib> - </author> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - </author> + <author><personname><firstname>James</firstname><surname>Raynard</surname></personname><contrib>Contributed by </contrib></author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> </authorgroup> - </chapterinfo> + </info> - <title>Programming Tools</title> - <sect1 id="tools-synopsis"><title>Synopsis</title> + + <sect1 xml:id="tools-synopsis"><title>Synopsis</title> <para>This chapter is an introduction to using some of the programming tools supplied with FreeBSD, although much of it @@ -33,7 +25,7 @@ </sect1> - <sect1 id="tools-intro"><title>Introduction</title> + <sect1 xml:id="tools-intro"><title>Introduction</title> <para>FreeBSD offers an excellent development environment. Compilers for C and C++ and an assembler come with the @@ -62,7 +54,7 @@ </sect1> - <sect1 id="tools-programming"> + <sect1 xml:id="tools-programming"> <title>Introduction to Programming</title> <para>A program is a set of instructions that tell the computer to @@ -121,8 +113,8 @@ <para>Instructions on how to get and install applications from the Ports Collection can be found in the - <ulink url="&url.books.handbook;/ports-using.html"> - Ports section</ulink> of the handbook.</para> + <link xlink:href="&url.books.handbook;/ports-using.html"> + Ports section</link> of the handbook.</para> <variablelist> <varlistentry> @@ -139,10 +131,10 @@ <para>The Bywater Basic Interpreter can be found in the Ports Collection as - <filename role="package">lang/bwbasic</filename> + <package>lang/bwbasic</package> and the Phil Cockroft's Basic Interpreter (formerly Rabbit Basic) is available as - <filename role="package">lang/pbasic</filename>.</para> + <package>lang/pbasic</package>.</para> </listitem> </varlistentry> @@ -164,14 +156,14 @@ <para>Various implementations of Lisp that can run on &unix; systems are available in the Ports Collection for &os;. GNU Common Lisp can be found as - <filename role="package">lang/gcl</filename>. CLISP + <package>lang/gcl</package>. CLISP by Bruno Haible and Michael Stoll is available as - <filename role="package">lang/clisp</filename>. + <package>lang/clisp</package>. For CMUCL, which includes a highly-optimizing compiler too, or simpler Lisp implementations like SLisp, which implements most of the Common Lisp constructs in a few hundred lines of C code, - <filename role="package">lang/cmucl</filename> and - <filename role="package">lang/slisp</filename> are available + <package>lang/cmucl</package> and + <package>lang/slisp</package> are available respectively.</para> </listitem> </varlistentry> @@ -185,7 +177,7 @@ writing <acronym>CGI</acronym> scripts.</para> <para>Perl is available in the Ports Collection as - <filename role="package">lang/perl5.16</filename> for all + <package>lang/perl5.16</package> for all &os; releases.</para> </listitem> </varlistentry> @@ -201,12 +193,12 @@ abstraction to be used in research work.</para> <para>Scheme is available from the Ports Collection as - <filename role="package">lang/elk</filename> for the + <package>lang/elk</package> for the Elk Scheme Interpreter. The MIT Scheme Interpreter can be found in - <filename role="package">lang/mit-scheme</filename> + <package>lang/mit-scheme</package> and the SCM Scheme Interpreter in - <filename role="package">lang/scm</filename>.</para> + <package>lang/scm</package>.</para> </listitem> </varlistentry> @@ -218,7 +210,7 @@ facilities for processing strings and structures. The version of Icon for &os; can be found in the Ports Collection as - <filename role="package">lang/icon</filename>.</para> + <package>lang/icon</package>.</para> </listitem> </varlistentry> @@ -235,7 +227,7 @@ <para>The latest version of Logo for &os; is available from the Ports Collection in - <filename role="package">lang/logo</filename>.</para> + <package>lang/logo</package>.</para> </listitem> </varlistentry> @@ -253,7 +245,7 @@ <para>The latest version of Python is available from the Ports Collection in - <filename role="package">lang/python</filename>.</para> + <package>lang/python</package>.</para> </listitem> </varlistentry> @@ -268,7 +260,7 @@ programs.</para> <para>Ruby is available from the Ports Collection as - <filename role="package">lang/ruby18</filename>.</para> + <package>lang/ruby18</package>.</para> </listitem> </varlistentry> @@ -285,7 +277,7 @@ <para>Various versions of Tcl are available as ports for &os;. The latest version, Tcl 8.5, can be found in - <filename role="package">lang/tcl85</filename>.</para> + <package>lang/tcl85</package>.</para> </listitem> </varlistentry> </variablelist> @@ -324,7 +316,7 @@ using separate programs, many commercial compiler makers have produced Integrated Development Environments (<acronym>IDE</acronym>s for short). FreeBSD does not include - an IDE in the base system, but <filename role="package">devel/kdevelop</filename> is + an IDE in the base system, but <package>devel/kdevelop</package> is available in the Ports Collection and many use <application>Emacs</application> for this purpose. Using <application>Emacs</application> as an IDE is discussed in @@ -333,7 +325,7 @@ </sect1> - <sect1 id="tools-compiling"> + <sect1 xml:id="tools-compiling"> <title>Compiling with <command>cc</command></title> <para>This section deals with the <application>gcc</application> @@ -448,8 +440,8 @@ </footnote></para> <informalexample> - <screen>&prompt.user; <userinput>cc foobar.c</userinput> <lineannotation>executable is <filename>a.out</filename></lineannotation> -&prompt.user; <userinput>cc -o foobar foobar.c</userinput> <lineannotation>executable is <filename>foobar</filename></lineannotation> + <screen>&prompt.user; <userinput>cc foobar.c</userinput> <lineannotation>executable is a.out</lineannotation> +&prompt.user; <userinput>cc -o foobar foobar.c</userinput> <lineannotation>executable is foobar</lineannotation> </screen> </informalexample> </listitem> @@ -608,7 +600,7 @@ compiler to add it.</para> <para>The rule is that if the library is called - <filename>lib<replaceable>something</replaceable>.a</filename>, + <filename>libsomething.a</filename>, you give <command>cc</command> the argument <option>-l<replaceable>something</replaceable></option>. For example, the math library is @@ -1004,7 +996,7 @@ free(foo); <para>to find out the process ID of your program, and do</para> - <screen>&prompt.user; <userinput>kill -ABRT <replaceable>pid</replaceable></userinput> + <screen>&prompt.user; <userinput>kill -ABRT pid</userinput> </screen> <para>where @@ -1032,7 +1024,7 @@ free(foo); </sect2> </sect1> - <sect1 id="tools-make"> + <sect1 xml:id="tools-make"> <title>Make</title> <sect2> @@ -1155,22 +1147,22 @@ install: <para>We can tell make which target we want to make by typing:</para> - <screen>&prompt.user; <userinput>make <replaceable>target</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>make target</userinput></screen> <para><command>make</command> will then only look at that target and ignore any others. For example, if we type <userinput>make foo</userinput> with the makefile above, make - will ignore the <maketarget>install</maketarget> target.</para> + will ignore the <buildtarget>install</buildtarget> target.</para> <para>If we just type <userinput>make</userinput> on its own, make will always look at the first target and then stop without looking at any others. So if we typed <userinput>make</userinput> here, it will just go to the - <maketarget>foo</maketarget> target, re-compile + <buildtarget>foo</buildtarget> target, re-compile <filename>foo</filename> if necessary, and then stop without - going on to the <maketarget>install</maketarget> target.</para> + going on to the <buildtarget>install</buildtarget> target.</para> - <para>Notice that the <maketarget>install</maketarget> target does not + <para>Notice that the <buildtarget>install</buildtarget> target does not actually depend on anything! This means that the command on the following line is always executed when we try to make that target by typing <userinput>make install</userinput>. In this @@ -1374,7 +1366,7 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz </sect2> </sect1> - <sect1 id="debugging"> + <sect1 xml:id="debugging"> <title>Debugging</title> <sect2> @@ -1384,12 +1376,12 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz <command>gdb</command> (<application>GNU debugger</application>). You start it up by typing</para> - <screen>&prompt.user; <userinput>gdb <replaceable>progname</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>gdb progname</userinput></screen> <para>although many people prefer to run it inside <application>Emacs</application>. You can do this by:</para> - <screen><userinput>M-x gdb RET <replaceable>progname</replaceable> RET</userinput></screen> + <screen><userinput>M-x gdb RET progname RET</userinput></screen> <para>Using a debugger allows you to run the program under more controlled circumstances. Typically, you can step through the @@ -1407,7 +1399,7 @@ DISTFILES= scheme-microcode+dist-7.3-freebsd.tgz <para>Finally, if you find its text-based command-prompt style off-putting, there is a graphical front-end for it - (<filename role="package">devel/xxgdb</filename>) in the Ports + (<package>devel/xxgdb</package>) in the Ports Collection.</para> <para>This section is intended to be an introduction to using @@ -1491,15 +1483,15 @@ GDB is free software and you are welcome to distribute copies of it There is absolutely no warranty for GDB; type "show warranty" for details. GDB 4.13 (i386-unknown-freebsd), Copyright 1994 Free Software Foundation, Inc. (gdb) <userinput>break main</userinput> <lineannotation>Skip the set-up code</lineannotation> -Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation><command>gdb</command> puts breakpoint at <function>main()</function></lineannotation> -(gdb) <userinput>run</userinput> <lineannotation>Run as far as <function>main()</function></lineannotation> +Breakpoint 1 at 0x160f: file temp.c, line 9. <lineannotation>gdb puts breakpoint at main()</lineannotation> +(gdb) <userinput>run</userinput> <lineannotation>Run as far as main()</lineannotation> Starting program: /home/james/tmp/temp <lineannotation>Program starts running</lineannotation> -Breakpoint 1, main () at temp.c:9 <lineannotation><command>gdb</command> stops at <function>main()</function></lineannotation> +Breakpoint 1, main () at temp.c:9 <lineannotation>gdb stops at main()</lineannotation> (gdb) <userinput>n</userinput> <lineannotation>Go to next line</lineannotation> This is my program <lineannotation>Program prints out</lineannotation> -(gdb) <userinput>s</userinput> <lineannotation>step into <function>bazz()</function></lineannotation> -bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays stack frame</lineannotation> +(gdb) <userinput>s</userinput> <lineannotation>step into bazz()</lineannotation> +bazz (anint=4231) at temp.c:17 <lineannotation>gdb displays stack frame</lineannotation> (gdb)</screen> <para>Hang on a minute! How did <symbol>anint</symbol> get to be @@ -1508,9 +1500,9 @@ bazz (anint=4231) at temp.c:17 <lineannotation><command>gdb</command> displays move up to <function>main()</function> and have a look.</para> <screen>(gdb) <userinput>up</userinput> <lineannotation>Move up call stack</lineannotation> -#1 0x1625 in main () at temp.c:11 <lineannotation><command>gdb</command> displays stack frame</lineannotation> -(gdb) <userinput>p i</userinput> <lineannotation>Show us the value of <symbol>i</symbol></lineannotation> -$1 = 4231 <lineannotation><command>gdb</command> displays <literal>4231</literal></lineannotation></screen> +#1 0x1625 in main () at temp.c:11 <lineannotation>gdb displays stack frame</lineannotation> +(gdb) <userinput>p i</userinput> <lineannotation>Show us the value of i</lineannotation> +$1 = 4231 <lineannotation>gdb displays 4231</lineannotation></screen> <para>Oh dear! Looking at the code, we forgot to initialize <symbol>i</symbol>. We meant to put</para> @@ -1551,7 +1543,7 @@ main() { listings of core files and sweat over machine code manuals, but now life is a bit easier. Incidentally, under FreeBSD and other 4.4BSD systems, a core file is called - <filename><replaceable>progname</replaceable>.core</filename> instead of just + <filename>progname.core</filename> instead of just <filename>core</filename>, to make it clearer which program a core file belongs to.</para> @@ -1559,7 +1551,7 @@ main() { the usual way. Instead of typing <command>break</command> or <command>run</command>, type</para> - <screen>(gdb) <userinput>core <replaceable>progname</replaceable>.core</userinput></screen> + <screen>(gdb) <userinput>core progname.core</userinput></screen> <para>If you are not in the same directory as the core file, you will have to do <userinput>dir @@ -1617,7 +1609,7 @@ Cannot access memory at address 0x7020796d. use <command>ps</command> to find the process ID for the child, and do</para> - <screen>(gdb) <userinput>attach <replaceable>pid</replaceable></userinput></screen> + <screen>(gdb) <userinput>attach pid</userinput></screen> <para>in <command>gdb</command>, and then debug as usual.</para> @@ -1645,7 +1637,7 @@ else if (pid == 0) { /* child */ </sect2> </sect1> - <sect1 id="emacs"> + <sect1 xml:id="emacs"> <title>Using Emacs as a Development Environment</title> <sect2> @@ -1708,7 +1700,7 @@ else if (pid == 0) { /* child */ <para>And doubtless many more that have been overlooked.</para> <para>Emacs can be installed on &os; using - the <filename role="package">editors/emacs</filename> + the <package>editors/emacs</package> port.</para> <para>Once it is installed, start it up and do <userinput>C-h @@ -1791,9 +1783,8 @@ else if (pid == 0) { /* child */ although it is considerably smaller (and thus easier to master).</para> - <para>The best way to learn Emacs Lisp is to download the <ulink - url="ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz">Emacs - Tutorial</ulink></para> + <para>The best way to learn Emacs Lisp is to download the <link xlink:href="ftp://ftp.gnu.org/old-gnu/emacs/elisp-manual-19-2.4.tar.gz">Emacs + Tutorial</link></para> <para>However, there is no need to actually know any Lisp to get started with configuring Emacs, as I have included a sample @@ -1860,7 +1851,7 @@ else if (pid == 0) { /* child */ if you are doing something outside Emacs and you want to edit a file, you can just type in</para> - <screen>&prompt.user; <userinput>emacsclient <replaceable>filename</replaceable></userinput> + <screen>&prompt.user; <userinput>emacsclient filename</userinput> </screen> <para>and then you can edit the file in your @@ -2239,7 +2230,7 @@ else if (pid == 0) { /* child */ </sect2> </sect1> - <sect1 id="tools-reading"> + <sect1 xml:id="tools-reading"> <title>Further Reading</title> <para>For information about setting up a development environment diff --git a/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml b/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml index 5f682a8a16..e72bb99840 100644 --- a/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/x86/chapter.xml @@ -18,8 +18,7 @@ $FreeBSD$ --> - -<chapter id="x86"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="x86"> <title>x86 Assembly Language Programming</title> <para> @@ -29,7 +28,7 @@ This chapter was written by &a.stanislav.email;. -<sect1 id="x86-intro"> +<sect1 xml:id="x86-intro"> <title>Synopsis</title> <para> @@ -64,11 +63,11 @@ how you can use assembly language writing This chapter does not explain the basics of assembly language. There are enough resources about that (for a complete online course in assembly language, see Randall Hyde's -<ulink url="http://webster.cs.ucr.edu/">Art -of Assembly Language</ulink>; or if you prefer +<link xlink:href="http://webster.cs.ucr.edu/">Art +of Assembly Language</link>; or if you prefer a printed book, take a look at Jeff Duntemann's -<ulink url="http://www.int80h.org/cgi-bin/isbn?isbn=0471375233">Assembly -Language Step-by-Step</ulink>). However, +<link xlink:href="http://www.int80h.org/cgi-bin/isbn?isbn=0471375233">Assembly +Language Step-by-Step</link>). However, once the chapter is finished, any assembly language programmer will be able to write programs for FreeBSD quickly and efficiently. @@ -80,10 +79,10 @@ Copyright © 2000-2001 G. Adam Stanislav. All rights reserved. </sect1> -<sect1 id="x86-the-tools"> +<sect1 xml:id="x86-the-tools"> <title>The Tools</title> -<sect2 id="x86-the-assembler"> +<sect2 xml:id="x86-the-assembler"> <title>The Assembler</title> <para> @@ -116,7 +115,7 @@ quite frankly, that is what I am used to. </sect2> -<sect2 id="x86-the-linker"> +<sect2 xml:id="x86-the-linker"> <title>The Linker</title> <para> @@ -134,10 +133,10 @@ code assembled with either assembler. </sect2> </sect1> -<sect1 id="x86-system-calls"> +<sect1 xml:id="x86-system-calls"> <title>System Calls</title> -<sect2 id="x86-default-calling-convention"> +<sect2 xml:id="x86-default-calling-convention"> <title>Default Calling Convention</title> <para> @@ -208,7 +207,7 @@ the kernel function, in this case <function role="syscall">open</function>. </para> </sect2> -<sect2 id="x86-alternate-calling-convention"> +<sect2 xml:id="x86-alternate-calling-convention"> <title>Alternate Calling Convention</title> <para> FreeBSD is an extremely flexible system. It offers other ways of @@ -250,11 +249,11 @@ the system know about it. After your program is assembled and linked, you need to brand the executable: </para> -<screen>&prompt.user; <userinput>brandelf -t Linux <replaceable>filename</replaceable></userinput></screen> +<screen>&prompt.user; <userinput>brandelf -t Linux filename</userinput></screen> </sect2> -<sect2 id="x86-use-geneva"> +<sect2 xml:id="x86-use-geneva"> <title>Which Convention Should You Use?</title> <para> @@ -274,7 +273,7 @@ how you can accomplish that after I have explained the basics. </sect2> -<sect2 id="x86-call-numbers"> +<sect2 xml:id="x86-call-numbers"> <title>Call Numbers</title> <para> @@ -283,7 +282,7 @@ place its number in <varname role="register">EAX</varname>. Of course, you need to know what the number is. </para> -<sect3 id="x86-the-syscalls-file"> +<sect3 xml:id="x86-the-syscalls-file"> <title>The <filename>syscalls</filename> File</title> <para> @@ -351,7 +350,7 @@ the <varname>path</varname> is stored. </sect1> -<sect1 id="x86-return-values"> +<sect1 xml:id="x86-return-values"> <title>Return Values</title> <para> @@ -367,7 +366,7 @@ occurs: A file does not exist, system resources are exhausted, we passed an invalid parameter, etc. </para> -<sect2 id="x86-man-pages"> +<sect2 xml:id="x86-man-pages"> <title>Man Pages</title> <para> @@ -405,7 +404,7 @@ information. </sect2> -<sect2 id="x86-where-return-values"> +<sect2 xml:id="x86-where-return-values"> <title>Where Are the Return Values?</title> <para> @@ -437,7 +436,7 @@ interfaces with the kernel. </tip> </sect2> -<sect2 id="x86-where-errno"> +<sect2 xml:id="x86-where-errno"> <title>Where Is <varname>errno</varname>?</title> <para> @@ -460,7 +459,7 @@ value. One register can contain either. </sect2> -<sect2 id="x86-how-to-know-error"> +<sect2 xml:id="x86-how-to-know-error"> <title>Determining an Error Occurred</title> <para> @@ -480,7 +479,7 @@ is negative, i.e., <varname>-errno</varname>. </sect1> -<sect1 id="x86-portable-code"> +<sect1 xml:id="x86-portable-code"> <title>Creating Portable Code</title> <para> @@ -504,7 +503,7 @@ programmer's perspective): The calling convention, the function numbers, and the way of returning values. </para> -<sect2 id="x86-deal-with-function-numbers"><title>Dealing with Function Numbers</title> +<sect2 xml:id="x86-deal-with-function-numbers"><title>Dealing with Function Numbers</title> <para> In many cases the function numbers are the same. However, @@ -522,7 +521,7 @@ architecture: %endif </programlisting> </sect2> -<sect2 id="x86-deal-with-geneva"><title>Dealing with Conventions</title> +<sect2 xml:id="x86-deal-with-geneva"><title>Dealing with Conventions</title> <para> Both, the calling convention, and the return value (the <varname>errno</varname> problem) can be resolved with macros: @@ -579,7 +578,7 @@ kernel: </sect2> -<sect2 id="x86-deal-with-other-portability"><title>Dealing with Other Portability Issues</title> +<sect2 xml:id="x86-deal-with-other-portability"><title>Dealing with Other Portability Issues</title> <para> The above solutions can handle most cases of writing code @@ -597,7 +596,7 @@ a few such conditional sections in your code. </sect2> -<sect2 id="x86-portable-library"><title>Using a Library</title> +<sect2 xml:id="x86-portable-library"><title>Using a Library</title> <para> You can avoid portability issues in your main code altogether @@ -676,7 +675,7 @@ main program. </sect2> -<sect2 id="x86-portable-include"> +<sect2 xml:id="x86-portable-include"> <title>Using an Include File</title> <para> @@ -784,7 +783,7 @@ discuss more syscalls. </sect1> -<sect1 id="x86-first-program"> +<sect1 xml:id="x86-first-program"> <title>Our First Program</title> <para> @@ -856,7 +855,7 @@ is for the system to figure out. </para> </note> -<sect2 id="x86-assemble-1"><title>Assembling the Code</title> +<sect2 xml:id="x86-assemble-1"><title>Assembling the Code</title> <para> Type the code (except the line numbers) in an editor, and save @@ -864,14 +863,14 @@ it in a file named <filename>hello.asm</filename>. You need <application>nasm</application> to assemble it. </para> -<sect3 id="x86-get-nasm"><title>Installing <application>nasm</application></title> +<sect3 xml:id="x86-get-nasm"><title>Installing <application>nasm</application></title> <para> If you do not have <application>nasm</application>, type: </para> <screen>&prompt.user; <userinput>su</userinput> -Password:<userinput><replaceable>your root password</replaceable></userinput> +Password:<userinput>your root password</userinput> &prompt.root; <userinput>cd /usr/ports/devel/nasm</userinput> &prompt.root; <userinput>make install</userinput> &prompt.root; <userinput>exit</userinput> @@ -893,8 +892,8 @@ compile it, and install it on your system. <para> If your system is not FreeBSD, you need to get <application>nasm</application> from its -<ulink url="https://sourceforge.net/projects/nasm">home -page</ulink>. You can still use it to assemble FreeBSD code. +<link xlink:href="https://sourceforge.net/projects/nasm">home +page</link>. You can still use it to assemble FreeBSD code. </para> </note> @@ -914,7 +913,7 @@ Hello, World! </sect1> -<sect1 id="x86-unix-filters"> +<sect1 xml:id="x86-unix-filters"> <title>Writing &unix; Filters</title> <para> @@ -1151,7 +1150,7 @@ to read it, another time to write the output). </sect1> -<sect1 id="x86-buffered-io"> +<sect1 xml:id="x86-buffered-io"> <title>Buffered Input and Output</title> <para> @@ -1361,9 +1360,9 @@ _start: .put: call putchar -> cmp al, 0Ah -> jne .loop -> call write +> cmp al, 0Ah +> jne .loop +> call write jmp short .loop align 4 @@ -1444,7 +1443,7 @@ fix—it later, when I talk about the side of buffering</link>.</para> </note> -<sect2 id="x86-ungetc"> +<sect2 xml:id="x86-ungetc"> <title>How to Unread a Character</title> <warning><para> @@ -1605,7 +1604,7 @@ the buffer or within the "spare"). </sect1> -<sect1 id="x86-command-line"><title>Command Line Arguments</title> +<sect1 xml:id="x86-command-line"><title>Command Line Arguments</title> <para> Our <application>hex</application> program will be more useful if it can @@ -1938,7 +1937,7 @@ You already know everything you need to know to implement them. </sect1> -<sect1 id="x86-environment"> +<sect1 xml:id="x86-environment"> <title>&unix; Environment</title> <para> @@ -1948,7 +1947,7 @@ by you, yet others by the <application>shell</application>, or any program that loads another program. </para> -<sect2 id="x86-find-environment"> +<sect2 xml:id="x86-find-environment"> <title>How to Find Environment Variables</title> <para> @@ -1977,7 +1976,7 @@ may be missing. We need to account for that possibility. </sect2> -<sect2 id="x86-webvar"> +<sect2 xml:id="x86-webvar"> <title>webvars</title> <para> @@ -1987,13 +1986,13 @@ I thought it would be more interesting to write a simple assembly language CGI utility. </para> -<sect3 id="x86-cgi"> +<sect3 xml:id="x86-cgi"> <title>CGI: A Quick Overview</title> <para> I have a -<ulink url="http://www.whizkidtech.redprince.net/cgi-bin/tutorial">detailed -<acronym>CGI</acronym> tutorial</ulink> on my web site, +<link xlink:href="http://www.whizkidtech.redprince.net/cgi-bin/tutorial">detailed +<acronym>CGI</acronym> tutorial</link> on my web site, but here is a very quick overview of <acronym>CGI</acronym>: </para> @@ -2039,7 +2038,7 @@ quite a useful diagnostic tool. </sect3> -<sect3 id="x86-webvars-the-code"> +<sect3 xml:id="x86-webvars-the-code"> <title>The Code</title> <para> @@ -2262,10 +2261,10 @@ or perhaps rename it with a <filename>.cgi</filename> extension. <para> Then you need to use your browser to view its output. To see its output on my web server, please go to -<ulink url="http://www.int80h.org/webvars/"><filename>http://www.int80h.org/webvars/</filename></ulink>. +<link xlink:href="http://www.int80h.org/webvars/"><filename>http://www.int80h.org/webvars/</filename></link>. If curious about the additional environment variables present in a password protected web directory, go to -<ulink url="http://www.int80h.org/private/"><filename>http://www.int80h.org/private/</filename></ulink>, +<link xlink:href="http://www.int80h.org/private/"><filename>http://www.int80h.org/private/</filename></link>, using the name <userinput>asm</userinput> and password <userinput>programmer</userinput>. </para> @@ -2276,7 +2275,7 @@ using the name <userinput>asm</userinput> and password </sect1> -<sect1 id="x86-files"> +<sect1 xml:id="x86-files"> <title>Working with Files</title> <para> @@ -2296,7 +2295,7 @@ supposed to do. <para> One of the first programs I wrote for &unix; was -<ulink url="ftp://ftp.int80h.org/unix/tuc/"><application>tuc</application></ulink>, +<link xlink:href="ftp://ftp.int80h.org/unix/tuc/"><application>tuc</application></link>, a text-to-&unix; file converter. It converts a text file from other operating systems to a &unix; text file. In other words, it changes from different kind of line endings @@ -2314,15 +2313,15 @@ to send the output to a different file. Most of the time, I end up using it like this: </para> -<screen>&prompt.user; <userinput>tuc <replaceable>myfile tempfile</replaceable></userinput> -&prompt.user; <userinput>mv <replaceable>tempfile myfile</replaceable></userinput></screen> +<screen>&prompt.user; <userinput>tuc myfile tempfile</userinput> +&prompt.user; <userinput>mv tempfile myfile</userinput></screen> <para> It would be nice to have a <application>ftuc</application>, i.e., <emphasis>fast tuc</emphasis>, and use it like this: </para> -<screen>&prompt.user; <userinput>ftuc <replaceable>myfile</replaceable></userinput></screen> +<screen>&prompt.user; <userinput>ftuc myfile</userinput></screen> <para> In this chapter, then, we will write @@ -2389,7 +2388,7 @@ combination of the above (e.g., carriage return followed by several line feeds). </para> -<sect2 id="x86-finite-state-machine"> +<sect2 xml:id="x86-finite-state-machine"> <title>Finite State Machine</title> <para> @@ -2545,7 +2544,7 @@ and leave the state unchanged. </listitem> </itemizedlist> -<sect3 id="x86-final-state"> +<sect3 xml:id="x86-final-state"> <title>The Final State</title> <para> @@ -2576,7 +2575,7 @@ an assembly language program. </sect3> -<sect3 id="x86-tuc-counter"> +<sect3 xml:id="x86-tuc-counter"> <title>The Output Counter</title> <para> @@ -2592,7 +2591,7 @@ to set the file to. </sect2> -<sect2 id="x86-software-fsm"> +<sect2 xml:id="x86-software-fsm"> <title>Implementing FSM in Software</title> <para> @@ -2657,7 +2656,7 @@ microprocessors do, either way may be equally fast. </sect2> -<sect2 id="memory-mapped-files"> +<sect2 xml:id="memory-mapped-files"> <title>Memory Mapped Files</title> <para> @@ -2739,14 +2738,14 @@ we unmap it with the <function role="syscall">munmap</function> syscall: <para> For an in-depth treatment of <function role="syscall">mmap</function>, see W. Richard Stevens' -<ulink url="http://www.int80h.org/cgi-bin/isbn?isbn=0130810819">Unix -Network Programming, Volume 2, Chapter 12</ulink>. +<link xlink:href="http://www.int80h.org/cgi-bin/isbn?isbn=0130810819">Unix +Network Programming, Volume 2, Chapter 12</link>. </para> </tip> </sect2> -<sect2 id="x86-file-size"> +<sect2 xml:id="x86-file-size"> <title>Determining File Size</title> <para> @@ -2775,14 +2774,14 @@ of <function role="syscall">fstat</function>, a traditional one <para> This is a very straightforward call: We pass to it the address -of a <structname>stat</structname> structure and the descriptor +of a <varname remap="structname">stat</varname> structure and the descriptor of an open file. It will fill out the contents of the -<structname>stat</structname> structure. +<varname remap="structname">stat</varname> structure. </para> <para> I do, however, have to say that I tried to declare the -<structname>stat</structname> structure in the +<varname remap="structname">stat</varname> structure in the <varname>.bss</varname> section, and <function role="syscall">fstat</function> did not like it: It set the carry flag indicating an error. After I changed the code to allocate @@ -2791,7 +2790,7 @@ the structure on the stack, everything was working fine. </sect2> -<sect2 id="x86-ftruncate"> +<sect2 xml:id="x86-ftruncate"> <title>Changing the File Size</title> <para> @@ -2826,7 +2825,7 @@ Please note that this one contains a <varname>int pad</varname> again. </sect2> -<sect2 id="x86-ftuc"> +<sect2 xml:id="x86-ftuc"> <title>ftuc</title> <para> @@ -3166,7 +3165,7 @@ its contents. </sect1> -<sect1 id="x86-one-pointed-mind"> +<sect1 xml:id="x86-one-pointed-mind"> <title>One-Pointed Mind</title> <para> @@ -3197,7 +3196,7 @@ write your own programs for that part of the problem that you do not have an existing solution for. </para> -<sect2 id="x86-csv"><title>CSV</title> +<sect2 xml:id="x86-csv"><title>CSV</title> <para> I will illustrate this principle with a specific real-life @@ -3344,7 +3343,7 @@ specified. To get the 11th field of each record, I can now do: </para> -<screen>&prompt.user; <userinput>csv '-t;' <replaceable>data.csv</replaceable> | awk '-F;' '{print $11}'</userinput></screen> +<screen>&prompt.user; <userinput>csv '-t;' data.csv | awk '-F;' '{print $11}'</userinput></screen> <para> The code stores the options (except for the file descriptors) @@ -3656,7 +3655,7 @@ keyboard, processes it, and sees its input buffer is empty. It flushes its output and reads the next line. </para> -<sect3 id="x86-buffered-dark-side"> +<sect3 xml:id="x86-buffered-dark-side"> <title>The Dark Side of Buffering</title> <para> This change prevents a mysterious lockup @@ -3794,7 +3793,7 @@ its output buffer <emphasis>before</emphasis> asking the </sect1> -<sect1 id="x86-fpu"> +<sect1 xml:id="x86-fpu"> <title>Using the <acronym>FPU</acronym></title> <para> Strangely enough, most of assembly language literature does not @@ -3808,7 +3807,7 @@ Yet, never does assembly language shine more than when we create highly optimized <acronym>FPU</acronym> code by doing things that can be done <emphasis>only</emphasis> in assembly language.</para> -<sect2 id="x86-fpu-organization"><title>Organization of the <acronym>FPU</acronym></title> +<sect2 xml:id="x86-fpu-organization"><title>Organization of the <acronym>FPU</acronym></title> <para> The <acronym>FPU</acronym> consists of 8 80–bit floating–point registers. These are organized in a stack fashion—you can @@ -3910,7 +3909,7 @@ and the <acronym>TOS</acronym> is always <varname role="register">st0</varname>, never just <function role="opcode">st</function>. </para> -<sect3 id="x86-fpu-packed-decimal"> +<sect3 xml:id="x86-fpu-packed-decimal"> <title>The Packed Decimal Format</title> <para> The <emphasis>packed decimal</emphasis> format @@ -3977,8 +3976,8 @@ in desperation! <note> <para> The book to read—if you can find it—is Richard Startz' -<ulink url="http://www.int80h.org/cgi-bin/isbn?isbn=013246604X">8087/80287/80387 -for the IBM PC & Compatibles</ulink>. +<link xlink:href="http://www.int80h.org/cgi-bin/isbn?isbn=013246604X">8087/80287/80387 +for the IBM PC & Compatibles</link>. Though it does seem to take the fact about the little–endian storage of the <emphasis>packed decimal</emphasis> for granted. I kid you not about the @@ -3993,7 +3992,7 @@ little–endian order even for this type of data. </sect2> -<sect2 id="x86-pinhole-photography"> +<sect2 xml:id="x86-pinhole-photography"> <title>Excursion to Pinhole Photography</title> <para> To write meaningful software, we must not only @@ -4008,7 +4007,7 @@ so, we need some background in <emphasis>pinhole photography</emphasis> before we can continue. </para> -<sect3 id="x86-camera"> +<sect3 xml:id="x86-camera"> <title>The Camera</title> <para> The easiest way to describe any camera ever built @@ -4040,7 +4039,7 @@ a lens assembly, often called the <emphasis>objective</emphasis>. </sect3> -<sect3 id="x86-the-pinhole"> +<sect3 xml:id="x86-the-pinhole"> <title>The Pinhole</title> <para> But, strictly speaking, the lens is not necessary: @@ -4059,7 +4058,7 @@ sharpness.</para> </sect3> -<sect3 id="x86-focal-length"> +<sect3 xml:id="x86-focal-length"> <title>Focal Length</title> <para> This ideal pinhole diameter is a function @@ -4089,7 +4088,7 @@ experimentation. </sect3> -<sect3 id="x86-f-number"> +<sect3 xml:id="x86-f-number"> <title>The F–Number</title> <para> The f–number is a very useful measure of @@ -4136,7 +4135,7 @@ at f–number <varname>B</varname> is:</para> </programlisting> </sect3> -<sect3 id="x86-normalized-f-number"> +<sect3 xml:id="x86-normalized-f-number"> <title>Normalized F–Number</title> <para> While many modern cameras can change the diameter @@ -4170,7 +4169,7 @@ be rounded somewhat. </sect3> -<sect3 id="x86-f-stop"> +<sect3 xml:id="x86-f-stop"> <title>The F–Stop</title> <para> A typical camera is designed in such a way that setting @@ -4193,14 +4192,14 @@ quadruple the required exposure. Moving the dial by </sect2> -<sect2 id="x86-pinhole-software"> +<sect2 xml:id="x86-pinhole-software"> <title>Designing the Pinhole Software</title> <para> We are now ready to decide what exactly we want our pinhole software to do. </para> -<sect3 id="xpinhole-processing-input"> +<sect3 xml:id="xpinhole-processing-input"> <title>Processing Program Input</title> <para> Since its main purpose is to help us design a working @@ -4326,7 +4325,7 @@ of course. </sect3> -<sect3 id="x86-pinhole-options"> +<sect3 xml:id="x86-pinhole-options"> <title>Offering Options</title> <para> The most important thing we need to know when building @@ -4501,7 +4500,7 @@ and <parameter>-c</parameter> as identical to <parameter>-p037</parameter>. </sect3> -<sect3 id="x86-pinhole-output"> +<sect3 xml:id="x86-pinhole-output"> <title>The Output</title> <para> We need to decide what we want our software to @@ -5083,7 +5082,7 @@ anyway.</para> </sect2> -<sect2 id="x86-fpu-optimizations"> +<sect2 xml:id="x86-fpu-optimizations"> <title>FPU Optimizations</title> <para> In assembly language we can optimize the <acronym>FPU</acronym> @@ -5249,7 +5248,7 @@ available about &postscript; than about the </sect2> -<sect2 id="x86-pinhole-the-code"> +<sect2 xml:id="x86-pinhole-the-code"> <title><application>pinhole</application>—The Code</title> <programlisting> ;;;;;;; pinhole.asm ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; @@ -6110,7 +6109,7 @@ tiny detail, the code almost writes itself. </sect2> -<sect2 id="x86-pinhole-using"> +<sect2 xml:id="x86-pinhole-using"> <title>Using <application>pinhole</application></title> <para> Because we have decided to make the program @@ -6168,7 +6167,7 @@ one half of a millimeter. </sect2> -<sect2 id="x86-pinhole-scripting"> +<sect2 xml:id="x86-pinhole-scripting"> <title>Scripting</title> <para> Because we have chosen the <constant>#</constant> @@ -6306,7 +6305,7 @@ focal length in millimeters,pinhole diameter in microns,F-number,normalized F-nu </sect1> -<sect1 id="x86-caveats"> +<sect1 xml:id="x86-caveats"> <title>Caveats</title> <para> @@ -6335,7 +6334,7 @@ That is generally a <emphasis>very bad idea</emphasis> in &unix; environment! Let me explain why. </para> -<sect2 id="x86-protected"> +<sect2 xml:id="x86-protected"> <title>&unix; Is Protected</title> <para> @@ -6350,7 +6349,7 @@ become a dinosaur overnight. </sect2> -<sect2 id="x86-abstraction"> +<sect2 xml:id="x86-abstraction"> <title>&unix; Is an Abstraction</title> <para> @@ -6451,7 +6450,7 @@ them and why. </sect1> -<sect1 id="x86-acknowledgements"> +<sect1 xml:id="x86-acknowledgements"> <title>Acknowledgements</title> <para> @@ -6465,8 +6464,8 @@ system programming in general and FreeBSD in particular. <para> Thomas M. Sommers opened the door for me. His -<ulink url="http://www.codebreakers-journal.com/content/view/262/27/">How -do I write "Hello, world" in FreeBSD assembler?</ulink> +<link xlink:href="http://www.codebreakers-journal.com/content/view/262/27/">How +do I write "Hello, world" in FreeBSD assembler?</link> web page was my first encounter with an example of assembly language programming under FreeBSD. </para> diff --git a/en_US.ISO8859-1/books/faq/book.xml b/en_US.ISO8859-1/books/faq/book.xml index 30a1e5be59..49a32f3954 100644 --- a/en_US.ISO8859-1/books/faq/book.xml +++ b/en_US.ISO8859-1/books/faq/book.xml @@ -1,30 +1,29 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY bibliography SYSTEM "../../../share/xml/bibliography.xml"> <!ENTITY rel.numbranch "3"> <!-- number of branches that follow in this list --> -<!ENTITY rel.head "<emphasis>10-CURRENT</emphasis>"> -<!ENTITY rel.head.relx "10.<replaceable>X</replaceable>"> -<!ENTITY rel.head.releng "<symbol>head/</symbol>"> +<!ENTITY rel.head "<emphasis xmlns='http://docbook.org/ns/docbook'>10-CURRENT</emphasis>"> +<!ENTITY rel.head.relx "10.<replaceable xmlns='http://docbook.org/ns/docbook'>X</replaceable>"> +<!ENTITY rel.head.releng "<symbol xmlns='http://docbook.org/ns/docbook'>head/</symbol>"> <!ENTITY rel.head.packages "packages-10-current"> -<!ENTITY rel.relx "9.<replaceable>X</replaceable>"> -<!ENTITY rel.stable "<emphasis>9-STABLE</emphasis>"> -<!ENTITY rel.releng "<symbol>stable/9/</symbol>"> +<!ENTITY rel.relx "9.<replaceable xmlns='http://docbook.org/ns/docbook'>X</replaceable>"> +<!ENTITY rel.stable "<emphasis xmlns='http://docbook.org/ns/docbook'>9-STABLE</emphasis>"> +<!ENTITY rel.releng "<symbol xmlns='http://docbook.org/ns/docbook'>stable/9/</symbol>"> <!ENTITY rel.relengdate "September 2011"> <!ENTITY rel.packages "packages-9-stable"> -<!ENTITY rel2.relx "8.<replaceable>X</replaceable>"> -<!ENTITY rel2.stable "<emphasis>8-STABLE</emphasis>"> -<!ENTITY rel2.releng "<symbol>stable/8/</symbol>"> +<!ENTITY rel2.relx "8.<replaceable xmlns='http://docbook.org/ns/docbook'>X</replaceable>"> +<!ENTITY rel2.stable "<emphasis xmlns='http://docbook.org/ns/docbook'>8-STABLE</emphasis>"> +<!ENTITY rel2.releng "<symbol xmlns='http://docbook.org/ns/docbook'>stable/8/</symbol>"> <!ENTITY rel2.relengdate "August 2009"> <!ENTITY rel2.packages "packages-8-stable"> ]> - -<book lang='en'> - <bookinfo> - <title>Frequently Asked Questions for &os; +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>Frequently Asked Questions for &os; &rel2.relx;, and &rel.relx;</title> + - <corpauthor>The &os; Documentation Project</corpauthor> + <author><orgname>The &os; Documentation Project</orgname></author> <copyright> <year>1995</year> @@ -51,7 +50,7 @@ &legalnotice; - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.ibm; @@ -76,30 +75,26 @@ &a.doc;.</para> <para>The latest version of - this document is always available from the <ulink - url="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html">&os; website</ulink>. - It may also be downloaded as one large <ulink - url="book.html">HTML</ulink> file with HTTP or as a variety - of other formats from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP - server</ulink>.</para> + this document is always available from the <link xlink:href="http://www.FreeBSD.org/doc/en_US.ISO8859-1/books/faq/index.html">&os; website</link>. + It may also be downloaded as one large <link xlink:href="book.html">HTML</link> file with HTTP or as a variety + of other formats from the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">&os; FTP + server</link>.</para> </abstract> - </bookinfo> + </info> - <chapter id="introduction"> + <chapter xml:id="introduction"> <title>Introduction</title> <qandaset> <qandaentry> - <question id="what-is-FreeBSD"> + <question xml:id="what-is-FreeBSD"> <para>What is &os;?</para> </question> <answer> <para>&os; is a modern operating system for desktops, laptops, servers, and embedded systems with - support for a large number of <ulink - url="http://www.FreeBSD.org/platforms/">platforms</ulink>.</para> + support for a large number of <link xlink:href="http://www.FreeBSD.org/platforms/">platforms</link>.</para> <para>It is based on U.C. Berkeley's <quote>4.4BSD-Lite</quote> release, with some @@ -115,13 +110,12 @@ recreation.</para> <para>For more detailed information on &os;, please see the - <ulink - url="&url.books.handbook;/index.html">&os; Handbook</ulink>.</para> + <link xlink:href="&url.books.handbook;/index.html">&os; Handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="FreeBSD-goals"> + <question xml:id="FreeBSD-goals"> <para>What is the goal of the &os; Project?</para> </question> @@ -135,15 +129,14 @@ </qandaentry> <qandaentry> - <question id="bsd-license-restrictions"> + <question xml:id="bsd-license-restrictions"> <para>Does the &os; license have any restrictions?</para> </question> <answer> <para>Yes. Those restrictions do not control how you use the code, merely how you treat the &os; Project itself. If you - have serious license concerns, read the actual <ulink - url="http://www.FreeBSD.org/copyright/freebsd-license.html">license</ulink>. + have serious license concerns, read the actual <link xlink:href="http://www.FreeBSD.org/copyright/freebsd-license.html">license</link>. For the simply curious, the license can be summarized like this.</para> @@ -176,23 +169,20 @@ support.</para> <para>Code in our source tree which falls under the - <ulink - url="http://www.FreeBSD.org/copyright/COPYING">GNU General Public License (GPL)</ulink> - or <ulink - url="http://www.FreeBSD.org/copyright/COPYING.LIB">GNU Library General Public License (LGPL)</ulink> + <link xlink:href="http://www.FreeBSD.org/copyright/COPYING">GNU General Public License (GPL)</link> + or <link xlink:href="http://www.FreeBSD.org/copyright/COPYING.LIB">GNU Library General Public License (LGPL)</link> comes with slightly more strings attached, though at least on the side of enforced access rather than the usual opposite. Due to the additional complexities that can evolve in the commercial use of GPL software, we do, however, endeavor to replace such software with submissions - under the more relaxed <ulink - url="http://www.FreeBSD.org/copyright/freebsd-license.html">&os; license</ulink> + under the more relaxed <link xlink:href="http://www.FreeBSD.org/copyright/freebsd-license.html">&os; license</link> whenever possible.</para> </answer> </qandaentry> <qandaentry> - <question id="replace-current-OS"> + <question xml:id="replace-current-OS"> <para>Can &os; replace my current operating system?</para> </question> @@ -208,8 +198,7 @@ readers, graphics programs, programming environments, network servers, and just about everything else you might want. Most of these applications can be managed through the - <ulink - url="http://www.FreeBSD.org/ports/">Ports Collection</ulink>.</para> + <link xlink:href="http://www.FreeBSD.org/ports/">Ports Collection</link>.</para> <para>If you need to use an application that is only available on one operating system, you simply cannot replace that @@ -226,19 +215,17 @@ environment, you already know most of what you need to. If your background is in graphic-driven operating systems such as &windows; and &macos;, you may be interested in using - <ulink - url="http://www.pcbsd.org/">PC-BSD</ulink>, a &os; based + <link xlink:href="http://www.pcbsd.org/">PC-BSD</link>, a &os; based distribution, instead. If you have not used &unix; before expect to invest additional time learning the &unix; way of doing things. - This FAQ and the <ulink - url="&url.books.handbook;/index.html">&os; Handbook</ulink> + This FAQ and the <link xlink:href="&url.books.handbook;/index.html">&os; Handbook</link> are excellent places to start.</para> </answer> </qandaentry> <qandaentry> - <question id="why-called-FreeBSD"> + <question xml:id="why-called-FreeBSD"> <para>Why is it called &os;?</para> </question> @@ -274,7 +261,7 @@ </qandaentry> <qandaentry> - <question id="differences-to-other-bsds"> + <question xml:id="differences-to-other-bsds"> <para>What are the differences between &os; and NetBSD, OpenBSD, and other open source BSD operating systems?</para> </question> @@ -282,8 +269,7 @@ <answer> <para>James Howard wrote a good explanation of the history and differences between the various projects, - called <ulink - url="http://www.freebsdworld.gr/freebsd/bsd-family-tree.html">The BSD Family Tree</ulink> + called <link xlink:href="http://www.freebsdworld.gr/freebsd/bsd-family-tree.html">The BSD Family Tree</link> which goes a fair way to answering this question. Some of the information is out of date, but the history portion in particular remains accurate.</para> @@ -319,7 +305,7 @@ </qandaentry> <qandaentry> - <question id="latest-version"> + <question xml:id="latest-version"> <para>What is the latest version of &os;?</para> </question> @@ -341,12 +327,10 @@ <quote>legacy</quote> branch and most current work will only become a part of &rel.stable; and &rel2.stable;.--></para> - <para>Version <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;</ulink> + <para>Version <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;</link> is the latest release from the &rel.stable; branch; it was released in &rel.current.date;. Version - <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;</ulink> + <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;</link> is the latest release from the &rel2.stable; branch; it was released in &rel2.current.date;.</para> @@ -360,37 +344,30 @@ volatility (relative to <emphasis>-STABLE</emphasis>, that is).</para> - <para>Releases are made <link - linkend="release-freq">every few months</link>. While + <para>Releases are made <link linkend="release-freq">every few months</link>. While many people stay more up-to-date with the &os; sources (see - the questions on <link - linkend="current">&os.current;</link> and <link - linkend="stable">&os.stable;</link>) than that, doing so + the questions on <link linkend="current">&os.current;</link> and <link linkend="stable">&os.stable;</link>) than that, doing so is more of a commitment, as the sources are a moving target.</para> <para>More information on &os; releases can be found on the - <ulink - url="http://www.FreeBSD.org/releng/index.html#release-build">Release Engineering page</ulink> + <link xlink:href="http://www.FreeBSD.org/releng/index.html#release-build">Release Engineering page</link> and in &man.release.7;.</para> </answer> </qandaentry> <qandaentry> - <question id="current"> + <question xml:id="current"> <para>What is <emphasis>&os;-CURRENT</emphasis>?</para> </question> <answer> - <para><ulink - url="&url.books.handbook;/current-stable.html#current">&os.current;</ulink> + <para><link xlink:href="&url.books.handbook;/current-stable.html#current">&os.current;</link> is the development version of the operating system, which will in due course become the new &os.stable; branch. As such, it is really only of interest to developers working on - the system and die-hard hobbyists. See the <ulink - url="&url.books.handbook;/current-stable.html#current">relevant section</ulink> - in the <ulink - url="&url.books.handbook;/index.html">Handbook</ulink> for + the system and die-hard hobbyists. See the <link xlink:href="&url.books.handbook;/current-stable.html#current">relevant section</link> + in the <link xlink:href="&url.books.handbook;/index.html">Handbook</link> for details on running <emphasis>-CURRENT</emphasis>.</para> <para>If you are not familiar with &os; @@ -400,8 +377,7 @@ People that use &os.current; are expected to be able to analyze, debug, and report problems.</para> - <para>&os; <ulink - url="&url.base;/snapshots/">snapshot</ulink> + <para>&os; <link xlink:href="&url.base;/snapshots/">snapshot</link> releases are made based on the current state of the <emphasis>-CURRENT</emphasis> and <emphasis>-STABLE</emphasis> branches. The goals behind @@ -442,8 +418,7 @@ to stick to full releases, or use the <emphasis>-STABLE</emphasis> snapshots.</para> - <para>Snapshot releases are directly available from <ulink - url="&url.base;/snapshots/">snapshot</ulink>.</para> + <para>Snapshot releases are directly available from <link xlink:href="&url.base;/snapshots/">snapshot</link>.</para> <para>Official snapshots are generated on a regular basis for all actively developed branches.</para> @@ -451,17 +426,15 @@ </qandaentry> <qandaentry> - <question id="stable"> + <question xml:id="stable"> <para>What is the <emphasis>&os;-STABLE</emphasis> concept?</para> </question> <answer> <para>Back when &os; 2.0.5 was released, &os; development - branched in two. One branch was named <ulink - url="&url.books.handbook;/current-stable.html#stable">-STABLE</ulink>, - one <ulink - url="&url.books.handbook;/current-stable.html#current">-CURRENT</ulink>. + branched in two. One branch was named <link xlink:href="&url.books.handbook;/current-stable.html#stable">-STABLE</link>, + one <link xlink:href="&url.books.handbook;/current-stable.html#current">-CURRENT</link>. <emphasis>&os;-STABLE</emphasis> is intended for Internet Service Providers and other commercial enterprises for whom sudden shifts or experimental features are quite @@ -470,11 +443,9 @@ <emphasis>&os;-CURRENT</emphasis>, on the other hand, has been one unbroken line since 2.0 was released, leading towards &rel.current;-RELEASE and beyond. For more detailed - information on branches see <quote><ulink - url="&url.articles.releng;/release-proc.html#rel-branch">&os; Release Engineering: Creating the Release Branch</ulink></quote>, + information on branches see <quote><link xlink:href="&url.articles.releng;/release-proc.html#rel-branch">&os; Release Engineering: Creating the Release Branch</link></quote>, the status of the branches and the upcoming release schedule - can be found on the <ulink - url="http://www.FreeBSD.org/releng">Release Engineering Information</ulink> page.</para> + can be found on the <link xlink:href="http://www.FreeBSD.org/releng">Release Engineering Information</link> page.</para> <para>&rel.current;-STABLE is the actively developed <emphasis>-STABLE</emphasis> branch. The latest release on @@ -483,14 +454,13 @@ <para>The &rel.head; branch is the actively developed <emphasis>-CURRENT</emphasis> branch toward the next - generation of &os;. See <link - linkend="current">What is &os;-CURRENT?</link> for more + generation of &os;. See <link linkend="current">What is &os;-CURRENT?</link> for more information on this branch.</para> </answer> </qandaentry> <qandaentry> - <question id="release-freq"> + <question xml:id="release-freq"> <para>When are &os; releases made?</para> </question> @@ -509,8 +479,7 @@ <para>More information on the release engineering process (including a schedule of upcoming releases) can be found on - the <ulink - url="http://www.FreeBSD.org/releng/index.html">release engineering</ulink> + the <link xlink:href="http://www.FreeBSD.org/releng/index.html">release engineering</link> pages on the &os; Web site.</para> <para>For people who need or want a little more excitement, @@ -519,18 +488,16 @@ </qandaentry> <qandaentry> - <question id="responsible"> + <question xml:id="responsible"> <para>Who is responsible for &os;?</para> </question> <answer> <para>The key decisions concerning the &os; project, such as the overall direction of the project and who is allowed to - add code to the source tree, are made by a <ulink - url="&url.base;/administration.html#t-core">core team</ulink> of + add code to the source tree, are made by a <link xlink:href="&url.base;/administration.html#t-core">core team</link> of 9 people. There is a much larger team of more than 350 - <ulink - url="&url.articles.contributors;/article.html#staff-committers">committers</ulink> + <link xlink:href="&url.articles.contributors;/article.html#staff-committers">committers</link> who are authorized to make changes directly to the &os; source tree.</para> @@ -542,92 +509,80 @@ </qandaentry> <qandaentry> - <question id="where-get"> + <question xml:id="where-get"> <para>Where can I get &os;?</para> </question> <answer> <para>Every significant release of &os; is available via - anonymous FTP from the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> &os; FTP site</ulink>:</para> + anonymous FTP from the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/"> &os; FTP site</link>:</para> <itemizedlist> <listitem> <para>The latest &rel.stable; release, &rel.current;-RELEASE - can be found in the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory</ulink>.</para> + can be found in the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/i386/&rel.current;-RELEASE/">&rel.current;-RELEASE directory</link>.</para> </listitem> <listitem> - <para><ulink url="&url.base;/snapshots/"> Snapshot</ulink> - releases are made monthly for the <link - linkend="current">-CURRENT</link> and <link - linkend="stable">-STABLE</link> branch, these being of + <para><link xlink:href="&url.base;/snapshots/"> Snapshot</link> + releases are made monthly for the <link linkend="current">-CURRENT</link> and <link linkend="stable">-STABLE</link> branch, these being of service purely to bleeding-edge testers and developers.</para> </listitem> <listitem> <para>The latest &rel2.stable; release, &rel2.current;-RELEASE - can be found in the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;-RELEASE directory</ulink>.</para> + can be found in the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">&rel2.current;-RELEASE directory</link>.</para> </listitem> </itemizedlist> <para>Information about obtaining &os; on CD, DVD, and other - media can be found in <ulink - url="&url.books.handbook;/mirrors.html">the Handbook</ulink>.</para> + media can be found in <link xlink:href="&url.books.handbook;/mirrors.html">the Handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="access-pr"> + <question xml:id="access-pr"> <para>How do I access the Problem Report database?</para> </question> <answer> <para>The Problem Report database of all user change requests - may be queried by using our web-based PR <ulink - url="http://www.FreeBSD.org/cgi/query-pr.cgi?query">query</ulink> + may be queried by using our web-based PR <link xlink:href="http://www.FreeBSD.org/cgi/query-pr.cgi?query">query</link> interface.</para> <para>The &man.send-pr.1; command can be used to submit problem reports and change requests via electronic mail. - Alternatively, the <ulink - url="http://www.freebsd.org/send-pr.html">web-based problem report submission interface</ulink> + Alternatively, the <link xlink:href="http://www.freebsd.org/send-pr.html">web-based problem report submission interface</link> can be used to submit problem reports through a web browser.</para> - <para>Before submitting a problem report, please read <ulink - url="&url.articles.problem-reports;/article.html">Writing &os; Problem Reports</ulink>, + <para>Before submitting a problem report, please read <link xlink:href="&url.articles.problem-reports;/article.html">Writing &os; Problem Reports</link>, an article on how to write good problem reports.</para> </answer> </qandaentry> </qandaset> </chapter> - <chapter id="support"> + <chapter xml:id="support"> <title>Documentation and Support</title> <qandaset> <qandaentry> - <question id="books"> + <question xml:id="books"> <para>What good books are there about &os;?</para> </question> <answer> <para>The project produces a wide range of documentation, - available online from this link: <ulink - url="http://www.FreeBSD.org/docs.html"></ulink>. In addition, <link - linkend="bibliography">the Bibliography</link> at the end of this - FAQ, and <ulink - url="&url.books.handbook;/bibliography.html">the one in the Handbook</ulink> + available online from this link: <uri xlink:href="http://www.FreeBSD.org/docs.html">http://www.FreeBSD.org/docs.html</uri>. In addition, <link linkend="bibliography">the Bibliography</link> at the end of this + FAQ, and <link xlink:href="&url.books.handbook;/bibliography.html">the one in the Handbook</link> reference other recommended books.</para> </answer> </qandaentry> <qandaentry> - <question id="doc-formats"> + <question xml:id="doc-formats"> <para>Is the documentation available in other formats, such as plain text (ASCII), or &postscript;?</para> </question> @@ -635,8 +590,7 @@ <answer> <para>Yes. The documentation is available in a number of different formats and compression schemes on the &os; FTP - site, in the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</ulink> + site, in the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</link> directory.</para> <para>The documentation is categorized in a number of @@ -651,7 +605,7 @@ <listitem> <para>The document's language and encoding. These are based on the locale names you will find under - <filename class="directory">/usr/share/locale</filename> on your &os; + <filename>/usr/share/locale</filename> on your &os; system. The current languages and encodings that we have for documentation are as follows:</para> @@ -862,10 +816,8 @@ <note> <para>Page numbers are not automatically updated when - loading Rich Text Format into Word. Press <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>A</keycap></keycombo>, - <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>End</keycap></keycombo>, + loading Rich Text Format into Word. Press <keycombo action="simul"><keycap>Ctrl</keycap><keycap>A</keycap></keycombo>, + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>End</keycap></keycombo>, <keycap>F9</keycap> after loading the document, to update the page numbers.</para> </note> @@ -886,7 +838,7 @@ <listitem> <para>All the other formats generate one file, called - <filename><replaceable>type</replaceable>.<replaceable>format</replaceable></filename> + <filename>type.format</filename> (i.e., <filename>article.pdf</filename>, <filename>book.html</filename>, and so on).</para> @@ -899,7 +851,7 @@ <para>So the &postscript; version of the Handbook, compressed using <literal>bzip2</literal> will be stored in a file called <filename>book.ps.bz2</filename> in the - <filename class="directory">handbook/</filename> directory.</para> + <filename>handbook/</filename> directory.</para> </listitem> </orderedlist> </listitem> @@ -932,21 +884,19 @@ </qandaentry> <qandaentry> - <question id="mailing"> + <question xml:id="mailing"> <para>Where do I find info on the &os; mailing lists? What &os; news groups are available?</para> </question> <answer> - <para>You can find full information in the <ulink - url="&url.books.handbook;/eresources.html#eresources-mail">Handbook entry on mailing-lists</ulink> - and the <ulink - url="&url.books.handbook;/eresources-news.html">Handbook entry on newsgroups</ulink>.</para> + <para>You can find full information in the <link xlink:href="&url.books.handbook;/eresources.html#eresources-mail">Handbook entry on mailing-lists</link> + and the <link xlink:href="&url.books.handbook;/eresources-news.html">Handbook entry on newsgroups</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="irc"> + <question xml:id="irc"> <para>Are there &os; IRC (Internet Relay Chat) channels?</para> </question> @@ -957,16 +907,14 @@ <itemizedlist> <listitem> - <para>Channel <literal>#FreeBSDhelp</literal> on <ulink - url="http://www.efnet.org/index.php">EFNet</ulink> is + <para>Channel <literal>#FreeBSDhelp</literal> on <link xlink:href="http://www.efnet.org/index.php">EFNet</link> is a channel dedicated to helping &os; users. They are much more sympathetic to questions than <literal>#FreeBSD</literal> is.</para> </listitem> <listitem> - <para>Channel <literal>#FreeBSD</literal> on <ulink - url="http://freenode.net/">Freenode</ulink> is a + <para>Channel <literal>#FreeBSD</literal> on <link xlink:href="http://freenode.net/">Freenode</link> is a general help channel with many users at any time. The conversations have been known to run off-topic for a while, but priority is given to users with &os; @@ -978,45 +926,41 @@ If you would like to speak in your native language, try to ask the question in English and then relocate to another channel - <literal>##freebsd-<replaceable>lang</replaceable></literal> + <literal>##freebsd-lang</literal> as appropriate.</para> </listitem> <listitem> - <para>Channel <literal>#FreeBSD</literal> on <ulink - url="http://www.dal.net/">DALNET</ulink> is available at - <hostid>irc.dal.net</hostid> in the US and - <hostid>irc.eu.dal.net</hostid> in Europe.</para> + <para>Channel <literal>#FreeBSD</literal> on <link xlink:href="http://www.dal.net/">DALNET</link> is available at + <systemitem>irc.dal.net</systemitem> in the US and + <systemitem>irc.eu.dal.net</systemitem> in Europe.</para> </listitem> <listitem> - <para>Channel <literal>#FreeBSD</literal> on <ulink - url="http://www.undernet.org/">UNDERNET</ulink> is - available at <hostid>us.undernet.org</hostid> in the US - and <hostid>eu.undernet.org</hostid> in Europe. Since + <para>Channel <literal>#FreeBSD</literal> on <link xlink:href="http://www.undernet.org/">UNDERNET</link> is + available at <systemitem>us.undernet.org</systemitem> in the US + and <systemitem>eu.undernet.org</systemitem> in Europe. Since it is a help channel, be prepared to read the documents you are referred to.</para> </listitem> <listitem> <para>Channel <literal>#FreeBSD</literal> on - <ulink url="http://www.rusnet.org.ru/">RUSNET</ulink> + <link xlink:href="http://www.rusnet.org.ru/">RUSNET</link> is a russian-language oriented channel dedicated to helping &os; users. This is also good place for non-technical discussions.</para> </listitem> <listitem> - <para>Channel <literal>#bsdchat</literal> on <ulink - url="http://freenode.net/">Freenode</ulink> is a + <para>Channel <literal>#bsdchat</literal> on <link xlink:href="http://freenode.net/">Freenode</link> is a Traditional-Chinese (UTF-8 encoding) language oriented channel dedicated to helping &os; users. This is also good place for non-technical discussions.</para> </listitem> </itemizedlist> - <para>The &os; wiki has a <ulink - url="http://wiki.freebsd.org/IrcChannels">good list</ulink> + <para>The &os; wiki has a <link xlink:href="http://wiki.freebsd.org/IrcChannels">good list</link> of IRC channels.</para> <para>Each of these channels are distinct and are not @@ -1031,34 +975,29 @@ </qandaentry> <qandaentry> - <question id="forums"> + <question xml:id="forums"> <para>Are there any web based forums to discuss &os;?</para> </question> <answer> - <para>The official &os; forums are located at <ulink - url="http://forums.FreeBSD.org/">http://forums.FreeBSD.org/</ulink>.</para> + <para>The official &os; forums are located at <link xlink:href="http://forums.FreeBSD.org/">http://forums.FreeBSD.org/</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="training"> + <question xml:id="training"> <para>Where can I get commercial &os; training and support?</para> </question> <answer> - <para><ulink - url="http://www.ixsystems.com">iXsystems, Inc.</ulink>, - parent company of the <ulink - url="http://www.freebsdmall.com/">&os; Mall</ulink>, - provides commercial &os; and PC-BSD software <ulink - url="http://www.ixsystems.com/bsdsupport">support</ulink>, + <para><link xlink:href="http://www.ixsystems.com">iXsystems, Inc.</link>, + parent company of the <link xlink:href="http://www.freebsdmall.com/">&os; Mall</link>, + provides commercial &os; and PC-BSD software <link xlink:href="http://www.ixsystems.com/bsdsupport">support</link>, in addition to &os; development and tuning solutions.</para> <para>BSD Certification Group, Inc. provides system administration certifications for DragonFly BSD, &os;, NetBSD, - OpenBSD. If you are interested in them, visit <ulink - url="http://www.BSDCertification.org">their site</ulink>.</para> + OpenBSD. If you are interested in them, visit <link xlink:href="http://www.BSDCertification.org">their site</link>.</para> <para>Any other organizations providing training and support should contact the Project to be listed here.</para> @@ -1067,23 +1006,19 @@ </qandaset> </chapter> - <chapter id="install"> - <chapterinfo> - <author> - <firstname>Nik</firstname> - <surname>Clayton</surname> - <affiliation> + <chapter xml:id="install"> + <info><title>Installation</title> + <author><personname><firstname>Nik</firstname><surname>Clayton</surname></personname><affiliation> <address><email>nik@FreeBSD.org</email></address> - </affiliation> - </author> - </chapterinfo> + </affiliation></author> + </info> - <title>Installation</title> + <qandaset> <qandaentry> - <question id="which-architecture"> + <question xml:id="which-architecture"> <para>Which platform should I download? I have a 64 bit capable &intel; CPU, but I only see <literal>amd64</literal>.</para> @@ -1102,13 +1037,13 @@ </qandaentry> <qandaentry> - <question id="floppy-download"> + <question xml:id="floppy-download"> <para>Which file do I download to get &os;?</para> </question> <answer> <para>On the - <ulink url="http://www.freebsd.org/where.html">Getting &os;</ulink> + <link xlink:href="http://www.freebsd.org/where.html">Getting &os;</link> page select <literal>[iso]</literal> next to the architecture you want to use.</para> @@ -1163,13 +1098,12 @@ <para>Full instructions on this procedure and a little bit more about installation issues in general can be found in - the <ulink - url="&url.books.handbook;/install.html">Handbook entry on installing &os;</ulink>.</para> + the <link xlink:href="&url.books.handbook;/install.html">Handbook entry on installing &os;</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="floppy-image-too-large"> + <question xml:id="floppy-image-too-large"> <para>What do I do if the images do not fit on a single disk?</para> </question> @@ -1212,29 +1146,26 @@ on the floppy as a regular file. You have to transfer it to the floppy <quote>raw</quote>, using the low-level tools (e.g., <command>fdimage</command> or - <command>rawrite</command>) described in the <ulink - url="&url.books.handbook;/install.html">installation guide to &os;</ulink>.</para> + <command>rawrite</command>) described in the <link xlink:href="&url.books.handbook;/install.html">installation guide to &os;</link>.</para> </listitem> </itemizedlist> </answer> </qandaentry> <qandaentry> - <question id="install-instructions-location"> + <question xml:id="install-instructions-location"> <para>Where are the instructions for installing &os;?</para> </question> <answer> <para>Installation instructions for versions since - &os; 9.0 can be found at <ulink - url="&url.books.handbook;/bsdinstall.html">Handbook entry on installing &os;</ulink>. - Older instructions can be found in the <ulink - url="&url.books.handbook;/install.html">legacy entry on installing &os;</ulink>.</para> + &os; 9.0 can be found at <link xlink:href="&url.books.handbook;/bsdinstall.html">Handbook entry on installing &os;</link>. + Older instructions can be found in the <link xlink:href="&url.books.handbook;/install.html">legacy entry on installing &os;</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="need-to-run"> + <question xml:id="need-to-run"> <para>What do I need to run &os;?</para> </question> @@ -1248,21 +1179,20 @@ </qandaentry> <qandaentry> - <question id="custom-boot-floppy"> + <question xml:id="custom-boot-floppy"> <para>How can I make my own custom release or install disk?</para> </question> <answer> <para>Customized &os; installation media can be created by building a custom release. Follow the instructions in the - <ulink - url="&url.articles.releng;/article.html">Release Engineering</ulink> + <link xlink:href="&url.articles.releng;/article.html">Release Engineering</link> article.</para> </answer> </qandaentry> <qandaentry> - <question id="windows-coexist"> + <question xml:id="windows-coexist"> <para>Can &windows; co-exist with &os;?</para> </question> @@ -1277,7 +1207,7 @@ </qandaentry> <qandaentry> - <question id="bootmanager-restore"> + <question xml:id="bootmanager-restore"> <para>Another operating system destroyed my Boot Manager. How do I get it back?</para> </question> @@ -1301,7 +1231,7 @@ </qandaentry> <qandaentry> - <question id="no-install-cdrom"> + <question xml:id="no-install-cdrom"> <para>I booted from my ATAPI CD-ROM, but the install program says no CD-ROM is found. Where did it go?</para> </question> @@ -1325,15 +1255,14 @@ </qandaentry> <qandaentry> - <question id="need-complete-sources"> + <question xml:id="need-complete-sources"> <para>Do I need to install the source?</para> </question> <answer> <para>In general, no. There is nothing in the base system which requires the presence of the source to - operate. Some ports, like <filename - role="package">sysutils/lsof</filename>, will not build + operate. Some ports, like <package>sysutils/lsof</package>, will not build unless the source is installed. In particular, if the port builds a kernel module or directly operates on kernel structures, the source must be installed.</para> @@ -1341,7 +1270,7 @@ </qandaentry> <qandaentry> - <question id="need-kernel"> + <question xml:id="need-kernel"> <para>Do I need to build a kernel?</para> </question> @@ -1359,7 +1288,7 @@ </qandaentry> <qandaentry> - <question id="password-encryption"> + <question xml:id="password-encryption"> <para>Should I use DES, Blowfish, or MD5 passwords and how do I specify which form my users receive?</para> </question> @@ -1387,15 +1316,14 @@ </qandaentry> <qandaentry> - <question id="memory-limits"> + <question xml:id="memory-limits"> <para>What are the limits for memory?</para> </question> <answer> <para>Memory limits depend on the platform used. On a standard &i386; install, the limit is 4 GB but more - memory can be supported through &man.pae.4;. See <link - linkend="memory-i386-over-4gb">instructions for using 4 GB or more memory on &i386;</link>.</para> + memory can be supported through &man.pae.4;. See <link linkend="memory-i386-over-4gb">instructions for using 4 GB or more memory on &i386;</link>.</para> <para>&os;/pc98 has a limit of 4 GB memory, and PAE can not be used with it. Other architectures supported by &os; @@ -1405,7 +1333,7 @@ </qandaentry> <qandaentry> - <question id="ffs-limits"> + <question xml:id="ffs-limits"> <para>What are the limits for FFS file systems?</para> </question> @@ -1500,7 +1428,7 @@ </qandaentry> <qandaentry> - <question id="archsw-readin-failed-error"> + <question xml:id="archsw-readin-failed-error"> <para>Why do I get an error message, <errorname>readin failed</errorname> after compiling and booting a new kernel?</para> @@ -1508,8 +1436,8 @@ <answer> <para>Because your world and kernel are out of sync. This is - not supported. Be sure you use <command>make <maketarget>buildworld</maketarget></command> - and <command>make <maketarget>buildkernel</maketarget></command> + not supported. Be sure you use <command>make buildworld</command> + and <command>make buildkernel</command> to update your kernel.</para> <para>You can boot by specifying the kernel directly at the @@ -1519,7 +1447,7 @@ </qandaentry> <qandaentry> - <question id="general-configuration-tool"> + <question xml:id="general-configuration-tool"> <para>Is there a tool to perform post-installation configuration tasks?</para> </question> @@ -1529,21 +1457,21 @@ <varname>WITH_BSDCONFIG</varname> in <filename>/etc/src.conf</filename>. Users of &rel.relx; and higher may also install - <filename role="package">sysutils/bsdconfig</filename>.</para> + <package>sysutils/bsdconfig</package>.</para> </answer> </qandaentry> </qandaset> </chapter> - <chapter id="hardware"> + <chapter xml:id="hardware"> <title>Hardware Compatibility</title> - <sect1 id="compatibility-general"> + <sect1 xml:id="compatibility-general"> <title>General</title> <qandaset> <qandaentry> - <question id="which-hardware-to-get"> + <question xml:id="which-hardware-to-get"> <para>I want to get a piece of hardware for my &os; system. Which model/brand/type is best?</para> </question> @@ -1553,12 +1481,9 @@ lists. Since hardware changes so quickly, however, we expect this. We <emphasis>still</emphasis> strongly recommend that you read through the Hardware Notes - for &os; <ulink - url="&rel.current.hardware;">&rel.current;</ulink> or - <ulink - url="&rel2.current.hardware;">&rel2.current;</ulink> and - search the mailing list <ulink - url="http://www.FreeBSD.org/search/#mailinglists">archives</ulink> + for &os; <link xlink:href="&rel.current.hardware;">&rel.current;</link> or + <link xlink:href="&rel2.current.hardware;">&rel2.current;</link> and + search the mailing list <link xlink:href="http://www.FreeBSD.org/search/#mailinglists">archives</link> before asking about the latest and greatest hardware. Chances are a discussion about the type of hardware you are looking for took place just last week.</para> @@ -1571,7 +1496,7 @@ </qandaentry> <qandaentry> - <question id="memory-upper-limitation"> + <question xml:id="memory-upper-limitation"> <para>Does &os; support more than 4 GB of memory (RAM)? More than 16 GB? More than 48 GB?</para> </question> @@ -1590,7 +1515,7 @@ </qandaentry> <qandaentry> - <question id="memory-i386-over-4gb"> + <question xml:id="memory-i386-over-4gb"> <para>Why does &os; report less than 4 GB memory when installed on an &i386; machine?</para> </question> @@ -1648,12 +1573,12 @@ </qandaset> </sect1> - <sect1 id="compatibility-processors"> + <sect1 xml:id="compatibility-processors"> <title>Architectures and Processors</title> <qandaset> <qandaentry> - <question id="architectures"> + <question xml:id="architectures"> <para>Does &os; support architectures other than the x86?</para> </question> @@ -1664,18 +1589,16 @@ fully supported. Tiers 2 and 3 are supported on an if-possible basis. A full explanation of the tier system is available in the - <ulink - url="&url.articles.committers-guide;/archs.html">Committer's Guide.</ulink></para> + <link xlink:href="&url.articles.committers-guide;/archs.html">Committer's Guide.</link></para> <para>A complete list of supported architectures can be found on the - <ulink - url="http://www.FreeBSD.org/platforms/">platforms page.</ulink></para> + <link xlink:href="http://www.FreeBSD.org/platforms/">platforms page.</link></para> </answer> </qandaentry> <qandaentry> - <question id="smp-support"> + <question xml:id="smp-support"> <para>Does &os; support Symmetric Multiprocessing (SMP)?</para> </question> @@ -1694,7 +1617,7 @@ </qandaentry> <qandaentry> - <question id="microcode"> + <question xml:id="microcode"> <para>What is microcode? How do I install &intel; CPU microcode updates?</para> </question> @@ -1704,7 +1627,7 @@ implementating hardware level instructions. This allows for CPU bugs to be fixed without replacing the on board chip.</para> - <para>Install <filename role="package">sysutils/devcpu-data</filename>, + <para>Install <package>sysutils/devcpu-data</package>, then add:</para> <programlisting>microcode_update_enable="YES"</programlisting> @@ -1714,12 +1637,12 @@ </qandaset> </sect1> - <sect1 id="compatibility-drives"> + <sect1 xml:id="compatibility-drives"> <title>Hard Drives, Tape Drives, and CD and DVD Drives</title> <qandaset> <qandaentry> - <question id="supported-hard-drives"> + <question xml:id="supported-hard-drives"> <para>What kind of hard drives does &os; support?</para> </question> @@ -1734,20 +1657,19 @@ </qandaentry> <qandaentry> - <question id="supported-scsi-controllers"> + <question xml:id="supported-scsi-controllers"> <para>Which SCSI or SAS controllers are supported?</para> </question> <answer> <para>See the complete list in the Hardware Notes for &os; - <ulink url="&rel.current.hardware;">&rel.current;</ulink> - or <ulink - url="&rel2.current.hardware;">&rel2.current;</ulink>.</para> + <link xlink:href="&rel.current.hardware;">&rel.current;</link> + or <link xlink:href="&rel2.current.hardware;">&rel2.current;</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="tape-support"> + <question xml:id="tape-support"> <para>What types of tape drives are supported?</para> </question> @@ -1757,7 +1679,7 @@ </qandaentry> <qandaentry> - <question id="tape-changer-support"> + <question xml:id="tape-changer-support"> <para>Does &os; support tape changers?</para> </question> @@ -1777,7 +1699,7 @@ </qandaentry> <qandaentry> - <question id="supported-cdrom-drives"> + <question xml:id="supported-cdrom-drives"> <para>Which CD-ROM drives are supported by &os;?</para> </question> @@ -1789,7 +1711,7 @@ </qandaentry> <qandaentry> - <question id="supported-cdrw-drives"> + <question xml:id="supported-cdrw-drives"> <para>Which CD-RW drives are supported by &os;?</para> </question> @@ -1800,19 +1722,19 @@ <para>&os; also supports any SCSI CD-R or CD-RW drives. Install and use <command>cdrecord</command> from the ports or packages system, and make sure that you - have the <devicename>pass</devicename> device compiled in + have the <filename>pass</filename> device compiled in your kernel.</para> </answer> </qandaentry> </qandaset> </sect1> - <sect1 id="compatibility-kbd-mice"> + <sect1 xml:id="compatibility-kbd-mice"> <title>Keyboards and Mice</title> <qandaset> <qandaentry> - <question id="moused"> + <question xml:id="moused"> <para>Is it possible to use a mouse in any way outside the X Window system?</para> </question> @@ -1824,7 +1746,7 @@ &man.moused.8;, and turn on the mouse pointer in the virtual console:</para> - <screen>&prompt.root; <userinput>moused -p /dev/<replaceable>xxxx</replaceable> -t <replaceable>yyyy</replaceable></userinput> + <screen>&prompt.root; <userinput>moused -p /dev/xxxx -t yyyy</userinput> &prompt.root; <userinput>vidcontrol -m on</userinput></screen> <para>Where <replaceable>xxxx</replaceable> is the mouse @@ -1848,14 +1770,13 @@ <para>When the mouse daemon is running, access to the mouse must be coordinated between the mouse daemon and other - programs such as X Windows. Refer to the FAQ <link - linkend="x-and-moused">Why does my mouse not work with X?</link> + programs such as X Windows. Refer to the FAQ <link linkend="x-and-moused">Why does my mouse not work with X?</link> for more details on this issue.</para> </answer> </qandaentry> <qandaentry> - <question id="text-mode-cut-paste"> + <question xml:id="text-mode-cut-paste"> <para>How do I cut and paste text with a mouse in the text console?</para> </question> @@ -1881,7 +1802,7 @@ </qandaentry> <qandaentry> - <question id="mouse-wheel-buttons"> + <question xml:id="mouse-wheel-buttons"> <para>My mouse has a fancy wheel and buttons. Can I use them in &os;?</para> </question> @@ -1895,13 +1816,12 @@ two, or three button mouse.</para> <para>For the possible usage of wheels in the X Window - environment, refer to <link - linkend="x-and-wheel">that section</link>.</para> + environment, refer to <link linkend="x-and-wheel">that section</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="keyboard-delete-key"> + <question xml:id="keyboard-delete-key"> <para>How do I use my delete key in <command>sh</command> and <command>csh</command>?</para> </question> @@ -1921,19 +1841,18 @@ bind ^[[3~ ed-delete-next-char # for xterm</programlisting> <programlisting>bindkey ^? delete-char # for console bindkey ^[[3~ delete-char # for xterm</programlisting> - <para>For more information, see <ulink - url="http://www.ibb.net/~anne/keyboard.html">this page</ulink>.</para> + <para>For more information, see <link xlink:href="http://www.ibb.net/~anne/keyboard.html">this page</link>.</para> </answer> </qandaentry> </qandaset> </sect1> - <sect1 id="compatibility-other"> + <sect1 xml:id="compatibility-other"> <title>Other Hardware</title> <qandaset> <qandaentry> - <question id="es1370-silent-pcm"> + <question xml:id="es1370-silent-pcm"> <para>Workarounds for no sound from my &man.pcm.4; sound card?</para> </question> @@ -1948,7 +1867,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </qandaentry> <qandaentry> - <question id="power-management-support"> + <question xml:id="power-management-support"> <para>Does &os; support power management on my laptop?</para> </question> @@ -1963,12 +1882,12 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </sect1> </chapter> - <chapter id="troubleshoot"> + <chapter xml:id="troubleshoot"> <title>Troubleshooting</title> <qandaset> <qandaentry> - <question id="pae"> + <question xml:id="pae"> <para>Why is &os; finding the wrong amount of memory on &i386; hardware?</para> </question> @@ -1995,8 +1914,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> <para>On a 32-bit version of &os;, the memory appears lost, since it will be remapped above 4 GB, which a 32-bit kernel is unable to access. In this case, the - solution is to build a PAE enabled kernel. See <link - linkend="memory-limits">the entry on memory limits</link> + solution is to build a PAE enabled kernel. See <link linkend="memory-limits">the entry on memory limits</link> and <link linkend="memory-upper-limitation">about different memory limits on different platforms</link> for more information.</para> @@ -2012,7 +1930,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </qandaentry> <qandaentry> - <question id="signal11"> + <question xml:id="signal11"> <para>Why do my programs occasionally die with <errorname>Signal 11</errorname> errors?</para> </question> @@ -2049,11 +1967,11 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> that the compiler is carrying out changes each time.</para> <para>For example, suppose you are running - <command>make <maketarget>buildworld</maketarget></command>, + <command>make buildworld</command>, and the compile fails while trying to compile <filename>ls.c</filename> into <filename>ls.o</filename>. If you then run - <command>make <maketarget>buildworld</maketarget></command> + <command>make buildworld</command> again, and the compile fails in the same place then this is a broken build — try updating your sources and try again. If the compile fails elsewhere then this is almost @@ -2134,13 +2052,12 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> you have just found a bug in &os;, and you should follow the instructions to send a problem report.</para> - <para>There is an extensive FAQ on this at <ulink - url="http://www.bitwizard.nl/sig11/">the SIG11 problem FAQ</ulink>.</para> + <para>There is an extensive FAQ on this at <link xlink:href="http://www.bitwizard.nl/sig11/">the SIG11 problem FAQ</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="trap-12-panic"> + <question xml:id="trap-12-panic"> <para>My system crashes with either <errorname>Fatal trap 12: page fault in kernel mode</errorname>, or <errorname>panic:</errorname>, and spits out a bunch of @@ -2151,8 +2068,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> <para>The &os; developers are very interested in these errors, but need some more information than just the error you see. Copy your full crash message. Then consult the - FAQ section on <link - linkend="kernel-panic-troubleshooting">kernel panics</link>, + FAQ section on <link linkend="kernel-panic-troubleshooting">kernel panics</link>, build a debugging kernel, and get a backtrace. This might sound difficult, but you do not need any programming skills; you just have to follow the instructions.</para> @@ -2160,7 +2076,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </qandaentry> <qandaentry> - <question id="proc-table-full"> + <question xml:id="proc-table-full"> <para>Why do I get the error <errorname>maxproc limit exceeded by uid %i, please see tuning(7) and login.conf(5)</errorname>?</para> @@ -2178,8 +2094,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> maximum number of processes.</para> <para>To adjust your <varname>kern.maxusers</varname> value, - see the <ulink - url="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">File/Process Limits</ulink> + see the <link xlink:href="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">File/Process Limits</link> section of the Handbook. (While that section refers to open files, the same limits apply to processes.)</para> @@ -2200,7 +2115,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </qandaentry> <qandaentry> - <question id="mail-loopback"> + <question xml:id="mail-loopback"> <para>Why does <application>sendmail</application> give me an error reading <errorname>mail loops back to myself</errorname>?</para> @@ -2208,13 +2123,12 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> <answer> <para>You can find a detailed answer for this question in the - <ulink - url="&url.books.handbook;/mail-trouble.html#q26.5.2.">Handbook</ulink>.</para> + <link xlink:href="&url.books.handbook;/mail-trouble.html#q26.5.2.">Handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="remote-fullscreen"> + <question xml:id="remote-fullscreen"> <para>Why do full screen applications on remote machines misbehave?</para> </question> @@ -2269,7 +2183,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </qandaentry> <qandaentry> - <question id="connection-delay"> + <question xml:id="connection-delay"> <para>Why does it take so long to connect to my computer via <command>ssh</command> or <command>telnet</command>?</para> </question> @@ -2309,7 +2223,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> for more information. If this is on the global Internet, the problem may be that your server's resolver is not functioning correctly. To check, try to look up another - host — say, <hostid>www.yahoo.com</hostid>. If it + host — say, <systemitem>www.yahoo.com</systemitem>. If it does not work, that is your problem.</para> <para>Following a fresh install of &os;, it is also possible @@ -2329,7 +2243,7 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> </qandaentry> <qandaentry> - <question id="file-table-full"> + <question xml:id="file-table-full"> <para>Why does <errorname>file: table is full</errorname> show up repeatedly in &man.dmesg.8;?</para> </question> @@ -2337,17 +2251,15 @@ bindkey ^[[3~ delete-char # for xterm</programlisting> <answer> <para>This error message indicates you have exhausted the number of available file descriptors on your system. Please - see the <ulink - url="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">kern.maxfiles</ulink> - section of the <ulink - url="&url.books.handbook;/configtuning-kernel-limits.html">Tuning Kernel Limits</ulink> + see the <link xlink:href="&url.books.handbook;/configtuning-kernel-limits.html#kern-maxfiles">kern.maxfiles</link> + section of the <link xlink:href="&url.books.handbook;/configtuning-kernel-limits.html">Tuning Kernel Limits</link> section of the Handbook for a discussion and solution.</para> </answer> </qandaentry> <qandaentry> - <question id="computer-clock-skew"> + <question xml:id="computer-clock-skew"> <para>Why does the clock on my computer keep incorrect time?</para> </question> @@ -2403,7 +2315,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="indefinite-wait-buffer"> + <question xml:id="indefinite-wait-buffer"> <para>What does the error <errorname>swap_pager: indefinite wait buffer:</errorname> mean?</para> </question> @@ -2422,7 +2334,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="lock-order-reversal"> + <question xml:id="lock-order-reversal"> <para>What is a <errorname>lock order reversal</errorname>?</para> </question> @@ -2464,7 +2376,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="called-with-non-sleepable-locks-held"> + <question xml:id="called-with-non-sleepable-locks-held"> <para>What does <errorname>Called ... with the following non-sleepable locks held</errorname> mean?</para> </question> @@ -2500,9 +2412,9 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="touch-not-found"> + <question xml:id="touch-not-found"> <para>Why does - <maketarget>buildworld</maketarget>/<maketarget>installworld</maketarget> + <buildtarget>buildworld</buildtarget>/<buildtarget>installworld</buildtarget> die with the message <errorname>touch: not found</errorname>?</para> </question> @@ -2519,18 +2431,17 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaset> </chapter> - <chapter id="applications"> + <chapter xml:id="applications"> <title>User Applications</title> <qandaset> <qandaentry> - <question id="user-apps"> + <question xml:id="user-apps"> <para>So, where are all the user applications?</para> </question> <answer> - <para>Please take a look at <ulink - url="&url.base;/ports/index.html">the ports page</ulink> + <para>Please take a look at <link xlink:href="&url.base;/ports/index.html">the ports page</link> for info on software packages ported to &os;. The list currently tops &os.numports; and is growing daily, so come back to check often or subscribe to the &a.announce; for @@ -2540,7 +2451,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> &rel2.relx;, and &rel.relx; branches. Each time a &os; release is made, a snapshot of the ports tree at the time of - release in also included in the <filename class="directory">ports/</filename> + release in also included in the <filename>ports/</filename> directory.</para> <para>We also support the concept of a <quote>package</quote>, @@ -2555,7 +2466,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> you are interested in installing. Package files can usually be identified by their <filename>.tbz</filename> suffix and CD-ROM distribution people will have a - <filename class="directory">packages/All</filename> directory on their CD + <filename>packages/All</filename> directory on their CD which contains such files. They can also be downloaded over the net for various versions of &os; at the following locations:</para> @@ -2565,8 +2476,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> <term>for &rel2.relx; -RELEASE/&rel2.stable;</term> <listitem> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;</ulink></para> + <para><link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel2.packages;</link></para> </listitem> </varlistentry> @@ -2574,8 +2484,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> <term>for &rel.relx; -RELEASE/&rel.stable;</term> <listitem> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;</ulink></para> + <para><link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/i386/&rel.packages;</link></para> </listitem> </varlistentry> </variablelist> @@ -2585,14 +2494,13 @@ kern.timecounter.hardware: TSC -> i8254</screen> <para>Note that all ports may not be available as packages since new ones are constantly being added. It is always a good idea to check back periodically to see which packages - are available at the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp.FreeBSD.org</ulink> + are available at the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp.FreeBSD.org</link> master site.</para> </answer> </qandaentry> <qandaentry> - <question id="how-do-download-ports-tree"> + <question xml:id="how-do-download-ports-tree"> <para>How do I download the Ports tree? Should I be using SVN?</para> </question> @@ -2621,18 +2529,17 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="java"> + <question xml:id="java"> <para>Does &os; support &java;?</para> </question> <answer> - <para>Yes. Please see <ulink - url="&url.base;/java/index.html">http://www.FreeBSD.org/java/</ulink>.</para> + <para>Yes. Please see <link xlink:href="&url.base;/java/index.html">http://www.FreeBSD.org/java/</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="ports-4x"> + <question xml:id="ports-4x"> <para>Why can I not build this port on my &rel2.relx; -, or &rel.relx; -STABLE machine?</para> @@ -2642,8 +2549,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> <para>If you are running a &os; version that lags significantly behind <emphasis>-CURRENT</emphasis> or <emphasis>-STABLE</emphasis>, you may need to update your - Ports Collection; see the <ulink - url="&url.books.porters-handbook;/keeping-up.html">Keeping Up</ulink> + Ports Collection; see the <link xlink:href="&url.books.porters-handbook;/keeping-up.html">Keeping Up</link> section of the Porter's Handbook for further information on how to do this. If you are up to date, then someone might have committed a change to the port which works for @@ -2657,9 +2563,9 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="make-index"> + <question xml:id="make-index"> <para>I just tried to build <filename>INDEX</filename> using - <command>make <maketarget>index</maketarget></command>, and + <command>make index</command>, and it failed. Why?</para> </question> @@ -2672,8 +2578,8 @@ kern.timecounter.hardware: TSC -> i8254</screen> <para>There are rare cases where <filename>INDEX</filename> will not build due to odd cases involving - <makevar>WITH_<replaceable>*</replaceable></makevar> or - <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + <varname>WITH_<replaceable>*</replaceable></varname> or + <varname>WITHOUT_<replaceable>*</replaceable></varname> variables being set in <filename>make.conf</filename>. If you suspect that this is the case, please try to make <filename>INDEX</filename> with those make variables turned @@ -2682,7 +2588,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="ports-update"> + <question xml:id="ports-update"> <para>I updated the sources, now how do I update my installed ports?</para> </question> @@ -2691,14 +2597,13 @@ kern.timecounter.hardware: TSC -> i8254</screen> <para>&os; does not include a port upgrading tool, but it does have some tools to make the upgrade process somewhat easier. You can also install additional tools to simplify port - handling, see the <ulink - url="&url.books.handbook;/ports-using.html">Upgrading Ports</ulink> + handling, see the <link xlink:href="&url.books.handbook;/ports-using.html">Upgrading Ports</link> section in the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="ports-major-upgrade"> + <question xml:id="ports-major-upgrade"> <para>Do I need to recompile every port each time I perform a major version update?</para> </question> @@ -2716,14 +2621,13 @@ kern.timecounter.hardware: TSC -> i8254</screen> the older versions may fail to start or, in other cases, fail to function properly.</para> - <para>For more information, see <ulink - url="&url.books.handbook;/updating-upgrading-freebsdupdate.html#freebsdupdate-upgrade">the section on upgrades</ulink> + <para>For more information, see <link xlink:href="&url.books.handbook;/updating-upgrading-freebsdupdate.html#freebsdupdate-upgrade">the section on upgrades</link> in the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="ports-minor-upgrade"> + <question xml:id="ports-minor-upgrade"> <para>Do I need to recompile every port each time I perform a minor version update?</para> </question> @@ -2738,7 +2642,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="minimal-sh"> + <question xml:id="minimal-sh"> <para>Why is <command>/bin/sh</command> so minimal? Why does &os; not use <command>bash</command> or another shell?</para> @@ -2770,43 +2674,39 @@ kern.timecounter.hardware: TSC -> i8254</screen> compare for yourself the memory utilization of all these shells by looking at the <quote>VSZ</quote> and <quote>RSS</quote> columns in a <command>ps - <option>-u</option></command> listing.)</para> + -u</command> listing.)</para> </answer> </qandaentry> <qandaentry> - <question id="midi-sound-files"> + <question xml:id="midi-sound-files"> <para>How do I create audio CDs from my MIDI files?</para> </question> <answer> <para>To create audio CDs from MIDI files, first install - <filename role="package">audio/timidity++</filename> from + <package>audio/timidity++</package> from ports then install manually the GUS patches set by Eric A. - Welsh, available at <ulink - url="http://alleg.sourceforge.net/digmid.html"></ulink>. + Welsh, available at <uri xlink:href="http://alleg.sourceforge.net/digmid.html">http://alleg.sourceforge.net/digmid.html</uri>. After <application>TiMidity++</application> has been installed properly, MIDI files may be converted to WAV files with the following command line:</para> - <screen>&prompt.user; <userinput>timidity -Ow -s 44100 -o <replaceable>/tmp/juke/01.wav</replaceable> <replaceable>01.mid</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>timidity -Ow -s 44100 -o /tmp/juke/01.wav 01.mid</userinput></screen> <para>The WAV files can then be converted to other formats or - burned onto audio CDs, as described in the <ulink - url="&url.books.handbook;/creating-cds.html">&os; Handbook</ulink>.</para> + burned onto audio CDs, as described in the <link xlink:href="&url.books.handbook;/creating-cds.html">&os; Handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="officesuite"> + <question xml:id="officesuite"> <para>Where can I get an Office Suite for &os;?</para> </question> <answer> - <para>The open-source <application><ulink - url="http://www.openoffice.org">Apache OpenOffice</ulink></application> - and <application><ulink - url="http://www.libreoffice.org">LibreOffice</ulink></application> + <para>The open-source <application>Apache OpenOffice</application> + and <application>LibreOffice</application> office suites work natively on &os;.</para> <para>&os; also includes a variety of text editors, @@ -2816,7 +2716,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="convert-back-from-pkgng"> + <question xml:id="convert-back-from-pkgng"> <para>How can I convert from pkgng to the old package tools?</para> </question> @@ -2837,25 +2737,24 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaset> </chapter> - <chapter id="kernelconfig"> + <chapter xml:id="kernelconfig"> <title>Kernel Configuration</title> <qandaset> <qandaentry> - <question id="make-kernel"> + <question xml:id="make-kernel"> <para>I would like to customize my kernel. Is it difficult?</para> </question> <answer> - <para>Not at all! Check out the <ulink - url="&url.books.handbook;/kernelconfig.html">kernel config section of the Handbook</ulink>.</para> + <para>Not at all! Check out the <link xlink:href="&url.books.handbook;/kernelconfig.html">kernel config section of the Handbook</link>.</para> <note> <para>The new <filename>kernel</filename> will be installed - to the <filename class="directory">/boot/kernel</filename> directory along + to the <filename>/boot/kernel</filename> directory along with its modules, while the old kernel and its modules - will be moved to the <filename class="directory">/boot/kernel.old</filename> + will be moved to the <filename>/boot/kernel.old</filename> directory, so if you make a mistake the next time you play with your configuration you can boot the previous version of your kernel.</para> @@ -2864,7 +2763,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="why-kernel-big"> + <question xml:id="why-kernel-big"> <para>Why is my kernel so big?</para> </question> @@ -2874,14 +2773,13 @@ kern.timecounter.hardware: TSC -> i8254</screen> Kernels built in debug mode contain many symbols in separate files that are used for debugging, thus greatly increasing the size of - <filename class="directory">/boot/kernel/</filename>. + <filename>/boot/kernel/</filename>. Note that there will be little or no performance loss from running a debug kernel, and it is useful to keep one around in case of a system panic.</para> <para>However, if you are running low on disk space, there - are different options to reduce the size of <filename - class="directory">/boot/kernel/</filename>.</para> + are different options to reduce the size of <filename>/boot/kernel/</filename>.</para> <para>If you do not want the symbol files to be installed, make sure you have the following line present in @@ -2930,7 +2828,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> <xref linkend="make-kernel"/> for more information.</para> <para>To put any of these options into effect you will have - to <ulink url="&url.books.handbook;/kernelconfig-building.html">build and install</ulink> + to <link xlink:href="&url.books.handbook;/kernelconfig-building.html">build and install</link> your new kernel.</para> <para>Most kernels (<filename>/boot/kernel/kernel</filename>) @@ -2939,7 +2837,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="generic-kernel-build-failure"> + <question xml:id="generic-kernel-build-failure"> <para>Why does every kernel I try to build fail to compile, even <filename>GENERIC</filename>?</para> </question> @@ -2951,8 +2849,8 @@ kern.timecounter.hardware: TSC -> i8254</screen> <itemizedlist> <listitem> <para>You are not using the - <command>make <maketarget>buildkernel</maketarget></command> and - <command>make <maketarget>installkernel</maketarget></command> + <command>make buildkernel</command> and + <command>make installkernel</command> targets, and your source tree is different from the one used to build the currently running system (e.g., you are compiling &rel.current;-RELEASE on a @@ -2965,21 +2863,20 @@ kern.timecounter.hardware: TSC -> i8254</screen> <listitem> <para>You are using the - <command>make <maketarget>buildkernel</maketarget></command> + <command>make buildkernel</command> and - <command>make <maketarget>installkernel</maketarget></command> + <command>make installkernel</command> targets, but you failed to assert the completion of the - <command>make <maketarget>buildworld</maketarget></command> + <command>make buildworld</command> target. The - <command>make <maketarget>buildkernel</maketarget></command> + <command>make buildkernel</command> target relies on files generated by the - <command>make <maketarget>buildworld</maketarget></command> + <command>make buildworld</command> target to complete its job correctly.</para> </listitem> <listitem> - <para>Even if you are trying to build <link - linkend="stable">&os;-STABLE</link>, it is possible that + <para>Even if you are trying to build <link linkend="stable">&os;-STABLE</link>, it is possible that you fetched the source tree at a time when it was either being modified, or broken for other reasons; only releases are absolutely guaranteed to be buildable, @@ -2994,7 +2891,7 @@ kern.timecounter.hardware: TSC -> i8254</screen> </qandaentry> <qandaentry> - <question id="scheduler-in-use"> + <question xml:id="scheduler-in-use"> <para>How can I verify which scheduler is in use on a running system?</para> </question> @@ -3010,7 +2907,7 @@ kern.sched.name: ULE</screen> </qandaentry> <qandaentry> - <question id="scheduler-kern-quantum"> + <question xml:id="scheduler-kern-quantum"> <para>What is <varname>kern.sched.quantum</varname>?</para> </question> @@ -3023,24 +2920,23 @@ kern.sched.name: ULE</screen> </qandaset> </chapter> - <chapter id="disks"> + <chapter xml:id="disks"> <title>Disks, File Systems, and Boot Loaders</title> <qandaset> <qandaentry> - <question id="adding-disks"> + <question xml:id="adding-disks"> <para>How can I add my new hard disk to my &os; system?</para> </question> <answer> - <para>See the <ulink - url="&url.books.handbook;/disks-adding.html">Adding Disks</ulink> + <para>See the <link xlink:href="&url.books.handbook;/disks-adding.html">Adding Disks</link> section in the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="new-huge-disk"> + <question xml:id="new-huge-disk"> <para>How do I move my system over to my huge new disk?</para> </question> @@ -3064,7 +2960,7 @@ kern.sched.name: ULE</screen> <para>Now you have the new disk set up, and are ready to move the data. Unfortunately, you cannot just blindly copy the data. Things like device files (in - <filename class="directory">/dev</filename>), flags, and links tend to screw + <filename>/dev</filename>), flags, and links tend to screw that up. You need to use tools that understand these things, which means &man.dump.8;. Although it is suggested that you move the data in single user mode, it is not @@ -3099,41 +2995,41 @@ kern.sched.name: ULE</screen> </procedure> <para>For example, if you are going to move root to - <devicename>/dev/<replaceable>ada1s1a</replaceable></devicename>, - with <filename class="directory"><replaceable>/mnt</replaceable></filename> as + <filename>/dev/ada1s1a</filename>, + with <filename>/mnt</filename> as the temporary mount point, it is:</para> - <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput> -&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput> + <screen>&prompt.root; <userinput>newfs /dev/ada1s1a</userinput> +&prompt.root; <userinput>mount /dev/ada1s1a /mnt</userinput> +&prompt.root; <userinput>cd /mnt</userinput> &prompt.root; <userinput>dump 0af - / | restore rf -</userinput></screen> <para>Rearranging your partitions with <command>dump</command> takes a bit more work. To merge a partition like - <filename class="directory">/var</filename> into its parent, create the new + <filename>/var</filename> into its parent, create the new partition large enough for both, move the parent partition as described above, then move the child partition into the empty directory that the first move created:</para> - <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput> -&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput> + <screen>&prompt.root; <userinput>newfs /dev/ada1s1a</userinput> +&prompt.root; <userinput>mount /dev/ada1s1a /mnt</userinput> +&prompt.root; <userinput>cd /mnt</userinput> &prompt.root; <userinput>dump 0af - / | restore rf -</userinput> &prompt.root; <userinput>cd var</userinput> &prompt.root; <userinput>dump 0af - /var | restore rf -</userinput></screen> <para>To split a directory from its parent, say putting - <filename class="directory">/var</filename> on its own partition when it was + <filename>/var</filename> on its own partition when it was not before, create both partitions, then mount the child partition on the appropriate directory in the temporary mount point, then move the old single partition:</para> - <screen>&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1a</replaceable></userinput> -&prompt.root; <userinput>newfs /dev/<replaceable>ada1s1d</replaceable></userinput> -&prompt.root; <userinput>mount /dev/<replaceable>ada1s1a</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>mkdir <replaceable>/mnt</replaceable>/var</userinput> -&prompt.root; <userinput>mount /dev/<replaceable>ada1s1d</replaceable> <replaceable>/mnt</replaceable>/var</userinput> -&prompt.root; <userinput>cd <replaceable>/mnt</replaceable></userinput> + <screen>&prompt.root; <userinput>newfs /dev/ada1s1a</userinput> +&prompt.root; <userinput>newfs /dev/ada1s1d</userinput> +&prompt.root; <userinput>mount /dev/ada1s1a /mnt</userinput> +&prompt.root; <userinput>mkdir /mnt/var</userinput> +&prompt.root; <userinput>mount /dev/ada1s1d /mnt/var</userinput> +&prompt.root; <userinput>cd /mnt</userinput> &prompt.root; <userinput>dump 0af - / | restore rf -</userinput></screen> <para>You might prefer &man.cpio.1;, &man.pax.1;, &man.tar.1; @@ -3144,9 +3040,9 @@ kern.sched.name: ULE</screen> </qandaentry> <qandaentry> - <question id="safe-softupdates"> + <question xml:id="safe-softupdates"> <para>Which partitions can safely use Soft Updates? I have - heard that Soft Updates on <filename class="directory">/</filename> can cause + heard that Soft Updates on <filename>/</filename> can cause problems. What about Journaled Soft Updates?</para> </question> @@ -3196,13 +3092,13 @@ kern.sched.name: ULE</screen> tolerate this much risk, do not use Soft Updates on the root file system!</para> - <para><filename class="directory">/</filename> is traditionally one of the + <para><filename>/</filename> is traditionally one of the smallest partitions. If you put the - <filename class="directory">/tmp</filename> directory on - <filename class="directory">/</filename> and you have a busy - <filename class="directory">/tmp</filename>, you might see intermittent space - problems. Symlinking <filename class="directory">/tmp</filename> to - <filename class="directory">/var/tmp</filename> will solve this + <filename>/tmp</filename> directory on + <filename>/</filename> and you have a busy + <filename>/tmp</filename>, you might see intermittent space + problems. Symlinking <filename>/tmp</filename> to + <filename>/var/tmp</filename> will solve this problem.</para> <para>Finally, &man.dump.8; does not work in live mode (-L) @@ -3212,7 +3108,7 @@ kern.sched.name: ULE</screen> </qandaentry> <qandaentry> - <question id="mount-foreign-fs"> + <question xml:id="mount-foreign-fs"> <para>Can I mount other foreign file systems under &os;?</para> </question> @@ -3248,9 +3144,8 @@ kern.sched.name: ULE</screen> <listitem> <para>FUSE based NTFS support is available as a port - (<filename role="package">sysutils/fusefs-ntfs</filename>). - For more information see <ulink - url="http://www.tuxera.com/community/ntfs-3g-manual/"><application>ntfs-3g</application></ulink>.</para> + (<package>sysutils/fusefs-ntfs</package>). + For more information see <link xlink:href="http://www.tuxera.com/community/ntfs-3g-manual/"><application>ntfs-3g</application></link>.</para> </listitem> </varlistentry> @@ -3278,14 +3173,13 @@ kern.sched.name: ULE</screen> <para>&os; also supports network file systems such as NFS (see &man.mount.nfs.8;), NetWare (see &man.mount.nwfs.8;), and Microsoft-style SMB file systems (see &man.mount.smbfs.8;). - You can find ports based on FUSE (<filename - role="package">sysutils/fusefs-kmod</filename>) for many + You can find ports based on FUSE (<package>sysutils/fusefs-kmod</package>) for many other file systems.</para> </answer> </qandaentry> <qandaentry> - <question id="mount-dos"> + <question xml:id="mount-dos"> <para>How do I mount a secondary DOS partition?</para> </question> @@ -3295,27 +3189,26 @@ kern.sched.name: ULE</screen> example, if you have an <quote>E</quote> partition as the second DOS partition on the second SCSI drive, there will be a device file for <quote>slice 5</quote> in - <filename class="directory">/dev</filename>, so simply mount it:</para> + <filename>/dev</filename>, so simply mount it:</para> <screen>&prompt.root; <userinput>mount -t msdosfs /dev/da1s5 /dos/e</userinput></screen> </answer> </qandaentry> <qandaentry> - <question id="crypto-file-system"> + <question xml:id="crypto-file-system"> <para>Is there a cryptographic file system for &os;?</para> </question> <answer> <para>Yes. You can use either &man.gbde.8; or &man.geli.8;, - see the <ulink - url="&url.books.handbook;/disks-encrypting.html">Encrypting Disk Partitions</ulink> + see the <link xlink:href="&url.books.handbook;/disks-encrypting.html">Encrypting Disk Partitions</link> section of the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="nt-bootloader"> + <question xml:id="nt-bootloader"> <para>How can I use the &windowsnt; loader to boot &os;?</para> </question> @@ -3372,7 +3265,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="lilo-bootloader"> + <question xml:id="lilo-bootloader"> <para>How do I boot &os; and &linux; from LILO?</para> </question> @@ -3390,9 +3283,9 @@ C:\="DOS"</programlisting> label=&os;</programlisting> <para>(the above assumes that your &os; slice is known to - &linux; as <devicename>/dev/hda2</devicename>; tailor to + &linux; as <filename>/dev/hda2</filename>; tailor to suit your setup). Then, run <command>lilo</command> as - <username>root</username> and you should be done.</para> + <systemitem class="username">root</systemitem> and you should be done.</para> <para>If &os; resides on another disk, you need to add <literal>loader=/boot/chain.b</literal> to the LILO entry. @@ -3414,15 +3307,14 @@ C:\="DOS"</programlisting> <para>You can configure &man.boot.8; to automatically do this for you at boot time.</para> - <para>The <ulink - url="http://tldp.org/HOWTO/Linux+FreeBSD.html">&linux;+&os; mini-HOWTO</ulink> + <para>The <link xlink:href="http://tldp.org/HOWTO/Linux+FreeBSD.html">&linux;+&os; mini-HOWTO</link> is a good reference for &os; and &linux; interoperability issues.</para> </answer> </qandaentry> <qandaentry> - <question id="grub-loader"> + <question xml:id="grub-loader"> <para>How do I boot &os; and &linux; using GRUB?</para> </question> @@ -3447,7 +3339,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="booteasy-loader"> + <question xml:id="booteasy-loader"> <para>How do I boot &os; and &linux; using <application>BootEasy?</application></para> </question> @@ -3466,7 +3358,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="changing-bootprompt"> + <question xml:id="changing-bootprompt"> <para>How do I change the boot prompt from <literal>???</literal> to something more meaningful?</para> </question> @@ -3474,13 +3366,13 @@ C:\="DOS"</programlisting> <answer> <para>You can not do that with the standard boot manager without rewriting it. There are a number of other boot - managers in the <filename class="directory">sysutils</filename> ports category + managers in the <filename>sysutils</filename> ports category that provide this functionality.</para> </answer> </qandaentry> <qandaentry> - <question id="removable-drives"> + <question xml:id="removable-drives"> <para>I have a new removable drive, how do I use it?</para> </question> @@ -3521,22 +3413,20 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="mount-cd-superblock"> + <question xml:id="mount-cd-superblock"> <para>Why do I get <errorname>Incorrect super block</errorname> when mounting a CD-ROM?</para> </question> <answer> <para>You have to tell &man.mount.8; the type of the device - that you want to mount. This is described in the <ulink - url="&url.books.handbook;/creating-cds.html"> Handbook section on optical media</ulink>, - specifically the section <ulink - url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</ulink>.</para> + that you want to mount. This is described in the <link xlink:href="&url.books.handbook;/creating-cds.html"> Handbook section on optical media</link>, + specifically the section <link xlink:href="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="cdrom-not-configured"> + <question xml:id="cdrom-not-configured"> <para>Why do I get <errorname>Device not configured</errorname> when mounting a CD-ROM?</para> </question> @@ -3544,15 +3434,14 @@ C:\="DOS"</programlisting> <answer> <para>This generally means that there is no CD-ROM in the CD-ROM drive, or the drive is not visible on the bus. - Please see the <ulink - url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</ulink> + Please see the <link xlink:href="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CDs</link> section of the Handbook for a detailed discussion of this issue.</para> </answer> </qandaentry> <qandaentry> - <question id="cdrom-unicode-filenames"> + <question xml:id="cdrom-unicode-filenames"> <para>Why do all non-English characters in filenames show up as <quote>?</quote> on my CDs when mounted in &os;?</para> </question> @@ -3561,15 +3450,13 @@ C:\="DOS"</programlisting> <para>Your CD-ROM probably uses the <quote>Joliet</quote> extension for storing information about files and directories. This is discussed in the Handbook chapter on - <ulink - url="&url.books.handbook;/creating-cds.html">creating and using CD-ROMs</ulink>, - specifically the section on <ulink - url="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CD-ROMs</ulink>.</para> + <link xlink:href="&url.books.handbook;/creating-cds.html">creating and using CD-ROMs</link>, + specifically the section on <link xlink:href="&url.books.handbook;/creating-cds.html#mounting-cd">Using Data CD-ROMs</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="burncd-isofs"> + <question xml:id="burncd-isofs"> <para>I burned a CD under &os; and now I can not read it under any other operating system. Why?</para> </question> @@ -3577,29 +3464,25 @@ C:\="DOS"</programlisting> <answer> <para>You most likely burned a raw file to your CD, rather than creating an ISO 9660 file system. Take a look at - the <ulink - url="&url.books.handbook;/creating-cds.html">Handbook chapter on creating CD-ROMs</ulink>, - particularly the section on <ulink - url="&url.books.handbook;/creating-cds.html#rawdata-cd">burning raw data CDs</ulink>.</para> + the <link xlink:href="&url.books.handbook;/creating-cds.html">Handbook chapter on creating CD-ROMs</link>, + particularly the section on <link xlink:href="&url.books.handbook;/creating-cds.html#rawdata-cd">burning raw data CDs</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="copy-cd"> + <question xml:id="copy-cd"> <para>How can I create an image of a data CD?</para> </question> <answer> - <para>This is discussed in the Handbook section on <ulink - url="&url.books.handbook;/creating-cds.html#imaging-cd">duplicating data CDs</ulink>. - For more on working with CD-ROMs, see the <ulink - url="&url.books.handbook;/creating-cds.html">Creating CDs Section</ulink> + <para>This is discussed in the Handbook section on <link xlink:href="&url.books.handbook;/creating-cds.html#imaging-cd">duplicating data CDs</link>. + For more on working with CD-ROMs, see the <link xlink:href="&url.books.handbook;/creating-cds.html">Creating CDs Section</link> in the Storage chapter in the Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="mount-audio-CD"> + <question xml:id="mount-audio-CD"> <para>Why can I not <command>mount</command> an audio CD?</para> </question> @@ -3610,13 +3493,12 @@ C:\="DOS"</programlisting> argument</errorname>. This is because <command>mount</command> only works on file systems. Audio CDs do not have file systems; they just have data. You need - a program that reads audio CDs, such as the <filename - role="package">audio/xmcd</filename> port.</para> + a program that reads audio CDs, such as the <package>audio/xmcd</package> port.</para> </answer> </qandaentry> <qandaentry> - <question id="multi-session-CD"> + <question xml:id="multi-session-CD"> <para>How do I <command>mount</command> a multi-session CD?</para> </question> @@ -3631,20 +3513,20 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="user-floppymount"> + <question xml:id="user-floppymount"> <para>How do I let ordinary users mount CD-ROMs, DVDs, USB drives, and other removable media?</para> </question> <answer> - <para>As <username>root</username> set the sysctl variable + <para>As <systemitem class="username">root</systemitem> set the sysctl variable <varname>vfs.usermount</varname> to <literal>1</literal>.</para> <screen>&prompt.root; <userinput>sysctl vfs.usermount=1</userinput></screen> <para>To make this persist across reboots, add the line - <literal><varname>vfs.usermount</varname>=1</literal> to + <literal>vfs.usermount=1</literal> to <filename>/etc/sysctl.conf</filename> so that it is reset at system boot time.</para> @@ -3663,17 +3545,16 @@ C:\="DOS"</programlisting> <para>All users can now mount devices they could read onto a directory that they own:</para> - <screen>&prompt.user; <userinput>mkdir <replaceable>~/my-mount-point</replaceable></userinput> -&prompt.user; <userinput>mount -t msdosfs /dev/da0<replaceable>~/my-mount-point</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mkdir ~/my-mount-point</userinput> +&prompt.user; <userinput>mount -t msdosfs /dev/da0~/my-mount-point</userinput></screen> <para>Unmounting the device is simple:</para> - <screen>&prompt.user; <userinput>umount <replaceable>~/my-mount-point</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>umount ~/my-mount-point</userinput></screen> <para>Enabling <varname>vfs.usermount</varname>, however, has negative security implications. A better way to access - &ms-dos; formatted media is to use the <filename - role="package">emulators/mtools</filename> package in the + &ms-dos; formatted media is to use the <package>emulators/mtools</package> package in the Ports Collection.</para> <note> @@ -3684,7 +3565,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="du-vs-df"> + <question xml:id="du-vs-df"> <para>The <command>du</command> and <command>df</command> commands show different amounts of disk space available. What is going on?</para> @@ -3724,7 +3605,7 @@ C:\="DOS"</programlisting> <para>This situation is common on web servers. Many people set up a &os; web server and forget to rotate the log files. - The access log fills up <filename class="directory">/var</filename>. The new + The access log fills up <filename>/var</filename>. The new administrator deletes the file, but the system still complains that the partition is full. Stopping and restarting the web server program would free the file, @@ -3738,21 +3619,19 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="add-swap-space"> + <question xml:id="add-swap-space"> <para>How can I add more swap space?</para> </question> <answer> - <para>In the <ulink - url="&url.books.handbook;/config-tuning.html">Configuration and Tuning</ulink> - section of the Handbook, you will find a <ulink - url="&url.books.handbook;/adding-swap-space.html">section</ulink> + <para>In the <link xlink:href="&url.books.handbook;/config-tuning.html">Configuration and Tuning</link> + section of the Handbook, you will find a <link xlink:href="&url.books.handbook;/adding-swap-space.html">section</link> describing how to do this.</para> </answer> </qandaentry> <qandaentry> - <question id="manufacturer-disk-size"> + <question xml:id="manufacturer-disk-size"> <para>Why does &os; see my disk as smaller than the manufacturer says it is?</para> </question> @@ -3764,14 +3643,13 @@ C:\="DOS"</programlisting> example, &os;'s boot messages will report a disk that supposedly has 80 GB as holding 76,319 MB.</para> - <para>Also note that &os; will (by default) <link - linkend="disk-more-than-full">reserve</link> 8% of the disk + <para>Also note that &os; will (by default) <link linkend="disk-more-than-full">reserve</link> 8% of the disk space.</para> </answer> </qandaentry> <qandaentry> - <question id="disk-more-than-full"> + <question xml:id="disk-more-than-full"> <para>How is it possible for a partition to be more than 100% full?</para> </question> @@ -3779,7 +3657,7 @@ C:\="DOS"</programlisting> <answer> <para>A portion of each UFS partition (8%, by default) is reserved for use by the operating system and the - <username>root</username> user. &man.df.1; does not count + <systemitem class="username">root</systemitem> user. &man.df.1; does not count that space when calculating the <literal>Capacity</literal> column, so it can exceed 100%. Also, you will notice that the <literal>Blocks</literal> column is always greater than @@ -3793,12 +3671,12 @@ C:\="DOS"</programlisting> </qandaentry> </qandaset> - <sect1 id="all-about-zfs"> + <sect1 xml:id="all-about-zfs"> <title>ZFS</title> <qandaset> <qandaentry> - <question id="how-much-ram-for-zfs"> + <question xml:id="how-much-ram-for-zfs"> <para>What is the minimum amount of RAM one should have to run ZFS?</para> </question> @@ -3810,7 +3688,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="what-is-zil"> + <question xml:id="what-is-zil"> <para>What is the ZIL and when does it get used?</para> </question> @@ -3832,7 +3710,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="need-ssd-for-zil"> + <question xml:id="need-ssd-for-zil"> <para>Do I need a SSD for ZIL?</para> </question> @@ -3847,7 +3725,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="what-is-l2arc"> + <question xml:id="what-is-l2arc"> <para>What is the L2ARC?</para> </question> @@ -3869,7 +3747,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="should-enable-dedup"> + <question xml:id="should-enable-dedup"> <para>Is enabling deduplication advisable?</para> </question> @@ -3894,7 +3772,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="zpool-fully-full"> + <question xml:id="zpool-fully-full"> <para>I can not delete or create files on my ZFS pool. How can I fix this?</para> </question> @@ -3906,7 +3784,7 @@ C:\="DOS"</programlisting> to a usable state, truncate a file you want to delete.</para> - <screen>&prompt.user; <userinput>truncate -s 0 <replaceable>unimportant-file</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>truncate -s 0 unimportant-file</userinput></screen> <para>File truncation works because a new transaction is not started, new spare blocks are created instead.</para> @@ -3920,13 +3798,13 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="zfs-ssd-trim"> + <question xml:id="zfs-ssd-trim"> <para>Does ZFS support TRIM for Solid State Drives?</para> </question> <answer> <para>ZFS TRIM support was added to &os; 10-CURRENT - with revision r<svnref>240868</svnref>. ZFS TRIM + with revision r<revnumber>240868</revnumber>. ZFS TRIM support is not yet available on the -STABLE branches.</para> @@ -3947,12 +3825,12 @@ C:\="DOS"</programlisting> </sect1> </chapter> - <chapter id="admin"> + <chapter xml:id="admin"> <title>System Administration</title> <qandaset> <qandaentry> - <question id="startup-config-files"> + <question xml:id="startup-config-files"> <para>Where are the system start-up configuration files?</para> </question> @@ -3961,8 +3839,8 @@ C:\="DOS"</programlisting> <para>The primary configuration file is <filename>/etc/defaults/rc.conf</filename> (see &man.rc.conf.5;). System startup scripts such as - <filename class="directory">/etc/rc</filename> and - <filename class="directory">/etc/rc.d</filename> (see &man.rc.8;) just include + <filename>/etc/rc</filename> and + <filename>/etc/rc.d</filename> (see &man.rc.8;) just include this file. <emphasis>Do not edit this file!</emphasis> Instead, if there is any entry in <filename>/etc/defaults/rc.conf</filename> that you want to @@ -3976,14 +3854,14 @@ C:\="DOS"</programlisting> <screen>&prompt.root; <userinput>echo 'named_enable="YES"' >> /etc/rc.conf</userinput></screen> <para>To start up local services, place shell scripts in the - <filename class="directory">/usr/local/etc/rc.d</filename> directory. These + <filename>/usr/local/etc/rc.d</filename> directory. These shell scripts should be set executable, the default file mode is <literal>555</literal>.</para> </answer> </qandaentry> <qandaentry> - <question id="adding-users"> + <question xml:id="adding-users"> <para>How do I add a user easily?</para> </question> @@ -3997,7 +3875,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="root-not-found-cron-errors"> + <question xml:id="root-not-found-cron-errors"> <para>Why do I keep getting messages like <errorname>root: not found</errorname> after editing <filename>/etc/crontab</filename></para> @@ -4028,7 +3906,7 @@ C:\="DOS"</programlisting> <para>If you want something to be run once per day, week, or month, it is probably better to add shell scripts - <filename class="directory">/usr/local/etc/periodic</filename>, and let the + <filename>/usr/local/etc/periodic</filename>, and let the &man.periodic.8; command run from the system <command>cron</command> schedule it with the other periodic system tasks.</para> @@ -4036,8 +3914,8 @@ C:\="DOS"</programlisting> <para>The actual reason for the error is that the system crontab has an extra field, specifying which user to run the command as. In the default system crontab provided with - &os;, this is <username>root</username> for all entries. - When this crontab is used as the <username>root</username> + &os;, this is <systemitem class="username">root</systemitem> for all entries. + When this crontab is used as the <systemitem class="username">root</systemitem> user's crontab (which is <emphasis>not</emphasis> the same as the system crontab), &man.cron.8; assumes the string <literal>root</literal> is the first word of the command to @@ -4046,39 +3924,39 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="su-wheel-group"> + <question xml:id="su-wheel-group"> <para>Why do I get the error, <errorname>you are not in the correct group to su root</errorname> when I try to - <command>su</command> to <username>root</username>?</para> + <command>su</command> to <systemitem class="username">root</systemitem>?</para> </question> <answer> <para>This is a security feature. To - <command>su</command> to <username>root</username> (or any + <command>su</command> to <systemitem class="username">root</systemitem> (or any other account with superuser privileges), you must be in the - <groupname>wheel</groupname> group. If this feature were + <systemitem class="groupname">wheel</systemitem> group. If this feature were not there, anybody with an account on a system who also - found out <username>root</username>'s password would be able + found out <systemitem class="username">root</systemitem>'s password would be able to gain superuser level access to the system. With this feature, this is not strictly true; &man.su.1; will prevent them from even trying to enter the password if they are not - in <groupname>wheel</groupname>.</para> + in <systemitem class="groupname">wheel</systemitem>.</para> <para>To allow someone to <command>su</command> to - <username>root</username>, simply put them in the - <groupname>wheel</groupname> group. Use &man.pw.8; + <systemitem class="username">root</systemitem>, simply put them in the + <systemitem class="groupname">wheel</systemitem> group. Use &man.pw.8; for this purpose.</para> - <screen>&prompt.root; <userinput>pw groupmod wheel -m <replaceable>lisa</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw groupmod wheel -m lisa</userinput></screen> <para>The above example will add user - <username>lisa</username> to the group - <groupname>wheel</groupname>.</para> + <systemitem class="username">lisa</systemitem> to the group + <systemitem class="groupname">wheel</systemitem>.</para> </answer> </qandaentry> <qandaentry> - <question id="rcconf-readonly"> + <question xml:id="rcconf-readonly"> <para>I made a mistake in <filename>rc.conf</filename>, or another startup file, and now I cannot edit it because the file system is read-only. What should I do?</para> @@ -4115,13 +3993,12 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="printer-setup"> + <question xml:id="printer-setup"> <para>Why am I having trouble setting up my printer?</para> </question> <answer> - <para>See the <ulink - url="&url.books.handbook;/printing.html">Handbook entry on printing</ulink>. + <para>See the <link xlink:href="&url.books.handbook;/printing.html">Handbook entry on printing</link>. It should cover most of your problem.</para> <para>Some printers require a host-based driver to do any kind @@ -4129,27 +4006,25 @@ C:\="DOS"</programlisting> not natively supported by &os;. If your printer does not work in DOS or &windows;, it is probably a WinPrinter. Your only hope of getting one of these to work is to check if the - <filename role="package">print/pnm2ppa</filename> port + <package>print/pnm2ppa</package> port supports it.</para> </answer> </qandaentry> <qandaentry> - <question id="keyboard-mappings"> + <question xml:id="keyboard-mappings"> <para>How can I correct the keyboard mappings for my system?</para> </question> <answer> - <para>Please see the Handbook section on <ulink - url="&url.books.handbook;/using-localization.html">using localization</ulink>, - specifically the section on <ulink - url="&url.books.handbook;/using-localization.html#setting-console">console setup</ulink>.</para> + <para>Please see the Handbook section on <link xlink:href="&url.books.handbook;/using-localization.html">using localization</link>, + specifically the section on <link xlink:href="&url.books.handbook;/using-localization.html#setting-console">console setup</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="user-quotas"> + <question xml:id="user-quotas"> <para>Why can I not get user quotas to work properly?</para> </question> @@ -4163,14 +4038,13 @@ C:\="DOS"</programlisting> <programlisting>options QUOTA</programlisting> - <para>Please read the <ulink - url="&url.books.handbook;/quotas.html">Handbook entry on quotas</ulink> + <para>Please read the <link xlink:href="&url.books.handbook;/quotas.html">Handbook entry on quotas</link> for full details.</para> </listitem> <listitem> <para>Do not turn on quotas on - <filename class="directory">/</filename>.</para> + <filename>/</filename>.</para> </listitem> <listitem> @@ -4189,13 +4063,13 @@ C:\="DOS"</programlisting> <tbody> <row> - <entry><filename class="directory">/usr</filename></entry> + <entry><filename>/usr</filename></entry> <entry><filename>/usr/admin/quotas</filename></entry> </row> <row> - <entry><filename class="directory">/home</filename></entry> + <entry><filename>/home</filename></entry> <entry><filename>/home/admin/quotas</filename></entry> </row> @@ -4214,7 +4088,7 @@ C:\="DOS"</programlisting> </qandaentry> <qandaentry> - <question id="sysv-ipc"> + <question xml:id="sysv-ipc"> <para>Does &os; support System V IPC primitives?</para> </question> @@ -4237,23 +4111,20 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="sendmail-alternative"> + <question xml:id="sendmail-alternative"> <para>What other mail-server software can I use instead of <application>sendmail</application>?</para> </question> <answer> - <para>The <ulink - url="http://www.sendmail.org/"><application>sendmail</application></ulink> + <para>The <link xlink:href="http://www.sendmail.org/"><application>sendmail</application></link> server is the default mail-server software for &os;, but you can easily replace it with one of the other MTA (for instance, an MTA installed from the ports).</para> <para>There are various alternative MTAs in the ports tree - already, with <filename role="package">mail/exim</filename>, - <filename role="package">mail/postfix</filename>, <filename - role="package">mail/qmail</filename>, and <filename - role="package">mail/zmailer</filename> being some of the + already, with <package>mail/exim</package>, + <package>mail/postfix</package>, <package>mail/qmail</package>, and <package>mail/zmailer</package> being some of the most popular choices.</para> <para>Diversity is nice, and the fact that you have many @@ -4269,8 +4140,8 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="forgot-root-pw"> - <para>I have forgotten the <username>root</username> password! + <question xml:id="forgot-root-pw"> + <para>I have forgotten the <systemitem class="username">root</systemitem> password! What do I do?</para> </question> @@ -4284,12 +4155,12 @@ options SYSVMSG # enable for messaging</programlisting> to remount your root file system read/write, then run <command>mount -a</command> to remount all the file systems. Run <command>passwd root</command> to change the - <username>root</username> password then run &man.exit.1; to + <systemitem class="username">root</systemitem> password then run &man.exit.1; to continue booting.</para> <note> <para>If you are still prompted to give the - <username>root</username> password when entering the + <systemitem class="username">root</systemitem> password when entering the Single User mode, it means that the console has been marked as <literal>insecure</literal> in <filename>/etc/ttys</filename>. In this case it will be @@ -4309,16 +4180,14 @@ options SYSVMSG # enable for messaging</programlisting> encrypted and it is impossible to mount them without the access keys. Your chances depend on the chosen implementation. For more information see the section - about encrypted disks in the &os; <ulink - url="&url.books.handbook;/disks-encrypting.html">Handbook</ulink>.</para> + about encrypted disks in the &os; <link xlink:href="&url.books.handbook;/disks-encrypting.html">Handbook</link>.</para> </note> </answer> </qandaentry> <qandaentry> - <question id="CAD-reboot"> - <para>How do I keep <keycombo - action="simul"><keycap>Control</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo> + <question xml:id="CAD-reboot"> + <para>How do I keep <keycombo action="simul"><keycap>Control</keycap><keycap>Alt</keycap><keycap>Delete</keycap></keycombo> from rebooting the system?</para> </question> @@ -4344,14 +4213,14 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="dos-to-unix-txt"> + <question xml:id="dos-to-unix-txt"> <para>How do I reformat DOS text files to &unix; ones?</para> </question> <answer> <para>Use this &man.perl.1; command:</para> - <screen>&prompt.user; <userinput>perl -i.bak -npe 's/\r\n/\n/g' <replaceable>file(s)</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>perl -i.bak -npe 's/\r\n/\n/g' file(s)</userinput></screen> <para>where <replaceable>file(s)</replaceable> is one or more files to process. The modification is done in-place, with the @@ -4360,7 +4229,7 @@ options SYSVMSG # enable for messaging</programlisting> <para>Alternatively you can use the &man.tr.1; command:</para> - <screen>&prompt.user; <userinput>tr -d '\r' < <replaceable>dos-text-file</replaceable> > <replaceable>unix-file</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>tr -d '\r' < dos-text-file > unix-file</userinput></screen> <para><replaceable>dos-text-file</replaceable> is the file containing DOS text while @@ -4369,14 +4238,14 @@ options SYSVMSG # enable for messaging</programlisting> <command>perl</command>.</para> <para>Yet another way to reformat DOS text files is to use the - <filename role="package">converters/dosunix</filename> port + <package>converters/dosunix</package> port from the Ports Collection. Consult its documentation about the details.</para> </answer> </qandaentry> <qandaentry> - <question id="kill-by-name"> + <question xml:id="kill-by-name"> <para>How do I kill processes by name?</para> </question> @@ -4386,7 +4255,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="reread-rc"> + <question xml:id="reread-rc"> <para>How do I re-read <filename>/etc/rc.conf</filename> and re-start <filename>/etc/rc</filename> without a reboot?</para> @@ -4407,7 +4276,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="release-candidate"> + <question xml:id="release-candidate"> <para>I tried to update my system to the latest <emphasis>-STABLE</emphasis>, but got <emphasis>-BETA<replaceable>x</replaceable></emphasis>, @@ -4427,8 +4296,7 @@ options SYSVMSG # enable for messaging</programlisting> <para>Long answer: &os; derives its releases from one of two places. Major, dot-zero, releases, such as 9.0-RELEASE are branched from the head of the development - stream, commonly referred to as <link - linkend="current">-CURRENT</link>. Minor releases, such as + stream, commonly referred to as <link linkend="current">-CURRENT</link>. Minor releases, such as 6.3-RELEASE or 5.2-RELEASE, have been snapshots of the active <link linkend="stable">-STABLE</link> branch. Starting with 4.3-RELEASE, each release also now has its own @@ -4454,14 +4322,13 @@ options SYSVMSG # enable for messaging</programlisting> 6.3-STABLE.</para> <para>For more information on version numbers and the various - Subversion branches, refer to the <ulink - url="&url.articles.releng;/article.html">Release Engineering</ulink> + Subversion branches, refer to the <link xlink:href="&url.articles.releng;/article.html">Release Engineering</link> article.</para> </answer> </qandaentry> <qandaentry> - <question id="kernel-chflag-failure"> + <question xml:id="kernel-chflag-failure"> <para>I tried to install a new kernel, and the &man.chflags.1; failed. How do I get around this?</para> </question> @@ -4489,7 +4356,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="kernel-securelevel-time"> + <question xml:id="kernel-securelevel-time"> <para>I cannot change the time on my system by more than one second! How do I get around this?</para> </question> @@ -4517,7 +4384,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="statd-mem-leak"> + <question xml:id="statd-mem-leak"> <para>Why is <command>rpc.statd</command> using 256 MB of memory?</para> </question> @@ -4531,7 +4398,7 @@ options SYSVMSG # enable for messaging</programlisting> off things like &man.top.1; and &man.ps.1;.</para> <para>&man.rpc.statd.8; maps its status file (resident on - <filename class="directory">/var</filename>) into its address space; to save + <filename>/var</filename>) into its address space; to save worrying about remapping it later when it needs to grow, it maps it with a generous size. This is very evident from the source code, where one can see that the length argument to @@ -4542,7 +4409,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="unsetting-schg"> + <question xml:id="unsetting-schg"> <para>Why can I not unset the <literal>schg</literal> file flag?</para> </question> @@ -4557,7 +4424,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="ssh-shosts"> + <question xml:id="ssh-shosts"> <para>Why does <application>SSH</application> authentication through <filename>.shosts</filename> not work by default in recent versions of &os;?</para> @@ -4567,14 +4434,14 @@ options SYSVMSG # enable for messaging</programlisting> <para>The reason why <filename>.shosts</filename> authentication does not work by default in more recent versions of &os; is because &man.ssh.1; is not installed - suid <username>root</username> by default. To + suid <systemitem class="username">root</systemitem> by default. To <quote>fix</quote> this, you can do one of the following:</para> <itemizedlist> <listitem> <para>As a permanent fix, set - <makevar>ENABLE_SUID_SSH</makevar> to + <varname>ENABLE_SUID_SSH</varname> to <literal>true</literal> in <filename>/etc/make.conf</filename> then rebuild and reinstall &man.ssh.1;.</para> @@ -4585,14 +4452,14 @@ options SYSVMSG # enable for messaging</programlisting> <filename>/usr/bin/ssh</filename> to <literal>4555</literal> by running <command>chmod 4555 /usr/bin/ssh</command> as - <username>root</username>.</para> + <systemitem class="username">root</systemitem>.</para> </listitem> </itemizedlist> </answer> </qandaentry> <qandaentry> - <question id="vnlru"> + <question xml:id="vnlru"> <para>What is <literal>vnlru</literal>?</para> </question> @@ -4606,7 +4473,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="top-memory-states"> + <question xml:id="top-memory-states"> <para>What do the various memory states displayed by <command>top</command> mean?</para> </question> @@ -4674,7 +4541,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="free-memory-amount"> + <question xml:id="free-memory-amount"> <para>How much free memory is available?</para> </question> @@ -4697,16 +4564,16 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="var-empty"> - <para>What is <filename class="directory">/var/empty</filename>? I can not + <question xml:id="var-empty"> + <para>What is <filename>/var/empty</filename>? I can not delete it!</para> </question> <answer> - <para><filename class="directory">/var/empty</filename> is a directory that the + <para><filename>/var/empty</filename> is a directory that the &man.sshd.8; program uses when performing privilege separation. - The <filename class="directory">/var/empty</filename> directory is empty, owned by - <username>root</username> and has the <literal>schg</literal> + The <filename>/var/empty</filename> directory is empty, owned by + <systemitem class="username">root</systemitem> and has the <literal>schg</literal> flag set.</para> <para>Although it is not recommended to delete this directory, to @@ -4718,7 +4585,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="newsyslog-expectations"> + <question xml:id="newsyslog-expectations"> <para>I just changed <filename>/etc/newsyslog.conf</filename>. How can I check if it does what I expect?</para> @@ -4733,7 +4600,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="timezone"> + <question xml:id="timezone"> <para>My time is wrong, how can I change the timezone?</para> </question> @@ -4745,12 +4612,12 @@ options SYSVMSG # enable for messaging</programlisting> </qandaset> </chapter> - <chapter id="x"> + <chapter xml:id="x"> <title>The X Window System and Virtual Consoles</title> <qandaset> <qandaentry> - <question id="whatis-X"> + <question xml:id="whatis-X"> <para>What is the X Window System?</para> </question> @@ -4758,9 +4625,8 @@ options SYSVMSG # enable for messaging</programlisting> <para>The X Window System (commonly <literal>X11</literal>) is the most widely available windowing system capable of running on &unix; or &unix; like systems, including &os;. - <ulink url= "http://www.x.org/wiki/">The X.Org Foundation</ulink> - administers the <ulink - url="http://en.wikipedia.org/wiki/X_Window_System_core_protocol">X protocol standards</ulink>, + <link xlink:href="http://www.x.org/wiki/">The X.Org Foundation</link> + administers the <link xlink:href="http://en.wikipedia.org/wiki/X_Window_System_core_protocol">X protocol standards</link>, with the current reference implementation, version 11 release &xorg.version;, so you will often see references shortened to <literal>X11</literal>.</para> @@ -4773,19 +4639,18 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="running-X"> + <question xml:id="running-X"> <para>I want to run &xorg;, how do I go about it?</para> </question> <answer> <para>To install &xorg; do one of the following:</para> - <para>Use the <filename role="package">x11/xorg</filename> + <para>Use the <package>x11/xorg</package> meta-port, which builds and installs every &xorg; component.</para> - <para>Use <filename - role="package">x11/xorg-minimal</filename>, which builds + <para>Use <package>x11/xorg-minimal</package>, which builds and installs only the necessary &xorg; components.</para> <para>Install &xorg; from &os; packages:</para> @@ -4797,14 +4662,13 @@ options SYSVMSG # enable for messaging</programlisting> <screen><userinput>&prompt.root; pkg install xorg</userinput></screen> <para>After the installation of &xorg;, follow - the instructions from the <ulink - url="&url.books.handbook;/x-config.html">X11 Configuration</ulink> section of + the instructions from the <link xlink:href="&url.books.handbook;/x-config.html">X11 Configuration</link> section of the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="running-X-securelevels"> + <question xml:id="running-X-securelevels"> <para>I <emphasis>tried</emphasis> to run X, but I get a <errorname>No devices detected.</errorname> error when I type @@ -4832,7 +4696,7 @@ options SYSVMSG # enable for messaging</programlisting> </qandaentry> <qandaentry> - <question id="x-and-moused"> + <question xml:id="x-and-moused"> <para>Why does my mouse not work with X?</para> </question> @@ -4841,12 +4705,11 @@ options SYSVMSG # enable for messaging</programlisting> driver), you can configure &os; to support a mouse pointer on each virtual screen. To avoid conflicting with X, &man.syscons.4; supports a virtual device called - <devicename>/dev/sysmouse</devicename>. All mouse events + <filename>/dev/sysmouse</filename>. All mouse events received from the real mouse device are written to the &man.sysmouse.4; device via &man.moused.8;. To use your mouse on one or more virtual consoles, - <emphasis>and</emphasis> use X, see <xref - linkend="moused" remap="another section"/> and set up + <emphasis>and</emphasis> use X, see <xref linkend="moused" remap="another section"/> and set up &man.moused.8;.</para> <para>Then edit <filename>/etc/X11/xorg.conf</filename> and @@ -4867,9 +4730,9 @@ options SYSVMSG # enable for messaging</programlisting> <programlisting>Option "AutoAddDevices" "false"</programlisting> <para>Some people prefer to use - <devicename>/dev/mouse</devicename> under X. To make this - work, <devicename>/dev/mouse</devicename> should be linked - to <devicename>/dev/sysmouse</devicename> (see + <filename>/dev/mouse</filename> under X. To make this + work, <filename>/dev/mouse</filename> should be linked + to <filename>/dev/sysmouse</filename> (see &man.sysmouse.4;) by adding the following line to <filename>/etc/devfs.conf</filename> (see &man.devfs.conf.5;):</para> @@ -4878,14 +4741,14 @@ options SYSVMSG # enable for messaging</programlisting> <para>This link can be created by restarting &man.devfs.5; with the following command (as - <username>root</username>):</para> + <systemitem class="username">root</systemitem>):</para> <screen>&prompt.root; <userinput>service devfs restart</userinput></screen> </answer> </qandaentry> <qandaentry> - <question id="x-and-wheel"> + <question xml:id="x-and-wheel"> <para>My mouse has a fancy wheel. Can I use it in X?</para> </question> @@ -4926,7 +4789,7 @@ EndSection</programlisting> </qandaentry> <qandaentry> - <question id="x-and-synaptic"> + <question xml:id="x-and-synaptic"> <para>My laptop has a Synaptics touchpad. Can I use it in X?</para> </question> @@ -4965,7 +4828,7 @@ EndSection</programlisting> </qandaentry> <qandaentry> - <question id="no-remote-x11"> + <question xml:id="no-remote-x11"> <para>How do I use remote X displays?</para> </question> @@ -4982,7 +4845,7 @@ EndSection</programlisting> </qandaentry> <qandaentry> - <question id="virtual-console"> + <question xml:id="virtual-console"> <para>What is a virtual console and how do I make more?</para> </question> @@ -5000,28 +4863,23 @@ EndSection</programlisting> <para>At some point, you will probably wish to start another session, perhaps to look at documentation for a program you are running or to read your mail while waiting for an FTP - transfer to finish. Just do <keycombo - action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo> + transfer to finish. Just do <keycombo action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo> (hold down <keycap>Alt</keycap> and press <keycap>F2</keycap>), and you will find a login prompt waiting for you on the second <quote>virtual console</quote>! When you want to go back to the original - session, do <keycombo - action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo>.</para> + session, do <keycombo action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo>.</para> <para>The default &os; installation has eight virtual consoles - enabled. <keycombo - action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo>, - <keycombo - action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, - <keycombo - action="simul"><keycap>Alt</keycap><keycap>F3</keycap></keycombo>, + enabled. <keycombo action="simul"><keycap>Alt</keycap><keycap>F1</keycap></keycombo>, + <keycombo action="simul"><keycap>Alt</keycap><keycap>F2</keycap></keycombo>, + <keycombo action="simul"><keycap>Alt</keycap><keycap>F3</keycap></keycombo>, and so on will switch between these virtual consoles.</para> <para>To enable more of them, edit <filename>/etc/ttys</filename> (see &man.ttys.5;) and add - entries for <devicename>ttyv8</devicename> to - <devicename>ttyvc</devicename> after the comment on + entries for <filename>ttyv8</filename> to + <filename>ttyvc</filename> after the comment on <quote>Virtual terminals</quote>:</para> <programlisting># Edit the existing entry for ttyv8 in /etc/ttys and change @@ -5078,7 +4936,7 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> <para>Next, the easiest (and cleanest) way to activate the virtual consoles is to reboot. However, if you really do not want to reboot, you can just shut down the X Window - system and execute (as <username>root</username>):</para> + system and execute (as <systemitem class="username">root</systemitem>):</para> <screen>&prompt.root; <userinput>kill -HUP 1</userinput></screen> @@ -5090,20 +4948,17 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> </qandaentry> <qandaentry> - <question id="vty-from-x"> + <question xml:id="vty-from-x"> <para>How do I access the virtual consoles from X?</para> </question> <answer> - <para>Use <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F<replaceable>n</replaceable></keycap></keycombo> - to switch back to a virtual console. <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> + <para>Use <keycombo action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F<replaceable>n</replaceable></keycap></keycombo> + to switch back to a virtual console. <keycombo action="simul"><keycap>Ctrl</keycap><keycap>Alt</keycap><keycap>F1</keycap></keycombo> would return you to the first virtual console.</para> <para>Once you are back to a text console, you can then use - <keycombo - action="simul"><keycap>Alt</keycap><keycap>F<replaceable>n</replaceable></keycap></keycombo> + <keycombo action="simul"><keycap>Alt</keycap><keycap>F<replaceable>n</replaceable></keycap></keycombo> as normal to move between them.</para> <para>To return to the X session, you must switch to the @@ -5112,14 +4967,13 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> the X session will attach to the next unused virtual console, not the text console from which it was invoked. If you have eight active virtual terminals then X will be - running on the ninth, and you would use <keycombo - action="simul"><keycap>Alt</keycap><keycap>F9</keycap></keycombo> + running on the ninth, and you would use <keycombo action="simul"><keycap>Alt</keycap><keycap>F9</keycap></keycombo> to return.</para> </answer> </qandaentry> <qandaentry> - <question id="xdm-boot"> + <question xml:id="xdm-boot"> <para>How do I start <application>XDM</application> on boot?</para> </question> @@ -5132,7 +4986,7 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> <command>xdm</command> from <filename>rc.local</filename> (see &man.rc.8;) or from an <filename>X</filename> script in - <filename class="directory">/usr/local/etc/rc.d</filename>. Both are equally + <filename>/usr/local/etc/rc.d</filename>. Both are equally valid, and one may work in situations where the other does not. In both cases the result is the same: X will pop up a graphical login prompt.</para> @@ -5163,14 +5017,14 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> <programlisting>:0 local /usr/local/bin/X vt4</programlisting> <para>The above example will direct the X server to run in - <devicename>/dev/ttyv3</devicename>. Note the number is + <filename>/dev/ttyv3</filename>. Note the number is offset by one. The X server counts the vty from one, whereas the &os; kernel numbers the vty from zero.</para> </answer> </qandaentry> <qandaentry> - <question id="xconsole-failure"> + <question xml:id="xconsole-failure"> <para>Why do I get <errorname>Couldn't open console</errorname> when I run <command>xconsole</command>?</para> @@ -5179,7 +5033,7 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> <answer> <para>If you start <application>X</application> with <command>startx</command>, the permissions on - <devicename>/dev/console</devicename> will + <filename>/dev/console</filename> will <emphasis>not</emphasis> get changed, resulting in things like <command>xterm -C</command> and <command>xconsole</command> not working.</para> @@ -5198,13 +5052,13 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> <programlisting>/dev/ttyv0 0600 /dev/console</programlisting> <para>It will ensure that whomever logs in on - <devicename>/dev/ttyv0</devicename> will own the + <filename>/dev/ttyv0</filename> will own the console.</para> </answer> </qandaentry> <qandaentry> - <question id="ps2-x"> + <question xml:id="ps2-x"> <para>Why does my PS/2 mouse misbehave under X?</para> </question> @@ -5234,7 +5088,7 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> </qandaentry> <qandaentry> - <question id="mouse-button-reverse"> + <question xml:id="mouse-button-reverse"> <para>How do I reverse the mouse buttons?</para> </question> @@ -5249,21 +5103,20 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> </qandaentry> <qandaentry> - <question id="install-splash"> + <question xml:id="install-splash"> <para>How do I install a splash screen and where do I find them?</para> </question> <answer> <para>The detailed answer for this question can be found in - the <ulink - url="&url.books.handbook;/boot-blocks.html#boot-splash">Boot Time Splash Screens</ulink> + the <link xlink:href="&url.books.handbook;/boot-blocks.html#boot-splash">Boot Time Splash Screens</link> section of the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="windows-keys"> + <question xml:id="windows-keys"> <para>Can I use the <keycap>Windows</keycap> keys on my keyboard in X?</para> </question> @@ -5325,8 +5178,7 @@ ttyvb "/usr/libexec/getty Pc" xterm off secure</programlisting> keycode 116 = F14 keycode 117 = F15</programlisting> - <para>If you use the <filename - role="package">x11-wm/fvwm2</filename> port, for example, + <para>If you use the <package>x11-wm/fvwm2</package> port, for example, you could map the keys so that <keycap>F13</keycap> iconifies (or de-iconifies) the window the cursor is in, <keycap>F14</keycap> brings the window the cursor is in to @@ -5347,7 +5199,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="x-3d-acceleration"> + <question xml:id="x-3d-acceleration"> <para>How can I get 3D hardware acceleration for &opengl;?</para> </question> @@ -5362,34 +5214,31 @@ Key F15 A A Menu Workplace Nop</programlisting> <itemizedlist> <listitem> <para>The latest versions of nVidia cards are supported by - the <filename role="package">x11/nvidia-driver</filename> + the <package>x11/nvidia-driver</package> port.</para> </listitem> <listitem> <para>nVidia cards like the GeForce2 MX/3/4 series are supported by the 96XX series of drivers, available - in the <filename - role="package">x11/nvidia-driver-96xx</filename> + in the <package>x11/nvidia-driver-96xx</package> port.</para> </listitem> <listitem> <para>Even older cards, like GeForce and RIVA TNT are supported by the 71XX series of drivers, available in - the <filename - role="package">x11/nvidia-driver-71xx</filename> + the <package>x11/nvidia-driver-71xx</package> port.</para> </listitem> </itemizedlist> <para>nVidia provides detailed information on which card is supported by which driver - on their web site: <ulink - url="http://www.nvidia.com/object/IO_32667.html"></ulink>.</para> + on their web site: <uri xlink:href="http://www.nvidia.com/object/IO_32667.html">http://www.nvidia.com/object/IO_32667.html</uri>.</para> <para>For Matrox G200/G400, check the - <filename role="package">x11-servers/mga_hal</filename> + <package>x11-servers/mga_hal</package> port.</para> <para>For ATI Rage 128 and Radeon see @@ -5399,12 +5248,12 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaset> </chapter> - <chapter id="networking"> + <chapter xml:id="networking"> <title>Networking</title> <qandaset> <qandaentry> - <question id="diskless-booting"> + <question xml:id="diskless-booting"> <para>Where can I get information on <quote>diskless booting</quote>?</para> </question> @@ -5413,27 +5262,24 @@ Key F15 A A Menu Workplace Nop</programlisting> <para><quote>Diskless booting</quote> means that the &os; box is booted over a network, and reads the necessary files from a server instead of its hard disk. For full - details, please read <ulink - url="&url.books.handbook;/network-diskless.html">the Handbook entry on diskless booting</ulink>.</para> + details, please read <link xlink:href="&url.books.handbook;/network-diskless.html">the Handbook entry on diskless booting</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="router"> + <question xml:id="router"> <para>Can a &os; box be used as a dedicated network router?</para> </question> <answer> - <para>Yes. Please see the Handbook entry on <ulink - url="&url.books.handbook;/advanced-networking.html">advanced networking</ulink>, - specifically the section on <ulink - url="&url.books.handbook;/network-routing.html">routing and gateways</ulink>.</para> + <para>Yes. Please see the Handbook entry on <link xlink:href="&url.books.handbook;/advanced-networking.html">advanced networking</link>, + specifically the section on <link xlink:href="&url.books.handbook;/network-routing.html">routing and gateways</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="win95-connection"> + <question xml:id="win95-connection"> <para>Can I connect my &windows; box to the Internet via &os;?</para> </question> @@ -5454,19 +5300,17 @@ Key F15 A A Menu Workplace Nop</programlisting> <filename>/etc/rc.conf</filename>. For more information, please see the &man.ppp.8; manual page or - the <ulink - url="&url.books.handbook;/userppp.html">Handbook entry on user PPP</ulink>.</para> + the <link xlink:href="&url.books.handbook;/userppp.html">Handbook entry on user PPP</link>.</para> <para>If you are using kernel-mode PPP or have an Ethernet connection to the Internet, you need to use &man.natd.8;. - Please look at the <ulink - url="&url.books.handbook;/network-natd.html">natd</ulink> + Please look at the <link xlink:href="&url.books.handbook;/network-natd.html">natd</link> section of the Handbook for a tutorial.</para> </answer> </qandaentry> <qandaentry> - <question id="slip-ppp-support"> + <question xml:id="slip-ppp-support"> <para>Does &os; support PPP?</para> </question> @@ -5475,29 +5319,26 @@ Key F15 A A Menu Workplace Nop</programlisting> incoming and outgoing connections.</para> <para>For more information on how to use this, please see the - <ulink - url="&url.books.handbook;/ppp-and-slip.html">Handbook chapter on PPP</ulink>.</para> + <link xlink:href="&url.books.handbook;/ppp-and-slip.html">Handbook chapter on PPP</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="natd"> + <question xml:id="natd"> <para>Does &os; support NAT or Masquerading?</para> </question> <answer> <para>Yes. If you want to use NAT over a user PPP connection, - please see the <ulink - url="&url.books.handbook;/userppp.html">Handbook entry on user PPP</ulink>. + please see the <link xlink:href="&url.books.handbook;/userppp.html">Handbook entry on user PPP</link>. If you want to use NAT over some other sort of network - connection, please look at the <ulink - url="&url.books.handbook;/network-natd.html">natd</ulink> + connection, please look at the <link xlink:href="&url.books.handbook;/network-natd.html">natd</link> section of the Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="ethernet-aliases"> + <question xml:id="ethernet-aliases"> <para>How can I set up Ethernet aliases?</para> </question> @@ -5507,20 +5348,19 @@ Key F15 A A Menu Workplace Nop</programlisting> 0xffffffff</literal> to your &man.ifconfig.8; command-line, as in the following:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>ed0</replaceable> alias <replaceable>192.0.2.2</replaceable> netmask 0xffffffff</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig ed0 alias 192.0.2.2 netmask 0xffffffff</userinput></screen> <para>Otherwise, just specify the network address and netmask as usual:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>ed0</replaceable> alias <replaceable>172.16.141.5</replaceable> netmask 0xffffff00</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig ed0 alias 172.16.141.5 netmask 0xffffff00</userinput></screen> - <para>You can read more about this in the &os; <ulink - url="&url.books.handbook;/configtuning-virtual-hosts.html">Handbook</ulink>.</para> + <para>You can read more about this in the &os; <link xlink:href="&url.books.handbook;/configtuning-virtual-hosts.html">Handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="nfs-linux"> + <question xml:id="nfs-linux"> <para>Why can I not NFS-mount from a &linux; box?</para> </question> @@ -5529,12 +5369,12 @@ Key F15 A A Menu Workplace Nop</programlisting> requests from a privileged port; try to issue the following command:</para> - <screen>&prompt.root; <userinput>mount -o -P <replaceable>linuxbox:/blah</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mount -o -P linuxbox:/blah /mnt</userinput></screen> </answer> </qandaentry> <qandaentry> - <question id="exports-errors"> + <question xml:id="exports-errors"> <para>Why does <command>mountd</command> keep telling me it <errorname>can't change attributes</errorname> and that I have a <errorname>bad exports list</errorname> on my &os; @@ -5544,15 +5384,13 @@ Key F15 A A Menu Workplace Nop</programlisting> <answer> <para>The most frequent problem is not understanding the correct format of <filename>/etc/exports</filename>. Please - review &man.exports.5; and the <ulink - url="&url.books.handbook;/network-nfs.html">NFS</ulink> - entry in the Handbook, especially the section on <ulink - url="&url.books.handbook;/network-nfs.html#configuring-nfs">configuring NFS</ulink>.</para> + review &man.exports.5; and the <link xlink:href="&url.books.handbook;/network-nfs.html">NFS</link> + entry in the Handbook, especially the section on <link xlink:href="&url.books.handbook;/network-nfs.html#configuring-nfs">configuring NFS</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="ip-multicast"> + <question xml:id="ip-multicast"> <para>How do I enable IP multicast support?</para> </question> @@ -5571,25 +5409,24 @@ Key F15 A A Menu Workplace Nop</programlisting> routing daemon, the &man.map-mbone.8; and &man.mrinfo.8; utilities have been removed from the base system. These programs are now available in the &os; Ports Collection as - <filename role="package">net/mrouted</filename>.</para> + <package>net/mrouted</package>.</para> </note> </answer> </qandaentry> <qandaentry> - <question id="fqdn-hosts"> + <question xml:id="fqdn-hosts"> <para>Why do I have to use the FQDN for hosts on my site?</para> </question> <answer> - <para>See the answer in the &os; <ulink - url="&url.books.handbook;/mail-trouble.html">Handbook</ulink>.</para> + <para>See the answer in the &os; <link xlink:href="&url.books.handbook;/mail-trouble.html">Handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="network-permission-denied"> + <question xml:id="network-permission-denied"> <para>Why do I get an error, <errorname>Permission denied</errorname>, for all networking operations?</para> </question> @@ -5603,7 +5440,7 @@ Key F15 A A Menu Workplace Nop</programlisting> <para>If you had unintentionally misconfigured your system for firewalling, you can restore network operability by typing the following while logged in as - <username>root</username>:</para> + <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>ipfw add 65534 allow all from any to any</userinput></screen> @@ -5611,13 +5448,12 @@ Key F15 A A Menu Workplace Nop</programlisting> in <filename>/etc/rc.conf</filename>.</para> <para>For further information on configuring a &os; firewall, - see the <ulink - url="&url.books.handbook;/firewalls.html">Handbook chapter</ulink>.</para> + see the <link xlink:href="&url.books.handbook;/firewalls.html">Handbook chapter</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="ipfw-fwd"> + <question xml:id="ipfw-fwd"> <para>Why is my <command>ipfw</command> <quote>fwd</quote> rule to redirect a service to another machine not working?</para> @@ -5645,24 +5481,22 @@ Key F15 A A Menu Workplace Nop</programlisting> <quote>fwd</quote> rule does not often work the way the user expects. This behavior is a feature and not a bug.</para> - <para>See the <link - linkend="service-redirect">FAQ about redirecting services</link>, + <para>See the <link linkend="service-redirect">FAQ about redirecting services</link>, the &man.natd.8; manual, or one of the several port - redirecting utilities in the <ulink - url="&url.base;/ports/index.html">Ports Collection</ulink> + redirecting utilities in the <link xlink:href="&url.base;/ports/index.html">Ports Collection</link> for a correct way to do this.</para> </answer> </qandaentry> <qandaentry> - <question id="service-redirect"> + <question xml:id="service-redirect"> <para>How can I redirect service requests from one machine to another?</para> </question> <answer> <para>You can redirect FTP (and other service) request with - the <filename role="package">sysutils/socket</filename> + the <package>sysutils/socket</package> port. Simply replace the service's command line to call <command>socket</command> instead, like so:</para> @@ -5675,24 +5509,22 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="bandwidth-mgr-tool"> + <question xml:id="bandwidth-mgr-tool"> <para>Where can I get a bandwidth management tool?</para> </question> <answer> <para>There are three bandwidth management tools available for &os;. &man.dummynet.4; is integrated into &os; as part of - &man.ipfw.4;. <ulink - url="http://www.sonycsl.co.jp/person/kjc/programs.html">ALTQ</ulink> + &man.ipfw.4;. <link xlink:href="http://www.sonycsl.co.jp/person/kjc/programs.html">ALTQ</link> has been integrated into &os; as part of &man.pf.4;. - Bandwidth Manager from <ulink - url="http://www.etinc.com/">Emerging Technologies</ulink> + Bandwidth Manager from <link xlink:href="http://www.etinc.com/">Emerging Technologies</link> is a commercial product.</para> </answer> </qandaentry> <qandaentry> - <question id="bpf-not-configured"> + <question xml:id="bpf-not-configured"> <para>Why do I get <errorname>/dev/bpf0: device not configured</errorname>?</para> </question> @@ -5708,7 +5540,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="mount-smb-share"> + <question xml:id="mount-smb-share"> <para>How do I mount a disk from a &windows; machine that is on my network, like smbmount in &linux;?</para> </question> @@ -5722,7 +5554,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="icmp-response-bw-limit"> + <question xml:id="icmp-response-bw-limit"> <para>What are these messages about: <errorname>Limiting icmp/open port/closed port response</errorname> in my log files?</para> @@ -5779,7 +5611,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="unknown-hw-addr-format"> + <question xml:id="unknown-hw-addr-format"> <para>What are these <errorname>arp: unknown hardware address format</errorname> error messages?</para> </question> @@ -5796,7 +5628,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="arp-wrong-iface"> + <question xml:id="arp-wrong-iface"> <para>Why do I keep seeing messages like: <errorname>192.168.0.10 is on fxp1 but got reply from 00:15:17:67:cf:82 on rl0</errorname>, and how do I disable it?</para> @@ -5812,12 +5644,12 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaset> </chapter> - <chapter id="security"> + <chapter xml:id="security"> <title>Security</title> <qandaset> <qandaentry> - <question id="sandbox"> + <question xml:id="sandbox"> <para>What is a sandbox?</para> </question> <answer> @@ -5844,9 +5676,9 @@ Key F15 A A Menu Workplace Nop</programlisting> <para>Take the <literal>ntalk</literal> service, for example (see &man.inetd.8;). This service used to run - as user ID <username>root</username>. Now it runs - as user ID <username>tty</username>. The - <username>tty</username> user is a sandbox designed to + as user ID <systemitem class="username">root</systemitem>. Now it runs + as user ID <systemitem class="username">tty</systemitem>. The + <systemitem class="username">tty</systemitem> user is a sandbox designed to make it more difficult for someone who has successfully hacked into the system via <literal>ntalk</literal> from being able to hack beyond that user ID.</para> @@ -5862,10 +5694,8 @@ Key F15 A A Menu Workplace Nop</programlisting> <para>The most common way to accomplish this is to build a simulated environment in a subdirectory and then run the - processes in that directory chrooted (i.e., <filename - class="directory">/</filename> for that process is this - directory, not the real <filename - class="directory">/</filename> of the system).</para> + processes in that directory chrooted (i.e., <filename>/</filename> for that process is this + directory, not the real <filename>/</filename> of the system).</para> <para>Another common use is to mount an underlying file system read-only and then create a file system layer on @@ -5889,7 +5719,7 @@ Key F15 A A Menu Workplace Nop</programlisting> address space of another.</para> <para>A &unix; process is owned by a particular userid. If - the user ID is not the <username>root</username> user, + the user ID is not the <systemitem class="username">root</systemitem> user, it serves to firewall the process off from processes owned by other users. The user ID is also used to firewall off on-disk data.</para> @@ -5897,7 +5727,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="securelevel"> + <question xml:id="securelevel"> <para>What is securelevel?</para> </question> @@ -5906,7 +5736,7 @@ Key F15 A A Menu Workplace Nop</programlisting> mechanism implemented in the kernel. When the securelevel is positive, the kernel restricts certain tasks; not even the superuser - (i.e., <username>root</username>) is allowed to do them. + (i.e., <systemitem class="username">root</systemitem>) is allowed to do them. The securelevel mechanism limits the ability to:</para> <itemizedlist> @@ -5918,8 +5748,8 @@ Key F15 A A Menu Workplace Nop</programlisting> <listitem> <para>Write to kernel memory via - <devicename>/dev/mem</devicename> and - <devicename>/dev/kmem</devicename>.</para> + <filename>/dev/mem</filename> and + <filename>/dev/kmem</filename>.</para> </listitem> <listitem> @@ -5944,7 +5774,7 @@ Key F15 A A Menu Workplace Nop</programlisting> <para>The securelevel of a running system can not be lowered as this would defeat its purpose. If you need to do a task that requires that the securelevel be - non-positive (e.g., an <maketarget>installworld</maketarget> + non-positive (e.g., an <buildtarget>installworld</buildtarget> or changing the date), you will have to change the securelevel setting in <filename>/etc/rc.conf</filename> (you want to look for the @@ -5977,8 +5807,7 @@ Key F15 A A Menu Workplace Nop</programlisting> <para>This point and others are often discussed on the mailing lists, particularly the &a.security;. Please - search the archives <ulink - url="&url.base;/search/index.html">here</ulink> for an + search the archives <link xlink:href="&url.base;/search/index.html">here</link> for an extensive discussion. A more fine-grained mechanism is preferred.</para> </warning> @@ -5986,7 +5815,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="extra-named-port"> + <question xml:id="extra-named-port"> <para>BIND (<command>named</command>) is listening on some high-numbered ports. What is going on?</para> </question> @@ -6019,7 +5848,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="sendmail-port-587"> + <question xml:id="sendmail-port-587"> <para>The <application>sendmail</application> daemon is listening on port 587 as well as the standard port 25! What is going on?</para> @@ -6034,59 +5863,58 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="toor-account"> - <para>What is this UID 0 <username>toor</username> account? + <question xml:id="toor-account"> + <para>What is this UID 0 <systemitem class="username">toor</systemitem> account? Have I been compromised?</para> </question> <answer> - <para>Do not worry. <username>toor</username> is an + <para>Do not worry. <systemitem class="username">toor</systemitem> is an <quote>alternative</quote> superuser account (toor is root spelt backwards). Previously it was created when the &man.bash.1; shell was installed but now it is created by default. It is intended to be used with a non-standard shell so you do not have to change - <username>root</username>'s default shell. This is + <systemitem class="username">root</systemitem>'s default shell. This is important as shells which are not part of the base distribution (for example a shell installed from ports or packages) are likely to be installed in - <filename class="directory">/usr/local/bin</filename> which, by default, + <filename>/usr/local/bin</filename> which, by default, resides on a different file system. If - <username>root</username>'s shell is located in - <filename class="directory">/usr/local/bin</filename> and - <filename class="directory">/usr</filename> (or whatever file system contains - <filename class="directory">/usr/local/bin</filename>) is not mounted for some - reason, <username>root</username> will not be able to log in + <systemitem class="username">root</systemitem>'s shell is located in + <filename>/usr/local/bin</filename> and + <filename>/usr</filename> (or whatever file system contains + <filename>/usr/local/bin</filename>) is not mounted for some + reason, <systemitem class="username">root</systemitem> will not be able to log in to fix a problem (although if you reboot into single user mode you will be prompted for the path to a shell).</para> - <para>Some people use <username>toor</username> for day-to-day - <username>root</username> tasks with a non-standard shell, - leaving <username>root</username>, with a standard shell, + <para>Some people use <systemitem class="username">toor</systemitem> for day-to-day + <systemitem class="username">root</systemitem> tasks with a non-standard shell, + leaving <systemitem class="username">root</systemitem>, with a standard shell, for single user mode or emergencies. By default you cannot - log in using <username>toor</username> as it does not have a - password, so log in as <username>root</username> and set a - password for <username>toor</username> if you want to use + log in using <systemitem class="username">toor</systemitem> as it does not have a + password, so log in as <systemitem class="username">root</systemitem> and set a + password for <systemitem class="username">toor</systemitem> if you want to use it.</para> </answer> </qandaentry> </qandaset> </chapter> - <chapter id="ppp"> + <chapter xml:id="ppp"> <title>PPP</title> <qandaset> <qandaentry> - <question id="userppp"> + <question xml:id="userppp"> <para>I cannot make &man.ppp.8; work. What am I doing wrong?</para> </question> <answer> <para>You should first read the &man.ppp.8; manual page and - the <ulink - url="&url.books.handbook;/ppp-and-slip.html#userppp">PPP section of the handbook</ulink>. + the <link xlink:href="&url.books.handbook;/ppp-and-slip.html#userppp">PPP section of the handbook</link>. Enable logging with the following command:</para> <programlisting>set log Phase Chat Connect Carrier lcp ipcp ccp command</programlisting> @@ -6111,7 +5939,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="ppp-hangs"> + <question xml:id="ppp-hangs"> <para>Why does &man.ppp.8; hang when I run it?</para> </question> @@ -6124,7 +5952,7 @@ Key F15 A A Menu Workplace Nop</programlisting> <literal>hosts</literal> line first. Then, simply put an entry in <filename>/etc/hosts</filename> for your local machine. If you have no local network, change your - <hostid>localhost</hostid> line:</para> + <systemitem>localhost</systemitem> line:</para> <programlisting>127.0.0.1 foo.example.com foo localhost</programlisting> @@ -6138,7 +5966,7 @@ Key F15 A A Menu Workplace Nop</programlisting> </qandaentry> <qandaentry> - <question id="ppp-nodial-auto"> + <question xml:id="ppp-nodial-auto"> <para>Why will &man.ppp.8; not dial in <literal>-auto</literal> mode?</para> </question> @@ -6168,14 +5996,13 @@ default 10.0.0.2 UGSc 0 0 tun0 <programlisting>delete ALL</programlisting> - <para>If this is the case, go back to the <ulink - url="&url.books.handbook;/userppp.html#userppp-final">Final System Configuration</ulink> + <para>If this is the case, go back to the <link xlink:href="&url.books.handbook;/userppp.html#userppp-final">Final System Configuration</link> section of the handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="no-route-to-host"> + <question xml:id="no-route-to-host"> <para>What does <errorname>No route to host</errorname> mean?</para> </question> @@ -6198,14 +6025,13 @@ default 10.0.0.2 UGSc 0 0 tun0 <programlisting>delete ALL add 0 0 HISADDR</programlisting> - <para>Refer to the <ulink - url="&url.books.handbook;/userppp.html#userppp-dynamicip">PPP and Dynamic IP addresses</ulink> + <para>Refer to the <link xlink:href="&url.books.handbook;/userppp.html#userppp-dynamicip">PPP and Dynamic IP addresses</link> section of the handbook for further details.</para> </answer> </qandaentry> <qandaentry> - <question id="connection-threeminutedrop"> + <question xml:id="connection-threeminutedrop"> <para>Why does my connection drop after about 3 minutes?</para> </question> @@ -6230,7 +6056,7 @@ add 0 0 HISADDR</programlisting> </qandaentry> <qandaentry> - <question id="ppp-drop-heavy-load"> + <question xml:id="ppp-drop-heavy-load"> <para>Why does my connection drop under heavy load?</para> </question> @@ -6247,7 +6073,7 @@ add 0 0 HISADDR</programlisting> </qandaentry> <qandaentry> - <question id="ppp-drop-random"> + <question xml:id="ppp-drop-random"> <para>Why does my connection drop after a random amount of time?</para> </question> @@ -6264,7 +6090,7 @@ add 0 0 HISADDR</programlisting> </qandaentry> <qandaentry> - <question id="ppp-hangs-random"> + <question xml:id="ppp-hangs-random"> <para>Why does my connection hang after a random amount of time?</para> </question> @@ -6299,20 +6125,18 @@ add 0 0 HISADDR</programlisting> <itemizedlist> <listitem> - <para>If the problem is remote, read on entry <xref - linkend="ppp-remote-not-responding"/>.</para> + <para>If the problem is remote, read on entry <xref linkend="ppp-remote-not-responding"/>.</para> </listitem> <listitem> - <para>If the problem is local, read on entry <xref - linkend="ppp-hung"/>.</para> + <para>If the problem is local, read on entry <xref linkend="ppp-hung"/>.</para> </listitem> </itemizedlist> </answer> </qandaentry> <qandaentry> - <question id="ppp-remote-not-responding"> + <question xml:id="ppp-remote-not-responding"> <para>The remote end is not responding. What can I do?</para> </question> @@ -6354,7 +6178,7 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> </qandaentry> <qandaentry> - <question id="ppp-hung"> + <question xml:id="ppp-hung"> <para>&man.ppp.8; has hung. What can I do?</para> </question> @@ -6388,7 +6212,7 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> </qandaentry> <qandaentry> - <question id="ppp-same-magic"> + <question xml:id="ppp-same-magic"> <para>I keep seeing errors about magic being the same. What does it mean?</para> </question> @@ -6455,7 +6279,7 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> </qandaentry> <qandaentry> - <question id="ppp-lcp-constant"> + <question xml:id="ppp-lcp-constant"> <para>LCP negotiations continue until the connection is closed. What is wrong?</para> </question> @@ -6468,32 +6292,32 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> other side, the other side will send two additional LCP configuration requests. This is fatal.</para> - <para>Consider two implementations, <hostid>A</hostid> and - <hostid>B</hostid>. <hostid>A</hostid> starts sending LCP - requests immediately after connecting and <hostid>B</hostid> - takes 7 seconds to start. When <hostid>B</hostid> starts, - <hostid>A</hostid> has sent 3 LCP REQs. We are assuming the + <para>Consider two implementations, <systemitem>A</systemitem> and + <systemitem>B</systemitem>. <systemitem>A</systemitem> starts sending LCP + requests immediately after connecting and <systemitem>B</systemitem> + takes 7 seconds to start. When <systemitem>B</systemitem> starts, + <systemitem>A</systemitem> has sent 3 LCP REQs. We are assuming the line has ECHO switched off, otherwise we would see magic number problems as described in the previous section. - <hostid>B</hostid> sends a REQ, then an ACK to the first of - <hostid>A</hostid>'s REQs. This results in - <hostid>A</hostid> entering the <acronym>OPENED</acronym> + <systemitem>B</systemitem> sends a REQ, then an ACK to the first of + <systemitem>A</systemitem>'s REQs. This results in + <systemitem>A</systemitem> entering the <acronym>OPENED</acronym> state and sending and ACK (the first) back to - <hostid>B</hostid>. In the meantime, <hostid>B</hostid> + <systemitem>B</systemitem>. In the meantime, <systemitem>B</systemitem> sends back two more ACKs in response to the two additional - REQs sent by <hostid>A</hostid> before <hostid>B</hostid> - started up. <hostid>B</hostid> then receives the first ACK - from <hostid>A</hostid> and enters the - <acronym>OPENED</acronym> state. <hostid>A</hostid> - receives the second ACK from <hostid>B</hostid> and goes + REQs sent by <systemitem>A</systemitem> before <systemitem>B</systemitem> + started up. <systemitem>B</systemitem> then receives the first ACK + from <systemitem>A</systemitem> and enters the + <acronym>OPENED</acronym> state. <systemitem>A</systemitem> + receives the second ACK from <systemitem>B</systemitem> and goes back to the <acronym>REQ-SENT</acronym> state, sending another (forth) REQ as per the RFC. It then receives the third ACK and enters the <acronym>OPENED</acronym> state. - In the meantime, <hostid>B</hostid> receives the forth REQ - from <hostid>A</hostid>, resulting in it reverting to the + In the meantime, <systemitem>B</systemitem> receives the forth REQ + from <systemitem>A</systemitem>, resulting in it reverting to the <acronym>ACK-SENT</acronym> state and sending another (second) REQ and (forth) ACK as per the RFC. - <hostid>A</hostid> gets the REQ, goes into + <systemitem>A</systemitem> gets the REQ, goes into <acronym>REQ-SENT</acronym> and sends another REQ. It immediately receives the following ACK and enters <acronym>OPENED</acronym>.</para> @@ -6525,7 +6349,7 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> </qandaentry> <qandaentry> - <question id="ppp-shell-test-lockup"> + <question xml:id="ppp-shell-test-lockup"> <para>Why does &man.ppp.8; lock up when I shell out to test it?</para> </question> @@ -6549,7 +6373,7 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> </qandaentry> <qandaentry> - <question id="ppp-null-modem"> + <question xml:id="ppp-null-modem"> <para>Why does &man.ppp.8; over a null-modem cable never exit?</para> </question> @@ -6569,7 +6393,7 @@ deny pred1 deflate deflate24 protocomp acfcomp shortseq vj</programlisting> </qandaentry> <qandaentry> - <question id="ppp-auto-noreasondial"> + <question xml:id="ppp-auto-noreasondial"> <para>Why does &man.ppp.8; dial for no reason in <option>-auto</option> mode?</para> </question> @@ -6608,8 +6432,7 @@ set dfilter 3 permit 0/0 0/0</programlisting> &man.sendmail.8; is the culprit. You should make sure that you tell <application>sendmail</application> not to do any DNS lookups in its configuration file. See the section on - <ulink - url="&url.books.handbook;/smtp-dialup.html">using email with a dialup connection</ulink> + <link xlink:href="&url.books.handbook;/smtp-dialup.html">using email with a dialup connection</link> in the &os; Handbook for details on how to create your own configuration file and what should go into it. You may also want to add the following line to @@ -6621,13 +6444,13 @@ set dfilter 3 permit 0/0 0/0</programlisting> everything until the queue is run (usually, sendmail is run with <option>-bd -q30m</option>, telling it to run the queue every 30 minutes) or until a <command>sendmail - <option>-q</option></command> is done (perhaps from your + -q</command> is done (perhaps from your <filename>ppp.linkup</filename>).</para> </answer> </qandaentry> <qandaentry> - <question id="ccp-errors"> + <question xml:id="ccp-errors"> <para>What do these CCP errors mean?</para> </question> @@ -6649,7 +6472,7 @@ CCP: Received Terminate Ack (1) state = Req-Sent (6)</programlisting> </qandaentry> <qandaentry> - <question id="ppp-connectionspeed"> + <question xml:id="ppp-connectionspeed"> <para>Why does &man.ppp.8; not log my connection speed?</para> </question> @@ -6681,7 +6504,7 @@ CCP: Received Terminate Ack (1) state = Req-Sent (6)</programlisting> </qandaentry> <qandaentry> - <question id="ppp-ignores-backslash"> + <question xml:id="ppp-ignores-backslash"> <para>Why does &man.ppp.8; ignore the <literal>\</literal> character in my chat script?</para> </question> @@ -6729,7 +6552,7 @@ ATDT1234567</programlisting> </qandaentry> <qandaentry> - <question id="ppp-segfault-nocore"> + <question xml:id="ppp-segfault-nocore"> <para>Why does &man.ppp.8; get a <errorname>Segmentation fault</errorname>, but I see no <filename>ppp.core</filename></para> @@ -6748,13 +6571,13 @@ ATDT1234567</programlisting> section), then you should install the system sources and do the following:</para> - <screen>&prompt.root; <userinput><command>cd</command> <filename class="directory">/usr/src/usr.sbin/ppp</filename></userinput> -&prompt.root; <userinput><command>echo</command> <makevar>STRIP</makevar>= >> <filename>/etc/make.conf</filename></userinput> -&prompt.root; <userinput><command>echo</command> <makevar>CFLAGS</makevar>+=<option>-g</option> >> <filename>/etc/make.conf</filename></userinput> -&prompt.root; <userinput><command>make</command> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen> + <screen>&prompt.root; <userinput>cd /usr/src/usr.sbin/ppp</userinput> +&prompt.root; <userinput>echo STRIP= >> /etc/make.conf</userinput> +&prompt.root; <userinput>echo CFLAGS+=-g >> /etc/make.conf</userinput> +&prompt.root; <userinput>make install clean</userinput></screen> <para>You will now have a debuggable version of &man.ppp.8; - installed. You will have to be <username>root</username> to + installed. You will have to be <systemitem class="username">root</systemitem> to run &man.ppp.8; as all of its privileges have been revoked. When you start &man.ppp.8;, take a careful note of what your current directory was at the time.</para> @@ -6786,7 +6609,7 @@ ATDT1234567</programlisting> </qandaentry> <qandaentry> - <question id="ppp-autodialprocess-noconnect"> + <question xml:id="ppp-autodialprocess-noconnect"> <para>Why does the process that forces a dial in <option>-auto</option> mode never connect?</para> </question> @@ -6839,12 +6662,11 @@ ATDT1234567</programlisting> <para>Yet another possibility is to allow an interface to be brought up without an IP number. Outgoing packets would be - given an IP number of <hostid - role="ipaddr">255.255.255.255</hostid> up until the first + given an IP number of <systemitem class="ipaddress">255.255.255.255</systemitem> up until the first <literal>SIOCAIFADDR</literal> &man.ioctl.2; is done. This would result in fully binding the socket. It would be up to &man.ppp.8; to change the source IP number, but only if it - is set to <hostid role="ipaddr">255.255.255.255</hostid>, + is set to <systemitem class="ipaddress">255.255.255.255</systemitem>, and only the IP number and IP checksum would need to change. This, however is a bit of a hack as the kernel would be sending bad packets to an improperly configured interface, @@ -6854,7 +6676,7 @@ ATDT1234567</programlisting> </qandaentry> <qandaentry> - <question id="ppp-nat-games"> + <question xml:id="ppp-nat-games"> <para>Why do most games not work with the <option>-nat</option> switch?</para> </question> @@ -6939,7 +6761,7 @@ ATDT1234567</programlisting> </qandaentry> <qandaentry> - <question id="fcs-errors"> + <question xml:id="fcs-errors"> <para>What are FCS errors?</para> </question> @@ -6988,7 +6810,7 @@ ATDT1234567</programlisting> </qandaentry> <qandaentry> - <question id="desperation"> + <question xml:id="desperation"> <para>None of this helps — I am desperate! What can I do?</para> </question> @@ -7006,23 +6828,21 @@ ATDT1234567</programlisting> </qandaset> </chapter> - <chapter id="serial"> + <chapter xml:id="serial"> <title>Serial Communications</title> <para>This section answers common questions about serial - communications with &os;. PPP is covered in the <link - linkend="networking">Networking</link> section.</para> + communications with &os;. PPP is covered in the <link linkend="networking">Networking</link> section.</para> <qandaset> <qandaentry> - <question id="multiport-serial-support"> + <question xml:id="multiport-serial-support"> <para>Which multi-port serial cards are supported by &os;?</para> </question> <answer> - <para>There is a list of these in the <ulink - url="&url.books.handbook;/serial.html">Serial Communications</ulink> + <para>There is a list of these in the <link xlink:href="&url.books.handbook;/serial.html">Serial Communications</link> chapter of the handbook.</para> <para>Most multi-port PCI cards that are based on 16550 or @@ -7037,19 +6857,18 @@ ATDT1234567</programlisting> </qandaentry> <qandaentry> - <question id="serial-console-prompt"> + <question xml:id="serial-console-prompt"> <para>How do I get the boot: prompt to show on the serial console?</para> </question> <answer> - <para>See <ulink - url="&url.books.handbook;/serialconsole-setup.html">this section of the handbook</ulink>.</para> + <para>See <link xlink:href="&url.books.handbook;/serialconsole-setup.html">this section of the handbook</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="found-serial"> + <question xml:id="found-serial"> <para>How do I tell if &os; found my serial ports or modem cards?</para> </question> @@ -7084,42 +6903,41 @@ sio1: type 16550A</programlisting> settings in the above example. If these settings are not right for your system, or if you have added modem cards or have more serial ports than your kernel is configured for, - just reconfigure your kernel. See section <link - linkend="make-kernel">about building a kernel</link> for + just reconfigure your kernel. See section <link linkend="make-kernel">about building a kernel</link> for more details.</para> </answer> </qandaentry> <qandaentry> - <question id="access-serial-ports"> + <question xml:id="access-serial-ports"> <para>How do I access the serial ports on &os;?</para> </question> <answer> - <para>The third serial port, <devicename>sio2</devicename> - (see &man.sio.4;, known as <devicename>COM3</devicename> in - DOS), is on <devicename>/dev/cuad2</devicename> for dial-out - devices, and on <devicename>/dev/ttyd2</devicename> for + <para>The third serial port, <filename>sio2</filename> + (see &man.sio.4;, known as <filename>COM3</filename> in + DOS), is on <filename>/dev/cuad2</filename> for dial-out + devices, and on <filename>/dev/ttyd2</filename> for dial-in devices. What is the difference between these two classes of devices?</para> <para>You use - <devicename>ttyd<replaceable>X</replaceable></devicename> + <filename>ttydX</filename> for dial-ins. When opening - <devicename>/dev/ttyd<replaceable>X</replaceable></devicename> + <filename>/dev/ttydX</filename> in blocking mode, a process will wait for the corresponding - <devicename>cuad<replaceable>X</replaceable></devicename> + <filename>cuadX</filename> device to become inactive, and then wait for the carrier detect line to go active. When you open the - <devicename>cuad<replaceable>X</replaceable></devicename> + <filename>cuadX</filename> device, it makes sure the serial port is not already in use by the - <devicename>ttyd<replaceable>X</replaceable></devicename> + <filename>ttydX</filename> device. If the port is available, it <quote>steals</quote> it from the - <devicename>ttyd<replaceable>X</replaceable></devicename> + <filename>ttydX</filename> device. Also, the - <devicename>cuad<replaceable>X</replaceable></devicename> + <filename>cuadX</filename> device does not care about carrier detect. With this scheme and an auto-answer modem, you can have remote users log in and you can still dial out with the same modem and the @@ -7128,7 +6946,7 @@ sio1: type 16550A</programlisting> </qandaentry> <qandaentry> - <question id="enable-multiport-serial"> + <question xml:id="enable-multiport-serial"> <para>How do I enable support for a multiport serial card?</para> </question> @@ -7170,56 +6988,53 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="default-serial-params"> + <question xml:id="default-serial-params"> <para>Can I set the default serial parameters for a port?</para> </question> <answer> - <para>See the <ulink - url="&url.books.handbook;/serial.html#serial-hw-config">Serial Communications</ulink> + <para>See the <link xlink:href="&url.books.handbook;/serial.html#serial-hw-config">Serial Communications</link> section in the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="enable-dialup"> + <question xml:id="enable-dialup"> <para>How can I enable dialup logins on my modem?</para> </question> <answer> - <para>Please read the section about <ulink - url="&url.books.handbook;/dialup.html">Dial-in Services</ulink> + <para>Please read the section about <link xlink:href="&url.books.handbook;/dialup.html">Dial-in Services</link> in the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="dumb-terminal"> + <question xml:id="dumb-terminal"> <para>How can I connect a dumb terminal to my &os; box?</para> </question> <answer> - <para>You can find this information in the <ulink - url="&url.books.handbook;/term.html">Terminals</ulink> + <para>You can find this information in the <link xlink:href="&url.books.handbook;/term.html">Terminals</link> section of the &os; Handbook.</para> </answer> </qandaentry> <qandaentry> - <question id="cannot-tip"> + <question xml:id="cannot-tip"> <para>Why can I not run <command>tip</command> or <command>cu</command>?</para> </question> <answer> <para>On your system, the programs &man.tip.1; and &man.cu.1; - can only access the <filename class="directory">/var/spool/lock</filename> - directory via user <username>uucp</username> and group - <groupname>dialer</groupname>. You can use the group - <groupname>dialer</groupname> to control who has access to + can only access the <filename>/var/spool/lock</filename> + directory via user <systemitem class="username">uucp</systemitem> and group + <systemitem class="groupname">dialer</systemitem>. You can use the group + <systemitem class="groupname">dialer</systemitem> to control who has access to your modem or remote systems. Just add yourself to group - <groupname>dialer</groupname>.</para> + <systemitem class="groupname">dialer</systemitem>.</para> <para>Alternatively, you can let everyone on your system run &man.tip.1; and &man.cu.1; by typing:</para> @@ -7231,12 +7046,12 @@ hint.sio.7.irq="12"</programlisting> </qandaset> </chapter> - <chapter id="misc"> + <chapter xml:id="misc"> <title>Miscellaneous Questions</title> <qandaset> <qandaentry> - <question id="more-swap"> + <question xml:id="more-swap"> <para>&os; uses a lot of swap space even when the computer has free memory left. Why?</para> </question> @@ -7257,7 +7072,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="top-freemem"> + <question xml:id="top-freemem"> <para>Why does <command>top</command> show very little free memory even when I have very few programs running?</para> </question> @@ -7278,7 +7093,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="chmod-symlinks"> + <question xml:id="chmod-symlinks"> <para>Why will <command>chmod</command> not change the permissions on symlinks?</para> </question> @@ -7310,11 +7125,11 @@ hint.sio.7.irq="12"</programlisting> &man.chmod.1;. If you want to change the permissions of a directory referenced by a symlink, use &man.chmod.1; without any options and follow the symlink with a trailing - slash (<filename class="directory">/</filename>). For example, if + slash (<filename>/</filename>). For example, if <filename>foo</filename> is a symlink to directory - <filename class="directory">bar</filename>, and you want to change the + <filename>bar</filename>, and you want to change the permissions of <filename>foo</filename> (actually - <filename class="directory">bar</filename>), you would do something + <filename>bar</filename>), you would do something like:</para> <screen>&prompt.user; <userinput>chmod 555 foo/</userinput></screen> @@ -7322,30 +7137,27 @@ hint.sio.7.irq="12"</programlisting> <para>With the trailing slash, &man.chmod.1; will follow the symlink, <filename>foo</filename>, to change the permissions of the directory, - <filename class="directory">bar</filename>.</para> + <filename>bar</filename>.</para> </warning> </answer> </qandaentry> <qandaentry> - <question id="dos-binaries"> + <question xml:id="dos-binaries"> <para>Can I run DOS binaries under &os;?</para> </question> <answer> - <para>Yes, you can use <filename - role="package">emulators/doscmd</filename>, a DOS + <para>Yes, you can use <package>emulators/doscmd</package>, a DOS emulation program, available in the &os; Ports Collection.</para> <para>If <application>doscmd</application> will not suffice, - the add-on utility <filename - role="package">emulators/pcemu</filename> emulates an 8088 + the add-on utility <package>emulators/pcemu</package> emulates an 8088 and enough BIOS services to run many DOS text mode applications. It requires the X Window System.</para> - <para>You may also try <filename - role="package">emulators/dosbox</filename> from the &os; + <para>You may also try <package>emulators/dosbox</package> from the &os; Ports Collection. The main focus of this application is emulating old DOS games using the local file system for files.</para> @@ -7353,26 +7165,24 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="translation"> + <question xml:id="translation"> <para>What do I need to do to translate a &os; document into my native language?</para> </question> <answer> - <para>See the <ulink - url="&url.books.fdp-primer;/translations.html">Translation FAQ</ulink> + <para>See the <link xlink:href="&url.books.fdp-primer;/translations.html">Translation FAQ</link> in the &os; Documentation Project Primer.</para> </answer> </qandaentry> <qandaentry> - <question id="freebsd-mail-bounces"> - <para>Why does my email to any address at <hostid - role="domainname">FreeBSD.org</hostid> bounce?</para> + <question xml:id="freebsd-mail-bounces"> + <para>Why does my email to any address at <systemitem class="fqdomainname">FreeBSD.org</systemitem> bounce?</para> </question> <answer> - <para>The <hostid role="domainname">FreeBSD.org</hostid> mail + <para>The <systemitem class="fqdomainname">FreeBSD.org</systemitem> mail system implements some <application>Postfix</application> checks on incoming mail and rejects mail that is either from misconfigured relays or @@ -7411,7 +7221,7 @@ hint.sio.7.irq="12"</programlisting> </itemizedlist> <para>If you still have trouble with email infrastructure at - <hostid role="domainname">FreeBSD.org</hostid> send a note + <systemitem class="fqdomainname">FreeBSD.org</systemitem> send a note with the details to <email>postmaster@freebsd.org</email>; Include a date/time interval so that logs may be reviewed — @@ -7422,7 +7232,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="free-account"> + <question xml:id="free-account"> <para>Where can I find a free &os; account?</para> </question> @@ -7431,8 +7241,7 @@ hint.sio.7.irq="12"</programlisting> servers, others do provide open access &unix; systems. The charge varies and limited services may be available.</para> - <para><ulink - url="http://www.arbornet.org/">Arbornet, Inc</ulink>, + <para><link xlink:href="http://www.arbornet.org/">Arbornet, Inc</link>, also known as <emphasis>M-Net</emphasis>, has been providing open access to &unix; systems since 1983. Starting on an Altos running System III, the site switched to BSD/OS in @@ -7449,7 +7258,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="daemon-name"> + <question xml:id="daemon-name"> <para>What is the cute little red guy's name?</para> </question> @@ -7459,57 +7268,53 @@ hint.sio.7.irq="12"</programlisting> <quote>beastie</quote>. Note that <quote>beastie</quote> is pronounced <quote>BSD</quote>.</para> - <para>You can learn more about the BSD daemon on his <ulink - url="http://www.mckusick.com/beastie/index.html">home page</ulink>.</para> + <para>You can learn more about the BSD daemon on his <link xlink:href="http://www.mckusick.com/beastie/index.html">home page</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="use-beastie"> + <question xml:id="use-beastie"> <para>Can I use the BSD daemon image?</para> </question> <answer> <para>Perhaps. The BSD daemon is copyrighted by Marshall Kirk - McKusick. You will want to check his <ulink - url="http://www.mckusick.com/beastie/mainpage/copyright.html">Statement on the Use of the BSD Daemon Figure</ulink> + McKusick. You will want to check his <link xlink:href="http://www.mckusick.com/beastie/mainpage/copyright.html">Statement on the Use of the BSD Daemon Figure</link> for detailed usage terms.</para> <para>In summary, you are free to use the image in a tasteful manner, for personal use, so long as appropriate credit is given. If you want to use him commercially, you must contact &a.mckusick.email;. More details are available on the - <ulink - url="http://www.mckusick.com/beastie/index.html">BSD Daemon's home page</ulink>.</para> + <link xlink:href="http://www.mckusick.com/beastie/index.html">BSD Daemon's home page</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="daemon-images"> + <question xml:id="daemon-images"> <para>Do you have any BSD daemon images I could use?</para> </question> <answer> <para>You will find eps and Xfig drawings under - <filename class="directory">/usr/share/examples/BSD_daemon/</filename>.</para> + <filename>/usr/share/examples/BSD_daemon/</filename>.</para> </answer> </qandaentry> <qandaentry> - <question id="glossary"> + <question xml:id="glossary"> <para>I have seen an acronym or other term on the mailing lists and I do not understand what it means. Where should I look?</para> </question> <answer> - <para>Please see the <ulink - url="&url.books.handbook;/freebsd-glossary.html">&os; Glossary</ulink>.</para> + <para>Please see the <link xlink:href="&url.books.handbook;/freebsd-glossary.html">&os; Glossary</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="bikeshed-painting"> + <question xml:id="bikeshed-painting"> <para>Why should I care what color the bikeshed is?</para> </question> @@ -7528,8 +7333,7 @@ hint.sio.7.irq="12"</programlisting> <para>The longer and more complete answer is that after a very long argument about whether &man.sleep.1; should take fractional second arguments, &a.phk.email; posted a long message - entitled <quote><ulink - url="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A bike shed (any color will do) on greener grass...</ulink></quote>. + entitled <quote><link xlink:href="http://www.FreeBSD.org/cgi/getmsg.cgi?fetch=506636+517178+/usr/local/www/db/text/1999/freebsd-hackers/19991003.freebsd-hackers">A bike shed (any color will do) on greener grass...</link></quote>. The appropriate portions of that message are quoted below.</para> @@ -7588,12 +7392,12 @@ hint.sio.7.irq="12"</programlisting> </qandaset> </chapter> - <chapter id="funnies"> + <chapter xml:id="funnies"> <title>The &os; Funnies</title> <qandaset> <qandaentry> - <question id="very-very-cool"> + <question xml:id="very-very-cool"> <para>How cool is &os;?</para> </question> @@ -7628,7 +7432,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="letmeoutofhere"> + <question xml:id="letmeoutofhere"> <para>Who is scratching in my memory banks??</para> </question> @@ -7665,7 +7469,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="changing-lightbulbs"> + <question xml:id="changing-lightbulbs"> <para>How many &os; hackers does it take to change a lightbulb?</para> </question> @@ -7782,7 +7586,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="dev-null"> + <question xml:id="dev-null"> <para>Where does data written to <filename>/dev/null</filename> go?</para> </question> @@ -7802,7 +7606,7 @@ hint.sio.7.irq="12"</programlisting> CPU by reading data out of <filename>/dev/random</filename> and sending it off somewhere; however you run the risk of overheating your network connection and - <filename class="directory">/</filename> or angering your ISP, as most of the + <filename>/</filename> or angering your ISP, as most of the data will end up getting converted to heat by their equipment, but they generally have good cooling, so if you do not overdo it you should be OK.</para> @@ -7839,13 +7643,13 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="punk-my-friend"> + <question xml:id="punk-my-friend"> <para>My colleague sits at the computer too much, how can I prank her?</para> </question> <answer> - <para>Install <filename role="port">games/sl</filename> and wait + <para>Install <package role="port">games/sl</package> and wait for her to mistype <userinput>sl</userinput> for <command>ls</command>.</para> </answer> @@ -7853,19 +7657,18 @@ hint.sio.7.irq="12"</programlisting> </qandaset> </chapter> - <chapter id="advanced"> + <chapter xml:id="advanced"> <title>Advanced Topics</title> <qandaset> <qandaentry> - <question id="learn-advanced"> + <question xml:id="learn-advanced"> <para>How can I learn more about &os;'s internals?</para> </question> <answer> <para>See the - <ulink - url="&url.books.arch-handbook;">&os; Architecture Handbook</ulink>.</para> + <link xlink:href="&url.books.arch-handbook;">&os; Architecture Handbook</link>.</para> <para>Additionally, much general &unix; knowledge is directly applicable to &os;.</para> @@ -7873,27 +7676,25 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="how-to-contribute"> + <question xml:id="how-to-contribute"> <para>How can I contribute to &os;?</para> </question> <answer> - <para>Please see the article on <ulink - url="&url.articles.contributing;/article.html">Contributing to &os;</ulink> + <para>Please see the article on <link xlink:href="&url.articles.contributing;/article.html">Contributing to &os;</link> for specific advice on how to do this. Assistance is more than welcome!</para> </answer> </qandaentry> <qandaentry> - <question id="define-snap-release"> + <question xml:id="define-snap-release"> <para>What are snapshots and releases?</para> </question> <answer> <para>There are currently &rel.numbranch; active/semi-active branches in - the &os; <ulink - url="http://svnweb.FreeBSD.org/base/">Subversion Repository</ulink>. + the &os; <link xlink:href="http://svnweb.FreeBSD.org/base/">Subversion Repository</link>. (Earlier branches are only changed very rarely, which is why there are only &rel.numbranch; active branches of development):</para> @@ -7933,27 +7734,25 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="ctm"> + <question xml:id="ctm"> <para>Can I follow <emphasis>-CURRENT</emphasis> with limited Internet access?</para> </question> <answer> <para>Yes, you can do this <emphasis>without</emphasis> - downloading the whole source tree by using the <ulink - url="&url.books.handbook;/synching.html#ctm">CTM facility</ulink>.</para> + downloading the whole source tree by using the <link xlink:href="&url.books.handbook;/synching.html#ctm">CTM facility</link>.</para> </answer> </qandaentry> <qandaentry> - <question id="submitting-kernel-extensions"> + <question xml:id="submitting-kernel-extensions"> <para>I have written a kernel extension, who do I send it to?</para> </question> <answer> - <para>Please take a look at the article on <ulink - url="&url.articles.contributing;/article.html">Contributing to &os;</ulink> + <para>Please take a look at the article on <link xlink:href="&url.articles.contributing;/article.html">Contributing to &os;</link> to learn how to submit code.</para> <para>And thanks for the thought!</para> @@ -7961,7 +7760,7 @@ hint.sio.7.irq="12"</programlisting> </qandaentry> <qandaentry> - <question id="kernel-panic-troubleshooting"> + <question xml:id="kernel-panic-troubleshooting"> <para>How can I make the most of the data I see when my kernel panics?</para> </question> @@ -8009,7 +7808,7 @@ panic: page fault</programlisting> <step> <para>When the system reboots, do the following:</para> - <screen>&prompt.user; <userinput><command>nm</command> <option>-n</option> <replaceable>kernel.that.caused.the.panic</replaceable> | <command>grep</command> f0xxxxxx</userinput></screen> + <screen>&prompt.user; <userinput>nm -n kernel.that.caused.the.panic | grep f0xxxxxx</userinput></screen> <para>where <literal>f0xxxxxx</literal> is the instruction pointer value. The odds are you will not @@ -8020,7 +7819,7 @@ panic: page fault</programlisting> get an exact match, omit the last digit from the instruction pointer value and try again, i.e.:</para> - <screen>&prompt.user; <userinput><command>nm</command> <option>-n</option> <replaceable>kernel.that.caused.the.panic</replaceable> | <command>grep</command> f0xxxxx</userinput></screen> + <screen>&prompt.user; <userinput>nm -n kernel.that.caused.the.panic | grep f0xxxxx</userinput></screen> <para>If that does not yield any results, chop off another digit. Repeat until you get some sort of output. The @@ -8041,23 +7840,22 @@ panic: page fault</programlisting> <step> <para>Make sure that the following line is included in your kernel configuration file - (<filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/<replaceable>MYKERNEL</replaceable></filename>):</para> + (<filename>/usr/src/sys/arch/conf/MYKERNEL</filename>):</para> <programlisting>makeoptions DEBUG=-g # Build kernel with gdb(1) debug symbols</programlisting> </step> <step> - <para>Change to the <filename - class="directory">/usr/src</filename> + <para>Change to the <filename>/usr/src</filename> directory:</para> - <screen>&prompt.root; <userinput><command>cd</command> <filename class="directory">/usr/src</filename></userinput></screen> + <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> </step> <step> <para>Compile the kernel:</para> - <screen>&prompt.root; <userinput><command>make</command> <maketarget>buildkernel</maketarget> <makevar>KERNCONF</makevar>=<replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make buildkernel KERNCONF=MYKERNEL</userinput></screen> </step> <step> @@ -8065,7 +7863,7 @@ panic: page fault</programlisting> </step> <step> - <screen>&prompt.root; <userinput><command>make</command> <maketarget>installkernel</maketarget> <makevar>KERNCONF</makevar>=<replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen> </step> <step> @@ -8074,15 +7872,15 @@ panic: page fault</programlisting> </procedure> <note> - <para>If you do not use the <makevar>KERNCONF</makevar> + <para>If you do not use the <varname>KERNCONF</varname> make variable a <filename>GENERIC</filename> kernel will be built and installed.</para> </note> <para>The &man.make.1; process will have built two kernels. - <filename>/usr/obj/usr/src/sys/<replaceable>MYKERNEL</replaceable>/kernel</filename> + <filename>/usr/obj/usr/src/sys/MYKERNEL/kernel</filename> and - <filename>/usr/obj/usr/src/sys/<replaceable>MYKERNEL</replaceable>/kernel.debug</filename>. + <filename>/usr/obj/usr/src/sys/MYKERNEL/kernel.debug</filename>. <filename>kernel</filename> was installed as <filename>/boot/kernel/kernel</filename>, while <filename>kernel.debug</filename> can be used as the source @@ -8098,19 +7896,19 @@ panic: page fault</programlisting> using &man.savecore.8;; if <literal>dumpdev</literal> is set in <filename>/etc/rc.conf</filename>, the &man.rc.8; scripts will run &man.savecore.8; automatically and put the crash - dump in <filename class="directory">/var/crash</filename>.</para> + dump in <filename>/var/crash</filename>.</para> <note> <para>&os; crash dumps are usually the same size as the physical RAM size of your machine. That is, if you have 512 MB of RAM, you will get a 512 MB crash dump. Therefore you must make sure there is enough space in - <filename class="directory">/var/crash</filename> to hold the dump. + <filename>/var/crash</filename> to hold the dump. Alternatively, you run &man.savecore.8; manually and have it recover the crash dump to another directory where you have more room. It is possible to limit the size of the crash dump by using <literal>options - MAXMEM=<replaceable>N</replaceable></literal> where + MAXMEM=N</literal> where <replaceable>N</replaceable> is the size of kernel's memory usage in KBs. For example, if you have 1 GB of RAM, you can limit the kernel's memory usage to @@ -8121,7 +7919,7 @@ panic: page fault</programlisting> <para>Once you have recovered the crash dump, you can get a stack trace with &man.kgdb.1; as follows:</para> - <screen>&prompt.user; <userinput><command>kgdb</command> <filename>/usr/obj/usr/src/sys/<replaceable>MYKERNEL</replaceable>/kernel.debug</filename> <filename class="directory">/var/crash/<replaceable>vmcore.0</replaceable></filename></userinput> + <screen>&prompt.user; <userinput>kgdb /usr/obj/usr/src/sys/MYKERNEL/kernel.debug /var/crash/vmcore.0</userinput> <prompt>(kgdb)</prompt> <userinput>backtrace</userinput></screen> <para>Note that there may be several screens worth of @@ -8157,7 +7955,7 @@ panic: page fault</programlisting> </qandaentry> <qandaentry> - <question id="dlsym-failure"> + <question xml:id="dlsym-failure"> <para>Why has <function>dlsym()</function> stopped working for ELF executables?</para> </question> @@ -8178,7 +7976,7 @@ panic: page fault</programlisting> </qandaentry> <qandaentry> - <question id="change-kernel-address-space"> + <question xml:id="change-kernel-address-space"> <para>How can I increase or reduce the kernel address space on i386?</para> </question> @@ -8204,7 +8002,7 @@ panic: page fault</programlisting> </qandaset> </chapter> - <chapter id="acknowledgments"> + <chapter xml:id="acknowledgments"> <title>Acknowledgments</title> <para>This innocent little Frequently Asked Questions document has @@ -8215,8 +8013,7 @@ panic: page fault</programlisting> Repeatedly.</para> <para>We wish to thank every one of the people responsible, and we - encourage you to <ulink - url="&url.articles.contributing;/article.html">join them</ulink> + encourage you to <link xlink:href="&url.articles.contributing;/article.html">join them</link> in making this FAQ even better.</para> </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml index c1e16f1040..31c9c556f3 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ b/en_US.ISO8859-1/books/fdp-primer/book.xml @@ -1,10 +1,9 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY % chapters SYSTEM "chapters.ent"> %chapters; <!-- ENTITY index SYSTEM "index.xml" --> ]> - <!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. Redistribution and use in source (SGML DocBook) and 'compiled' forms @@ -36,13 +35,12 @@ $FreeBSD$ --> - -<book lang='en'> - <bookinfo> - <title>FreeBSD Documentation Project Primer for New +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD Documentation Project Primer for New Contributors</title> + - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> <copyright> <year>1998</year> @@ -84,12 +82,12 @@ <para>This is a work in progress. Corrections and additions are always welcome.</para> </abstract> - </bookinfo> + </info> - <preface id="preface"> + <preface xml:id="preface"> <title>Preface</title> - <sect1 id="preface-prompts"> + <sect1 xml:id="preface-prompts"> <title>Shell Prompts</title> <para>This table shows the default system prompt and @@ -112,7 +110,7 @@ </row> <row> - <entry><username>root</username></entry> + <entry><systemitem class="username">root</systemitem></entry> <entry>&prompt.root;</entry> </row> </tbody> @@ -120,7 +118,7 @@ </informaltable> </sect1> - <sect1 id="preface-conventions"> + <sect1 xml:id="preface-conventions"> <title>Typographic Conventions</title> <para>This table describes the typographic conventions @@ -167,7 +165,7 @@ The time is 09:18</screen></entry> <row> <entry>User and group names.</entry> - <entry>Only <username>root</username> can do + <entry>Only <systemitem class="username">root</systemitem> can do this.</entry> </row> @@ -183,7 +181,7 @@ The time is 09:18</screen></entry> <entry>To search for a keyword in the manual pages, type <command>man -k - <replaceable>keyword</replaceable></command></entry> + keyword</command></entry> </row> <row> @@ -196,7 +194,7 @@ The time is 09:18</screen></entry> </informaltable> </sect1> - <sect1 id="preface-notes"> + <sect1 xml:id="preface-notes"> <title>Notes, Tips, Important Information, Warnings, and Examples</title> @@ -238,7 +236,7 @@ The time is 09:18</screen></entry> </example> </sect1> - <sect1 id="preface-acknowledgements"> + <sect1 xml:id="preface-acknowledgements"> <title>Acknowledgments</title> <para>My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, @@ -265,7 +263,5 @@ The time is 09:18</screen></entry> &app.examples; -<!-- - &index; ---> + <index/> </book> diff --git a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml index 95ab3e73a0..1f95722816 100644 --- a/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/doc-build/chapter.xml @@ -30,14 +30,13 @@ $FreeBSD$ --> - -<chapter id="doc-build"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="doc-build"> <title>The Documentation Build Process</title> <para>This chapter covers organization of the documentation build process and how &man.make.1; is used to control it.</para> - <sect1 id="doc-build-toolset"> + <sect1 xml:id="doc-build-toolset"> <title>The &os; Documentation Build Toolset</title> <para>These are the tools used to build and install the @@ -67,7 +66,7 @@ </itemizedlist> </sect1> - <sect1 id="doc-build-makefiles"> + <sect1 xml:id="doc-build-makefiles"> <title>Understanding <filename>Makefile</filename>s in the Documentation Tree</title> @@ -90,15 +89,14 @@ </listitem> <listitem> - <para><link - linkend="make-includes"><application>Make</application> + <para><link linkend="make-includes"><application>Make</application> includes</link> are the glue that perform the document production, and are usually of the form - <filename>doc.<replaceable>xxx</replaceable>.mk</filename>.</para> + <filename>doc.xxx.mk</filename>.</para> </listitem> </itemizedlist> - <sect2 id="sub-make"> + <sect2 xml:id="sub-make"> <title>Subdirectory <filename>Makefile</filename>s</title> <para>These <filename>Makefile</filename>s usually take the form @@ -113,40 +111,40 @@ DOC_PREFIX?= ${.CURDIR}/.. .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> <para>The first four non-empty lines define the &man.make.1; - variables <makevar>SUBDIR</makevar>, - <makevar>COMPAT_SYMLINK</makevar>, and - <makevar>DOC_PREFIX</makevar>.</para> + variables <varname>SUBDIR</varname>, + <varname>COMPAT_SYMLINK</varname>, and + <varname>DOC_PREFIX</varname>.</para> - <para>The <makevar>SUBDIR</makevar> statement and - <makevar>COMPAT_SYMLINK</makevar> statement show how to + <para>The <varname>SUBDIR</varname> statement and + <varname>COMPAT_SYMLINK</varname> statement show how to assign a value to a variable, overriding any previous value.</para> - <para>The second <makevar>SUBDIR</makevar> statement shows how a + <para>The second <varname>SUBDIR</varname> statement shows how a value is appended to the current value of a variable. The - <makevar>SUBDIR</makevar> variable is now <literal>articles + <varname>SUBDIR</varname> variable is now <literal>articles books</literal>.</para> - <para>The <makevar>DOC_PREFIX</makevar> assignment shows how a + <para>The <varname>DOC_PREFIX</varname> assignment shows how a value is assigned to the variable, but only if it is not already defined. This is useful if - <makevar>DOC_PREFIX</makevar> is not where this + <varname>DOC_PREFIX</varname> is not where this <filename>Makefile</filename> thinks it is - the user can override this and provide the correct value.</para> - <para>What does it all mean? <makevar>SUBDIR</makevar> + <para>What does it all mean? <varname>SUBDIR</varname> mentions which subdirectories below this one the build process should pass any work on to.</para> - <para><makevar>COMPAT_SYMLINK</makevar> is specific to + <para><varname>COMPAT_SYMLINK</varname> is specific to compatibility symlinks (amazingly enough) for languages to their official encoding (<filename>doc/en</filename> would point to <filename>en_US.ISO-8859-1</filename>).</para> - <para><makevar>DOC_PREFIX</makevar> is the path to the root of + <para><varname>DOC_PREFIX</varname> is the path to the root of the &os; Document Project tree. This is not always that easy to find, and is also easily overridden, to allow for - flexibility. <makevar>.CURDIR</makevar> is a &man.make.1; + flexibility. <varname>.CURDIR</varname> is a &man.make.1; builtin variable with the path to the current directory.</para> @@ -156,7 +154,7 @@ DOC_PREFIX?= ${.CURDIR}/.. converts these variables into build instructions.</para> </sect2> - <sect2 id="doc-make"> + <sect2 xml:id="doc-make"> <title>Documentation <filename>Makefile</filename>s</title> <para>These <filename>Makefile</filename>s set &man.make.1; @@ -181,32 +179,32 @@ DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> - <para>The <makevar>MAINTAINER</makevar> variable allows + <para>The <varname>MAINTAINER</varname> variable allows committers to claim ownership of a document in the &os; Documentation Project, and take responsibility for maintaining it.</para> - <para><makevar>DOC</makevar> is the name (sans the + <para><varname>DOC</varname> is the name (sans the <filename>.xml</filename> extension) of the main document - created by this directory. <makevar>SRCS</makevar> lists all + created by this directory. <varname>SRCS</varname> lists all the individual files that make up the document. This should also include important files in which a change should result in a rebuild.</para> - <para><makevar>FORMATS</makevar> indicates the default formats + <para><varname>FORMATS</varname> indicates the default formats that should be built for this document. - <makevar>INSTALL_COMPRESSED</makevar> is the default list of + <varname>INSTALL_COMPRESSED</varname> is the default list of compression techniques that should be used in the document - build. <makevar>INSTALL_ONLY_COMPRESS</makevar>, empty by + build. <varname>INSTALL_ONLY_COMPRESS</varname>, empty by default, should be non-empty if only compressed documents are desired in the build.</para> - <para>The <makevar>DOC_PREFIX</makevar> and include statements + <para>The <varname>DOC_PREFIX</varname> and include statements should be familiar already.</para> </sect2> </sect1> - <sect1 id="make-includes"> + <sect1 xml:id="make-includes"> <title>&os; Documentation Project <application>Make</application> Includes</title> @@ -233,8 +231,8 @@ DOC_PREFIX?= ${.CURDIR}/../../.. <listitem> <para><filename>doc.docbook.mk</filename> is included if - <makevar>DOCFORMAT</makevar> is <literal>docbook</literal> - and <makevar>DOC</makevar> is set.</para> + <varname>DOCFORMAT</varname> is <literal>docbook</literal> + and <varname>DOC</varname> is set.</para> </listitem> </itemizedlist> @@ -262,22 +260,22 @@ PRI_LANG?= en_US.ISO8859-1 <title>Variables</title> - <para><makevar>DOCFORMAT</makevar> and - <makevar>MAINTAINER</makevar> are assigned default values, + <para><varname>DOCFORMAT</varname> and + <varname>MAINTAINER</varname> are assigned default values, if these are not set by the document make file.</para> - <para><makevar>PREFIX</makevar> is the prefix under which the + <para><varname>PREFIX</varname> is the prefix under which the <link linkend="tools">documentation building tools</link> are installed. For normal package and port installation, this is <filename>/usr/local</filename>.</para> - <para><makevar>PRI_LANG</makevar> should be set to whatever + <para><varname>PRI_LANG</varname> should be set to whatever language and encoding is natural amongst users these documents are being built for. US English is the default.</para> <note> - <para><makevar>PRI_LANG</makevar> does not affect which + <para><varname>PRI_LANG</varname> does not affect which documents can, or even will, be built. Its main use is creating links to commonly referenced documents into the &os; documentation install root.</para> @@ -294,7 +292,7 @@ PRI_LANG?= en_US.ISO8859-1 returns whether the variable given is defined or not.</para> <para><literal>.if ${DOCFORMAT} == "docbook"</literal>, next, - tests whether the <makevar>DOCFORMAT</makevar> variable is + tests whether the <varname>DOCFORMAT</varname> variable is <literal>"docbook"</literal>, and in this case, includes <filename>doc.docbook.mk</filename>.</para> @@ -314,21 +312,21 @@ PRI_LANG?= en_US.ISO8859-1 <itemizedlist> <listitem> - <para><makevar>SUBDIR</makevar> is a list of + <para><varname>SUBDIR</varname> is a list of subdirectories that the build process should go further down into.</para> </listitem> <listitem> - <para><makevar>ROOT_SYMLINKS</makevar> is the name of + <para><varname>ROOT_SYMLINKS</varname> is the name of directories that should be linked to the document install root from their actual locations, if the current language is the primary language (specified by - <makevar>PRI_LANG</makevar>).</para> + <varname>PRI_LANG</varname>).</para> </listitem> <listitem> - <para><makevar>COMPAT_SYMLINK</makevar> is described in + <para><varname>COMPAT_SYMLINK</varname> is described in the <link linkend="sub-make">Subdirectory Makefile</link> section.</para> @@ -340,9 +338,9 @@ PRI_LANG?= en_US.ISO8859-1 <title>Targets and Macros</title> <para>Dependencies are described by - <literal><replaceable>target</replaceable>: - <replaceable>dependency1 dependency2 - ...</replaceable></literal> tuples, where to build + <literal>target: + dependency1 dependency2 + ...</literal> tuples, where to build <literal>target</literal>, the given dependencies must be built first.</para> @@ -362,7 +360,7 @@ PRI_LANG?= en_US.ISO8859-1 ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor</programlisting> - <para>In the above, <maketarget>_SUBDIRUSE</maketarget> is now + <para>In the above, <buildtarget>_SUBDIRUSE</buildtarget> is now a macro which will execute the given commands when it is listed as a dependency.</para> @@ -370,18 +368,18 @@ PRI_LANG?= en_US.ISO8859-1 Basically, it is executed <emphasis>after</emphasis> the instructions given in the build procedure it is listed as a dependency to, and it does not adjust - <makevar>.TARGET</makevar>, which is the variable which + <varname>.TARGET</varname>, which is the variable which contains the name of the target currently being built.</para> <programlisting>clean: _SUBDIRUSE rm -f ${CLEANFILES}</programlisting> - <para>In the above, <maketarget>clean</maketarget> will use - the <maketarget>_SUBDIRUSE</maketarget> macro after it has + <para>In the above, <buildtarget>clean</buildtarget> will use + the <buildtarget>_SUBDIRUSE</buildtarget> macro after it has executed the instruction <command>rm -f ${CLEANFILES}</command>. In effect, this - causes <maketarget>clean</maketarget> to go further and + causes <buildtarget>clean</buildtarget> to go further and further down the directory tree, deleting built files as it goes <emphasis>down</emphasis>, not on the way back up.</para> @@ -391,20 +389,20 @@ PRI_LANG?= en_US.ISO8859-1 <itemizedlist> <listitem> - <para><maketarget>install</maketarget> and - <maketarget>package</maketarget> both go down the + <para><buildtarget>install</buildtarget> and + <buildtarget>package</buildtarget> both go down the directory tree calling the real versions of themselves in the subdirectories - (<maketarget>realinstall</maketarget> and - <maketarget>realpackage</maketarget> + (<buildtarget>realinstall</buildtarget> and + <buildtarget>realpackage</buildtarget> respectively).</para> </listitem> <listitem> - <para><maketarget>clean</maketarget> removes files + <para><buildtarget>clean</buildtarget> removes files created by the build process (and goes down the directory tree too). - <maketarget>cleandir</maketarget> does the same, and + <buildtarget>cleandir</buildtarget> does the same, and also removes the object directory, if any.</para> </listitem> </itemizedlist> @@ -449,11 +447,11 @@ PRI_LANG?= en_US.ISO8859-1 ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ ) .endfor</programlisting> - <para>In the above, if <makevar>SUBDIR</makevar> is empty, no + <para>In the above, if <varname>SUBDIR</varname> is empty, no action is taken; if it has one or more elements, the instructions between <literal>.for</literal> and <literal>.endfor</literal> would repeat for every element, - with <makevar>entry</makevar> being replaced with the value + with <varname>entry</varname> being replaced with the value of the current element.</para> </sect3> </sect2> diff --git a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml index dd987da928..46f1573f99 100644 --- a/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/docbook-markup/chapter.xml @@ -30,11 +30,10 @@ $FreeBSD$ --> - -<chapter id="docbook-markup"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="docbook-markup"> <title>DocBook Markup</title> - <sect1 id="docbook-markup-introduction"> + <sect1 xml:id="docbook-markup-introduction"> <title>Introduction</title> <para>This chapter is an introduction to DocBook as it is used for @@ -49,12 +48,10 @@ O'Reilly & Associates to be a Document Type Definition (<acronym>DTD</acronym>) for writing technical documentation <footnote><para>A short history - can be found under <ulink - url="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> - http://www.oasis-open.org/docbook/intro.shtml#d0e41</ulink>.</para></footnote>. - Since 1998 it is maintained by the <ulink - url="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> - DocBook Technical Committee</ulink>. As such, and unlike + can be found under <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> + http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. + Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</link>. As such, and unlike LinuxDoc and <acronym>XHTML</acronym>, DocBook is very heavily oriented towards markup that describes <emphasis>what</emphasis> something is, rather than describing <emphasis>how</emphasis> it @@ -62,9 +59,9 @@ <para>The DocBook <acronym>DTD</acronym> is available from the Ports Collection in the - <filename role="package">textproc/docbook-xml-450</filename> + <package>textproc/docbook-xml-450</package> port. It is automatically installed as part of the - <filename role="package">textproc/docproj</filename> + <package>textproc/docproj</package> port.</para> <note> @@ -89,7 +86,7 @@ </note> </sect1> - <sect1 id="docbook-markup-freebsd-extensions"> + <sect1 xml:id="docbook-markup-freebsd-extensions"> <title>&os; Extensions</title> <para>The &os; Documentation Project has extended the @@ -111,25 +108,24 @@ &a.doceng;.</para> </note> - <sect2 id="docbook-markup-freebsd-extensions-elements"> + <sect2 xml:id="docbook-markup-freebsd-extensions-elements"> <title>&os; Elements</title> <para>The additional &os; elements are not (currently) in the Ports Collection. They are stored in the &os; Subversion - tree, as <ulink - url="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</ulink>.</para> + tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> <para>&os;-specific elements used in the examples below are clearly marked.</para> </sect2> - <sect2 id="docbook-markup-freebsd-extensions-entities"> + <sect2 xml:id="docbook-markup-freebsd-extensions-entities"> <title>&os; Entities</title> <para>This table shows some of the most useful entities available in the <acronym>FDP</acronym>. For a complete list, see the <filename>*.ent</filename> files in - <filename class="directory">doc/share/xml</filename>.</para> + <filename>doc/share/xml</filename>.</para> <informaltable frame="none" pgwide="1"> <tgroup cols="3"> @@ -145,25 +141,25 @@ <row> <entry><literal>&os;</literal></entry> <entry><literal>&os;</literal></entry> - <entry></entry> + <entry/> </row> <row> <entry><literal>&os.stable;</literal></entry> <entry><literal>&os.stable;</literal></entry> - <entry></entry> + <entry/> </row> <row> <entry><literal>&os.current;</literal></entry> <entry><literal>&os.current;</literal></entry> - <entry></entry> + <entry/> </row> <row> - <entry></entry> - <entry></entry> - <entry></entry> + <entry/> + <entry/> + <entry/> </row> <row> @@ -173,30 +169,29 @@ <row> <entry><literal>&man.ls.1;</literal></entry> <entry>&man.ls.1;</entry> - <entry>Usage: <literal>&man.ls.1; is the manual page for <sgmltag class="starttag">command</sgmltag>ls<sgmltag class="endtag">command</sgmltag>.</literal></entry> + <entry>Usage: <literal>&man.ls.1; is the manual page for commandlscommand.</literal></entry> </row> <row> <entry><literal>&man.cp.1;</literal></entry> <entry>&man.cp.1;</entry> - <entry>Usage: <literal>The manual page for <sgmltag class="starttag">command</sgmltag>cp<sgmltag class="endtag">command</sgmltag> is &man.cp.1;.</literal></entry> + <entry>Usage: <literal>The manual page for commandcpcommand is &man.cp.1;.</literal></entry> </row> <row> - <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</literal></entry> + <entry><literal>&man.command.sectionnumber;</literal></entry> <entry><emphasis>link to <replaceable>command</replaceable> manual page in section <replaceable>sectionnumber</replaceable></emphasis></entry> - <entry>Entities are defined for all the <ulink - url="&url.base;/cgi/man.cgi">&os; manual - pages</ulink>.</entry> + <entry>Entities are defined for all the <link xlink:href="&url.base;/cgi/man.cgi">&os; manual + pages</link>.</entry> </row> <row> - <entry></entry> - <entry></entry> - <entry></entry> + <entry/> + <entry/> + <entry/> </row> <row> @@ -216,18 +211,17 @@ </row> <row> - <entry><literal>&a.<replaceable>listname</replaceable>;</literal></entry> + <entry><literal>&a.listname;</literal></entry> <entry><emphasis>link to <replaceable>listname</replaceable></emphasis></entry> - <entry>Entities are defined for all the <ulink - url="&url.books.handbook;/eresources.html#eresources-mail">&os; - mailing lists</ulink>.</entry> + <entry>Entities are defined for all the <link xlink:href="&url.books.handbook;/eresources.html#eresources-mail">&os; + mailing lists</link>.</entry> </row> <row> - <entry></entry> - <entry></entry> - <entry></entry> + <entry/> + <entry/> + <entry/> </row> <row> @@ -237,45 +231,41 @@ <row> <entry><literal>&url.books.handbook;</literal></entry> <entry><literal>&url.books.handbook;</literal></entry> - <entry>Usage: <literal>A link to the <sgmltag - class="starttag">ulink - url="&url.books.handbook;/advanced-networking.html"</sgmltag>Advanced - Networking<sgmltag class="endtag">ulink</sgmltag> + <entry>Usage: <literal>A link to the ulink + url="&url.books.handbook;/advanced-networking.html"Advanced + Networkingulink chapter of the Handbook.</literal></entry> </row> <row> - <entry><literal>&url.books.<replaceable>bookname</replaceable>;</literal></entry> + <entry><literal>&url.books.bookname;</literal></entry> <entry><emphasis>relative path to <replaceable>bookname</replaceable></emphasis></entry> - <entry>Entities are defined for all the <ulink - url="&url.doc.langbase;/books/">&os; - books</ulink>.</entry> + <entry>Entities are defined for all the <link xlink:href="&url.doc.langbase;/books/">&os; + books</link>.</entry> </row> <row> <entry><literal>&url.articles.committers-guide;</literal></entry> <entry><literal>&url.articles.committers-guide;</literal></entry> - <entry>Usage: <literal>A link to the <sgmltag - class="starttag">ulink - url="&url.articles.committers-guide;"</sgmltag>Committer's - Guide<sgmltag class="endtag">ulink</sgmltag> + <entry>Usage: <literal>A link to the ulink + url="&url.articles.committers-guide;"Committer's + Guideulink article.</literal></entry> </row> <row> - <entry><literal>&url.articles.<replaceable>articlename</replaceable>;</literal></entry> + <entry><literal>&url.articles.articlename;</literal></entry> <entry><emphasis>relative path to <replaceable>articlename</replaceable></emphasis></entry> - <entry>Entities are defined for all the <ulink - url="&url.doc.langbase;/articles/">&os; - articles</ulink>.</entry> + <entry>Entities are defined for all the <link xlink:href="&url.doc.langbase;/articles/">&os; + articles</link>.</entry> </row> <row> - <entry></entry> - <entry></entry> - <entry></entry> + <entry/> + <entry/> + <entry/> </row> <row> @@ -301,9 +291,9 @@ </row> <row> - <entry></entry> - <entry></entry> - <entry></entry> + <entry/> + <entry/> + <entry/> </row> <row> @@ -313,7 +303,7 @@ <row> <entry><literal>&prompt.root;</literal></entry> <entry>&prompt.root;</entry> - <entry>The <username>root</username> user + <entry>The <systemitem class="username">root</systemitem> user prompt.</entry> </row> @@ -349,7 +339,7 @@ </sect2> </sect1> - <sect1 id="docbook-markup-fpi"> + <sect1 xml:id="docbook-markup-fpi"> <title>Formal Public Identifier (FPI)</title> <para>In compliance with the DocBook guidelines for writing @@ -360,32 +350,32 @@ <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> </sect1> - <sect1 id="docbook-markup-document-structure"> + <sect1 xml:id="docbook-markup-document-structure"> <title>Document Structure</title> <para>DocBook allows structuring documentation in several ways. The &os; Documentation Project uses two primary types of DocBook document: the book and the article.</para> - <para>Books are organized into <sgmltag>chapter</sgmltag>s. + <para>Books are organized into <tag>chapter</tag>s. This is a mandatory requirement. There may be - <sgmltag>part</sgmltag>s between the book and the chapter to + <tag>part</tag>s between the book and the chapter to provide another layer of organization. For example, the Handbook is arranged in this way.</para> <para>A chapter may (or may not) contain one or more sections. - These are indicated with the <sgmltag>sect1</sgmltag> element. + These are indicated with the <tag>sect1</tag> element. If a section contains another section then use the - <sgmltag>sect2</sgmltag> element, and so on, up to - <sgmltag>sect5</sgmltag>.</para> + <tag>sect2</tag> element, and so on, up to + <tag>sect5</tag>.</para> <para>Chapters and sections contain the remainder of the content.</para> <para>An article is simpler than a book, and does not use chapters. Instead, the content of an article is organized into - one or more sections, using the same <sgmltag>sect1</sgmltag> - (and <sgmltag>sect2</sgmltag> and so on) elements that are used + one or more sections, using the same <tag>sect1</tag> + (and <tag>sect2</tag> and so on) elements that are used in books.</para> <para>The nature of the document being written should be used to @@ -397,200 +387,200 @@ several chapters, possibly with appendices and similar content as well.</para> - <para>The <ulink url="&url.base;/docs.html">&os; tutorials</ulink> + <para>The <link xlink:href="&url.base;/docs.html">&os; tutorials</link> are all marked up as articles, while this document, the - <ulink url="&url.books.faq;/index.html">FreeBSD FAQ</ulink>, - and the <ulink url="&url.books.handbook;/index.html">FreeBSD - Handbook</ulink> are all marked up as books, for + <link xlink:href="&url.books.faq;/index.html">FreeBSD FAQ</link>, + and the <link xlink:href="&url.books.handbook;/index.html">FreeBSD + Handbook</link> are all marked up as books, for example.</para> - <sect2 id="docbook-markup-starting-a-book"> + <sect2 xml:id="docbook-markup-starting-a-book"> <title>Starting a Book</title> <para>The content of a book is contained within the - <sgmltag>book</sgmltag> element. As well as containing + <tag>book</tag> element. As well as containing structural markup, this element can contain elements that include additional information about the book. This is either meta-information, used for reference purposes, or additional content used to produce a title page.</para> <para>This additional information is contained within - <sgmltag>bookinfo</sgmltag>.</para> + <tag>bookinfo</tag>.</para> <example> - <title>Boilerplate <sgmltag>book</sgmltag> with - <sgmltag>bookinfo</sgmltag></title> + <title>Boilerplate <tag>book</tag> with + <tag>bookinfo</tag></title> <!-- Cannot put this in a marked section because of the replaceable elements --> - <programlisting><sgmltag class="starttag">book</sgmltag> - <sgmltag class="starttag">bookinfo</sgmltag> - <sgmltag class="starttag">title</sgmltag><replaceable>Your Title Here</replaceable><sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">book</tag> + <tag class="starttag">bookinfo</tag> + <tag class="starttag">title</tag><replaceable>Your Title Here</replaceable><tag class="endtag">title</tag> - <sgmltag class="starttag">author</sgmltag> - <sgmltag class="starttag">firstname</sgmltag><replaceable>Your first name</replaceable><sgmltag class="endtag">firstname</sgmltag> - <sgmltag class="starttag">surname</sgmltag><replaceable>Your surname</replaceable><sgmltag class="endtag">surname</sgmltag> - <sgmltag class="starttag">affiliation</sgmltag> - <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag><replaceable>Your email address</replaceable><sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag> - <sgmltag class="endtag">affiliation</sgmltag> - <sgmltag class="endtag">author</sgmltag> + <tag class="starttag">author</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag><tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> - <sgmltag class="starttag">copyright</sgmltag> - <sgmltag class="starttag">year</sgmltag><replaceable>1998</replaceable><sgmltag class="endtag">year</sgmltag> - <sgmltag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</sgmltag><replaceable>Your name</replaceable><sgmltag class="endtag">holder</sgmltag> - <sgmltag class="endtag">copyright</sgmltag> + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> - <sgmltag class="starttag">releaseinfo</sgmltag>$&os;$<sgmltag class="endtag">releaseinfo</sgmltag> + <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> - <sgmltag class="starttag">abstract</sgmltag> - <sgmltag class="starttag">para</sgmltag><replaceable>Include an abstract of the book's contents here.</replaceable><sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">abstract</sgmltag> - <sgmltag class="endtag">bookinfo</sgmltag> + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the book's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">bookinfo</tag> … -<sgmltag class="endtag">book</sgmltag></programlisting> +<tag class="endtag">book</tag></programlisting> </example> </sect2> - <sect2 id="docbook-markup-starting-an-article"> + <sect2 xml:id="docbook-markup-starting-an-article"> <title>Starting an Article</title> <para>The content of the article is contained within the - <sgmltag>article</sgmltag> element. As well as containing + <tag>article</tag> element. As well as containing structural markup, this element can contain elements that include additional information about the article. This is either meta-information, used for reference purposes, or additional content used to produce a title page.</para> <para>This additional information is contained within - <sgmltag>articleinfo</sgmltag>.</para> + <tag>articleinfo</tag>.</para> <example> - <title>Boilerplate <sgmltag>article</sgmltag> with - <sgmltag>articleinfo</sgmltag></title> + <title>Boilerplate <tag>article</tag> with + <tag>articleinfo</tag></title> <!-- Cannot put this in a marked section because of the replaceable elements --> - <programlisting><sgmltag class="starttag">article</sgmltag> - <sgmltag class="starttag">articleinfo</sgmltag> - <sgmltag class="starttag">title</sgmltag><replaceable>Your title here</replaceable><sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">article</tag> + <tag class="starttag">articleinfo</tag> + <tag class="starttag">title</tag><replaceable>Your title here</replaceable><tag class="endtag">title</tag> - <sgmltag class="starttag">author</sgmltag> - <sgmltag class="starttag">firstname</sgmltag><replaceable>Your first name</replaceable><sgmltag class="endtag">firstname</sgmltag> - <sgmltag class="starttag">surname</sgmltag><replaceable>Your surname</replaceable><sgmltag class="endtag">surname</sgmltag> - <sgmltag class="starttag">affiliation</sgmltag> - <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag><replaceable>Your email address</replaceable><sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag> - <sgmltag class="endtag">affiliation</sgmltag> - <sgmltag class="endtag">author</sgmltag> + <tag class="starttag">author</tag> + <tag class="starttag">firstname</tag><replaceable>Your first name</replaceable><tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag><replaceable>Your surname</replaceable><tag class="endtag">surname</tag> + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag><tag class="starttag">email</tag><replaceable>Your email address</replaceable><tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> - <sgmltag class="starttag">copyright</sgmltag> - <sgmltag class="starttag">year</sgmltag><replaceable>1998</replaceable><sgmltag class="endtag">year</sgmltag> - <sgmltag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</sgmltag><replaceable>Your name</replaceable><sgmltag class="endtag">holder</sgmltag> - <sgmltag class="endtag">copyright</sgmltag> + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag><replaceable>1998</replaceable><tag class="endtag">year</tag> + <tag class="starttag">holder role="mailto:<replaceable>your email address</replaceable>"</tag><replaceable>Your name</replaceable><tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> - <sgmltag class="starttag">releaseinfo</sgmltag>$&os;$<sgmltag class="endtag">releaseinfo</sgmltag> + <tag class="starttag">releaseinfo</tag>$&os;$<tag class="endtag">releaseinfo</tag> - <sgmltag class="starttag">abstract</sgmltag> - <sgmltag class="starttag">para</sgmltag><replaceable>Include an abstract of the article's contents here.</replaceable><sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">abstract</sgmltag> - <sgmltag class="endtag">articleinfo</sgmltag> + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag><replaceable>Include an abstract of the article's contents here.</replaceable><tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">articleinfo</tag> … -<sgmltag class="endtag">article</sgmltag></programlisting> +<tag class="endtag">article</tag></programlisting> </example> </sect2> - <sect2 id="docbook-markup-indicating-chapters"> + <sect2 xml:id="docbook-markup-indicating-chapters"> <title>Indicating Chapters</title> - <para>Use <sgmltag>chapter</sgmltag> to mark up your chapters. - Each chapter has a mandatory <sgmltag>title</sgmltag>. + <para>Use <tag>chapter</tag> to mark up your chapters. + Each chapter has a mandatory <tag>title</tag>. Articles do not contain chapters, they are reserved for books.</para> <example> <title>A Simple Chapter</title> - <programlisting><sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>The Chapter's Title<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>The Chapter's Title<tag class="endtag">title</tag> ... -<sgmltag class="endtag">chapter</sgmltag></programlisting> +<tag class="endtag">chapter</tag></programlisting> </example> <para>A chapter cannot be empty; it must contain elements in - addition to <sgmltag>title</sgmltag>. If you need to + addition to <tag>title</tag>. If you need to include an empty chapter then just use an empty paragraph.</para> <example> <title>Empty Chapters</title> - <programlisting><sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>This is An Empty Chapter<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>This is An Empty Chapter<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag><sgmltag class="endtag">para</sgmltag> -<sgmltag class="endtag">chapter</sgmltag></programlisting> + <tag class="starttag">para</tag><tag class="endtag">para</tag> +<tag class="endtag">chapter</tag></programlisting> </example> </sect2> - <sect2 id="docbook-markup-sections-below-chapters"> + <sect2 xml:id="docbook-markup-sections-below-chapters"> <title>Sections Below Chapters</title> <para>In books, chapters may (but do not need to) be broken up into sections, subsections, and so on. In articles, sections are the main structural element, and each article must contain at least one section. Use the - <sgmltag>sect<replaceable>n</replaceable></sgmltag> element. + <tag>sect<replaceable>n</replaceable></tag> element. The <replaceable>n</replaceable> indicates the section number, which identifies the section level.</para> <para>The first - <sgmltag>sect<replaceable>n</replaceable></sgmltag> is - <sgmltag>sect1</sgmltag>. You can have one or more of these + <tag>sect<replaceable>n</replaceable></tag> is + <tag>sect1</tag>. You can have one or more of these in a chapter. They can contain one or more - <sgmltag>sect2</sgmltag> elements, and so on, down to - <sgmltag>sect5</sgmltag>.</para> + <tag>sect2</tag> elements, and so on, down to + <tag>sect5</tag>.</para> <example> <title>Sections in Chapters</title> - <programlisting><sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>A Sample Chapter<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>A Sample Chapter<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>Some text in the chapter.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">para</tag>Some text in the chapter.<tag class="endtag">para</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>First Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>First Section<tag class="endtag">title</tag> … - <sgmltag class="endtag">sect1</sgmltag> + <tag class="endtag">sect1</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>Second Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>Second Section<tag class="endtag">title</tag> - <sgmltag class="starttag">sect2</sgmltag> - <sgmltag class="starttag">title</sgmltag>First Sub-Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>First Sub-Section<tag class="endtag">title</tag> - <sgmltag class="starttag">sect3</sgmltag> - <sgmltag class="starttag">title</sgmltag>First Sub-Sub-Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect3</tag> + <tag class="starttag">title</tag>First Sub-Sub-Section<tag class="endtag">title</tag> … - <sgmltag class="endtag">sect3</sgmltag> - <sgmltag class="endtag">sect2</sgmltag> + <tag class="endtag">sect3</tag> + <tag class="endtag">sect2</tag> - <sgmltag class="starttag">sect2</sgmltag> - <sgmltag class="starttag">title</sgmltag>Second Sub-Section (1.2.2)<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Second Sub-Section (1.2.2)<tag class="endtag">title</tag> … - <sgmltag class="endtag">sect2</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">chapter</sgmltag></programlisting> + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> </example> <note> @@ -623,64 +613,64 @@ </note> </sect2> - <sect2 id="docbook-markup-subdividing-part"> - <title>Subdividing Using <sgmltag>part</sgmltag> + <sect2 xml:id="docbook-markup-subdividing-part"> + <title>Subdividing Using <tag>part</tag> Elements</title> - <para><sgmltag>part</sgmltag>s introduce another level of - organization between <sgmltag>book</sgmltag> and - <sgmltag>chapter</sgmltag> with one or more - <sgmltag>part</sgmltag>s. This cannot be done in an - <sgmltag>article</sgmltag>.</para> + <para><tag>part</tag>s introduce another level of + organization between <tag>book</tag> and + <tag>chapter</tag> with one or more + <tag>part</tag>s. This cannot be done in an + <tag>article</tag>.</para> - <programlisting><sgmltag class="starttag">part</sgmltag> - <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">part</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> - <sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>Overview<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>Overview<tag class="endtag">title</tag> ... - <sgmltag class="endtag">chapter</sgmltag> + <tag class="endtag">chapter</tag> - <sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>What is FreeBSD?<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>What is FreeBSD?<tag class="endtag">title</tag> ... - <sgmltag class="endtag">chapter</sgmltag> + <tag class="endtag">chapter</tag> - <sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>History<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>History<tag class="endtag">title</tag> ... - <sgmltag class="endtag">chapter</sgmltag> -<sgmltag class="endtag">part</sgmltag></programlisting> + <tag class="endtag">chapter</tag> +<tag class="endtag">part</tag></programlisting> </sect2> </sect1> - <sect1 id="docbook-markup-block-elements"> + <sect1 xml:id="docbook-markup-block-elements"> <title>Block Elements</title> - <sect2 id="docbook-markup-paragraphs"> + <sect2 xml:id="docbook-markup-paragraphs"> <title>Paragraphs</title> <para>DocBook supports three types of paragraphs: - <sgmltag>formalpara</sgmltag>, <sgmltag>para</sgmltag>, and - <sgmltag>simpara</sgmltag>.</para> + <tag>formalpara</tag>, <tag>para</tag>, and + <tag>simpara</tag>.</para> <para>Almost all paragraphs in &os; documentation use - <sgmltag>para</sgmltag>. <sgmltag>formalpara</sgmltag> - includes a <sgmltag>title</sgmltag> element, and - <sgmltag>simpara</sgmltag> disallows some elements from - within <sgmltag>para</sgmltag>. Stick with - <sgmltag>para</sgmltag>.</para> + <tag>para</tag>. <tag>formalpara</tag> + includes a <tag>title</tag> element, and + <tag>simpara</tag> disallows some elements from + within <tag>para</tag>. Stick with + <tag>para</tag>.</para> <example> - <title><sgmltag>para</sgmltag></title> + <title><tag>para</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>This is a paragraph. It can contain just about any - other element.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>This is a paragraph. It can contain just about any + other element.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -689,7 +679,7 @@ </example> </sect2> - <sect2 id="docbook-markup-block-quotations"> + <sect2 xml:id="docbook-markup-block-quotations"> <title>Block Quotations</title> <para>A block quotation is an extended quotation from another @@ -701,24 +691,24 @@ unattributed).</para> <example> - <title><sgmltag>blockquote</sgmltag></title> + <title><tag>blockquote</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>A small excerpt from the US Constitution:<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>A small excerpt from the US Constitution:<tag class="endtag">para</tag> -<sgmltag class="starttag">blockquote</sgmltag> - <sgmltag class="starttag">title</sgmltag>Preamble to the Constitution of the United States<sgmltag class="endtag">title</sgmltag> +<tag class="starttag">blockquote</tag> + <tag class="starttag">title</tag>Preamble to the Constitution of the United States<tag class="endtag">title</tag> - <sgmltag class="starttag">attribution</sgmltag>Copied from a web site somewhere<sgmltag class="endtag">attribution</sgmltag> + <tag class="starttag">attribution</tag>Copied from a web site somewhere<tag class="endtag">attribution</tag> - <sgmltag class="starttag">para</sgmltag>We the People of the United States, in Order to form a more + <tag class="starttag">para</tag>We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of - America.<sgmltag class="endtag">para</sgmltag> -<sgmltag class="endtag">blockquote</sgmltag></programlisting> + America.<tag class="endtag">para</tag> +<tag class="endtag">blockquote</tag></programlisting> <para>Appearance:</para> @@ -742,7 +732,7 @@ </example> </sect2> - <sect2 id="docbook-markup-tips-notes"> + <sect2 xml:id="docbook-markup-tips-notes"> <title>Tips, Notes, Warnings, Cautions, Important Information and Sidebars</title> @@ -752,11 +742,11 @@ aware.</para> <para>Depending on the nature of the information, one of - <sgmltag>tip</sgmltag>, <sgmltag>note</sgmltag>, - <sgmltag>warning</sgmltag>, <sgmltag>caution</sgmltag>, and - <sgmltag>important</sgmltag> should be used. Alternatively, + <tag>tip</tag>, <tag>note</tag>, + <tag>warning</tag>, <tag>caution</tag>, and + <tag>important</tag> should be used. Alternatively, if the information is related to the main text but is not - one of the above, use <sgmltag>sidebar</sgmltag>.</para> + one of the above, use <tag>sidebar</tag>.</para> <para>The circumstances in which to choose one of these elements over another is loosely defined by the DocBook @@ -784,14 +774,14 @@ </itemizedlist> <example> - <title><sgmltag>warning</sgmltag></title> + <title><tag>warning</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">warning</sgmltag> - <sgmltag class="starttag">para</sgmltag>Installing FreeBSD may make you want to delete Windows from your - hard disk.<sgmltag class="endtag">para</sgmltag> -<sgmltag class="endtag">warning</sgmltag></programlisting> + <programlisting><tag class="starttag">warning</tag> + <tag class="starttag">para</tag>Installing FreeBSD may make you want to delete Windows from your + hard disk.<tag class="endtag">para</tag> +<tag class="endtag">warning</tag></programlisting> </example> <para>Appearance:</para> @@ -802,76 +792,76 @@ </warning> </sect2> - <sect2 id="docbook-markup-lists-and-procedures"> + <sect2 xml:id="docbook-markup-lists-and-procedures"> <title>Lists and Procedures</title> <para>Information often needs to be presented as lists, or as a number of steps that must be carried out in order to accomplish a particular goal.</para> - <para>To do this, use <sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, or - <sgmltag>procedure</sgmltag><footnote><para>There are other + <para>To do this, use <tag>itemizedlist</tag>, + <tag>orderedlist</tag>, or + <tag>procedure</tag><footnote><para>There are other types of list element in DocBook, but we are not concerned with those at the moment.</para></footnote></para> - <para><sgmltag>itemizedlist</sgmltag> and - <sgmltag>orderedlist</sgmltag> are similar to their - counterparts in <acronym>HTML</acronym>, <sgmltag>ul</sgmltag> - and <sgmltag>ol</sgmltag>. Each one consists of one or more - <sgmltag>listitem</sgmltag> elements, and each - <sgmltag>listitem</sgmltag> contains one or more block - elements. The <sgmltag>listitem</sgmltag> elements are - analogous to <acronym>HTML</acronym>'s <sgmltag>li</sgmltag> + <para><tag>itemizedlist</tag> and + <tag>orderedlist</tag> are similar to their + counterparts in <acronym>HTML</acronym>, <tag>ul</tag> + and <tag>ol</tag>. Each one consists of one or more + <tag>listitem</tag> elements, and each + <tag>listitem</tag> contains one or more block + elements. The <tag>listitem</tag> elements are + analogous to <acronym>HTML</acronym>'s <tag>li</tag> tags. However, unlike HTML, they are required.</para> - <para><sgmltag>procedure</sgmltag> is slightly different. It - consists of <sgmltag>step</sgmltag>s, which may in turn - consists of more <sgmltag>step</sgmltag>s or - <sgmltag>substep</sgmltag>s. Each <sgmltag>step</sgmltag> + <para><tag>procedure</tag> is slightly different. It + consists of <tag>step</tag>s, which may in turn + consists of more <tag>step</tag>s or + <tag>substep</tag>s. Each <tag>step</tag> contains block elements.</para> <example> - <title><sgmltag>itemizedlist</sgmltag>, - <sgmltag>orderedlist</sgmltag>, and - <sgmltag>procedure</sgmltag></title> + <title><tag>itemizedlist</tag>, + <tag>orderedlist</tag>, and + <tag>procedure</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">itemizedlist</sgmltag> - <sgmltag class="starttag">listitem</sgmltag> - <sgmltag class="starttag">para</sgmltag>This is the first itemized item.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">listitem</sgmltag> + <programlisting><tag class="starttag">itemizedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> - <sgmltag class="starttag">listitem</sgmltag> - <sgmltag class="starttag">para</sgmltag>This is the second itemized item.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">listitem</sgmltag> -<sgmltag class="endtag">itemizedlist</sgmltag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second itemized item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">itemizedlist</tag> -<sgmltag class="starttag">orderedlist</sgmltag> - <sgmltag class="starttag">listitem</sgmltag> - <sgmltag class="starttag">para</sgmltag>This is the first ordered item.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">listitem</sgmltag> +<tag class="starttag">orderedlist</tag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the first ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> - <sgmltag class="starttag">listitem</sgmltag> - <sgmltag class="starttag">para</sgmltag>This is the second ordered item.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">listitem</sgmltag> -<sgmltag class="endtag">orderedlist</sgmltag> + <tag class="starttag">listitem</tag> + <tag class="starttag">para</tag>This is the second ordered item.<tag class="endtag">para</tag> + <tag class="endtag">listitem</tag> +<tag class="endtag">orderedlist</tag> -<sgmltag class="starttag">procedure</sgmltag> - <sgmltag class="starttag">step</sgmltag> - <sgmltag class="starttag">para</sgmltag>Do this.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">step</sgmltag> +<tag class="starttag">procedure</tag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> - <sgmltag class="starttag">step</sgmltag> - <sgmltag class="starttag">para</sgmltag>Then do this.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">step</sgmltag> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>Then do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> - <sgmltag class="starttag">step</sgmltag> - <sgmltag class="starttag">para</sgmltag>And now do this.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">step</sgmltag> -<sgmltag class="endtag">procedure</sgmltag></programlisting> + <tag class="starttag">step</tag> + <tag class="starttag">para</tag>And now do this.<tag class="endtag">para</tag> + <tag class="endtag">step</tag> +<tag class="endtag">procedure</tag></programlisting> <para>Appearance:</para> @@ -911,15 +901,15 @@ </example> </sect2> - <sect2 id="docbook-markup-showing-file-samples"> + <sect2 xml:id="docbook-markup-showing-file-samples"> <title>Showing File Samples</title> <para>Fragments of a file (or perhaps a complete file) are shown - by wrapping them in the <sgmltag>programlisting</sgmltag> + by wrapping them in the <tag>programlisting</tag> element.</para> <para>White space and line breaks within - <sgmltag>programlisting</sgmltag> <emphasis>are</emphasis> + <tag>programlisting</tag> <emphasis>are</emphasis> significant. In particular, this means that the opening tag should appear on the same line as the first line of the output, and the closing tag should appear on the same line @@ -927,20 +917,20 @@ lines may be included.</para> <example> - <title><sgmltag>programlisting</sgmltag></title> + <title><tag>programlisting</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>When finished, the program will look like - this:<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> -<sgmltag class="starttag">programlisting</sgmltag>#include &lt;stdio.h&gt; +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; int main(void) { printf("hello, world\n"); -}<sgmltag class="endtag">programlisting</sgmltag></programlisting> +}<tag class="endtag">programlisting</tag></programlisting> <para>Notice how the angle brackets in the <literal>#include</literal> line need to be referenced by @@ -960,60 +950,60 @@ main(void) </example> </sect2> - <sect2 id="docbook-markup-callouts"> + <sect2 xml:id="docbook-markup-callouts"> <title>Callouts</title> <para>A callout is a visual marker for referring to a piece of text or specific position within an example.</para> - <para>Callouts are marked with the <sgmltag>co</sgmltag> + <para>Callouts are marked with the <tag>co</tag> element. Each element must have a unique <literal>id</literal> assigned to it. After the example, - include a <sgmltag>calloutlist</sgmltag> that describes each + include a <tag>calloutlist</tag> that describes each callout.</para> <example> - <title><sgmltag>co</sgmltag> and - <sgmltag>calloutlist</sgmltag></title> + <title><tag>co</tag> and + <tag>calloutlist</tag></title> - <programlisting><sgmltag class="starttag">para</sgmltag>When finished, the program will look like - this:<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>When finished, the program will look like + this:<tag class="endtag">para</tag> -<sgmltag class="starttag">programlisting</sgmltag>#include &lt;stdio.h&gt; <sgmltag class="emptytag">co id="co-ex-include"</sgmltag> +<tag class="starttag">programlisting</tag>#include &lt;stdio.h&gt; <tag class="emptytag">co id="co-ex-include"</tag> -int <sgmltag class="emptytag">co id="co-ex-return"</sgmltag> +int <tag class="emptytag">co id="co-ex-return"</tag> main(void) { - printf("hello, world\n"); <sgmltag class="emptytag">co id="co-ex-printf"</sgmltag> -}<sgmltag class="endtag">programlisting</sgmltag> + printf("hello, world\n"); <tag class="emptytag">co id="co-ex-printf"</tag> +}<tag class="endtag">programlisting</tag> -<sgmltag class="starttag">calloutlist</sgmltag> - <sgmltag class="starttag">callout arearefs="co-ex-include"</sgmltag> - <sgmltag class="starttag">para</sgmltag>Includes the standard IO header file.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">callout</sgmltag> +<tag class="starttag">calloutlist</tag> + <tag class="starttag">callout arearefs="co-ex-include"</tag> + <tag class="starttag">para</tag>Includes the standard IO header file.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> - <sgmltag class="starttag">callout arearefs="co-ex-return"</sgmltag> - <sgmltag class="starttag">para</sgmltag>Specifies that <sgmltag class="starttag">function</sgmltag>main()<sgmltag class="endtag">function</sgmltag> returns an - int.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">callout</sgmltag> + <tag class="starttag">callout arearefs="co-ex-return"</tag> + <tag class="starttag">para</tag>Specifies that <tag class="starttag">function</tag>main()<tag class="endtag">function</tag> returns an + int.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> - <sgmltag class="starttag">callout arearefs="co-ex-printf"</sgmltag> - <sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">function</sgmltag>printf()<sgmltag class="endtag">function</sgmltag> call that writes - <sgmltag class="starttag">literal</sgmltag>hello, world<sgmltag class="endtag">literal</sgmltag> to standard output.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">callout</sgmltag> -<sgmltag class="endtag">calloutlist</sgmltag></programlisting> + <tag class="starttag">callout arearefs="co-ex-printf"</tag> + <tag class="starttag">para</tag>The <tag class="starttag">function</tag>printf()<tag class="endtag">function</tag> call that writes + <tag class="starttag">literal</tag>hello, world<tag class="endtag">literal</tag> to standard output.<tag class="endtag">para</tag> + <tag class="endtag">callout</tag> +<tag class="endtag">calloutlist</tag></programlisting> <para>Appearance:</para> <para>When finished, the program will look like this:</para> - <programlisting>#include <stdio.h> <co id="co-ex-include"/> + <programlisting>#include <stdio.h> <co xml:id="co-ex-include"/> -int <co id="co-ex-return"/> +int <co xml:id="co-ex-return"/> main(void) { - printf("hello, world\n"); <co id="co-ex-printf"/> + printf("hello, world\n"); <co xml:id="co-ex-printf"/> }</programlisting> <calloutlist> @@ -1035,7 +1025,7 @@ main(void) </example> </sect2> - <sect2 id="docbook-markup-tables"> + <sect2 xml:id="docbook-markup-tables"> <title>Tables</title> <para>Unlike <acronym>HTML</acronym>, DocBook does not need @@ -1045,48 +1035,48 @@ main(void) <para>In general terms (and see the DocBook documentation for more detail) a table (which can be either formal or informal) - consists of a <sgmltag>table</sgmltag> element. This contains - at least one <sgmltag>tgroup</sgmltag> element, which + consists of a <tag>table</tag> element. This contains + at least one <tag>tgroup</tag> element, which specifies (as an attribute) the number of columns in this table group. Within the tablegroup there is one - <sgmltag>thead</sgmltag> element, which contains elements for + <tag>thead</tag> element, which contains elements for the table headings (column headings), and one - <sgmltag>tbody</sgmltag> which contains the body of the + <tag>tbody</tag> which contains the body of the table.</para> - <para>Both <sgmltag>tgroup</sgmltag> and - <sgmltag>thead</sgmltag> contain <sgmltag>row</sgmltag> - elements, which in turn contain <sgmltag>entry</sgmltag> - elements. Each <sgmltag>entry</sgmltag> element specifies + <para>Both <tag>tgroup</tag> and + <tag>thead</tag> contain <tag>row</tag> + elements, which in turn contain <tag>entry</tag> + elements. Each <tag>entry</tag> element specifies one cell in the table.</para> <example> - <title><sgmltag>informaltable</sgmltag></title> + <title><tag>informaltable</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">informaltable pgwide="1"</sgmltag> - <sgmltag class="starttag">tgroup cols="2"</sgmltag> - <sgmltag class="starttag">thead</sgmltag> - <sgmltag class="starttag">row</sgmltag> - <sgmltag class="starttag">entry</sgmltag>This is Column Head 1<sgmltag class="endtag">entry</sgmltag> - <sgmltag class="starttag">entry</sgmltag>This is Column Head 2<sgmltag class="endtag">entry</sgmltag> - <sgmltag class="endtag">row</sgmltag> - <sgmltag class="endtag">thead</sgmltag> - - <sgmltag class="starttag">tbody</sgmltag> - <sgmltag class="starttag">row</sgmltag> - <sgmltag class="starttag">entry</sgmltag>Row 1, column 1<sgmltag class="endtag">entry</sgmltag> - <sgmltag class="starttag">entry</sgmltag>Row 1, column 2<sgmltag class="endtag">entry</sgmltag> - <sgmltag class="endtag">row</sgmltag> - - <sgmltag class="starttag">row</sgmltag> - <sgmltag class="starttag">entry</sgmltag>Row 2, column 1<sgmltag class="endtag">entry</sgmltag> - <sgmltag class="starttag">entry</sgmltag>Row 2, column 2<sgmltag class="endtag">entry</sgmltag> - <sgmltag class="endtag">row</sgmltag> - <sgmltag class="endtag">tbody</sgmltag> - <sgmltag class="endtag">tgroup</sgmltag> -<sgmltag class="endtag">informaltable</sgmltag></programlisting> + <programlisting><tag class="starttag">informaltable pgwide="1"</tag> + <tag class="starttag">tgroup cols="2"</tag> + <tag class="starttag">thead</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>This is Column Head 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>This is Column Head 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">thead</tag> + + <tag class="starttag">tbody</tag> + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 1, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 1, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + + <tag class="starttag">row</tag> + <tag class="starttag">entry</tag>Row 2, column 1<tag class="endtag">entry</tag> + <tag class="starttag">entry</tag>Row 2, column 2<tag class="endtag">entry</tag> + <tag class="endtag">row</tag> + <tag class="endtag">tbody</tag> + <tag class="endtag">tgroup</tag> +<tag class="endtag">informaltable</tag></programlisting> <para>Appearance:</para> @@ -1116,15 +1106,15 @@ main(void) <para>Always use the <literal>pgwide</literal> attribute with a value of <literal>1</literal> with the - <sgmltag>informaltable</sgmltag> element. A bug in Internet + <tag>informaltable</tag> element. A bug in Internet Explorer can cause the table to render incorrectly if this is omitted.</para> <para>Table borders can be suppressed by setting the <literal>frame</literal> attribute to <literal>none</literal> - in the <sgmltag>informaltable</sgmltag> element. For example, - <literal><sgmltag class="starttag">informaltable - frame="none"</sgmltag></literal>.</para> + in the <tag>informaltable</tag> element. For example, + <literal>informaltable + frame="none"</literal>.</para> <example> <title>Tables Where <literal>frame="none"</literal></title> @@ -1156,7 +1146,7 @@ main(void) </example> </sect2> - <sect2 id="docbook-markup-examples"> + <sect2 xml:id="docbook-markup-examples"> <title>Examples for the User to Follow</title> <para>Examples for the user to follow are often necessary. @@ -1169,20 +1159,20 @@ main(void) <variablelist> <varlistentry> - <term><sgmltag>screen</sgmltag></term> + <term><tag>screen</tag></term> <listitem> <para>Everything the user sees in this example will be on the computer screen, so the next element is - <sgmltag>screen</sgmltag>.</para> + <tag>screen</tag>.</para> - <para>Within <sgmltag>screen</sgmltag>, white space is + <para>Within <tag>screen</tag>, white space is significant.</para> </listitem> </varlistentry> <varlistentry> - <term><sgmltag>prompt</sgmltag>, + <term><tag>prompt</tag>, <literal>&prompt.root;</literal> and <literal>&prompt.user;</literal></term> @@ -1191,7 +1181,7 @@ main(void) screen are prompts from the computer (either from the operating system, command shell, or application). These should be marked up using - <sgmltag>prompt</sgmltag>.</para> + <tag>prompt</tag>.</para> <para>As a special case, the two shell prompts for the normal user and the root user have been provided as @@ -1199,7 +1189,7 @@ main(void) use one of <literal>&prompt.root;</literal> and <literal>&prompt.user;</literal> as necessary. They do not need to be inside - <sgmltag>prompt</sgmltag>.</para> + <tag>prompt</tag>.</para> <note> <para><literal>&prompt.root;</literal> and @@ -1211,32 +1201,32 @@ main(void) </varlistentry> <varlistentry> - <term><sgmltag>userinput</sgmltag></term> + <term><tag>userinput</tag></term> <listitem> <para>When displaying text that the user should type in, - wrap it in <sgmltag>userinput</sgmltag> tags. It will + wrap it in <tag>userinput</tag> tags. It will be displayed differently than system output text.</para> </listitem> </varlistentry> </variablelist> <example> - <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, - and <sgmltag>userinput</sgmltag></title> + <title><tag>screen</tag>, <tag>prompt</tag>, + and <tag>userinput</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">screen</sgmltag>&prompt.user; <sgmltag class="starttag">userinput</sgmltag>ls -1<sgmltag class="endtag">userinput</sgmltag> + <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>ls -1<tag class="endtag">userinput</tag> foo1 foo2 foo3 -&prompt.user; <sgmltag class="starttag">userinput</sgmltag>ls -1 | grep foo2<sgmltag class="endtag">userinput</sgmltag> +&prompt.user; <tag class="starttag">userinput</tag>ls -1 | grep foo2<tag class="endtag">userinput</tag> foo2 -&prompt.user; <sgmltag class="starttag">userinput</sgmltag>su<sgmltag class="endtag">userinput</sgmltag> -<sgmltag class="starttag">prompt</sgmltag>Password: <sgmltag class="endtag">prompt</sgmltag> -&prompt.root; <sgmltag class="starttag">userinput</sgmltag>cat foo2<sgmltag class="endtag">userinput</sgmltag> -This is the file called 'foo2'<sgmltag class="endtag">screen</sgmltag></programlisting> +&prompt.user; <tag class="starttag">userinput</tag>su<tag class="endtag">userinput</tag> +<tag class="starttag">prompt</tag>Password: <tag class="endtag">prompt</tag> +&prompt.root; <tag class="starttag">userinput</tag>cat foo2<tag class="endtag">userinput</tag> +This is the file called 'foo2'<tag class="endtag">screen</tag></programlisting> <para>Appearance:</para> @@ -1255,40 +1245,40 @@ This is the file called 'foo2'</screen> <note> <para>Even though we are displaying the contents of the file <filename>foo2</filename>, it is <emphasis>not</emphasis> - marked up as <sgmltag>programlisting</sgmltag>. Reserve - <sgmltag>programlisting</sgmltag> for showing fragments of + marked up as <tag>programlisting</tag>. Reserve + <tag>programlisting</tag> for showing fragments of files outside the context of user actions.</para> </note> </sect2> </sect1> - <sect1 id="docbook-markup-inline-elements"> + <sect1 xml:id="docbook-markup-inline-elements"> <title>In-line Elements</title> - <sect2 id="docbook-markup-inline-emphasizing"> + <sect2 xml:id="docbook-markup-inline-emphasizing"> <title>Emphasizing Information</title> <para>To emphasize a particular word or phrase, use - <sgmltag>emphasis</sgmltag>. This may be presented as + <tag>emphasis</tag>. This may be presented as italic, or bold, or might be spoken differently with a text-to-speech system.</para> <para>There is no way to change the presentation of the emphasis within the document, no equivalent of - <acronym>HTML</acronym>'s <sgmltag>b</sgmltag> and - <sgmltag>i</sgmltag>. If the information being presented is + <acronym>HTML</acronym>'s <tag>b</tag> and + <tag>i</tag>. If the information being presented is important, then consider presenting it in - <sgmltag>important</sgmltag> rather than - <sgmltag>emphasis</sgmltag>.</para> + <tag>important</tag> rather than + <tag>emphasis</tag>.</para> <example> - <title><sgmltag>emphasis</sgmltag></title> + <title><tag>emphasis</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>FreeBSD is without doubt <sgmltag class="starttag">emphasis</sgmltag>the<sgmltag class="endtag">emphasis</sgmltag> + <programlisting><tag class="starttag">para</tag>FreeBSD is without doubt <tag class="starttag">emphasis</tag>the<tag class="endtag">emphasis</tag> premiere &unix;-like operating system for the Intel - architecture.<sgmltag class="endtag">para</sgmltag></programlisting> + architecture.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1298,13 +1288,13 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-acronyms"> + <sect2 xml:id="docbook-markup-acronyms"> <title>Acronyms</title> <para>Many computer terms are <emphasis>acronyms</emphasis>, words formed from the first letter of each word in a phrase. Acronyms are marked up into - <sgmltag>acronym</sgmltag> elements. It is helpful to the + <tag>acronym</tag> elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below.</para> @@ -1313,11 +1303,11 @@ This is the file called 'foo2'</screen> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Request For Comments (<sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag>) 1149 + <programlisting><tag class="starttag">para</tag>Request For Comments (<tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag>) 1149 defined the use of avian carriers for transmission of - Internet Protocol (<sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag>) data. The - quantity of <sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag> data currently - transmitted in that manner is unknown.<sgmltag class="endtag">para</sgmltag></programlisting> + Internet Protocol (<tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag>) data. The + quantity of <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> data currently + transmitted in that manner is unknown.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1329,23 +1319,23 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-quotations"> + <sect2 xml:id="docbook-markup-quotations"> <title>Quotations</title> <para>To quote text from another document or source, or to denote a phrase that is used figuratively, use - <sgmltag>quote</sgmltag>. Most of the markup tags available + <tag>quote</tag>. Most of the markup tags available for normal text are also available from within a - <sgmltag>quote</sgmltag>.</para> + <tag>quote</tag>.</para> <example> <title>Quotations</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>However, make sure that the search does not go beyond the - <sgmltag class="starttag">quote</sgmltag>boundary between local and public administration<sgmltag class="endtag">quote</sgmltag>, - as <sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag> 1535 calls it.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>However, make sure that the search does not go beyond the + <tag class="starttag">quote</tag>boundary between local and public administration<tag class="endtag">quote</tag>, + as <tag class="starttag">acronym</tag>RFC<tag class="endtag">acronym</tag> 1535 calls it.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1356,16 +1346,16 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-keys"> + <sect2 xml:id="docbook-markup-keys"> <title>Keys, Mouse Buttons, and Combinations</title> <para>To refer to a specific key on the keyboard, use - <sgmltag>keycap</sgmltag>. To refer to a mouse button, use - <sgmltag>mousebutton</sgmltag>. And to refer to + <tag>keycap</tag>. To refer to a mouse button, use + <tag>mousebutton</tag>. And to refer to combinations of key presses or mouse clicks, wrap them all - in <sgmltag>keycombo</sgmltag>.</para> + in <tag>keycombo</tag>.</para> - <para><sgmltag>keycombo</sgmltag> has an attribute called + <para><tag>keycombo</tag> has an attribute called <literal>action</literal>, which may be one of <literal>click</literal>, <literal>double-click</literal>, <literal>other</literal>, <literal>press</literal>, @@ -1375,25 +1365,25 @@ This is the file called 'foo2'</screen> <para>The stylesheets automatically add any connecting symbols, such as <literal>+</literal>, between the key - names, when wrapped in <sgmltag>keycombo</sgmltag>.</para> + names, when wrapped in <tag>keycombo</tag>.</para> <example> <title>Keys, Mouse Buttons, and Combinations</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>To switch to the second virtual terminal, press - <sgmltag class="starttag">keycombo action="simul"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Alt<sgmltag class="endtag">keycap</sgmltag> - <sgmltag class="starttag">keycap</sgmltag>F1<sgmltag class="endtag">keycap</sgmltag><sgmltag class="endtag">keycombo</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>To switch to the second virtual terminal, press + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>F1<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>To exit <sgmltag class="starttag">command</sgmltag>vi<sgmltag class="endtag">command</sgmltag> without saving changes, type - <sgmltag class="starttag">keycombo action="seq"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Esc<sgmltag class="endtag">keycap</sgmltag><sgmltag class="starttag">keycap</sgmltag>:<sgmltag class="endtag">keycap</sgmltag> - <sgmltag class="starttag">keycap</sgmltag>q<sgmltag class="endtag">keycap</sgmltag><sgmltag class="starttag">keycap</sgmltag>!<sgmltag class="endtag">keycap</sgmltag><sgmltag class="endtag">keycombo</sgmltag>.<sgmltag class="endtag">para</sgmltag> +<tag class="starttag">para</tag>To exit <tag class="starttag">command</tag>vi<tag class="endtag">command</tag> without saving changes, type + <tag class="starttag">keycombo action="seq"</tag><tag class="starttag">keycap</tag>Esc<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>:<tag class="endtag">keycap</tag> + <tag class="starttag">keycap</tag>q<tag class="endtag">keycap</tag><tag class="starttag">keycap</tag>!<tag class="endtag">keycap</tag><tag class="endtag">keycombo</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>My window manager is configured so that - <sgmltag class="starttag">keycombo action="simul"</sgmltag><sgmltag class="starttag">keycap</sgmltag>Alt<sgmltag class="endtag">keycap</sgmltag> - <sgmltag class="starttag">mousebutton</sgmltag>right<sgmltag class="endtag">mousebutton</sgmltag> - <sgmltag class="endtag">keycombo</sgmltag> mouse button is used to move windows.<sgmltag class="endtag">para</sgmltag></programlisting> +<tag class="starttag">para</tag>My window manager is configured so that + <tag class="starttag">keycombo action="simul"</tag><tag class="starttag">keycap</tag>Alt<tag class="endtag">keycap</tag> + <tag class="starttag">mousebutton</tag>right<tag class="endtag">mousebutton</tag> + <tag class="endtag">keycombo</tag> mouse button is used to move windows.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1416,7 +1406,7 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-applications"> + <sect2 xml:id="docbook-markup-applications"> <title>Applications, Commands, Options, and Cites</title> <para>Both applications and commands are frequently referred to @@ -1434,23 +1424,23 @@ This is the file called 'foo2'</screen> format so common in Unix manuals.</para> <para>Mark up application names with - <sgmltag>application</sgmltag>.</para> + <tag>application</tag>.</para> <para>To list a command with its manual section number (which should be most of the time) the DocBook - element is <sgmltag>citerefentry</sgmltag>. This will + element is <tag>citerefentry</tag>. This will contain a further two elements, - <sgmltag>refentrytitle</sgmltag> and - <sgmltag>manvolnum</sgmltag>. The content of - <sgmltag>refentrytitle</sgmltag> is the name of the command, - and the content of <sgmltag>manvolnum</sgmltag> is the + <tag>refentrytitle</tag> and + <tag>manvolnum</tag>. The content of + <tag>refentrytitle</tag> is the name of the command, + and the content of <tag>manvolnum</tag> is the manual page section.</para> <para>This can be cumbersome to write, and so a series of <link linkend="xml-primer-general-entities">general entities</link> have been created to make this easier. Each entity takes the form - <literal>&man.<replaceable>manual-page</replaceable>.<replaceable>manual-section</replaceable>;</literal>.</para> + <literal>&man.manual-page.manual-section;</literal>.</para> <para>The file that contains these entities is in <filename>doc/share/xml/man-refs.ent</filename>, and can be @@ -1470,18 +1460,18 @@ This is the file called 'foo2'</screen> ]></programlisting> - <para>Use <sgmltag>command</sgmltag> when to include a command + <para>Use <tag>command</tag> when to include a command name <quote>in-line</quote> but present it as something the user should type in.</para> - <para>Use <sgmltag>option</sgmltag> to mark up the options + <para>Use <tag>option</tag> to mark up the options which will be passed to a command.</para> <para>When referring to the same command multiple times in close proximity, it is preferred to use the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + <literal>&man.command.section;</literal> notation to markup the first reference and use - <sgmltag>command</sgmltag> to markup subsequent references. + <tag>command</tag> to markup subsequent references. This makes the generated output, especially <acronym>HTML</acronym>, appear visually better.</para> @@ -1490,22 +1480,22 @@ This is the file called 'foo2'</screen> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">application</sgmltag>Sendmail<sgmltag class="endtag">application</sgmltag> is the most - widely used Unix mail application.<sgmltag class="starttag">para</sgmltag> + <programlisting><tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> is the most + widely used Unix mail application.<tag class="starttag">para</tag> -<sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">application</sgmltag>Sendmail<sgmltag class="endtag">application</sgmltag> includes the - <sgmltag class="starttag">citerefentry</sgmltag> - <sgmltag class="starttag">refentrytitle</sgmltag>sendmail<sgmltag class="endtag">refentrytitle</sgmltag> - <sgmltag class="starttag">manvolnum</sgmltag>8<sgmltag class="endtag">manvolnum</sgmltag> - <sgmltag class="endtag">citerefentry</sgmltag>, &man.mailq.1;, and &man.newaliases.1; - programs.<sgmltag class="endtag">para</sgmltag> +<tag class="starttag">para</tag><tag class="starttag">application</tag>Sendmail<tag class="endtag">application</tag> includes the + <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, &man.mailq.1;, and &man.newaliases.1; + programs.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>One of the command line parameters to <sgmltag class="starttag">citerefentry</sgmltag> - <sgmltag class="starttag">refentrytitle</sgmltag>sendmail<sgmltag class="endtag">refentrytitle</sgmltag> - <sgmltag class="starttag">manvolnum</sgmltag>8<sgmltag class="endtag">manvolnum</sgmltag> - <sgmltag class="endtag">citerefentry</sgmltag>, <sgmltag class="starttag">option</sgmltag>-bp<sgmltag class="endtag">option</sgmltag>, will display the current +<tag class="starttag">para</tag>One of the command line parameters to <tag class="starttag">citerefentry</tag> + <tag class="starttag">refentrytitle</tag>sendmail<tag class="endtag">refentrytitle</tag> + <tag class="starttag">manvolnum</tag>8<tag class="endtag">manvolnum</tag> + <tag class="endtag">citerefentry</tag>, <tag class="starttag">option</tag>-bp<tag class="endtag">option</tag>, will display the current status of messages in the mail queue. Check this on the command - line by running <sgmltag class="starttag">command</sgmltag>sendmail -bp<sgmltag class="endtag">command</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + line by running <tag class="starttag">command</tag>sendmail -bp<tag class="endtag">command</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1531,28 +1521,28 @@ This is the file called 'foo2'</screen> <note> <para>Notice how the - <literal>&man.<replaceable>command</replaceable>.<replaceable>section</replaceable>;</literal> + <literal>&man.command.section;</literal> notation is easier to follow.</para> </note> </sect2> - <sect2 id="docbook-markup-files"> + <sect2 xml:id="docbook-markup-files"> <title>Files, Directories, Extensions</title> <para>To refer to the name of a file, a directory, or a file - extension, use <sgmltag>filename</sgmltag>.</para> + extension, use <tag>filename</tag>.</para> <example> - <title><sgmltag>filename</sgmltag></title> + <title><tag>filename</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>The XML source for the Handbook in English is - found in <sgmltag class="starttag">filename class="directory"</sgmltag>/usr/doc/en_US.ISO8859-1/books/handbook/<sgmltag class="endtag">filename</sgmltag>. The first - file is called <sgmltag class="starttag">filename</sgmltag>book.xml<sgmltag class="endtag">filename</sgmltag> in that - directory. There is also a <sgmltag class="starttag">filename</sgmltag>Makefile<sgmltag class="endtag">filename</sgmltag> - and a number of files with a <sgmltag class="starttag">filename</sgmltag>.ent<sgmltag class="endtag">filename</sgmltag> - extension.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>The XML source for the Handbook in English is + found in <tag class="starttag">filename class="directory"</tag>/usr/doc/en_US.ISO8859-1/books/handbook/<tag class="endtag">filename</tag>. The first + file is called <tag class="starttag">filename</tag>book.xml<tag class="endtag">filename</tag> in that + directory. There is also a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> + and a number of files with a <tag class="starttag">filename</tag>.ent<tag class="endtag">filename</tag> + extension.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1565,7 +1555,7 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-name-of-ports"> + <sect2 xml:id="docbook-markup-name-of-ports"> <title>The Name of Ports</title> <note> @@ -1578,7 +1568,7 @@ This is the file called 'foo2'</screen> <para>To include the name of a program from the &os; Ports Collection in the document, use the - <sgmltag>filename</sgmltag> tag with the + <tag>filename</tag> tag with the <literal>role</literal> attribute set to <literal>package</literal>. Since ports can be installed in any number of locations, only include the category and the @@ -1586,22 +1576,21 @@ This is the file called 'foo2'</screen> <filename>/usr/ports</filename>.</para> <example> - <title><sgmltag>filename</sgmltag> Tag with + <title><tag>filename</tag> Tag with <literal>package</literal> Role</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Install the <sgmltag class="starttag">filename role="package"</sgmltag>net/wireshark<sgmltag class="endtag">filename</sgmltag> port to view network traffic.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Install the <tag class="starttag">filename role="package"</tag>net/wireshark<tag class="endtag">filename</tag> port to view network traffic.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> - <para>Install the <filename - role="package">net/wireshark</filename> port to view + <para>Install the <package>net/wireshark</package> port to view network traffic.</para> </example> </sect2> - <sect2 id="docbook-markup-devices"> + <sect2 xml:id="docbook-markup-devices"> <title>Devices</title> <note> @@ -1615,7 +1604,7 @@ This is the file called 'foo2'</screen> <para>There are two names for devices: the device name as it appears in <filename>/dev</filename>, or the name of the device as it appears in the kernel. For this latter course, - use <sgmltag>devicename</sgmltag>.</para> + use <tag>devicename</tag>.</para> <para>Sometimes there is no choice. Some devices, such as network cards, do not have entries in @@ -1623,42 +1612,42 @@ This is the file called 'foo2'</screen> different from their kernel device names.</para> <example> - <title><sgmltag>devicename</sgmltag></title> + <title><tag>devicename</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">devicename</sgmltag>sio<sgmltag class="endtag">devicename</sgmltag> is used for serial - communication in FreeBSD. <sgmltag class="starttag">devicename</sgmltag>sio<sgmltag class="endtag">devicename</sgmltag> manifests - through a number of entries in <sgmltag class="starttag">filename</sgmltag>/dev<sgmltag class="endtag">filename</sgmltag>, including - <sgmltag class="starttag">filename</sgmltag>/dev/ttyd0<sgmltag class="endtag">filename</sgmltag> and <sgmltag class="starttag">filename</sgmltag>/dev/cuaa0<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag><tag class="starttag">devicename</tag>sio<tag class="endtag">devicename</tag> is used for serial + communication in FreeBSD. <tag class="starttag">devicename</tag>sio<tag class="endtag">devicename</tag> manifests + through a number of entries in <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>, including + <tag class="starttag">filename</tag>/dev/ttyd0<tag class="endtag">filename</tag> and <tag class="starttag">filename</tag>/dev/cuaa0<tag class="endtag">filename</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>By contrast, network devices such as - <sgmltag class="starttag">devicename</sgmltag>ed0<sgmltag class="endtag">devicename</sgmltag> do not appear in <sgmltag class="starttag">filename</sgmltag>/dev<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag> +<tag class="starttag">para</tag>By contrast, network devices such as + <tag class="starttag">devicename</tag>ed0<tag class="endtag">devicename</tag> do not appear in <tag class="starttag">filename</tag>/dev<tag class="endtag">filename</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>In MS-DOS, the first floppy drive is referred to as - <sgmltag class="starttag">devicename</sgmltag>a:<sgmltag class="endtag">devicename</sgmltag>. In FreeBSD it is - <sgmltag class="starttag">filename</sgmltag>/dev/fd0<sgmltag class="endtag">filename</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> +<tag class="starttag">para</tag>In MS-DOS, the first floppy drive is referred to as + <tag class="starttag">devicename</tag>a:<tag class="endtag">devicename</tag>. In FreeBSD it is + <tag class="starttag">filename</tag>/dev/fd0<tag class="endtag">filename</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> - <para><devicename>sio</devicename> is used for serial - communication in FreeBSD. <devicename>sio</devicename> + <para><filename>sio</filename> is used for serial + communication in FreeBSD. <filename>sio</filename> manifests through a number of entries in <filename>/dev</filename>, including <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> <para>By contrast, network devices such as - <devicename>ed0</devicename> do not appear in + <filename>ed0</filename> do not appear in <filename>/dev</filename>.</para> <para>In MS-DOS, the first floppy drive is referred to as - <devicename>a:</devicename>. In FreeBSD it is + <filename>a:</filename>. In FreeBSD it is <filename>/dev/fd0</filename>.</para> </example> </sect2> - <sect2 id="docbook-markup-hosts"> + <sect2 xml:id="docbook-markup-hosts"> <title>Hosts, Domains, IP Addresses, and So Forth</title> <note> @@ -1671,7 +1660,7 @@ This is the file called 'foo2'</screen> <para>Identification information for networked computers (hosts) can be marked up in several ways, depending on the nature of - the information. All of them use <sgmltag>hostid</sgmltag> as + the information. All of them use <tag>hostid</tag> as the element, with the <literal>role</literal> attribute selecting the type of the marked up information.</para> @@ -1682,7 +1671,7 @@ This is the file called 'foo2'</screen> <listitem> <para>With no <literal>role</literal> attribute (i.e., - <sgmltag>hostid</sgmltag>...<sgmltag>/hostid</sgmltag>) + <tag>hostid</tag>...<tag>/hostid</tag>) the marked up information is the simple hostname, such as <literal>freefall</literal> or <literal>wcarchive</literal>. The hostname can be @@ -1752,57 +1741,57 @@ This is the file called 'foo2'</screen> </variablelist> <example> - <title><sgmltag>hostid</sgmltag> and Roles</title> + <title><tag>hostid</tag> and Roles</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>The local machine can always be referred to by the - name <sgmltag class="starttag">hostid</sgmltag>localhost<sgmltag class="endtag">hostid</sgmltag>, which will have the IP - address <sgmltag class="starttag">hostid role="ipaddr"</sgmltag>127.0.0.1<sgmltag class="endtag">hostid</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>The local machine can always be referred to by the + name <tag class="starttag">hostid</tag>localhost<tag class="endtag">hostid</tag>, which will have the IP + address <tag class="starttag">hostid role="ipaddr"</tag>127.0.0.1<tag class="endtag">hostid</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">hostid role="domainname"</sgmltag>FreeBSD.org<sgmltag class="endtag">hostid</sgmltag> +<tag class="starttag">para</tag>The <tag class="starttag">hostid role="domainname"</tag>FreeBSD.org<tag class="endtag">hostid</tag> domain contains a number of different hosts, including - <sgmltag class="starttag">hostid role="fqdn"</sgmltag>freefall.FreeBSD.org<sgmltag class="endtag">hostid</sgmltag> and - <sgmltag class="starttag">hostid role="fqdn"</sgmltag>bento.FreeBSD.org<sgmltag class="endtag">hostid</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">hostid role="fqdn"</tag>freefall.FreeBSD.org<tag class="endtag">hostid</tag> and + <tag class="starttag">hostid role="fqdn"</tag>bento.FreeBSD.org<tag class="endtag">hostid</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>When adding an <sgmltag class="starttag">acronym</sgmltag>IP<sgmltag class="endtag">acronym</sgmltag> alias to an - interface (using <sgmltag class="starttag">command</sgmltag>ifconfig<sgmltag class="endtag">command</sgmltag>) - <sgmltag class="starttag">emphasis</sgmltag>always<sgmltag class="endtag">emphasis</sgmltag> use a netmask of - <sgmltag class="starttag">hostid role="netmask"</sgmltag>255.255.255.255<sgmltag class="endtag">hostid</sgmltag> (which can +<tag class="starttag">para</tag>When adding an <tag class="starttag">acronym</tag>IP<tag class="endtag">acronym</tag> alias to an + interface (using <tag class="starttag">command</tag>ifconfig<tag class="endtag">command</tag>) + <tag class="starttag">emphasis</tag>always<tag class="endtag">emphasis</tag> use a netmask of + <tag class="starttag">hostid role="netmask"</tag>255.255.255.255<tag class="endtag">hostid</tag> (which can also be expressed as - <sgmltag class="starttag">hostid role="netmask"</sgmltag>0xffffffff<sgmltag class="endtag">hostid</sgmltag>).<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">hostid role="netmask"</tag>0xffffffff<tag class="endtag">hostid</tag>).<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">acronym</sgmltag>MAC<sgmltag class="endtag">acronym</sgmltag> address uniquely identifies +<tag class="starttag">para</tag>The <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address uniquely identifies every network card in existence. A typical - <sgmltag class="starttag">acronym</sgmltag>MAC<sgmltag class="endtag">acronym</sgmltag> address looks like - <sgmltag class="starttag">hostid role="mac"</sgmltag>08:00:20:87:ef:d0<sgmltag class="endtag">hostid</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <tag class="starttag">acronym</tag>MAC<tag class="endtag">acronym</tag> address looks like + <tag class="starttag">hostid role="mac"</tag>08:00:20:87:ef:d0<tag class="endtag">hostid</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>The local machine can always be referred to by the - name <hostid>localhost</hostid>, which will have the IP - address <hostid role="ipaddr">127.0.0.1</hostid>.</para> + name <systemitem>localhost</systemitem>, which will have the IP + address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> - <para>The <hostid role="domainname">FreeBSD.org</hostid> + <para>The <systemitem class="fqdomainname">FreeBSD.org</systemitem> domain contains a number of different hosts, including - <hostid role="fqdn">freefall.FreeBSD.org</hostid> and - <hostid role="fqdn">bento.FreeBSD.org</hostid>.</para> + <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and + <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> <para>When adding an <acronym>IP</acronym> alias to an interface (using <command>ifconfig</command>) <emphasis>always</emphasis> use a netmask of - <hostid role="netmask">255.255.255.255</hostid> (which can + <systemitem class="netmask">255.255.255.255</systemitem> (which can also be expressed as - <hostid role="netmask">0xffffffff</hostid>).</para> + <systemitem class="netmask">0xffffffff</systemitem>).</para> <para>The <acronym>MAC</acronym> address uniquely identifies every network card in existence. A typical <acronym>MAC</acronym> address looks like - <hostid role="mac">08:00:20:87:ef:d0</hostid>.</para> + <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> </example> </sect2> - <sect2 id="docbook-markup-usernames"> + <sect2 xml:id="docbook-markup-usernames"> <title>Usernames</title> <note> @@ -1815,40 +1804,40 @@ This is the file called 'foo2'</screen> <para>To refer to a specific username, such as <literal>root</literal> or <literal>bin</literal>, use - <sgmltag>username</sgmltag>.</para> + <tag>username</tag>.</para> <example> - <title><sgmltag>username</sgmltag></title> + <title><tag>username</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>To carry out most system administration functions - requires logging in as <sgmltag class="starttag">username</sgmltag>root<sgmltag class="endtag">username</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>To carry out most system administration functions + requires logging in as <tag class="starttag">username</tag>root<tag class="endtag">username</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>To carry out most system administration functions - requires logging in as <username>root</username>.</para> + requires logging in as <systemitem class="username">root</systemitem>.</para> </example> </sect2> - <sect2 id="docbook-markup-email-addresses"> + <sect2 xml:id="docbook-markup-email-addresses"> <title>Email Addresses</title> - <para>Email addresses are marked up as <sgmltag>email</sgmltag> + <para>Email addresses are marked up as <tag>email</tag> elements. In the <acronym>HTML</acronym> output format, the wrapped text becomes a hyperlink to the email address. Other output formats that support hyperlinks may also make the email address into a link.</para> <example> - <title><sgmltag>email</sgmltag> with a Hyperlink</title> + <title><tag>email</tag> with a Hyperlink</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>An email address that does not actually exist, like - <sgmltag class="starttag">email</sgmltag>notreal@example.com<sgmltag class="endtag">email</sgmltag>, can be used as an - example.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>An email address that does not actually exist, like + <tag class="starttag">email</tag>notreal@example.com<tag class="endtag">email</tag>, can be used as an + example.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1863,13 +1852,13 @@ This is the file called 'foo2'</screen> address.</para> <example> - <title><sgmltag>email</sgmltag> Without a Hyperlink</title> + <title><tag>email</tag> Without a Hyperlink</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Sometimes a link to an email address like - <sgmltag class="starttag">email role="nolink"</sgmltag>notreal@example.com<sgmltag class="endtag">email</sgmltag> is not - desired.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Sometimes a link to an email address like + <tag class="starttag">email role="nolink"</tag>notreal@example.com<tag class="endtag">email</tag> is not + desired.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1879,7 +1868,7 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-describing-makefiles"> + <sect2 xml:id="docbook-markup-describing-makefiles"> <title>Describing <filename>Makefile</filename>s</title> <note> @@ -1891,57 +1880,57 @@ This is the file called 'foo2'</screen> </note> <para>Two elements exist to describe parts of - <filename>Makefile</filename>s, <sgmltag>maketarget</sgmltag> - and <sgmltag>makevar</sgmltag>.</para> + <filename>Makefile</filename>s, <tag>maketarget</tag> + and <tag>makevar</tag>.</para> - <para><sgmltag>maketarget</sgmltag> identifies a build target + <para><tag>maketarget</tag> identifies a build target exported by a <filename>Makefile</filename> that can be given as a parameter to <command>make</command>. - <sgmltag>makevar</sgmltag> identifies a variable that can be + <tag>makevar</tag> identifies a variable that can be set (in the environment, on the command line with <command>make</command>, or within the <filename>Makefile</filename>) to influence the process.</para> <example> - <title><sgmltag>maketarget</sgmltag> and - <sgmltag>makevar</sgmltag></title> + <title><tag>maketarget</tag> and + <tag>makevar</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Two common targets in a <sgmltag class="starttag">filename</sgmltag>Makefile<sgmltag class="endtag">filename</sgmltag> - are <sgmltag class="starttag">maketarget</sgmltag>all<sgmltag class="endtag">maketarget</sgmltag> and - <sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>Two common targets in a <tag class="starttag">filename</tag>Makefile<tag class="endtag">filename</tag> + are <tag class="starttag">maketarget</tag>all<tag class="endtag">maketarget</tag> and + <tag class="starttag">maketarget</tag>clean<tag class="endtag">maketarget</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>Typically, invoking <sgmltag class="starttag">maketarget</sgmltag>all<sgmltag class="endtag">maketarget</sgmltag> will +<tag class="starttag">para</tag>Typically, invoking <tag class="starttag">maketarget</tag>all<tag class="endtag">maketarget</tag> will rebuild the application, and invoking - <sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag> will remove the temporary - files (<sgmltag class="starttag">filename</sgmltag>.o<sgmltag class="endtag">filename</sgmltag> for example) created by the - build process.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">maketarget</tag>clean<tag class="endtag">maketarget</tag> will remove the temporary + files (<tag class="starttag">filename</tag>.o<tag class="endtag">filename</tag> for example) created by the + build process.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag><sgmltag class="starttag">maketarget</sgmltag>clean<sgmltag class="endtag">maketarget</sgmltag> may be controlled by a - number of variables, including <sgmltag class="starttag">makevar</sgmltag>CLOBBER<sgmltag class="endtag">makevar</sgmltag> - and <sgmltag class="starttag">makevar</sgmltag>RECURSE<sgmltag class="endtag">makevar</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> +<tag class="starttag">para</tag><tag class="starttag">maketarget</tag>clean<tag class="endtag">maketarget</tag> may be controlled by a + number of variables, including <tag class="starttag">makevar</tag>CLOBBER<tag class="endtag">makevar</tag> + and <tag class="starttag">makevar</tag>RECURSE<tag class="endtag">makevar</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>Two common targets in a <filename>Makefile</filename> - are <maketarget>all</maketarget> and - <maketarget>clean</maketarget>.</para> + are <buildtarget>all</buildtarget> and + <buildtarget>clean</buildtarget>.</para> - <para>Typically, invoking <maketarget>all</maketarget> will + <para>Typically, invoking <buildtarget>all</buildtarget> will rebuild the application, and invoking - <maketarget>clean</maketarget> will remove the temporary + <buildtarget>clean</buildtarget> will remove the temporary files (<filename>.o</filename> for example) created by the build process.</para> - <para><maketarget>clean</maketarget> may be controlled by a - number of variables, including <makevar>CLOBBER</makevar> - and <makevar>RECURSE</makevar>.</para> + <para><buildtarget>clean</buildtarget> may be controlled by a + number of variables, including <varname>CLOBBER</varname> + and <varname>RECURSE</varname>.</para> </example> </sect2> - <sect2 id="docbook-markup-literal-text"> + <sect2 xml:id="docbook-markup-literal-text"> <title>Literal Text</title> <para>Literal text, or text which should be entered verbatim, is @@ -1949,25 +1938,25 @@ This is the file called 'foo2'</screen> from another file, or which should be copied exactly as shown from the documentation into another file.</para> - <para>Some of the time, <sgmltag>programlisting</sgmltag> will + <para>Some of the time, <tag>programlisting</tag> will be sufficient to denote this text. But - <sgmltag>programlisting</sgmltag> is not always appropriate, + <tag>programlisting</tag> is not always appropriate, particularly when you want to include a portion of a file <quote>in-line</quote> with the rest of the paragraph.</para> <para>On these occasions, use - <sgmltag>literal</sgmltag>.</para> + <tag>literal</tag>.</para> <example> - <title><sgmltag>literal</sgmltag></title> + <title><tag>literal</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">literal</sgmltag>maxusers 10<sgmltag class="endtag">literal</sgmltag> line in the kernel + <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers 10<tag class="endtag">literal</tag> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will - support.<sgmltag class="endtag">para</sgmltag></programlisting> + support.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -1978,7 +1967,7 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-replaceable"> + <sect2 xml:id="docbook-markup-replaceable"> <title>Showing Items That the User <emphasis>Must</emphasis> Fill In</title> @@ -1987,45 +1976,45 @@ This is the file called 'foo2'</screen> cannot simply copy the example provided. Instead, they must supply some information themselves.</para> - <para><sgmltag>replaceable</sgmltag> is designed for this + <para><tag>replaceable</tag> is designed for this eventuality. Use it <emphasis>inside</emphasis> other elements to indicate parts of that element's content that the user must replace.</para> <example> - <title><sgmltag>replaceable</sgmltag></title> + <title><tag>replaceable</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">screen</sgmltag>&prompt.user; <sgmltag class="starttag">userinput</sgmltag>man <sgmltag class="starttag">replaceable</sgmltag>command<sgmltag class="endtag">replaceable</sgmltag><sgmltag class="endtag">userinput</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting> + <programlisting><tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>man <tag class="starttag">replaceable</tag>command<tag class="endtag">replaceable</tag><tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> <para>Appearance:</para> <informalexample> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>man command</userinput></screen> </informalexample> - <para><sgmltag>replaceable</sgmltag> can be used in many - different elements, including <sgmltag>literal</sgmltag>. - This example also shows that <sgmltag>replaceable</sgmltag> + <para><tag>replaceable</tag> can be used in many + different elements, including <tag>literal</tag>. + This example also shows that <tag>replaceable</tag> should only be wrapped around the content that the user <emphasis>is</emphasis> meant to provide. The other content should be left alone.</para> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>The <sgmltag class="starttag">literal</sgmltag>maxusers <sgmltag class="starttag">replaceable</sgmltag>n<sgmltag class="endtag">replaceable</sgmltag><sgmltag class="endtag">literal</sgmltag> + <programlisting><tag class="starttag">para</tag>The <tag class="starttag">literal</tag>maxusers <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag><tag class="endtag">literal</tag> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will - support.<sgmltag class="endtag">para</sgmltag> + support.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>For a desktop workstation, <sgmltag class="starttag">literal</sgmltag>32<sgmltag class="endtag">literal</sgmltag> is a good value - for <sgmltag class="starttag">replaceable</sgmltag>n<sgmltag class="endtag">replaceable</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> +<tag class="starttag">para</tag>For a desktop workstation, <tag class="starttag">literal</tag>32<tag class="endtag">literal</tag> is a good value + for <tag class="starttag">replaceable</tag>n<tag class="endtag">replaceable</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>The - <literal>maxusers <replaceable>n</replaceable></literal> + <literal>maxusers n</literal> line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.</para> @@ -2035,22 +2024,22 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-gui-buttons"> + <sect2 xml:id="docbook-markup-gui-buttons"> <title>Showing <acronym>GUI</acronym> Buttons</title> <para>Buttons presented by a graphical user interface are marked - with <sgmltag>guibutton</sgmltag>. To make the text look more + with <tag>guibutton</tag>. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text.</para> <example> - <title><sgmltag>guibutton</sgmltag></title> + <title><tag>guibutton</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Edit the file, then click - <sgmltag class="starttag">guibutton</sgmltag>[&nbsp;Save&nbsp;]<sgmltag class="endtag">guibutton</sgmltag> to save the - changes.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Edit the file, then click + <tag class="starttag">guibutton</tag>[&nbsp;Save&nbsp;]<tag class="endtag">guibutton</tag> to save the + changes.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> @@ -2060,19 +2049,19 @@ This is the file called 'foo2'</screen> </example> </sect2> - <sect2 id="docbook-markup-system-errors"> + <sect2 xml:id="docbook-markup-system-errors"> <title>Quoting System Errors</title> <para>System errors generated by &os; are marked with - <sgmltag>errorname</sgmltag>. This indicates the exact error + <tag>errorname</tag>. This indicates the exact error that appears.</para> <example> - <title><sgmltag>errorname</sgmltag></title> + <title><tag>errorname</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">screen</sgmltag><sgmltag class="starttag">errorname</sgmltag>Panic: cannot mount root<sgmltag class="endtag">errorname</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting> + <programlisting><tag class="starttag">screen</tag><tag class="starttag">errorname</tag>Panic: cannot mount root<tag class="endtag">errorname</tag><tag class="endtag">screen</tag></programlisting> <para>Appearance:</para> @@ -2083,7 +2072,7 @@ This is the file called 'foo2'</screen> </sect2> </sect1> - <sect1 id="docbook-markup-images"> + <sect1 xml:id="docbook-markup-images"> <title>Images</title> <important> @@ -2092,9 +2081,9 @@ This is the file called 'foo2'</screen> change, but that is not guaranteed.</para> <para>To provide conversion between different image formats, the - <filename role="package">graphics/ImageMagick</filename> + <package>graphics/ImageMagick</package> port must be installed. This port is not included in the - <filename role="package">textproc/docproj</filename> meta + <package>textproc/docproj</package> meta port, and must be installed separately.</para> <para>A good example of the use of images is the @@ -2105,7 +2094,7 @@ This is the file called 'foo2'</screen> in the rendered document.</para> </important> - <sect2 id="docbook-markup-image-formats"> + <sect2 xml:id="docbook-markup-image-formats"> <title>Image Formats</title> <para>Two image formats are currently supported. The type of @@ -2143,7 +2132,7 @@ This is the file called 'foo2'</screen> </important> </sect2> - <sect2 id="docbook-markup-image-file-locations"> + <sect2 xml:id="docbook-markup-image-file-locations"> <title>Image File Locations</title> <para>Image files can be stored in one of several locations, @@ -2165,15 +2154,14 @@ This is the file called 'foo2'</screen> main document directory, the subdirectory name must be included in their paths in the <filename>Makefile</filename> and the - <sgmltag>imagedata</sgmltag> element.</para> + <tag>imagedata</tag> element.</para> </listitem> <listitem> <para>In a subdirectory of - <filename class="directory">doc/share/images</filename> + <filename>doc/share/images</filename> named after the document. For example, images for the - Handbook are stored in <filename - class="directory">doc/share/images/books/handbook</filename>. + Handbook are stored in <filename>doc/share/images/books/handbook</filename>. Images that work for multiple translations are stored in this upper level of the documentation file tree. Generally, these are images that can be used unchanged in @@ -2182,21 +2170,21 @@ This is the file called 'foo2'</screen> </itemizedlist> </sect2> - <sect2 id="docbook-markup-image-markup"> + <sect2 xml:id="docbook-markup-image-markup"> <title>Image Markup</title> <para>Images are included as part of a - <sgmltag>mediaobject</sgmltag>. The - <sgmltag>mediaobject</sgmltag> can contain other, more + <tag>mediaobject</tag>. The + <tag>mediaobject</tag> can contain other, more specific objects. We are concerned with two, the - <sgmltag>imageobject</sgmltag> and the - <sgmltag>textobject</sgmltag>.</para> + <tag>imageobject</tag> and the + <tag>textobject</tag>.</para> - <para>Include one <sgmltag>imageobject</sgmltag>, and two - <sgmltag>textobject</sgmltag> elements. The - <sgmltag>imageobject</sgmltag> will point to the name of the + <para>Include one <tag>imageobject</tag>, and two + <tag>textobject</tag> elements. The + <tag>imageobject</tag> will point to the name of the image file without the extension. The - <sgmltag>textobject</sgmltag> elements contain information + <tag>textobject</tag> elements contain information that will be presented to the user as well as, or instead of, the image itself.</para> @@ -2212,26 +2200,26 @@ This is the file called 'foo2'</screen> <filename>fig1.png</filename> in a document. The image is a rectangle with an A inside it:</para> - <programlisting><sgmltag class="starttag">mediaobject</sgmltag> - <sgmltag class="starttag">imageobject</sgmltag> - <sgmltag class="starttag">imagedata fileref="fig1"</sgmltag> <co id="co-image-ext"/> - <sgmltag class="endtag">imageobject</sgmltag> + <programlisting><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="starttag">imagedata fileref="fig1"</tag> <co xml:id="co-image-ext"/> + <tag class="endtag">imageobject</tag> - <sgmltag class="starttag">textobject</sgmltag> - <sgmltag class="starttag">literallayout class="monospaced"</sgmltag>+---------------+ <co id="co-image-literal"/> + <tag class="starttag">textobject</tag> + <tag class="starttag">literallayout class="monospaced"</tag>+---------------+ <co xml:id="co-image-literal"/> | A | -+---------------+<sgmltag class="endtag">literallayout</sgmltag> - <sgmltag class="endtag">textobject</sgmltag> ++---------------+<tag class="endtag">literallayout</tag> + <tag class="endtag">textobject</tag> - <sgmltag class="starttag">textobject</sgmltag> - <sgmltag class="starttag">phrase</sgmltag>A picture<sgmltag class="endtag">phrase</sgmltag> <co id="co-image-phrase"/> - <sgmltag class="endtag">textobject</sgmltag> -<sgmltag class="endtag">mediaobject</sgmltag></programlisting> + <tag class="starttag">textobject</tag> + <tag class="starttag">phrase</tag>A picture<tag class="endtag">phrase</tag> <co xml:id="co-image-phrase"/> + <tag class="endtag">textobject</tag> +<tag class="endtag">mediaobject</tag></programlisting> <calloutlist> <callout arearefs="co-image-ext"> - <para>Include an <sgmltag>imagedata</sgmltag> element - inside the <sgmltag>imageobject</sgmltag> element. The + <para>Include an <tag>imagedata</tag> element + inside the <tag>imageobject</tag> element. The <literal>fileref</literal> attribute should contain the filename of the image to include, without the extension. The stylesheets will work out which extension should be @@ -2240,8 +2228,8 @@ This is the file called 'foo2'</screen> <callout arearefs="co-image-literal"> - <para>The first <sgmltag>textobject</sgmltag> contains a - <sgmltag>literallayout</sgmltag> element, where the + <para>The first <tag>textobject</tag> contains a + <tag>literallayout</tag> element, where the <literal>class</literal> attribute is set to <literal>monospaced</literal>. This is an opportunity to demonstrate <acronym>ASCII</acronym> art skills. This @@ -2249,14 +2237,14 @@ This is the file called 'foo2'</screen> text.</para> <para>Notice how the first and last lines of the content - of the <sgmltag>literallayout</sgmltag> element butt up + of the <tag>literallayout</tag> element butt up next to the element's tags. This ensures no extraneous white space is included.</para> </callout> <callout arearefs="co-image-phrase"> - <para>The second <sgmltag>textobject</sgmltag> contains a - single <sgmltag>phrase</sgmltag> element. The contents of + <para>The second <tag>textobject</tag> contains a + single <tag>phrase</tag> element. The contents of this phrase will become the <literal>alt</literal> attribute for the image when this document is converted to <acronym>HTML</acronym>.</para> @@ -2264,11 +2252,11 @@ This is the file called 'foo2'</screen> </calloutlist> </sect2> - <sect2 id="docbook-markup-image-makefile-entries"> + <sect2 xml:id="docbook-markup-image-makefile-entries"> <title>Image <filename>Makefile</filename> Entries</title> <para>Images must be listed in the <filename>Makefile</filename> - in the <makevar>IMAGES</makevar> variable. This variable must + in the <varname>IMAGES</varname> variable. This variable must contain the names of all the <emphasis>source</emphasis> images. For example, if there are three figures, <filename>fig1.eps</filename>, <filename>fig2.png</filename>, @@ -2294,12 +2282,11 @@ IMAGES+= fig3.png provided.</para> </sect2> - <sect2 id="docbook-markup-images-in-subdirectories"> + <sect2 xml:id="docbook-markup-images-in-subdirectories"> <title>Images and Chapters in Subdirectories</title> <para>Be careful when separating documentation into smaller - files in different directories (see <xref - linkend="xml-primer-include-using-gen-entities"/>).</para> + files in different directories (see <xref linkend="xml-primer-include-using-gen-entities"/>).</para> <para>Suppose there is a book with three chapters, and the chapters are stored in their own directories, called @@ -2313,10 +2300,10 @@ IMAGES+= fig3.png <filename>chapter3/</filename>).</para> <para>However, doing this requires including the directory - names in the <makevar>IMAGES</makevar> variable in the + names in the <varname>IMAGES</varname> variable in the <filename>Makefile</filename>, <emphasis>and</emphasis> including the directory name in the - <sgmltag>imagedata</sgmltag> element in the document + <tag>imagedata</tag> element in the document document.</para> <para>For example, if the book has @@ -2324,14 +2311,14 @@ IMAGES+= fig3.png <filename>chapter1/chapter.xml</filename> should contain:</para> - <programlisting><sgmltag class="starttag">mediaobject</sgmltag> - <sgmltag class="starttag">imageobject</sgmltag> - <sgmltag class="emptytag">imagedata fileref="chapter1/fig1"</sgmltag> <co id="co-image-dir"/> - <sgmltag class="endtag">imageobject</sgmltag> + <programlisting><tag class="starttag">mediaobject</tag> + <tag class="starttag">imageobject</tag> + <tag class="emptytag">imagedata fileref="chapter1/fig1"</tag> <co xml:id="co-image-dir"/> + <tag class="endtag">imageobject</tag> … -<sgmltag class="endtag">mediaobject</sgmltag></programlisting> +<tag class="endtag">mediaobject</tag></programlisting> <calloutlist> <callout arearefs="co-image-dir"> @@ -2348,14 +2335,14 @@ IMAGES= chapter1/fig1.png </sect2> </sect1> - <sect1 id="docbook-markup-links"> + <sect1 xml:id="docbook-markup-links"> <title>Links</title> <note> <para>Links are also in-line elements.</para> </note> - <sect2 id="docbook-markup-links-ids"> + <sect2 xml:id="docbook-markup-links-ids"> <title><literal>id</literal> Attributes</title> <para>Most DocBook elements accept an <literal>id</literal> @@ -2375,18 +2362,18 @@ IMAGES= chapter1/fig1.png <title><literal>id</literal> on Chapters and Sections</title> - <programlisting><sgmltag class="starttag">chapter id="introduction"</sgmltag> - <sgmltag class="starttag">title</sgmltag>Introduction<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">chapter id="introduction"</tag> + <tag class="starttag">title</tag>Introduction<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>This is the introduction. It contains a subsection, - which is identified as well.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">para</tag>This is the introduction. It contains a subsection, + which is identified as well.<tag class="endtag">para</tag> - <sgmltag class="starttag">sect1 id="introduction-moredetails"</sgmltag> - <sgmltag class="starttag">title</sgmltag>More Details<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1 id="introduction-moredetails"</tag> + <tag class="starttag">title</tag>More Details<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>This is a subsection.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">chapter</sgmltag></programlisting> + <tag class="starttag">para</tag>This is a subsection.<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> </example> <para>Use descriptive values for <literal>id</literal> names. @@ -2401,40 +2388,40 @@ IMAGES= chapter1/fig1.png <para>To allow the user to jump into a specific portion of the document, even in the middle of a paragraph or an example, use - <sgmltag>anchor</sgmltag>. This element has no content, but + <tag>anchor</tag>. This element has no content, but takes an <literal>id</literal> attribute.</para> <example> - <title><sgmltag>anchor</sgmltag></title> + <title><tag>anchor</tag></title> - <programlisting><sgmltag class="starttag">para</sgmltag>This paragraph has an embedded - <sgmltag class="emptytag">anchor id="para1"</sgmltag>link target in it. It will not - show up in the document.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>This paragraph has an embedded + <tag class="emptytag">anchor id="para1"</tag>link target in it. It will not + show up in the document.<tag class="endtag">para</tag></programlisting> </example> </sect2> - <sect2 id="docbook-markup-links-crossreferences"> + <sect2 xml:id="docbook-markup-links-crossreferences"> <title>Crossreferences with <literal>xref</literal></title> - <para><sgmltag>xref</sgmltag> provides the reader with a link to + <para><tag>xref</tag> provides the reader with a link to jump to another section of the document. The target <literal>id</literal> is specified in the <literal>linkend</literal> attribute, and - <sgmltag>xref</sgmltag> generates the link text + <tag>xref</tag> generates the link text automatically.</para> <example> - <title>Using <sgmltag>xref</sgmltag></title> + <title>Using <tag>xref</tag></title> <para>Assume that this fragment appears somewhere in a document that includes the <literal>id</literal> example shown above:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found - in <sgmltag class="emptytag">xref linkend="introduction"</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>More information can be found + in <tag class="emptytag">xref linkend="introduction"</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>More specific information can be found - in <sgmltag class="emptytag">xref linkend="introduction-moredetails"</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> +<tag class="starttag">para</tag>More specific information can be found + in <tag class="emptytag">xref linkend="introduction-moredetails"</tag>.<tag class="endtag">para</tag></programlisting> <para>The link text will be generated automatically, looking like (<emphasis>emphasized</emphasis> text indicates the @@ -2455,16 +2442,16 @@ IMAGES= chapter1/fig1.png elements.</para> <note> - <para><sgmltag>xref</sgmltag> cannot link to an + <para><tag>xref</tag> cannot link to an <literal>id</literal> attribute on an - <sgmltag>anchor</sgmltag> element. The - <sgmltag>anchor</sgmltag> has no content, so the - <sgmltag>xref</sgmltag> cannot generate the link + <tag>anchor</tag> element. The + <tag>anchor</tag> has no content, so the + <tag>xref</tag> cannot generate the link text.</para> </note> </sect2> - <sect2 id="docbook-markup-links-to-same-or-web-documents"> + <sect2 xml:id="docbook-markup-links-to-same-or-web-documents"> <title>Linking to the Same Document or Other Documents on the Web</title> @@ -2477,28 +2464,28 @@ IMAGES= chapter1/fig1.png text is not descriptive enough, the reader may not be able to locate the linked section.</para> - <sect3 id="docbook-markup-links-to-same-document"> + <sect3 xml:id="docbook-markup-links-to-same-document"> <title>Links to the Same Document</title> - <para><sgmltag>link</sgmltag> is used to create a link + <para><tag>link</tag> is used to create a link within the same document. The target <literal>id</literal> is specified in the <literal>linkend</literal> attribute. This element wraps content, which is used for the link text.</para> <example> - <title>Using <sgmltag>link</sgmltag></title> + <title>Using <tag>link</tag></title> <para>Assume that this fragment appears somewhere in a document that includes the <literal>id</literal> example.</para> - <programlisting><sgmltag class="starttag">para</sgmltag>More information can be found in the - <sgmltag class="starttag">link linkend="introduction"</sgmltag>sample introduction<sgmltag class="endtag">link</sgmltag>.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>More information can be found in the + <tag class="starttag">link linkend="introduction"</tag>sample introduction<tag class="endtag">link</tag>.<tag class="endtag">para</tag> -<sgmltag class="starttag">para</sgmltag>More specific information can be found in the - <sgmltag class="starttag">link linkend="introduction-moredetails"</sgmltag>sample introduction with more - details<sgmltag class="endtag">link</sgmltag> section.<sgmltag class="endtag">para</sgmltag></programlisting> +<tag class="starttag">para</tag>More specific information can be found in the + <tag class="starttag">link linkend="introduction-moredetails"</tag>sample introduction with more + details<tag class="endtag">link</tag> section.<tag class="endtag">para</tag></programlisting> <para>This output will be generated (<emphasis>emphasized</emphasis> text is used to show the @@ -2515,25 +2502,25 @@ IMAGES= chapter1/fig1.png </example> <note> - <para><sgmltag>link</sgmltag> can be used to include links + <para><tag>link</tag> can be used to include links to the <literal>id</literal> of an - <sgmltag>anchor</sgmltag> element, since the - <sgmltag>link</sgmltag> content defines the link + <tag>anchor</tag> element, since the + <tag>link</tag> content defines the link text.</para> </note> </sect3> - <sect3 id="docbook-markup-links-to-web-documents"> + <sect3 xml:id="docbook-markup-links-to-web-documents"> <title>Linking to Other Documents on the Web</title> - <para>The <sgmltag>ulink</sgmltag> is used to link to + <para>The <tag>ulink</tag> is used to link to external documents on the web. The <literal>url</literal> attribute is the <acronym>URL</acronym> of the page that the link points to, and the content of the element is the text that will be displayed for the user to activate.</para> <example> - <title><sgmltag>ulink</sgmltag> to a &os; Documentation Web + <title><tag>ulink</tag> to a &os; Documentation Web Page</title> <para>Link to the book or article <acronym>URL</acronym> @@ -2547,81 +2534,76 @@ IMAGES= chapter1/fig1.png <para>Usage for book links:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Read the <sgmltag class="starttag">ulink - url="&url.books.handbook;/svn.html#svn-intro"</sgmltag>SVN - introduction<sgmltag class="endtag">ulink</sgmltag>, then pick the nearest mirror from - the list of <sgmltag class="starttag">ulink - url="&url.books.handbook;/svn-mirrors.html"</sgmltag>Subversion - mirror sites<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Read the <tag class="starttag">ulink + url="&url.books.handbook;/svn.html#svn-intro"</tag>SVN + introduction<tag class="endtag">ulink</tag>, then pick the nearest mirror from + the list of <tag class="starttag">ulink + url="&url.books.handbook;/svn-mirrors.html"</tag>Subversion + mirror sites<tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> - <para>Read the <ulink - url="&url.books.handbook;/svn.html#svn-intro">SVN - introduction</ulink>, then pick the nearest mirror from - the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> + <para>Read the <link xlink:href="&url.books.handbook;/svn.html#svn-intro">SVN + introduction</link>, then pick the nearest mirror from + the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror sites</link>.</para> <para>Usage for article links:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Read this - <sgmltag class="starttag">ulink url="&url.articles.bsdl-gpl;"</sgmltag>article - about the BSD license<sgmltag class="endtag">ulink</sgmltag>, or just the - <sgmltag class="starttag">ulink url="&url.articles.bsdl-gpl;#intro"</sgmltag>introduction<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Read this + <tag class="starttag">ulink url="&url.articles.bsdl-gpl;"</tag>article + about the BSD license<tag class="endtag">ulink</tag>, or just the + <tag class="starttag">ulink url="&url.articles.bsdl-gpl;#intro"</tag>introduction<tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> - <para>Read this <ulink url="&url.articles.bsdl-gpl;">article - about the BSD license</ulink>, or just the <ulink - url="&url.articles.bsdl-gpl;#intro">introduction</ulink>.</para> + <para>Read this <link xlink:href="&url.articles.bsdl-gpl;">article + about the BSD license</link>, or just the <link xlink:href="&url.articles.bsdl-gpl;#intro">introduction</link>.</para> </example> <example> - <title><sgmltag>ulink</sgmltag> to a &os; Web Page</title> + <title><tag>ulink</tag> to a &os; Web Page</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Of course, you could stop reading this document and go to the - <sgmltag class="starttag">ulink url="&url.base;/index.html"</sgmltag>FreeBSD home page<sgmltag class="endtag">ulink</sgmltag> instead.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Of course, you could stop reading this document and go to the + <tag class="starttag">ulink url="&url.base;/index.html"</tag>FreeBSD home page<tag class="endtag">ulink</tag> instead.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>Of course, you could stop reading this document and go - to the <ulink url="&url.base;/index.html">FreeBSD home - page</ulink> instead.</para> + to the <link xlink:href="&url.base;/index.html">FreeBSD home + page</link> instead.</para> </example> <example> - <title><sgmltag>ulink</sgmltag> to an External Web + <title><tag>ulink</tag> to an External Web Page</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on - <sgmltag class="starttag">ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag>GUID - Partition Tables<sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + <tag class="starttag">ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag>GUID + Partition Tables<tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>Wikipedia has an excellent reference on - <ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Tables</ulink>.</para> + <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</link>.</para> <para>The link text can be omitted to show the actual URL:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Wikipedia has an excellent reference on - GUID Partition Tables: <sgmltag class="starttag">ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</sgmltag><sgmltag class="endtag">ulink</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>Wikipedia has an excellent reference on + GUID Partition Tables: <tag class="starttag">ulink + url="http://en.wikipedia.org/wiki/GUID_Partition_Table"</tag><tag class="endtag">ulink</tag>.<tag class="endtag">para</tag></programlisting> <para>Appearance:</para> <para>Wikipedia has an excellent reference on - GUID Partition Tables: <ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"></ulink>.</para> + GUID Partition Tables: <uri xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">http://en.wikipedia.org/wiki/GUID_Partition_Table</uri>.</para> </example> </sect3> </sect2> diff --git a/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml index 485ec0a3b1..2f41229243 100644 --- a/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml @@ -27,19 +27,18 @@ $FreeBSD$ --> - -<chapter id="editor-config"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="editor-config"> <title>Editor Configuration</title> <para>Adjusting text editor configuration can make working on document files quicker and easier, and help documents conform to <acronym>FDP</acronym> guidelines.</para> - <sect1 id="editor-config-vim"> + <sect1 xml:id="editor-config-vim"> <title><application>Vim</application></title> - <para>Install from <filename role="package">editors/vim</filename> - or <filename role="package">editors/vim-lite</filename>.</para> + <para>Install from <package>editors/vim</package> + or <package>editors/vim-lite</package>.</para> <para>Edit <filename>~/.vimrc</filename>, adding these lines:</para> @@ -55,12 +54,12 @@ augroup END</programlisting> </sect1> - <sect1 id="editor-config-emacs"> + <sect1 xml:id="editor-config-emacs"> <title><application>Emacs</application></title> <para>Install from - <filename role="package">editors/emacs</filename> - or <filename role="package">editors/xemacs</filename>.</para> + <package>editors/emacs</package> + or <package>editors/xemacs</package>.</para> <para>Edit <filename>~/.emacs</filename>, adding these lines:</para> @@ -77,14 +76,14 @@ augroup END</programlisting> '(lambda () (local-psgml-mode-hook)))</programlisting> </sect1> - <sect1 id="editor-config-nano"> + <sect1 xml:id="editor-config-nano"> <title><application>nano</application></title> <para>Install from - <filename role="package">editors/nano</filename> or - <filename role="package">editors/nano-devel</filename>.</para> + <package>editors/nano</package> or + <package>editors/nano-devel</package>.</para> - <sect2 id="editor-config-nano-config"> + <sect2 xml:id="editor-config-nano-config"> <title>Configuration</title> <para>Copy the sample <acronym>XML</acronym> syntax highlight @@ -112,13 +111,13 @@ color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"</programlisti <screen>&prompt.user; <userinput>perl -i'' -pe 's/TAB/\t/g' ~/.nanorc</userinput></screen> </sect2> - <sect2 id="editor-config-nano-use"> + <sect2 xml:id="editor-config-nano-use"> <title>Use</title> <para>Specify additional helpful options when running the editor:</para> - <screen>&prompt.user; <userinput>nano -AKipwz -r 70 -T8 <replaceable>chapter.xml</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>nano -AKipwz -r 70 -T8 chapter.xml</userinput></screen> <para>Users of &man.csh.1; can define an alias in <filename>~/.cshrc</filename> to automate these @@ -129,7 +128,7 @@ color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$"</programlisti <para>After the alias is defined, the options will be added automatically:</para> - <screen>&prompt.user; <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>nano chapter.xml</userinput></screen> </sect2> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml index f8a98e33fc..6b6ea42ca9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml +++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<appendix id="examples"> +<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="examples"> <title>Examples</title> <para>This appendix contains example <acronym>XML</acronym> files @@ -46,7 +45,7 @@ examine the <acronym>XML</acronym> source for this and other documents available in the <application>svn</application> <literal>doc</literal> repository, or available online starting at - <ulink url="http://svnweb.FreeBSD.org/doc/"></ulink>.</para> + <uri xlink:href="http://svnweb.FreeBSD.org/doc/">http://svnweb.FreeBSD.org/doc/</uri>.</para> <para>To avoid confusion, these examples use the standard DocBook 4.1 <acronym>DTD</acronym> rather than the &os; extension. They @@ -55,106 +54,106 @@ Documentation Project. This makes them more useful as generic DocBook examples.</para> - <sect1 id="examples-docbook-book"> - <title>DocBook <sgmltag>book</sgmltag></title> + <sect1 xml:id="examples-docbook-book"> + <title>DocBook <tag>book</tag></title> <example> - <title>DocBook <sgmltag>book</sgmltag></title> + <title>DocBook <tag>book</tag></title> <programlisting><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> -<sgmltag class="starttag">book lang='en'</sgmltag> - <sgmltag class="starttag">bookinfo</sgmltag> - <sgmltag class="starttag">title</sgmltag>An Example Book<sgmltag class="endtag">title</sgmltag> +<tag class="starttag">book lang='en'</tag> + <tag class="starttag">bookinfo</tag> + <tag class="starttag">title</tag>An Example Book<tag class="endtag">title</tag> - <sgmltag class="starttag">author</sgmltag> - <sgmltag class="starttag">firstname</sgmltag>Your first name<sgmltag class="endtag">firstname</sgmltag> - <sgmltag class="starttag">surname</sgmltag>Your surname<sgmltag class="endtag">surname</sgmltag> - <sgmltag class="starttag">affiliation</sgmltag> - <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag>foo@example.com<sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag> - <sgmltag class="endtag">affiliation</sgmltag> - <sgmltag class="endtag">author</sgmltag> + <tag class="starttag">author</tag> + <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag> + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag><tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> - <sgmltag class="starttag">copyright</sgmltag> - <sgmltag class="starttag">year</sgmltag>2000<sgmltag class="endtag">year</sgmltag> - <sgmltag class="starttag">holder</sgmltag>Copyright string here<sgmltag class="endtag">holder</sgmltag> - <sgmltag class="endtag">copyright</sgmltag> + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag>2000<tag class="endtag">year</tag> + <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> - <sgmltag class="starttag">abstract</sgmltag> - <sgmltag class="starttag">para</sgmltag>If your book has an abstract then it should go here.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">abstract</sgmltag> - <sgmltag class="endtag">bookinfo</sgmltag> + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>If your book has an abstract then it should go here.<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">bookinfo</tag> - <sgmltag class="starttag">preface</sgmltag> - <sgmltag class="starttag">title</sgmltag>Preface<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">preface</tag> + <tag class="starttag">title</tag>Preface<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>Your book may have a preface, in which case it should be placed - here.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">preface</sgmltag> + <tag class="starttag">para</tag>Your book may have a preface, in which case it should be placed + here.<tag class="endtag">para</tag> + <tag class="endtag">preface</tag> - <sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>My First Chapter<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>My First Chapter<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>This is the first chapter in my book.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">para</tag>This is the first chapter in my book.<tag class="endtag">para</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>My First Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>This is the first section in my book.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> - <sgmltag class="endtag">chapter</sgmltag> -<sgmltag class="endtag">book</sgmltag></programlisting> + <tag class="starttag">para</tag>This is the first section in my book.<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> + <tag class="endtag">chapter</tag> +<tag class="endtag">book</tag></programlisting> </example> </sect1> - <sect1 id="examples-docbook-article"> - <title>DocBook <sgmltag>article</sgmltag></title> + <sect1 xml:id="examples-docbook-article"> + <title>DocBook <tag>article</tag></title> <example> - <title>DocBook <sgmltag>article</sgmltag></title> + <title>DocBook <tag>article</tag></title> <programlisting><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> -<sgmltag class="starttag">article lang='en'</sgmltag> - <sgmltag class="starttag">articleinfo</sgmltag> - <sgmltag class="starttag">title</sgmltag>An Example Article<sgmltag class="endtag">title</sgmltag> +<tag class="starttag">article lang='en'</tag> + <tag class="starttag">articleinfo</tag> + <tag class="starttag">title</tag>An Example Article<tag class="endtag">title</tag> - <sgmltag class="starttag">author</sgmltag> - <sgmltag class="starttag">firstname</sgmltag>Your first name<sgmltag class="endtag">firstname</sgmltag> - <sgmltag class="starttag">surname</sgmltag>Your surname<sgmltag class="endtag">surname</sgmltag> - <sgmltag class="starttag">affiliation</sgmltag> - <sgmltag class="starttag">address</sgmltag><sgmltag class="starttag">email</sgmltag>foo@example.com<sgmltag class="endtag">email</sgmltag><sgmltag class="endtag">address</sgmltag> - <sgmltag class="endtag">affiliation</sgmltag> - <sgmltag class="endtag">author</sgmltag> + <tag class="starttag">author</tag> + <tag class="starttag">firstname</tag>Your first name<tag class="endtag">firstname</tag> + <tag class="starttag">surname</tag>Your surname<tag class="endtag">surname</tag> + <tag class="starttag">affiliation</tag> + <tag class="starttag">address</tag><tag class="starttag">email</tag>foo@example.com<tag class="endtag">email</tag><tag class="endtag">address</tag> + <tag class="endtag">affiliation</tag> + <tag class="endtag">author</tag> - <sgmltag class="starttag">copyright</sgmltag> - <sgmltag class="starttag">year</sgmltag>2000<sgmltag class="endtag">year</sgmltag> - <sgmltag class="starttag">holder</sgmltag>Copyright string here<sgmltag class="endtag">holder</sgmltag> - <sgmltag class="endtag">copyright</sgmltag> + <tag class="starttag">copyright</tag> + <tag class="starttag">year</tag>2000<tag class="endtag">year</tag> + <tag class="starttag">holder</tag>Copyright string here<tag class="endtag">holder</tag> + <tag class="endtag">copyright</tag> - <sgmltag class="starttag">abstract</sgmltag> - <sgmltag class="starttag">para</sgmltag>If your article has an abstract then it should go here.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">abstract</sgmltag> - <sgmltag class="endtag">articleinfo</sgmltag> + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>If your article has an abstract then it should go here.<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">articleinfo</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>My First Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>My First Section<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>This is the first section in my article.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">para</tag>This is the first section in my article.<tag class="endtag">para</tag> - <sgmltag class="starttag">sect2</sgmltag> - <sgmltag class="starttag">title</sgmltag>My First Sub-Section<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>My First Sub-Section<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>This is the first sub-section in my article.<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect2</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">article</sgmltag></programlisting> + <tag class="starttag">para</tag>This is the first sub-section in my article.<tag class="endtag">para</tag> + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">article</tag></programlisting> </example> </sect1> - <sect1 id="examples-formatted"> + <sect1 xml:id="examples-formatted"> <title>Producing Formatted Output</title> <para>Before using these examples, install the required tools as @@ -167,12 +166,12 @@ <title>Converting DocBook to <acronym>XHTML</acronym> (One Large File)</title> - <screen>&prompt.user; <userinput>jade -V nochunks \ <co id="examples-co-jade-1-nochunks"/> - -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-1-catalog"/> + <screen>&prompt.user; <userinput>jade -V nochunks \ <co xml:id="examples-co-jade-1-nochunks"/> + -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-1-catalog"/> -c /usr/local/share/xml/docbook/catalog \ -c /usr/local/share/xml/jade/catalog \ - -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-1-dsssl"/> - -t sgml <co id="examples-co-jade-1-transform"/> <replaceable>file</replaceable>.xml > <replaceable>file</replaceable>.html <co id="examples-co-jade-1-filename"/></userinput></screen> + -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-1-dsssl"/> + -t sgml <co xml:id="examples-co-jade-1-transform"/> file.xml > file.html <co xml:id="examples-co-jade-1-filename"/></userinput></screen> <calloutlist> <callout arearefs="examples-co-jade-1-nochunks"> @@ -223,11 +222,11 @@ Small Files)</title> <screen>&prompt.user; <userinput>jade \ - -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog"/> + -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-2-catalog"/> -c /usr/local/share/xml/docbook/catalog \ -c /usr/local/share/xml/jade/catalog \ - -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co id="examples-co-jade-2-dsssl"/> - -t sgml <co id="examples-co-jade-2-transform"/> <replaceable>file</replaceable>.xml <co id="examples-co-jade-2-filename"/></userinput></screen> + -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \<co xml:id="examples-co-jade-2-dsssl"/> + -t sgml <co xml:id="examples-co-jade-2-transform"/> file.xml <co xml:id="examples-co-jade-2-filename"/></userinput></screen> <calloutlist> <callout arearefs="examples-co-jade-2-catalog"> @@ -273,18 +272,18 @@ for splitting output.</para> </example> - <example id="examples-docbook-postscript"> + <example xml:id="examples-docbook-postscript"> <title>Converting DocBook to &postscript;</title> <para>The source <acronym>XML</acronym> file must be converted to a &tex; file.</para> - <screen>&prompt.user; <userinput>jade -V tex-backend \ <co id="examples-co-jade-3-tex-backend"/> - -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-3-catalog"/> + <screen>&prompt.user; <userinput>jade -V tex-backend \ <co xml:id="examples-co-jade-3-tex-backend"/> + -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co xml:id="examples-co-jade-3-catalog"/> -c /usr/local/share/xml/docbook/catalog \ -c /usr/local/share/xml/jade/catalog \ - -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \<co id="examples-co-jade-3-dsssl"/> - -t tex <co id="examples-co-jade-3-tex"/> <replaceable>file</replaceable>.xml</userinput></screen> + -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \<co xml:id="examples-co-jade-3-dsssl"/> + -t tex <co xml:id="examples-co-jade-3-tex"/> file.xml</userinput></screen> <calloutlist> <callout arearefs="examples-co-jade-3-tex-backend"> @@ -320,7 +319,7 @@ run through <command>tex</command>, specifying the <literal>&jadetex</literal> macro package.</para> - <screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen> + <screen>&prompt.user; <userinput>tex "&jadetex" file.tex</userinput></screen> <para><command>tex</command> commands must be run <emphasis>at least</emphasis> three times. The first run @@ -342,12 +341,12 @@ necessary.</para> <para>The output from this stage will be - <filename><replaceable>file</replaceable>.dvi</filename>.</para> + <filename>file.dvi</filename>.</para> <para>Finally, run <command>dvips</command> to convert the <filename>.dvi</filename> file to &postscript;.</para> - <screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>dvips -o file.ps file.dvi</userinput></screen> </example> <example> @@ -355,20 +354,19 @@ <para>The first part of this process is identical to that of converting DocBook to &postscript;, using the same - <command>jade</command> command line (<xref - linkend="examples-docbook-postscript"/>).</para> + <command>jade</command> command line (<xref linkend="examples-docbook-postscript"/>).</para> <para>After the <filename>.tex</filename> file has been generated, run <application>pdfTeX</application>. However, use the <literal>&pdfjadetex</literal> macro package instead.</para> - <screen>&prompt.user; <userinput>pdftex "&pdfjadetex" <replaceable>file</replaceable>.tex</userinput></screen> + <screen>&prompt.user; <userinput>pdftex "&pdfjadetex" file.tex</userinput></screen> <para>Again, run this command three times.</para> <para>This will generate - <filename><replaceable>file</replaceable>.pdf</filename>, + <filename>file.pdf</filename>, which does not need to be processed any further.</para> </example> </sect2> diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml index 66eb8593f2..b0cf2cc198 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<chapter id="overview"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="overview"> <title>Overview</title> <para>Welcome to the &os; Documentation Project @@ -69,7 +68,7 @@ </listitem> </itemizedlist> - <sect1 id="overview-doc"> + <sect1 xml:id="overview-doc"> <title>The &os; Documentation Set</title> <para>The <acronym>FDP</acronym> is responsible for four @@ -101,8 +100,7 @@ <listitem> <para><emphasis>Web site</emphasis>: This is the main &os; - presence on the web, visible at <ulink - url="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</ulink> + presence on the web, visible at <link xlink:href="http://www.freebsd.org/index.html">http://www.FreeBSD.org/</link> and many mirrors around the world. The web site is typically a new user's first exposure to &os;.</para> </listitem> @@ -123,7 +121,7 @@ <para>Documentation commit messages are visible with <command>svn log</command>. Commit messages are also - archived at <ulink url="&a.svn-doc-all.url;"></ulink>.</para> + archived at <uri xlink:href="&a.svn-doc-all.url;">&a.svn-doc-all.url;</uri>.</para> <para>Many people have written tutorials or how-to articles about &os;. Some are stored as part of the <acronym>FDP</acronym> @@ -133,21 +131,21 @@ possible.</para> </sect1> - <sect1 id="overview-quick-start"> + <sect1 xml:id="overview-quick-start"> <title>Quick Start</title> <para>Some preparatory steps must be taken before editing the &os; documentation. First, subscribe to the &a.doc;. Some team members also interact on the <literal>#bsddocs</literal> <acronym>IRC</acronym> channel on - <ulink url="http://www.efnet.org/">EFnet</ulink>. These people + <link xlink:href="http://www.efnet.org/">EFnet</link>. These people can help with questions or problems involving the documentation.</para> <procedure> <step> <para>Install the - <filename role="package">textproc/docproj</filename> + <package>textproc/docproj</package> package or port. This meta-port installs all of the software needed to edit and build &os; documentation.</para> </step> @@ -155,10 +153,10 @@ <step> <para>Install a local working copy of the documentation from a mirror of the &os; repository in - <filename class="directory">~/doc</filename> (see + <filename>~/doc</filename> (see <xref linkend="working-copy"/>).</para> - <screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>~/doc</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/doc/head ~/doc</userinput></screen> </step> <step> @@ -186,7 +184,7 @@ <step> <para>Update the local working copy:</para> - <screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn up ~/doc</userinput></screen> </step> <step> @@ -226,18 +224,18 @@ <quote>diff file</quote>:</para> <screen>&prompt.user; <userinput>cd /usr/doc</userinput> -&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> +&prompt.user; <userinput>svn diff > bsdinstall.diff.txt</userinput></screen> <para>Give the diff file a descriptive name. In the example above, changes have been made to the - <filename class="directory">bsdinstall</filename> portion of + <filename>bsdinstall</filename> portion of the Handbook.</para> </step> <step> <para>Submit the diff file using the web-based - <ulink url="&url.base;/support.html#gnats">Problem - Report</ulink> system or with &man.send-pr.1;. If using + <link xlink:href="&url.base;/support.html#gnats">Problem + Report</link> system or with &man.send-pr.1;. If using the web form, enter a synopsis of <emphasis>[patch] <replaceable>short description of problem</replaceable></emphasis>. Select the category diff --git a/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml new file mode 100644 index 0000000000..03c12c8545 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/psgml-mode/chapter.xml @@ -0,0 +1,171 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="psgml-mode"> + <title>Using <literal>sgml-mode</literal> with + <application>Emacs</application></title> + + <para>Recent versions of <application>Emacs</application> or + <application>XEmacs</application> (available from the Ports + Collection) contain a very useful package called PSGML (can be + installed from <package>editors/psgml</package>). + Automatically invoked when a file with the + <filename>.xml</filename> extension is loaded, or by typing + <command>M-x sgml-mode</command>, it is a major mode for dealing + with SGML files, elements and attributes.</para> + + <para>An understanding of some of the commands provided by this mode + can make working with SGML documents such as the Handbook much + easier.</para> + + <variablelist> + <varlistentry> + <term><command>C-c C-e</command></term> + + <listitem> + <para>Runs <function>sgml-insert-element</function>. You will + be prompted for the name of the element to insert at the + current point. You can use the <keycap>Tab</keycap> key to + complete the element. Elements that are not valid at the + current point will be disallowed.</para> + + <para>The start and end tags for the element will be inserted. + If the element contains other, mandatory, elements then + these will be inserted as well.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c =</command></term> + + <listitem> + <para>Runs <function>sgml-change-element-name</function>. + Place the point within an element and run this command. You + will be prompted for the name of the element to change to. + Both the start and end tags of the current element will be + changed to the new element.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-r</command></term> + + <listitem> + <para>Runs <function>sgml-tag-region</function>. Select some + text (move to start of text, <command>C-space</command>, + move to end of text, <command>C-space</command>) and then + run this command. You will be prompted for the element to + use. This element will then be inserted immediately before + and after your marked region.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c -</command></term> + + <listitem> + <para>Runs <function>sgml-untag-element</function>. Place the + point within the start or end tag of an element you want to + remove, and run this command. The element's start and end + tags will be removed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-q</command></term> + + <listitem> + <para>Runs <function>sgml-fill-element</function>. Will + recursively fill (i.e., reformat) content from the current + element in. The filling <emphasis>will</emphasis> affect + content in which whitespace is significant, such as within + <tag>programlisting</tag> elements, so run this + command with care.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-a</command></term> + + <listitem> + <para>Runs <function>sgml-edit-attributes</function>. Opens a + second buffer containing a list of all the attributes for + the closest enclosing element, and their current values. + Use <keycap>Tab</keycap> to navigate between attributes, + <command>C-k</command> to remove an existing value and + replace it with a new one, <command>C-c C-c</command> to + close this buffer and return to the main document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c C-v</command></term> + + <listitem> + <para>Runs <function>sgml-validate</function>. Prompts you to + save the current document (if necessary) and then runs an + SGML validator. The output from the validator is captured + into a new buffer, and you can then navigate from one + troublespot to the next, fixing markup errors as you + go.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><command>C-c /</command></term> + + <listitem> + <para>Runs <function>sgml-insert-end-tag</function>. Inserts + the end tag for the current open element.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>Doubtless there are other useful functions of this mode, but + those are the ones I use most often.</para> + + <para>You can also use the following entries in + <filename>.emacs</filename> to set proper spacing, indentation, + and column width for working with the Documentation + Project.</para> + + <programlisting> (defun local-sgml-mode-hook + (setq fill-column 70 + indent-tabs-mode nil + next-line-add-newlines nil + standard-indent 4 + sgml-indent-data t) + (auto-fill-mode t) + (setq sgml-catalog-files '("/usr/local/share/xml/catalog"))) + (add-hook 'psgml-mode-hook + '(lambda () (local-psgml-mode-hook)))</programlisting> +</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml index 65f4df3962..88bbc9491e 100644 --- a/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/see-also/chapter.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<chapter id="see-also"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="see-also"> <title>See Also</title> <para>This document is deliberately not an exhaustive discussion of @@ -39,80 +38,80 @@ more information about these, you are encouraged to see the following web sites.</para> - <sect1 id="see-also-fdp"> + <sect1 xml:id="see-also-fdp"> <title>The FreeBSD Documentation Project</title> <itemizedlist> <listitem> - <para><ulink url="&url.base;/docproj/index.html">The FreeBSD - Documentation Project web pages</ulink></para> + <para><link xlink:href="&url.base;/docproj/index.html">The FreeBSD + Documentation Project web pages</link></para> </listitem> <listitem> - <para><ulink url="&url.books.handbook;/index.html">The FreeBSD - Handbook</ulink></para> + <para><link xlink:href="&url.books.handbook;/index.html">The FreeBSD + Handbook</link></para> </listitem> </itemizedlist> </sect1> - <sect1 id="see-also-xml"> + <sect1 xml:id="see-also-xml"> <title>XML</title> <itemizedlist> <listitem> - <para><ulink url="http://www.w3.org/XML/">W3C's XML page - SGML/XML web page</ulink></para> + <para><link xlink:href="http://www.w3.org/XML/">W3C's XML page + SGML/XML web page</link></para> </listitem> </itemizedlist> </sect1> - <sect1 id="see-also-html"> + <sect1 xml:id="see-also-html"> <title>HTML</title> <itemizedlist> <listitem> - <para><ulink url="http://www.w3.org/">The World Wide Web - Consortium</ulink></para> + <para><link xlink:href="http://www.w3.org/">The World Wide Web + Consortium</link></para> </listitem> <listitem> - <para><ulink url="http://www.w3.org/TR/REC-html40/">The HTML - 4.0 specification</ulink></para> + <para><link xlink:href="http://www.w3.org/TR/REC-html40/">The HTML + 4.0 specification</link></para> </listitem> </itemizedlist> </sect1> - <sect1 id="see-also-docbook"> + <sect1 xml:id="see-also-docbook"> <title>DocBook</title> <itemizedlist> <listitem> - <para><ulink url="http://www.oasis-open.org/docbook/">The - DocBook Technical Committee</ulink>, maintainers of the + <para><link xlink:href="http://www.oasis-open.org/docbook/">The + DocBook Technical Committee</link>, 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 + <para><link xlink:href="http://www.docbook.org/">DocBook: The + Definitive Guide</link>, 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 + <para><link xlink:href="http://docbook.sourceforge.net/">The DocBook + Open Repository</link> contains DSSSL stylesheets and other resources for people using DocBook</para> </listitem> </itemizedlist> </sect1> - <sect1 id="see-also-linuxdoc"> + <sect1 xml:id="see-also-linuxdoc"> <title>The Linux Documentation Project</title> <itemizedlist> <listitem> - <para><ulink url="http://www.tldp.org/">The Linux - Documentation Project web pages</ulink></para> + <para><link xlink:href="http://www.tldp.org/">The Linux + Documentation Project web pages</link></para> </listitem> </itemizedlist> </sect1> diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml new file mode 100644 index 0000000000..d83b9f788d --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-markup/chapter.xml @@ -0,0 +1,2746 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-markup"> + <title>XML 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>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> + + <note> + <title>Inline Versus 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> + </note> + + <sect1 xml:id="xml-markup-xhtml"> + <title>XHTML</title> + + <para>XHTML is the XML version of the HyperText Markup Language, + which is the markup language + of choice on the World Wide Web. More information can be found + at <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para> + + <para>XHTML 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 XHTML 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, + 4.0 and then an XML-compliant version has also been created, which + is called XHTML and the latest widespread version of it is + XHTML 1.0(available in both + <emphasis>strict</emphasis> and <emphasis>transitional</emphasis> + variants).</para> + + <para>The XHTML DTDs are available from the Ports Collection + in the <package>textproc/xhtml</package> port. + They are automatically installed as part of the <package>textproc/docproj</package> port.</para> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>There are a number of XHTML FPIs, depending upon the + version (also known as the level) of XHTML that you want to + declare your document to be compliant with.</para> + + <para>The majority of XHTML documents on the FreeBSD web site + comply with the transitional version of XHTML 1.0.</para> + + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> + </sect2> + + <sect2> + <title>Sectional Elements</title> + + <para>An XHTML 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 <tag>head</tag> + and <tag>body</tag> elements respectively. These + elements are contained within the top-level + <tag>html</tag> element.</para> + + <example> + <title>Normal XHTML Document Structure</title> + + <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title><replaceable>The Document's Title</replaceable></title> + </head> + + <body> + + … + + </body> +</html></programlisting> + </example> + </sect2> + + <sect2> + <title>Block Elements</title> + + <sect3> + <title>Headings</title> + + <para>XHTML allows you to denote headings in your document, at + up to six different levels.</para> + + <para>The largest and most prominent heading is + <tag>h1</tag>, then <tag>h2</tag>, + continuing down to <tag>h6</tag>.</para> + + <para>The element's content is the text of the heading.</para> + + <example> + <title><tag>h1</tag>, <tag>h2</tag>, + and Other Header Tags</title> + + <para>Use:</para> + + <programlisting><h1>First section</h1> + +<!‐- Document introduction goes here -‐> + +<h2>This is the heading for the first section</h2> + +<!‐- Content for the first section goes here -‐> + +<h3>This is the heading for the first sub-section</h3> + +<!‐- Content for the first sub-section goes here -‐> + +<h2>This is the heading for the second section</h2> + +<!‐- Content for the second section goes here -‐></programlisting> + </example> + + <para>Generally, an XHTML page should have one first level + heading (<tag>h1</tag>). This can contain many + second level headings (<tag>h2</tag>), which can in + turn contain many third level headings. Each + <tag>h<replaceable>n</replaceable></tag> 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 + <tag>h<replaceable>n</replaceable></tag> + Elements</title> + + <para>Use:</para> + + <programlisting><h1>First section</h1> + +<!‐- Document introduction -‐> + +<h3>Sub-section</h3> + +<!‐- This is bad, <h2> has been left out -‐></programlisting> + </example> + </sect3> + + <sect3> + <title>Paragraphs</title> + + <para>XHTML supports a single paragraph element, + <tag>p</tag>.</para> + + <example> + <title><tag>p</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any + other element.</p>]]></programlisting> + </example> + </sect3> + + <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> + + <example> + <title><tag>blockquote</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p> + +<blockquote>We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the general + Welfare, and secure the Blessings of Liberty to ourselves and our + Posterity, do ordain and establish this Constitution for the + United States of America.</blockquote>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Lists</title> + + <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>Ordered lists are indicated by the <tag>ol</tag> + element, unordered lists by the <tag>ul</tag> + element, and definition lists by the <tag>dl</tag> + element.</para> + + <para>Ordered and unordered lists contain listitems, indicated + by the <tag>li</tag> element. A listitem can + contain textual content, or it may be further wrapped in one + or more <tag>p</tag> elements.</para> + + <para>Definition lists contain definition terms + (<tag>dt</tag>) and definition descriptions + (<tag>dd</tag>). A definition term can only contain + inline elements. A definition description can contain other + block elements.</para> + + <example> + <title><tag>ul</tag> and + <tag>ol</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>An unordered list. Listitems will probably be + preceded by bullets.</p> + +<ul> + <li>First item</li> + + <li>Second item</li> + + <li>Third item</li> +</ul> + +<p>An ordered list, with list items consisting of multiple + paragraphs. Each item (note: not each paragraph) will be + numbered.</p> + +<ol> + <li><p>This is the first item. It only has one paragraph.</p></li> + + <li><p>This is the first paragraph of the second item.</p> + + <p>This is the second paragraph of the second item.</p></li> + + <li><p>This is the first and only paragraph of the third + item.</p></li> +</ol>]]></programlisting> + </example> + + <example> + <title>Definition Lists with <tag>dl</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<dl> + <dt>Term 1</dt> + + <dd><p>Paragraph 1 of definition 1.</p> + + <p>Paragraph 2 of definition 1.</p></dd> + + <dt>Term 2</dt> + + <dd><p>Paragraph 1 of definition 2.</p></dd> + + <dt>Term 3</dt> + + <dd><p>Paragraph 1 of definition 3.</p></dd> +</dl>]]></programlisting> + </example> + </sect3> + + <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>In order to do this, wrap the content in the + <tag>pre</tag> element.</para> + + <example> + <title><tag>pre</tag></title> + + <para>You could use <tag>pre</tag> to mark up an + email message:</para> + + <programlisting><![CDATA[<pre> From: nik@FreeBSD.org + To: freebsd-doc@FreeBSD.org + Subject: New documentation available + + There is a new copy of my primer for contributors to the FreeBSD + Documentation Project available at + + <URL:http://people.FreeBSD.org/~nik/primer/index.html> + + Comments appreciated. + + N</pre>]]></programlisting> + + <para>Keep in mind that <literal><</literal> and + <literal>&</literal> still are recognized as special + characters in pre-formatted text. This is why the example + 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> + </example> + </sect3> + + <sect3> + <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> + </note> + + <para>Mark up tabular information using the + <tag>table</tag> element. A table consists of one + or more table rows (<tag>tr</tag>), each containing + one or more cells of table data (<tag>td</tag>). + 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 + <tag>p</tag> element.</para> + + <example> + <title>Simple Use of <tag>table</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>This is a simple 2x2 table.</p> + +<table> + <tr> + <td>Top left cell</td> + + <td>Top right cell</td> + </tr> + + <tr> + <td>Bottom left cell</td> + + <td>Bottom right cell</td> + </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> + + <example> + <title>Using <literal>rowspan</literal></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>One tall thin cell on the left, two short cells next to + it on the right.</p> + +<table> + <tr> + <td rowspan="2">Long and thin</td> + </tr> + + <tr> + <td>Top cell</td> + + <td>Bottom cell</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Using <literal>colspan</literal></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>One long cell on top, two short cells below it.</p> + +<table> + <tr> + <td colspan="2">Top cell</td> + </tr> + + <tr> + <td>Bottom left cell</td> + + <td>Bottom right cell</td> + </tr> +</table>]]></programlisting> + </example> + + <example> + <title>Using <literal>rowspan</literal> and + <literal>colspan</literal> Together</title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>On a 3x3 grid, the top left block is a 2x2 set of + cells merged into one. The other cells are normal.</p> + +<table> + <tr> + <td colspan="2" rowspan="2">Top left large cell</td> + + <td>Top right cell</td> + </tr> + + <tr> + <td>Middle right cell</td> + </tr> + + <tr> + <td>Bottom left cell</td> + + <td>Bottom middle cell</td> + + <td>Bottom right cell</td> + </tr> +</table>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>In-line Elements</title> + + <sect3> + <title>Emphasizing Information</title> + + <para>You have two levels of emphasis available in XHTML, + <tag>em</tag> and <tag>strong</tag>. + <tag>em</tag> is for a normal level of emphasis and + <tag>strong</tag> indicates stronger + emphasis.</para> + + <para>Typically, <tag>em</tag> is rendered in italic + and <tag>strong</tag> is rendered in bold. This is + not always the case, however, and you should not rely on + it. According to best practices, webpages only hold + structural and semantical information and stylesheets are + later applied to use these two so you should think of + semantics not formatting when using these tags.</para> + + <example> + <title><tag>em</tag> and + <tag>strong</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p><em>This</em> has been emphasized, while + <strong>this</strong> has been strongly emphasized.</p>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating Fixed-Pitch Text</title> + + <para>If you have content that should be rendered in a fixed + pitch (typewriter) typeface, use <tag>tt</tag> (for + <quote>teletype</quote>).</para> + + <example> + <title><tag>tt</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>This document was originally written by + Nik Clayton, who can be reached by email as + <tt>nik@FreeBSD.org</tt>.</p>]]></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also inline elements.</para> + </note> + + <sect3> + <title>Linking to Other Documents on the WWW</title> + + <para>In order to include a link to another document on the + WWW you must know the URL of the document you want to link + to.</para> + + <para>The link is indicated with <tag>a</tag>, and the + <literal>href</literal> attribute contains the URL of the + target document. The content of the element becomes the + link, and is normally indicated to the user in some way + (underlining, change of color, different mouse cursor when + over the link, and so on).</para> + + <example> + <title>Using <literal><a href="..."></literal></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p>More information is available at the + <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> + </example> + + <para>These links will take the user to the top of the chosen + document.</para> + </sect3> + + <sect3> + <title>Linking to Other Parts of Documents</title> + + <para>Linking to a point within another document (or within + the same document) requires that the document author include + anchors that you can link to.</para> + + <para>Anchors are indicated with <tag>a</tag> and the + <literal>id</literal> attribute instead of + <literal>href</literal>.</para> + + <example> + <title>Using <literal><a id="..."></literal></title> + + <para>Use:</para> + + <programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced + in other links with the name <tt>para1</tt>.</p>]]></programlisting> + </example> + + <para>To link to a named part of a document, write a normal + link to that document, but include the id of the anchor + after a <literal>#</literal> symbol.</para> + + <example> + <title>Linking to a Named Part of Another Document</title> + + <para>Assume that the <literal>para1</literal> example + resides in a document called + <filename>foo.html</filename>.</para> + + <programlisting><![CDATA[<p>More information can be found in the + <a href="foo.html#para1">first paragraph</a> of + <tt>foo.html</tt>.</p>]]></programlisting> + </example> + + <para>If you are linking to a named anchor within the same + document then you can omit the document's URL, and just + include the name of the anchor (with the preceding + <literal>#</literal>).</para> + + <example> + <title>Linking to a Named Part of the Same Document</title> + + <para>Assume that the <literal>para1</literal> example + resides in this document:</para> + + <programlisting><![CDATA[<p>More information can be found in the + <a href="#para1">first paragraph</a> of this + document.</p>]]></programlisting> + </example> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="xml-markup-docbook"> + <title>DocBook</title> + + <para>DocBook was originally developed by HaL Computer Systems and + O'Reilly & Associates to be a DTD for writing technical + documentation <footnote><para>A short history can be found under + <link xlink:href="http://www.oasis-open.org/docbook/intro.shtml#d0e41"> + http://www.oasis-open.org/docbook/intro.shtml#d0e41</link>.</para></footnote>. + Since 1998 it is maintained by the <link xlink:href="http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=docbook"> + DocBook Technical Committee</link>. As such, and unlike + LinuxDoc and XHTML, DocBook is very heavily oriented towards + markup that describes <emphasis>what</emphasis> something is, + rather than describing <emphasis>how</emphasis> it should be + presented.</para> + + <note> + <title>Formal Versus Informal</title> + + <para>Some elements may exist in two forms, + <emphasis>formal</emphasis> and <emphasis>informal</emphasis>. + Typically, the formal version of the element will consist of a + title followed by the informal version of the element. The + informal version will not have a title.</para> + </note> + + <para>The DocBook DTD is available from the Ports Collection + in the <package>textproc/docbook-xml-450</package> + port. It is automatically installed as part of the <package>textproc/docproj</package> port.</para> + + <sect2> + <title>&os; Extensions</title> + + <para>The FreeBSD Documentation Project has extended the DocBook + DTD by adding some new elements. These elements serve to make + some of the markup more precise.</para> + + <para>Where a FreeBSD specific element is listed below it is + clearly marked.</para> + + <para>Throughout the rest of this document, the term + <quote>DocBook</quote> is used to mean the FreeBSD extended + DocBook DTD.</para> + + <note> + <para>There is nothing about these extensions that is FreeBSD + specific, it was just felt that they were useful + enhancements for this particular project. Should anyone + from any of the other *nix camps (NetBSD, OpenBSD, Linux, + …) be interested in collaborating on a standard + DocBook extension set, please get in touch with + &a.doceng;.</para> + </note> + + <para>The &os; extensions are not (currently) in the + Ports Collection. They are stored in the &os; Subversion + tree, as <link xlink:href="http://svnweb.FreeBSD.org/doc/head/share/xml/freebsd.dtd">head/share/xml/freebsd.dtd</link>.</para> + </sect2> + + <sect2> + <title>Formal Public Identifier (FPI)</title> + + <para>In compliance with the DocBook guidelines for writing FPIs + for DocBook customizations, the FPI for the FreeBSD extended + DocBook DTD is:</para> + + <programlisting>PUBLIC "-//FreeBSD//DTD DocBook V4.2-Based Extension//EN"</programlisting> + </sect2> + + <sect2> + <title>Document Structure</title> + + <para>DocBook allows you to structure your documentation in + several ways. In the FreeBSD Documentation Project we are + using two primary types of DocBook document: the book and the + article.</para> + + <para>A book is organized into <tag>chapter</tag>s. + This is a mandatory requirement. There may be + <tag>part</tag>s between the book and the chapter to + provide another layer of organization. For example, the + Handbook is arranged in this way.</para> + + <para>A chapter may (or may not) contain one or more sections. + These are indicated with the <tag>sect1</tag> element. + If a section contains another section then use the + <tag>sect2</tag> element, and so on, up to + <tag>sect5</tag>.</para> + + <para>Chapters and sections contain the remainder of the + content.</para> + + <para>An article is simpler than a book, and does not use + chapters. Instead, the content of an article is organized + into one or more sections, using the same + <tag>sect1</tag> (and <tag>sect2</tag> and so + on) elements that are used in books.</para> + + <para>Obviously, you should consider the nature of the + documentation you are writing in order to decide whether it is + best marked up as a book or an article. Articles are well + suited to information that does not need to be broken down + into several chapters, and that is, relatively speaking, quite + short, at up to 20-25 pages of content. Books are best suited + to information that can be broken up into several chapters, + possibly with appendices and similar content as well.</para> + + <para>The <link xlink:href="&url.base;/docs.html">FreeBSD + tutorials</link> are all marked up as articles, while this + document, the + <link xlink:href="&url.books.faq;/index.html">FreeBSD FAQ</link>, + and the <link xlink:href="&url.books.handbook;/index.html">FreeBSD + Handbook</link> are all marked up as books, for + example.</para> + + <sect3> + <title>Starting a Book</title> + + <para>The content of the book is contained within the + <tag>book</tag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the book. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page.</para> + + <para>This additional information should be contained within + <tag>bookinfo</tag>.</para> + + <example> + <title>Boilerplate <tag>book</tag> with + <tag>bookinfo</tag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + + <programlisting><book> + <bookinfo> + <title><replaceable>Your Title Here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your email address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the book's contents here.</replaceable></para> + </abstract> + </bookinfo> + + … + +</book></programlisting> + </example> + </sect3> + + <sect3> + <title>Starting an Article</title> + + <para>The content of the article is contained within the + <tag>article</tag> element. As well as containing + structural markup, this element can contain elements that + include additional information about the article. This is + either meta-information, used for reference purposes, or + additional content used to produce a title page.</para> + + <para>This additional information should be contained within + <tag>articleinfo</tag>.</para> + + <example> + <title>Boilerplate <tag>article</tag> with + <tag>articleinfo</tag></title> + + <!-- Can't put this in a marked section because of the + replaceable elements --> + + <programlisting><article> + <articleinfo> + <title><replaceable>Your title here</replaceable></title> + + <author> + <firstname><replaceable>Your first name</replaceable></firstname> + <surname><replaceable>Your surname</replaceable></surname> + <affiliation> + <address><email><replaceable>Your email address</replaceable></email></address> + </affiliation> + </author> + + <copyright> + <year><replaceable>1998</replaceable></year> + <holder role="mailto:<replaceable>your email address</replaceable>"><replaceable>Your name</replaceable></holder> + </copyright> + + <releaseinfo>$FreeBSD$</releaseinfo> + + <abstract> + <para><replaceable>Include an abstract of the article's contents here.</replaceable></para> + </abstract> + </articleinfo> + + … + +</article></programlisting> + </example> + </sect3> + + <sect3> + <title>Indicating Chapters</title> + + <para>Use <tag>chapter</tag> to mark up your chapters. + Each chapter has a mandatory <tag>title</tag>. + Articles do not contain chapters, they are reserved for + books.</para> + + <example> + <title>A Simple Chapter</title> + + <programlisting><![CDATA[<chapter> + <title>The Chapter's Title</title> + + ... +</chapter>]]></programlisting> + </example> + + <para>A chapter cannot be empty; it must contain elements in + addition to <tag>title</tag>. If you need to + include an empty chapter then just use an empty + paragraph.</para> + + <example> + <title>Empty Chapters</title> + + <programlisting><![CDATA[<chapter> + <title>This is An Empty Chapter</title> + + <para></para> +</chapter>]]></programlisting> + </example> + </sect3> + + <sect3> + <title>Sections Below Chapters</title> + + <para>In books, chapters may (but do not need to) be broken up + into sections, subsections, and so on. In articles, + sections are the main structural element, and each article + must contain at least one section. Use the + <tag>sect<replaceable>n</replaceable></tag> element. + The <replaceable>n</replaceable> indicates the section + number, which identifies the section level.</para> + + <para>The first + <tag>sect<replaceable>n</replaceable></tag> is + <tag>sect1</tag>. You can have one or more of these + in a chapter. They can contain one or more + <tag>sect2</tag> elements, and so on, down to + <tag>sect5</tag>.</para> + + <example> + <title>Sections in Chapters</title> + + <programlisting><![CDATA[<chapter> + <title>A Sample Chapter</title> + + <para>Some text in the chapter.</para> + + <sect1> + <title>First Section (1.1)</title> + + … + </sect1> + + <sect1> + <title>Second Section (1.2)</title> + + <sect2> + <title>First Sub-Section (1.2.1)</title> + + <sect3> + <title>First Sub-Sub-Section (1.2.1.1)</title> + + … + </sect3> + </sect2> + + <sect2> + <title>Second Sub-Section (1.2.2)</title> + + … + </sect2> + </sect1> +</chapter>]]></programlisting> + </example> + + <note> + <para>This example includes section numbers in the section + titles. You should not do this in your documents. Adding + the section numbers is carried out by the stylesheets (of + which more later), and you do not need to manage them + yourself.</para> + </note> + </sect3> + + <sect3> + <title>Subdividing Using <tag>part</tag> + Elements</title> + + <para>You can introduce another layer of organization between + <tag>book</tag> and <tag>chapter</tag> with + one or more <tag>part</tag>s. This cannot be done + in an <tag>article</tag>.</para> + + <programlisting><![CDATA[<part> + <title>Introduction</title> + + <chapter> + <title>Overview</title> + + ... + </chapter> + + <chapter> + <title>What is FreeBSD?</title> + + ... + </chapter> + + <chapter> + <title>History</title> + + ... + </chapter> +</part>]]></programlisting> + </sect3> + </sect2> + + <sect2> + <title>Block Elements</title> + + <sect3> + <title>Paragraphs</title> + + <para>DocBook supports three types of paragraphs: + <tag>formalpara</tag>, <tag>para</tag>, and + <tag>simpara</tag>.</para> + + <para>Most of the time you will only need to use + <tag>para</tag>. <tag>formalpara</tag> + includes a <tag>title</tag> element, and + <tag>simpara</tag> disallows some elements from + within <tag>para</tag>. Stick with + <tag>para</tag>.</para> + + <example> + <title><tag>para</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>This is a paragraph. It can contain just about any + other element.</para> ]]></programlisting> + + <para>Appearance:</para> + + <para>This is a paragraph. It can contain just about any + other element.</para> + </example> + </sect3> + + <sect3> + <title>Block Quotations</title> + + <para>A block quotation is an extended quotation from another + document that should not appear within the current + paragraph. You will probably only need it + infrequently.</para> + + <para>Blockquotes can optionally contain a title and an + attribution (or they can be left untitled and + unattributed).</para> + + <example> + <title><tag>blockquote</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>A small excerpt from the US Constitution:</para> + +<blockquote> + <title>Preamble to the Constitution of the United States</title> + + <attribution>Copied from a web site somewhere</attribution> + + <para>We the People of the United States, in Order to form a more perfect + Union, establish Justice, insure domestic Tranquility, provide for the + common defence, promote the general Welfare, and secure the Blessings + of Liberty to ourselves and our Posterity, do ordain and establish this + Constitution for the United States of America.</para> +</blockquote>]]></programlisting> + + <para>Appearance:</para> + + <para>A small excerpt from the US Constitution:</para> + + <blockquote> + <title>Preamble to the Constitution of the United + States</title> + + <attribution>Copied from a web site + somewhere</attribution> + + <para>We the People of the United States, in Order to form + a more perfect Union, establish Justice, insure domestic + Tranquility, provide for the common defence, promote the + general Welfare, and secure the Blessings of Liberty to + ourselves and our Posterity, do ordain and establish + this Constitution for the United States of + America.</para> + </blockquote> + </example> + </sect3> + + <sect3> + <title>Tips, Notes, Warnings, Cautions, Important Information + and Sidebars</title> + + <para>You may need to include extra information separate from + the main body of the text. Typically this is + <quote>meta</quote> information that the user should be + aware of.</para> + + <para>Depending on the nature of the information, one of + <tag>tip</tag>, <tag>note</tag>, + <tag>warning</tag>, <tag>caution</tag>, and + <tag>important</tag> should be used. Alternatively, + if the information is related to the main text but is not + one of the above, use <tag>sidebar</tag>.</para> + + <para>The circumstances in which to choose one of these + elements over another is unclear. The DocBook documentation + suggests:</para> + + <itemizedlist> + <listitem> + <para>A Note is for information that should be heeded by + all readers.</para> + </listitem> + + <listitem> + <para>An Important element is a variation on Note.</para> + </listitem> + + <listitem> + <para>A Caution is for information regarding possible data + loss or software damage.</para> + </listitem> + + <listitem> + <para>A Warning is for information regarding possible + hardware damage or injury to life or limb.</para> + </listitem> + </itemizedlist> + + <example> + <title><tag>warning</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<warning> + <para>Installing FreeBSD may make you want to delete Windows from your + hard disk.</para> +</warning>]]></programlisting> + </example> + + <para>Appearance:</para> + <!-- Need to do this outside of the example --> + <warning> + <para>Installing FreeBSD may make you want to delete Windows + from your hard disk.</para> + </warning> + </sect3> + + <sect3> + <title>Lists and Procedures</title> + + <para>You will often need to list pieces of information to the + user, or present them with a number of steps that must be + carried out in order to accomplish a particular goal.</para> + + <para>In order to do this, use + <tag>itemizedlist</tag>, + <tag>orderedlist</tag>, or + <tag>procedure</tag><footnote><para>There are other + types of list element in DocBook, but we are not + concerned with those at the + moment.</para></footnote></para> + + <para><tag>itemizedlist</tag> and + <tag>orderedlist</tag> are similar to their + counterparts in HTML, <tag>ul</tag> and + <tag>ol</tag>. Each one consists of one or more + <tag>listitem</tag> elements, and each + <tag>listitem</tag> contains one or more block + elements. The <tag>listitem</tag> elements are + analogous to HTML's <tag>li</tag> tags. However, + unlike HTML, they are required.</para> + + <para><tag>procedure</tag> is slightly different. It + consists of <tag>step</tag>s, which may in turn + consists of more <tag>step</tag>s or + <tag>substep</tag>s. Each <tag>step</tag> + contains block elements.</para> + + <example> + <title><tag>itemizedlist</tag>, + <tag>orderedlist</tag>, and + <tag>procedure</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<itemizedlist> + <listitem> + <para>This is the first itemized item.</para> + </listitem> + + <listitem> + <para>This is the second itemized item.</para> + </listitem> +</itemizedlist> + +<orderedlist> + <listitem> + <para>This is the first ordered item.</para> + </listitem> + + <listitem> + <para>This is the second ordered item.</para> + </listitem> +</orderedlist> + +<procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <para>And now do this.</para> + </step> +</procedure>]]></programlisting> + + <para>Appearance:</para> + + <itemizedlist> + <listitem> + <para>This is the first itemized item.</para> + </listitem> + + <listitem> + <para>This is the second itemized item.</para> + </listitem> + </itemizedlist> + + <orderedlist> + <listitem> + <para>This is the first ordered item.</para> + </listitem> + + <listitem> + <para>This is the second ordered item.</para> + </listitem> + </orderedlist> + </example> + + <!-- Can't have <procedure> inside <example>, so this is a cheat --> + + <procedure> + <step> + <para>Do this.</para> + </step> + + <step> + <para>Then do this.</para> + </step> + + <step> + <para>And now do this.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Showing File Samples</title> + + <para>If you want to show a fragment of a file (or perhaps a + complete file) to the user, wrap it in the + <tag>programlisting</tag> element.</para> + + <para>White space and line breaks within + <tag>programlisting</tag> <emphasis>are</emphasis> + significant. In particular, this means that the opening tag + should appear on the same line as the first line of the + output, and the closing tag should appear on the same line + as the last line of the output, otherwise spurious blank + lines may be included.</para> + + <example> + <title><tag>programlisting</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>When you have finished, your program should look like + this:</para> + +<programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting>]]></programlisting> + + <para>Notice how the angle brackets in the + <literal>#include</literal> line need to be referenced by + their entities instead of being included literally.</para> + + <para>Appearance:</para> + + <para>When you have finished, your program should look like + this:</para> + + <programlisting>#include <stdio.h> + +int +main(void) +{ + printf("hello, world\n"); +}</programlisting> + </example> + </sect3> + + <sect3> + <title>Callouts</title> + + <para>A callout is a mechanism for referring back to an + earlier piece of text or specific position within an earlier + example without linking to it within the text.</para> + + <para>To do this, mark areas of interest in your example + (<tag>programlisting</tag>, + <tag>literallayout</tag>, or whatever) with the + <tag>co</tag> element. Each element must have a + unique <literal>id</literal> assigned to it. After the + example include a <tag>calloutlist</tag> that refers + back to the example and provides additional + commentary.</para> + + <example> + <title><tag>co</tag> and + <tag>calloutlist</tag></title> + + <programlisting><![CDATA[<para>When you have finished, your program should look like + this:</para> + +<programlisting>#include <stdio.h> <co id="co-ex-include"/> + +int <co id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co id="co-ex-printf"/> +}</programlisting> + +<calloutlist> + <callout arearefs="co-ex-include"> + <para>Includes the standard IO header file.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Specifies that <function>main()</function> returns an + int.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>The <function>printf()</function> call that writes + <literal>hello, world</literal> to standard output.</para> + </callout> +</calloutlist>]]></programlisting> + + <para>Appearance:</para> + + <para>When you have finished, your program should look like + this:</para> + + <programlisting>#include <stdio.h> <co xml:id="co-ex-include"/> + +int <co xml:id="co-ex-return"/> +main(void) +{ + printf("hello, world\n"); <co xml:id="co-ex-printf"/> +}</programlisting> + + <calloutlist> + <callout arearefs="co-ex-include"> + <para>Includes the standard IO header file.</para> + </callout> + + <callout arearefs="co-ex-return"> + <para>Specifies that <function>main()</function> returns + an int.</para> + </callout> + + <callout arearefs="co-ex-printf"> + <para>The <function>printf()</function> call that writes + <literal>hello, world</literal> to standard + output.</para> + </callout> + </calloutlist> + </example> + </sect3> + + <sect3> + <title>Tables</title> + + <para>Unlike HTML, you do not need to use tables for layout + purposes, as the stylesheet handles those issues for you. + Instead, just use tables for marking up tabular data.</para> + + <para>In general terms (and see the DocBook documentation for + more detail) a table (which can be either formal or + informal) consists of a <tag>table</tag> element. + This contains at least one <tag>tgroup</tag> + element, which specifies (as an attribute) the number of + columns in this table group. Within the tablegroup you can + then have one <tag>thead</tag> element, which + contains elements for the table headings (column headings), + and one <tag>tbody</tag> which contains the body of + the table.</para> + + <para>Both <tag>tgroup</tag> and + <tag>thead</tag> contain <tag>row</tag> + elements, which in turn contain <tag>entry</tag> + elements. Each <tag>entry</tag> element specifies + one cell in the table.</para> + + <example> + <title><tag>informaltable</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> +</informaltable>]]></programlisting> + + <para>Appearance:</para> + + <informaltable pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + + <para>Always use the <literal>pgwide</literal> attribute with + a value of <literal>1</literal> with the + <tag>informaltable</tag> element. A bug in Internet + Explorer can cause the table to render incorrectly if this + is omitted.</para> + + <para>If you do not want a border around the table the + <literal>frame</literal> attribute can be added to the + <tag>informaltable</tag> element with a value of + <literal>none</literal> (i.e., <literal><informaltable + frame="none"></literal>).</para> + + <example> + <title>Tables Where <literal>frame="none"</literal></title> + + <para>Appearance:</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <thead> + <row> + <entry>This is Column Head 1</entry> + <entry>This is Column Head 2</entry> + </row> + </thead> + + <tbody> + <row> + <entry>Row 1, column 1</entry> + <entry>Row 1, column 2</entry> + </row> + + <row> + <entry>Row 2, column 1</entry> + <entry>Row 2, column 2</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </example> + </sect3> + + <sect3> + <title>Examples for the User to Follow</title> + + <para>A lot of the time you need to show examples for the user + to follow. Typically, these will consist of dialogs with + the computer; the user types in a command, the user gets a + response back, they type in another command, and so + on.</para> + + <para>A number of distinct elements and entities come into + play here.</para> + + <variablelist> + <varlistentry> + <term><tag>screen</tag></term> + + <listitem> + <para>Everything the user sees in this example will be + on the computer screen, so the next element is + <tag>screen</tag>.</para> + + <para>Within <tag>screen</tag>, white space is + significant.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><tag>prompt</tag>, + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal></term> + + <listitem> + <para>Some of the things the user will be seeing on the + screen are prompts from the computer (either from the + operating system, command shell, or application). + These should be marked up using + <tag>prompt</tag>.</para> + + <para>As a special case, the two shell prompts for the + normal user and the root user have been provided as + entities. Every time you want to indicate the user is + at a shell prompt, use one of + <literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> as necessary. + They do not need to be inside + <tag>prompt</tag>.</para> + + <note> + <para><literal>&prompt.root;</literal> and + <literal>&prompt.user;</literal> are FreeBSD + extensions to DocBook, and are not part of the + original DTD.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><tag>userinput</tag></term> + + <listitem> + <para>When displaying text that the user should type in, + wrap it in <tag>userinput</tag> tags. It will + probably be displayed differently to the user.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><tag>screen</tag>, <tag>prompt</tag>, + and <tag>userinput</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen>]]></programlisting> + + <para>Appearance:</para> + + <screen>&prompt.user; <userinput>ls -1</userinput> +foo1 +foo2 +foo3 +&prompt.user; <userinput>ls -1 | grep foo2</userinput> +foo2 +&prompt.user; <userinput>su</userinput> +<prompt>Password: </prompt> +&prompt.root; <userinput>cat foo2</userinput> +This is the file called 'foo2'</screen> + </example> + + <note> + <para>Even though we are displaying the contents of the file + <filename>foo2</filename>, it is <emphasis>not</emphasis> + marked up as <tag>programlisting</tag>. Reserve + <tag>programlisting</tag> for showing fragments of + files outside the context of user actions.</para> + </note> + </sect3> + </sect2> + + <sect2> + <title>In-line Elements</title> + + <sect3> + <title>Emphasizing Information</title> + + <para>When you want to emphasize a particular word or phrase, + use <tag>emphasis</tag>. This may be presented as + italic, or bold, or might be spoken differently with a + text-to-speech system.</para> + + <para>There is no way to change the presentation of the + emphasis within your document, no equivalent of HTML's + <tag>b</tag> and <tag>i</tag>. If the + information you are presenting is important then consider + presenting it in <tag>important</tag> rather than + <tag>emphasis</tag>.</para> + + <example> + <title><tag>emphasis</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>FreeBSD is without doubt <emphasis>the</emphasis> + premiere Unix like operating system for the Intel architecture.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>FreeBSD is without doubt <emphasis>the</emphasis> + premiere Unix like operating system for the Intel + architecture.</para> + </example> + </sect3> + + <sect3> + <title>Quotations</title> + + <para>To quote text from another document or source, or to + denote a phrase that is used figuratively, use + <tag>quote</tag>. Within a <tag>quote</tag> + tag, you may use most of the markup tags available for + normal text.</para> + + <example> + <title>Quotations</title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>However, make sure that the search does not go beyond the + <quote>boundary between local and public administration</quote>, + as RFC 1535 calls it.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>However, make sure that the search does not go beyond + the <quote>boundary between local and public + administration</quote>, as RFC 1535 calls it.</para> + </example> + </sect3> + + <sect3> + <title>Keys, Mouse Buttons, and Combinations</title> + + <para>To refer to a specific key on the keyboard, use + <tag>keycap</tag>. To refer to a mouse button, use + <tag>mousebutton</tag>. And to refer to + combinations of key presses or mouse clicks, wrap them all + in <tag>keycombo</tag>.</para> + + <para><tag>keycombo</tag> has an attribute called + <literal>action</literal>, which may be one of + <literal>click</literal>, <literal>double-click</literal>, + <literal>other</literal>, <literal>press</literal>, + <literal>seq</literal>, or <literal>simul</literal>. The + last two values denote whether the keys or buttons should be + pressed in sequence, or simultaneously.</para> + + <para>The stylesheets automatically add any connecting + symbols, such as <literal>+</literal>, between the key + names, when wrapped in <tag>keycombo</tag>.</para> + + <example> + <title>Keys, Mouse Buttons, and Combinations</title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>To switch to the second virtual terminal, press + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + +<para>To exit <command>vi</command> without saving your work, type + <keycombo action="seq"><keycap>Esc</keycap><keycap>:</keycap> + <keycap>q</keycap><keycap>!</keycap></keycombo>.</para> + +<para>My window manager is configured so that + <keycombo action="simul"><keycap>Alt</keycap> + <mousebutton>right</mousebutton> + </keycombo> mouse button is used to move windows.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To switch to the second virtual terminal, press + <keycombo action="simul"><keycap>Alt</keycap> + <keycap>F1</keycap></keycombo>.</para> + + <para>To exit <command>vi</command> without saving your + work, type <keycombo action="seq"> + <keycap>Esc</keycap> + <keycap>:</keycap> + <keycap>q</keycap> + <keycap>!</keycap></keycombo>.</para> + + <para>My window manager is configured so that + <keycombo action="simul"> + <keycap>Alt</keycap> + <mousebutton>right</mousebutton></keycombo> mouse button + is used to move windows.</para> + </example> + </sect3> + + <sect3> + <title>Applications, Commands, Options, and Cites</title> + + <para>You will frequently want to refer to both applications + and commands when writing documentation. The distinction + between them is simple: an application is the name for a + suite (or possibly just 1) of programs that fulfill a + particular task. A command is the name of a program that + the user can run.</para> + + <para>In addition, you will occasionally need to list one or + more of the options that a command might take.</para> + + <para>Finally, you will often want to list a command with its + manual section number, in the <quote>command(number)</quote> + format so common in Unix manuals.</para> + + <para>Mark up application names with + <tag>application</tag>.</para> + + <para>When you want to list a command with its manual section + number (which should be most of the time) the DocBook + element is <tag>citerefentry</tag>. This will + contain a further two elements, + <tag>refentrytitle</tag> and + <tag>manvolnum</tag>. The content of + <tag>refentrytitle</tag> is the name of the command, + and the content of <tag>manvolnum</tag> is the + manual page section.</para> + + <para>This can be cumbersome to write, and so a series of + <link linkend="xml-primer-general-entities">general + entities</link> have been created to make this easier. + Each entity takes the form + <literal>&man.manual-page.manual-section;</literal>.</para> + + <para>The file that contains these entities is in + <filename>doc/share/xml/man-refs.ent</filename>, and can be + referred to using this FPI:</para> + + <programlisting>PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"</programlisting> + + <para>Therefore, the introduction to your documentation will + probably look like this:</para> + + <programlisting><!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [ + +<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"> +%man; + +… + +]></programlisting> + + <para>Use <tag>command</tag> when you want to include + a command name <quote>in-line</quote> but present it as + something the user should type in.</para> + + <para>Use <tag>option</tag> to mark up the options + which will be passed to a command.</para> + + <para>When referring to the same command multiple times in + close proximity it is preferred to use the + <literal>&man.command.section;</literal> + notation to markup the first reference and use + <tag>command</tag> to markup subsequent references. + This makes the generated output, especially HTML, appear + visually better.</para> + + <para>This can be confusing, and sometimes the choice is not + always clear. Hopefully this example makes it + clearer.</para> + + <example> + <title>Applications, Commands, and Options</title> + + <para>Use:</para> + + <programlisting><![CDATA[<para><application>Sendmail</application> is the most + widely used Unix mail application.</para> + +<para><application>Sendmail</application> includes the + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.mailq.1;, and &man.newaliases.1; + programs.</para> + +<para>One of the command line parameters to <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, will display the current + status of messages in the mail queue. Check this on the command + line by running <command>sendmail -bp</command>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para><application>Sendmail</application> is the most widely + used Unix mail application.</para> + + <para><application>Sendmail</application> includes the + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, &man.mailq.1;, and &man.newaliases.1; + programs.</para> + + <para>One of the command line parameters to + <citerefentry> + <refentrytitle>sendmail</refentrytitle> + <manvolnum>8</manvolnum> + </citerefentry>, <option>-bp</option>, will display the + current status of messages in the mail queue. Check this + on the command line by running + <command>sendmail -bp</command>.</para> + </example> + + <note> + <para>Notice how the + <literal>&man.command.section;</literal> + notation is easier to follow.</para> + </note> + </sect3> + + <sect3> + <title>Files, Directories, Extensions</title> + + <para>Whenever you wish to refer to the name of a file, a + directory, or a file extension, use + <tag>filename</tag>.</para> + + <example> + <title><tag>filename</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>The SGML source for the Handbook in English can be + found in <filename class="directory">/usr/doc/en_US.ISO8859-1/books/handbook/</filename>. The first + file is called <filename>book.xml</filename> in that + directory. You should also see a <filename>Makefile</filename> + and a number of files with a <filename>.ent</filename> + extension.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The SGML source for the Handbook in English can be + found in <filename>/usr/doc/en/handbook/</filename>. The + first file is called <filename>handbook.xml</filename> in + that directory. You should also see a + <filename>Makefile</filename> and a number of files with a + <filename>.ent</filename> extension.</para> + </example> + </sect3> + + <sect3> + <title>The Name of Ports</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + DTD.</para> + </note> + + <para>You might need to include the name of a program from the + FreeBSD Ports Collection in the documentation. Use the + <tag>filename</tag> tag with the + <literal>role</literal> attribute set to + <literal>package</literal> to identify these. Since ports + can be installed in any number of locations, only include + the category and the port name; do not include + <filename>/usr/ports</filename>.</para> + + <example> + <title><tag>filename</tag> Tag with + <literal>package</literal> Role</title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>Install the <filename role="package">net/ethereal</filename> port to view network traffic.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Install the <package>net/ethereal</package> port to view + network traffic.</para> + </example> + </sect3> + + <sect3> + <title>Devices</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + DTD.</para> + </note> + + <para>When referring to devices you have two choices. You can + either refer to the device as it appears in + <filename>/dev</filename>, or you can use the name of the + device as it appears in the kernel. For this latter course, + use <tag>devicename</tag>.</para> + + <para>Sometimes you will not have a choice. Some devices, + such as networking cards, do not have entries in + <filename>/dev</filename>, or the entries are markedly + different from those entries.</para> + + <example> + <title><tag>devicename</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para><devicename>sio</devicename> is used for serial + communication in FreeBSD. <devicename>sio</devicename> manifests + through a number of entries in <filename>/dev</filename>, including + <filename>/dev/ttyd0</filename> and <filename>/dev/cuaa0</filename>.</para> + +<para>By contrast, the networking devices, such as + <devicename>ed0</devicename> do not appear in <filename>/dev</filename>.</para> + +<para>In MS-DOS, the first floppy drive is referred to as + <devicename>a:</devicename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para><filename>sio</filename> is used for serial + communication in FreeBSD. <filename>sio</filename> + manifests through a number of entries in + <filename>/dev</filename>, including + <filename>/dev/ttyd0</filename> and + <filename>/dev/cuaa0</filename>.</para> + + <para>By contrast, the networking devices, such as + <filename>ed0</filename> do not appear in + <filename>/dev</filename>.</para> + + <para>In MS-DOS, the first floppy drive is referred to as + <filename>a:</filename>. In FreeBSD it is + <filename>/dev/fd0</filename>.</para> + </example> + </sect3> + + <sect3> + <title>Hosts, Domains, IP Addresses, and So Forth</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + DTD.</para> + </note> + + <para>You can markup identification information for networked + computers (hosts) in several ways, depending on the nature + of the information. All of them use + <tag>hostid</tag> as the element, with the + <literal>role</literal> attribute selecting the type of the + marked up information.</para> + + <variablelist> + <varlistentry> + <term>No <literal>role</literal> attribute, or + <literal>role="hostname"</literal></term> + + <listitem> + <para>With no <literal>role</literal> attribute (i.e., + <tag>hostid</tag>...<tag>/hostid</tag>) + the marked up information is the simple hostname, such + as <literal>freefall</literal> or + <literal>wcarchive</literal>. You can explicitly + specify this with + <literal>role="hostname"</literal>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="domainname"</literal></term> + + <listitem> + <para>The text is a domain name, such as + <literal>FreeBSD.org</literal> or + <literal>ngo.org.uk</literal>. There is no hostname + component.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="fqdn"</literal></term> + + <listitem> + <para>The text is a Fully Qualified Domain Name, with + both hostname and domain name parts.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ipaddr"</literal></term> + + <listitem> + <para>The text is an IP address, probably expressed as a + dotted quad.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="ip6addr"</literal></term> + + <listitem> + <para>The text is an IPv6 address.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="netmask"</literal></term> + + <listitem> + <para>The text is a network mask, which might be + expressed as a dotted quad, a hexadecimal string, or + as a <literal>/</literal> followed by a number.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>role="mac"</literal></term> + + <listitem> + <para>The text is an Ethernet MAC address, expressed as + a series of 2 digit hexadecimal numbers separated by + colons.</para> + </listitem> + </varlistentry> + </variablelist> + + <example> + <title><tag>hostid</tag> and Roles</title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>The local machine can always be referred to by the + name <hostid>localhost</hostid>, which will have the IP address + <hostid role="ipaddr">127.0.0.1</hostid>.</para> + +<para>The <hostid role="domainname">FreeBSD.org</hostid> domain + contains a number of different hosts, including + <hostid role="fqdn">freefall.FreeBSD.org</hostid> and + <hostid role="fqdn">pointyhat.FreeBSD.org</hostid>.</para> + +<para>When adding an IP alias to an interface (using + <command>ifconfig</command>) <emphasis>always</emphasis> use a + netmask of <hostid role="netmask">255.255.255.255</hostid> + (which can also be expressed as <hostid + role="netmask">0xffffffff</hostid>).</para> + +<para>The MAC address uniquely identifies every network card + in existence. A typical MAC address looks like <hostid + role="mac">08:00:20:87:ef:d0</hostid>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The local machine can always be referred to by the + name <systemitem>localhost</systemitem>, which will have the IP + address <systemitem class="ipaddress">127.0.0.1</systemitem>.</para> + + <para>The <systemitem class="fqdomainname">FreeBSD.org</systemitem> + domain contains a number of different hosts, including + <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> and + <systemitem class="fqdomainname">bento.FreeBSD.org</systemitem>.</para> + + <para>When adding an IP alias to an interface (using + <command>ifconfig</command>) <emphasis>always</emphasis> + use a netmask of + <systemitem class="netmask">255.255.255.255</systemitem> + (which can also be expressed as <systemitem class="netmask">0xffffffff</systemitem>).</para> + + <para>The MAC address uniquely identifies every network card + in existence. A typical MAC address looks like <systemitem class="etheraddress">08:00:20:87:ef:d0</systemitem>.</para> + </example> + </sect3> + + <sect3> + <title>Usernames</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + DTD.</para> + </note> + + <para>When you need to refer to a specific username, such as + <literal>root</literal> or <literal>bin</literal>, use + <tag>username</tag>.</para> + + <example> + <title><tag>username</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>To carry out most system administration functions you + will need to be <username>root</username>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>To carry out most system administration functions you + will need to be <systemitem class="username">root</systemitem>.</para> + </example> + </sect3> + + <sect3> + <title>Describing <filename>Makefile</filename>s</title> + + <note> + <title>&os; Extension</title> + + <para>These elements are part of the FreeBSD extension to + DocBook, and do not exist in the original DocBook + DTD.</para> + </note> + + <para>Two elements exist to describe parts of + <filename>Makefile</filename>s, + <tag>maketarget</tag> and + <tag>makevar</tag>.</para> + + <para><tag>maketarget</tag> identifies a build target + exported by a <filename>Makefile</filename> that can be + given as a parameter to <command>make</command>. + <tag>makevar</tag> identifies a variable that can be + set (in the environment, on the <command>make</command> + command line, or within the <filename>Makefile</filename>) + to influence the process.</para> + + <example> + <title><tag>maketarget</tag> and + <tag>makevar</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>Two common targets in a <filename>Makefile</filename> + are <maketarget>all</maketarget> and <maketarget>clean</maketarget>.</para> + +<para>Typically, invoking <maketarget>all</maketarget> will rebuild the + application, and invoking <maketarget>clean</maketarget> will remove + the temporary files (<filename>.o</filename> for example) created by + the build process.</para> + +<para><maketarget>clean</maketarget> may be controlled by a number of + variables, including <makevar>CLOBBER</makevar> and + <makevar>RECURSE</makevar>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Two common targets in a <filename>Makefile</filename> + are <buildtarget>all</buildtarget> and + <buildtarget>clean</buildtarget>.</para> + + <para>Typically, invoking <buildtarget>all</buildtarget> will + rebuild the application, and invoking + <buildtarget>clean</buildtarget> will remove the temporary + files (<filename>.o</filename> for example) created by the + build process.</para> + + <para><buildtarget>clean</buildtarget> may be controlled by a + number of variables, including <varname>CLOBBER</varname> + and <varname>RECURSE</varname>.</para> + </example> + </sect3> + + <sect3> + <title>Literal Text</title> + + <para>You will often need to include <quote>literal</quote> + text in the documentation. This is text that is excerpted + from another file, or which should be copied from the + documentation into another file verbatim.</para> + + <para>Some of the time, <tag>programlisting</tag> will + be sufficient to denote this text. + <tag>programlisting</tag> is not always appropriate, + particularly when you want to include a portion of a file + <quote>in-line</quote> with the rest of the + paragraph.</para> + + <para>On these occasions, use + <tag>literal</tag>.</para> + + <example> + <title><tag>literal</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>The <literal>maxusers 10</literal> line in the kernel + configuration file determines the size of many system tables, and is + a rough guide to how many simultaneous logins the system will + support.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The <literal>maxusers 10</literal> line in the kernel + configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous + logins the system will support.</para> + </example> + </sect3> + + <sect3> + <title>Showing Items That the User <emphasis>Must</emphasis> + Fill In</title> + + <para>There will often be times when you want to show the user + what to do, or refer to a file, or command line, or similar, + where the user cannot simply copy the examples that you + provide, but must instead include some information + themselves.</para> + + <para><tag>replaceable</tag> is designed for this + eventuality. Use it <emphasis>inside</emphasis> other + elements to indicate parts of that element's content that + the user must replace.</para> + + <example> + <title><tag>replaceable</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen>]]></programlisting> + + <para>Appearance:</para> + + <informalexample> + <screen>&prompt.user; <userinput>man command</userinput></screen> + </informalexample> + + <para><tag>replaceable</tag> can be used in many + different elements, including <tag>literal</tag>. + This example also shows that + <tag>replaceable</tag> should only be wrapped + around the content that the user <emphasis>is</emphasis> + meant to provide. The other content should be left + alone.</para> + + <para>Use:</para> + + <programlisting><![CDATA[<para>The <literal>maxusers <replaceable>n</replaceable></literal> + line in the kernel configuration file determines the size of many system + tables, and is a rough guide to how many simultaneous logins the system will + support.</para> + +<para>For a desktop workstation, <literal>32</literal> is a good value + for <replaceable>n</replaceable>.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>The + <literal>maxusers n</literal> + line in the kernel configuration file determines the size + of many system tables, and is a rough guide to how many + simultaneous logins the system will support.</para> + + <para>For a desktop workstation, <literal>32</literal> is a + good value for <replaceable>n</replaceable>.</para> + </example> + </sect3> + + <sect3> + <title>Quoting System Errors</title> + + <para>You might want to show errors generated by FreeBSD. + Mark these with <tag>errorname</tag>. This + indicates the exact error that appears.</para> + + <example> + <title><tag>errorname</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[ +<screen><errorname>Panic: cannot mount root</errorname></screen> ]]> +</programlisting> + + + <para>Appearance:</para> + + <informalexample> + <screen><errorname>Panic: cannot mount root</errorname></screen> + </informalexample> + </example> + </sect3> + </sect2> + + <sect2> + <title>Images</title> + + <important> + <para>Image support in the documentation is currently + extremely experimental. The mechanisms described here are + unlikely to change, but that is not guaranteed.</para> + + <para>You will also need to install the + <package>graphics/ImageMagick</package> + port, which is used to convert between the different image + formats. This is a big port, and most of it is not + required. However, while we are working on the + <filename>Makefile</filename>s and other infrastructure it + makes things easier. This port is <emphasis>not</emphasis> + in the <package>textproc/docproj</package> + meta port, you must install it by hand.</para> + + <para>The best example of what follows in practice is the + <filename>doc/en_US.ISO8859-1/articles/vm-design/</filename> + document. If you are unsure of the description that + follows, take a look at the files in that directory to see + how everything hangs together. Experiment with creating + different formatted versions of the document to see how the + image markup appears in the formatted output.</para> + </important> + + <sect3> + <title>Image Formats</title> + + <para>We currently support two formats for images. The format + you should use will depend on the nature of your + image.</para> + + <para>For images that are primarily vector based, such as + network diagrams, time lines, and similar, use Encapsulated + Postscript, and make sure that your images have the + <filename>.eps</filename> extension.</para> + + <para>For bitmaps, such as screen captures, use the Portable + Network Graphic format, and make sure that your images have + the <filename>.png</filename> extension.</para> + + <para>These are the <emphasis>only</emphasis> formats in which + images should be committed to the Subversion + repository.</para> + + <para>Use the right format for the right image. It is to be + expected that your documentation will have a mix of EPS and + PNG images. The <filename>Makefile</filename>s ensure that + the correct format image is chosen depending on the output + format that you use for your documentation. <emphasis>Do + not commit the same image to the repository in two different + formats</emphasis>.</para> + + <important> + <para>It is anticipated that the Documentation Project will + switch to using the Scalable Vector Graphic (SVG) format + for vector images. However, the current state of SVG + capable editing tools makes this impractical.</para> + </important> + </sect3> + + <sect3> + <title>Markup</title> + + <para>The markup for an image is relatively simple. First, + markup a <tag>mediaobject</tag>. The + <tag>mediaobject</tag> can contain other, more + specific objects. We are concerned with two, the + <tag>imageobject</tag> and the + <tag>textobject</tag>.</para> + + <para>You should include one <tag>imageobject</tag>, + and two <tag>textobject</tag> elements. The + <tag>imageobject</tag> will point to the name of the + image file that will be used (without the extension). The + <tag>textobject</tag> elements contain information + that will be presented to the user as well as, or instead + of, the image.</para> + + <para>There are two circumstances where this can + happen.</para> + + <itemizedlist> + <listitem> + <para>When the reader is viewing the documentation in + HTML. In this case, each image will need to have + associated alternate text to show the user, typically + whilst the image is loading, or if they hover the mouse + pointer over the image.</para> + </listitem> + + <listitem> + <para>When the reader is viewing the documentation in + plain text. In this case, each image should have an + ASCII art equivalent to show the user.</para> + </listitem> + </itemizedlist> + + <para>An example will probably make things easier to + understand. Suppose you have an image, called + <filename>fig1.png</filename>, that you want to include in the + document. This image is of a rectangle with an A inside it. + The markup for this would be as follows.</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="fig1"> <co xml:id="co-image-ext"/> + </imageobject> + + <textobject> + <literallayout class="monospaced">+---------------+ <co xml:id="co-image-literal"/> +| A | ++---------------+</literallayout> + </textobject> + + <textobject> + <phrase>A picture</phrase> <co xml:id="co-image-phrase"/> + </textobject> +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-ext"> + <para>Include an <tag>imagedata</tag> element + inside the <tag>imageobject</tag> element. The + <literal>fileref</literal> attribute should contain the + filename of the image to include, without the extension. + The stylesheets will work out which extension should be + added to the filename automatically.</para> + </callout> + + <callout arearefs="co-image-literal"> + + <para>The first <tag>textobject</tag> should + contain a <tag>literallayout</tag> element, + where the <literal>class</literal> attribute is set to + <literal>monospaced</literal>. This is your opportunity + to demonstrate your ASCII art skills. This content will + be used if the document is converted to plain + text.</para> + + <para>Notice how the first and last lines of the content + of the <tag>literallayout</tag> element butt up + next to the element's tags. This ensures no extraneous + white space is included.</para> + </callout> + + <callout arearefs="co-image-phrase"> + <para>The second <tag>textobject</tag> should + contain a single <tag>phrase</tag> element. The + contents of this will become the <literal>alt</literal> + attribute for the image when this document is converted + to HTML.</para> + </callout> + </calloutlist> + </sect3> + + <sect3> + <title><filename>Makefile</filename> Entries</title> + + <para>Your images must be listed in the + <filename>Makefile</filename> in the + <varname>IMAGES</varname> variable. This variable should + contain the name of all your <emphasis>source</emphasis> + images. For example, if you have created three figures, + <filename>fig1.eps</filename>, + <filename>fig2.png</filename>, + <filename>fig3.png</filename>, then your + <filename>Makefile</filename> should have lines like this in + it.</para> + + <programlisting>… +IMAGES= fig1.eps fig2.png fig3.png +…</programlisting> + + <para>or</para> + + <programlisting>… +IMAGES= fig1.eps +IMAGES+= fig2.png +IMAGES+= fig3.png +…</programlisting> + + <para>Again, the <filename>Makefile</filename> will work out + the complete list of images it needs to build your source + document, you only need to list the image files + <emphasis>you</emphasis> provided.</para> + </sect3> + + <sect3> + <title>Images and Chapters in Subdirectories</title> + + <para>You must be careful when you separate your documentation + into smaller files (see + <xref linkend="xml-primer-include-using-gen-entities"/>) in + different directories.</para> + + <para>Suppose you have a book with three chapters, and the + chapters are stored in their own directories, called + <filename>chapter1/chapter.xml</filename>, + <filename>chapter2/chapter.xml</filename>, and + <filename>chapter3/chapter.xml</filename>. If each chapter + has images associated with it, it is suggested to place + those images in each chapter's subdirectory + (<filename>chapter1/</filename>, + <filename>chapter2/</filename>, and + <filename>chapter3/</filename>).</para> + + <para>However, if you do this you must include the directory + names in the <varname>IMAGES</varname> variable in the + <filename>Makefile</filename>, <emphasis>and</emphasis> you + must include the directory name in the + <tag>imagedata</tag> element in your + document.</para> + + <para>For example, if you have + <filename>chapter1/fig1.png</filename>, then + <filename>chapter1/chapter.xml</filename> should + contain:</para> + + <programlisting><mediaobject> + <imageobject> + <imagedata fileref="chapter1/fig1"> <co xml:id="co-image-dir"/> + </imageobject> + + … + +</mediaobject></programlisting> + + <calloutlist> + <callout arearefs="co-image-dir"> + <para>The directory name must be included in the + <literal>fileref</literal> attribute.</para> + </callout> + </calloutlist> + + <para>The <filename>Makefile</filename> must contain:</para> + + <programlisting>… +IMAGES= chapter1/fig1.png +…</programlisting> + + <para>Then everything should just work.</para> + </sect3> + </sect2> + + <sect2> + <title>Links</title> + + <note> + <para>Links are also in-line elements.</para> + </note> + + <sect3> + <title>Linking to Other Parts of the Same Document</title> + + <para>Linking within the same document requires you to specify + where you are linking from (i.e., the text the user will + click, or otherwise indicate, as the source of the link) and + where you are linking to (the link's destination).</para> + + <para>Each element within DocBook has an attribute called + <literal>id</literal>. You can place text in this attribute + to uniquely name the element it is attached to.</para> + + <para>This value will be used when you specify the link + source.</para> + + <para>Normally, you will only be linking to chapters or + sections, so you would add the <literal>id</literal> + attribute to these elements.</para> + + <example> + <title>Attribute <literal>id</literal> on Chapters and + Sections</title> + + <programlisting><![CDATA[<chapter id="chapter1"> + <title>Introduction</title> + + <para>This is the introduction. It contains a subsection, + which is identified as well.</para> + + <sect1 id="chapter1-sect1"> + <title>Sub-sect 1</title> + + <para>This is the subsection.</para> + </sect1> +</chapter>]]></programlisting> + </example> + + <para>Obviously, you should use more descriptive values. The + values must be unique within the document (i.e., not just + the file, but the document the file might be included in as + well). Notice how the <literal>id</literal> for the + subsection is constructed by appending text to the + <literal>id</literal> of the chapter. This helps to ensure + that they are unique.</para> + + <para>If you want to allow the user to jump into a specific + portion of the document (possibly in the middle of a + paragraph or an example), use <tag>anchor</tag>. + This element has no content, but takes an + <literal>id</literal> attribute.</para> + + <example> + <title><tag>anchor</tag></title> + + <programlisting><![CDATA[<para>This paragraph has an embedded + <anchor id="para1">link target in it. It will not show up in + the document.</para>]]></programlisting> + </example> + + <para>When you want to provide the user with a link they can + activate (probably by clicking) to go to a section of the + document that has an <literal>id</literal> attribute, you + can use either <tag>xref</tag> or + <tag>link</tag>.</para> + + <para>Both of these elements have a <literal>linkend</literal> + attribute. The value of this attribute should be the value + that you have used in a <literal>id</literal> attribute (it + does not matter if that value has not yet occurred in your + document; this will work for forward links as well as + backward links).</para> + + <para>If you use <tag>xref</tag> then you have no + control over the text of the link. It will be generated for + you.</para> + + <example> + <title>Using <tag>xref</tag></title> + + <para>Assume that this fragment appears somewhere in a + document that includes the <literal>id</literal> + example:</para> + + <programlisting><![CDATA[<para>More information can be found + in <xref linkend="chapter1"/>.</para> + +<para>More specific information can be found + in <xref linkend="chapter1-sect1"/>.</para>]]></programlisting> + + <para>The text of the link will be generated automatically, + and will look like (<emphasis>emphasized</emphasis> text + indicates the text that will be the link):</para> + + <blockquote> + <para>More information can be found in <emphasis>Chapter + One</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>the section called Sub-Sect + 1</emphasis>.</para> + </blockquote> + </example> + + <para>Notice how the text from the link is derived from the + section title or the chapter number.</para> + + <note> + <para>This means that you <emphasis>cannot</emphasis> use + <tag>xref</tag> to link to an + <literal>id</literal> attribute on an + <tag>anchor</tag> element. The + <tag>anchor</tag> has no content, so the + <tag>xref</tag> cannot generate the text for the + link.</para> + </note> + + <para>If you want to control the text of the link then use + <tag>link</tag>. This element wraps content, and + the content will be used for the link.</para> + + <example> + <title>Using <tag>link</tag></title> + + <para>Assume that this fragment appears somewhere in a + document that includes the <literal>id</literal> + example.</para> + + <programlisting><![CDATA[<para>More information can be found in + <link linkend="chapter1">the first chapter</link>.</para> + +<para>More specific information can be found in + <link linkend="chapter1-sect1">this</link> section.</para>]]></programlisting> + + <para>This will generate the following + (<emphasis>emphasized</emphasis> text indicates the text + that will be the link):</para> + + <blockquote> + <para>More information can be found in <emphasis>the first + chapter</emphasis>.</para> + + <para>More specific information can be found in + <emphasis>this</emphasis> section.</para> + </blockquote> + </example> + + <note> + <para>That last one is a bad example. Never use words like + <quote>this</quote> or <quote>here</quote> as the source + for the link. The reader will need to hunt around the + surrounding context to see where the link is actually + taking them.</para> + </note> + + <note> + <para>You <emphasis>can</emphasis> use + <tag>link</tag> to include a link to an + <literal>id</literal> on an <tag>anchor</tag> + element, since the <tag>link</tag> content defines + the text that will be used for the link.</para> + </note> + </sect3> + + <sect3> + <title>Linking to Documents on the WWW</title> + + <para>Linking to external documents is much simpler, as long + as you know the URL of the document you want to link to. + Use <tag>ulink</tag>. The <literal>url</literal> + attribute is the URL of the page that the link points to, + and the content of the element is the text that will be + displayed for the user to activate.</para> + + <example> + <title><tag>ulink</tag></title> + + <para>Use:</para> + + <programlisting><![CDATA[<para>Of course, you could stop reading this document and + go to the <ulink url="&url.base;/index.html">FreeBSD + home page</ulink> instead.</para>]]></programlisting> + + <para>Appearance:</para> + + <para>Of course, you could stop reading this document and go + to the <link xlink:href="&url.base;/index.html">FreeBSD home + page</link> instead.</para> + </example> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.xml new file mode 100644 index 0000000000..51336b2eb3 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/sgml-primer/chapter.xml @@ -0,0 +1,1529 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Copyright (c) 1998, 1999 Nik Clayton, All rights reserved. + + Redistribution and use in source (SGML DocBook) and 'compiled' forms + (SGML, HTML, PDF, PostScript, RTF and so forth) with or without + modification, are permitted provided that the following conditions + are met: + + 1. Redistributions of source code (SGML DocBook) must retain the above + copyright notice, this list of conditions and the following + disclaimer as the first lines of this file unmodified. + + 2. Redistributions in compiled form (transformed to other DTDs, + converted to PDF, PostScript, RTF and other formats) must reproduce + the above copyright notice, this list of conditions and the + following disclaimer in the documentation and/or other materials + provided with the distribution. + + THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "AS IS" AND ANY EXPRESS OR + IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES + OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE + DISCLAIMED. IN NO EVENT SHALL NIK CLAYTON BE LIABLE FOR ANY DIRECT, + INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES + (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR + SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) + HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, + STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN + ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE + POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-primer"> + <title>XML Primer</title> + + <para>The majority of FDP documentation is written in applications + of XML. This chapter explains exactly what that means, how to + read and understand the source to the documentation, and the sort + of XML tricks you will see used in the documentation.</para> + + <para>Portions of this section were inspired by Mark Galassi's + <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get + Going With DocBook</link>.</para> + + <sect1 xml:id="xml-primer-overview"> + <title>Overview</title> + + <para>Way back when, electronic text was simple to deal with. + Admittedly, you had to know which character set your document + was written in (ASCII, EBCDIC, or one of a number of others) but + that was about it. Text was text, and what you saw really was + what you got. No frills, no formatting, no intelligence.</para> + + <para>Inevitably, this was not enough. Once you have text in a + machine-usable format, you expect machines to be able to use it + and manipulate it intelligently. You would like to indicate + that certain phrases should be emphasized, or added to a + glossary, or be hyperlinks. You might want filenames to be + shown in a <quote>typewriter</quote> style font for viewing on + screen, but as <quote>italics</quote> when printed, or any of a + myriad of other options for presentation.</para> + + <para>It was once hoped that Artificial Intelligence (AI) would + make this easy. Your computer would read in the document and + automatically identify key phrases, filenames, text that the + reader should type in, examples, and more. Unfortunately, real + life has not happened quite like that, and our computers require + some assistance before they can meaningfully process our + text.</para> + + <para>More precisely, they need help identifying what is what. + Let's look at this text:</para> + + <blockquote> + <para>To remove <filename>/tmp/foo</filename> use + &man.rm.1;.</para> + + <screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen> + </blockquote> + + <para>It is easy to see which parts are filenames, which are + commands to be typed in, which parts are references to manual + pages, and so on. But the computer processing the document + cannot. For this we need markup.</para> + + <para><quote>Markup</quote> is commonly used to describe + <quote>adding value</quote> or <quote>increasing cost</quote>. + The term takes on both these meanings when applied to text. + Markup is additional text included in the document, + distinguished from the document's content in some way, so that + programs that process the document can read the markup and use + it when making decisions about the document. Editors can hide + the markup from the user, so the user is not distracted by + it.</para> + + <para>The extra information stored in the markup <emphasis>adds + value</emphasis> to the document. Adding the markup to the + document must typically be done by a person—after all, if + computers could recognize the text sufficiently well to add the + markup then there would be no need to add it in the first place. + This <emphasis>increases the cost</emphasis> (i.e., the effort + required) to create the document.</para> + + <para>The previous example is actually represented in this + document like this:</para> + + <programlisting><![CDATA[ +<para>To remove <filename>/tmp/foo</filename> use &man.rm.1;.</para> + +<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting> + + <para>As you can see, the markup is clearly separate from the + content.</para> + + <para>Obviously, if you are going to use markup you need to define + what your markup means, and how it should be interpreted. You + will need a markup language that you can follow when marking up + your documents.</para> + + <para>Of course, one markup language might not be enough. A + markup language for technical documentation has very different + requirements than a markup language that was to be used for + cookery recipes. This, in turn, would be very different from a + markup language used to describe poetry. What you really need + is a first language that you use to write these other markup + languages. A <emphasis>meta markup language</emphasis>.</para> + + <para>This is exactly what the eXtensible Markup + Language (XML) is. Many markup languages have been written in + XML, including the two most used by the FDP, XHTML and + DocBook.</para> + + <para>Each language definition is more properly called a grammar, + vocabulary, schema or Document Type Definition (DTD). There + are various languages to specify an XML grammar, for example, + DTD (yes, it also means the specification language itself), + XML Schema (XSD) or RELANG NG. The schema specifies the name + of the elements that can be used, what order they appear in (and + whether some markup can be used inside other markup) and related + information.</para> + + <para xml:id="xml-primer-validating">A schema is a + <emphasis>complete</emphasis> specification of all the elements + that are allowed to appear, the order in which they should + appear, which elements are mandatory, which are optional, and so + forth. This makes it possible to write an XML + <emphasis>parser</emphasis> which reads in both the schema and a + document which claims to conform to the schema. The parser can + then confirm whether or not all the elements required by the vocabulary + are in the document in the right order, and whether there are + any errors in the markup. This is normally referred to as + <quote>validating the document</quote>.</para> + + <note> + <para>This processing simply confirms that the choice of + elements, their ordering, and so on, conforms to that listed + in the grammar. It does <emphasis>not</emphasis> check that you + have used <emphasis>appropriate</emphasis> markup for the + content. If you tried to mark up all the filenames in your + document as function names, the parser would not flag this as + an error (assuming, of course, that your schema defines elements + for filenames and functions, and that they are allowed to + appear in the same place).</para> + </note> + + <para>It is likely that most of your contributions to the + Documentation Project will consist of content marked up in + either XHTML or DocBook, rather than alterations to the schemas. + For this reason this book will not touch on how to write a + vocabulary.</para> + </sect1> + + <sect1 xml:id="xml-primer-elements"> + <title>Elements, Tags, and Attributes</title> + + <para>All the vocabularies written in XML share certain characteristics. + This is hardly surprising, as the philosophy behind XML will + inevitably show through. One of the most obvious manifestations + of this philosophy is that of <emphasis>content</emphasis> and + <emphasis>elements</emphasis>.</para> + + <para>Your documentation (whether it is a single web page, or a + lengthy book) is considered to consist of content. This content + is then divided (and further subdivided) into elements. The + purpose of adding markup is to name and identify the boundaries + of these elements for further processing.</para> + + <para>For example, consider a typical book. At the very top + level, the book is itself an element. This <quote>book</quote> + element obviously contains chapters, which can be considered to + be elements in their own right. Each chapter will contain more + elements, such as paragraphs, quotations, and footnotes. Each + paragraph might contain further elements, identifying content + that was direct speech, or the name of a character in the + story.</para> + + <para>You might like to think of this as <quote>chunking</quote> + content. At the very top level you have one chunk, the book. + Look a little deeper, and you have more chunks, the individual + chapters. These are chunked further into paragraphs, footnotes, + character names, and so on.</para> + + <para>Notice how you can make this differentiation between + different elements of the content without resorting to any XML + terms. It really is surprisingly straightforward. You could do + this with a highlighter pen and a printout of the book, using + different colors to indicate different chunks of content.</para> + + <para>Of course, we do not have an electronic highlighter pen, so + we need some other way of indicating which element each piece of + content belongs to. In languages written in XML (XHTML, + DocBook, et al) this is done by means of + <emphasis>tags</emphasis>.</para> + + <para>A tag is used to identify where a particular element starts, + and where the element ends. <emphasis>The tag is not part of + the element itself</emphasis>. Because each grammar was normally + written to mark up specific types of information, each one will + recognize different elements, and will therefore have different + names for the tags.</para> + + <para>For an element called + <replaceable>element-name</replaceable> the start tag will + normally look like + <tag><replaceable>element-name</replaceable></tag>. The + corresponding closing tag for this element is + <tag>/<replaceable>element-name</replaceable></tag>.</para> + + <example> + <title>Using an Element (Start and End Tags)</title> + + <para>XHTML has an element for indicating that the content + enclosed by the element is a paragraph, called + <tag>p</tag>.</para> + + <programlisting><![CDATA[<p>This is a paragraph. It starts with the start tag for + the 'p' element, and it will end with the end tag for the 'p' + element.</p> + +<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> + </example> + + <para>Some elements have no + content. For example, in XHTML you can indicate that you want a + horizontal line to appear in the document.</para> + + <para>For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form:</para> + + <programlisting><![CDATA[<hr/>]]></programlisting> + + <example> + <title>Using an Element (Without Content)</title> + + <para>XHTML has an element for indicating a horizontal rule, + called <tag>hr</tag>. This element does not wrap + content, so it looks like this.</para> + + <programlisting><![CDATA[<p>One paragraph.</p> +<hr></hr> + +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> + + <para>For such elements, that have no content at all, XML introduced + a shorthand form, which is ccompletely equivalent to the above + form:</para> + + <programlisting><![CDATA[<p>One paragraph.</p> +<hr/> + +<p>This is another paragraph. A horizontal rule separates this + from the previous paragraph.</p>]]></programlisting> + </example> + + <para>If it is not obvious by now, elements can contain other + elements. In the book example earlier, the book element + contained all the chapter elements, which in turn contained all + the paragraph elements, and so on.</para> + + <example> + <title>Elements within Elements; <tag>em</tag></title> + + <programlisting><![CDATA[<p>This is a simple <em>paragraph</em> where some + of the <em>words</em> have been <em>emphasized</em>.</p>]]></programlisting> + </example> + + <para>The grammar will specify the rules detailing which elements can + contain other elements, and exactly what they can + contain.</para> + + <important> + <para>People often confuse the terms tags and elements, and use + the terms as if they were interchangeable. They are + not.</para> + + <para>An element is a conceptual part of your document. An + element has a defined start and end. The tags mark where the + element starts and end.</para> + + <para>When this document (or anyone else knowledgeable about + XML) refers to <quote>the <tag>p</tag> tag</quote> + they mean the literal text consisting of the three characters + <literal><</literal>, <literal>p</literal>, and + <literal>></literal>. But the phrase <quote>the + <tag>p</tag> element</quote> refers to the whole + element.</para> + + <para>This distinction <emphasis>is</emphasis> very subtle. But + keep it in mind.</para> + </important> + + <para>Elements can have attributes. An attribute has a name and a + value, and is used for adding extra information to the element. + This might be information that indicates how the content should + be rendered, or might be something that uniquely identifies that + occurrence of the element, or it might be something else.</para> + + <para>An element's attributes are written + <emphasis>inside</emphasis> the start tag for that element, and + take the form + <literal>attribute-name="attribute-value"</literal>.</para> + + <para>In XHTML, the + <tag>p</tag> element has an attribute called + <tag>align</tag>, which suggests an alignment + (justification) for the paragraph to the program displaying the + XHTML.</para> + + <para>The <literal>align</literal> attribute can take one of four + defined values, <literal>left</literal>, + <literal>center</literal>, <literal>right</literal> and + <literal>justify</literal>. If the attribute is not specified + then the default is <literal>left</literal>.</para> + + <example> + <title>Using An Element with An Attribute</title> + + <programlisting><![CDATA[<p align="left">The inclusion of the align attribute + on this paragraph was superfluous, since the default is left.</p> + +<p align="center">This may appear in the center.</p>]]></programlisting> + </example> + + <para>Some attributes will only take specific values, such as + <literal>left</literal> or <literal>justify</literal>. Others + will allow you to enter anything you want.</para> + + <example> + <title>Single Quotes Around Attributes</title> + + <programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting> + </example> + + <para>XML requires you to quote each attribute value with either + single or double quotes. It is more habitual to use double quotes + but you may use single quotes, as well. Using single quotes is + practical if you want to include double quotes in the attribute + value.</para> + + <para>The information on attributes, elements, and tags is stored + in XML catalogs. The various Documentation Project tools use + these catalog files to validate your work. The tools in + <package>textproc/docproj</package> include a + variety of XML catalog files. The FreeBSD Documentation + Project includes its own set of catalog files. Your tools need + to know about both sorts of catalog files.</para> + + <sect2> + <title>For You to Do…</title> + + <para>In order to run the examples in this document you will + need to install some software on your system and ensure that + an environment variable is set correctly.</para> + + <procedure> + <step> + <para>Download and install + <package>textproc/docproj</package> from + the FreeBSD ports system. This is a + <emphasis>meta-port</emphasis> that should download and + install all of the programs and supporting files that are + used by the Documentation Project.</para> + </step> + + <step> + <para>Add lines to your shell startup files to set + <envar>SGML_CATALOG_FILES</envar>. (If you are not working + on the English version of the documentation, you will want + to substitute the correct directory for your + language.)</para> + + <example xml:id="xml-primer-envars"> + <title><filename>.profile</filename>, for &man.sh.1; and + &man.bash.1; Users</title> + + <programlisting>SGML_ROOT=/usr/local/share/xml +SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog +SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/share/xml/catalog:$SGML_CATALOG_FILES +SGML_CATALOG_FILES=/usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES +export SGML_CATALOG_FILES</programlisting> + </example> + + <example> + <title><filename>.cshrc</filename>, for &man.csh.1; and + &man.tcsh.1; Users</title> + + <programlisting>setenv SGML_ROOT /usr/local/share/xml +setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog +setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/share/xml/catalog:$SGML_CATALOG_FILES +setenv SGML_CATALOG_FILES /usr/doc/en_US.ISO8859-1/share/xml/catalog:$SGML_CATALOG_FILES</programlisting> + </example> + + <para>Then either log out, and log back in again, or run + those commands from the command line to set the variable + values.</para> + </step> + </procedure> + + <procedure> + <step> + <para>Create <filename>example.xml</filename>, and enter + the following text:</para> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>An Example XHTML File</title> + </head> + + <body> + <p>This is a paragraph containing some text.</p> + + <p>This paragraph contains some more text.</p> + + <p align="right">This paragraph might be right-justified.</p> + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Try to validate this file using an XML parser.</para> + + <para>Part of + <package>textproc/docproj</package> is + the <command>xmllint</command> + <link linkend="xml-primer-validating">validating + parser</link>.</para> + + <para>Use <command>xmllint</command> in the following way to + check that your document is valid:</para> + + <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput></screen> + + <para>As you will see, <command>xmllint</command> returns + without displaying any output. This means that your + document validated successfully.</para> + </step> + + <step> + <para>See what happens when required elements are omitted. + Try removing the <tag>title</tag> and + <tag>/title</tag> tags, and re-run the + validation.</para> + + <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput> +example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()</screen> + + <para>This line tells you that the validation error comes from + the <replaceable>fifth</replaceable> line of the + <replaceable>example.xml</replaceable> file and that the + content of the <tag>head</tag> is the part, which + does not follow the rules described by the XHTML grammar.</para> + + <para>Below this line <command>xmllint</command> will show you + the line where the error has been found and will also mark the + exact character position with a ^ sign.</para> + </step> + + <step> + <para>Put the <tag>title</tag> element back + in.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-doctype-declaration"> + <title>The DOCTYPE Declaration</title> + + <para>The beginning of each document that you write may specify + the name of the DTD that the document conforms to in case you use + the DTD specification language. Other specification languages, like + XML Schema and RELAX NG are not referred in the source document. + This DOCTYPE declaration serves the XML parsers so that they can + determine the DTD and ensure that the document does conform to it.</para> + + <para>A typical declaration for a document written to conform with + version 1.0 of the XHTML DTD looks like this:</para> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">]]></programlisting> + + <para>That line contains a number of different components.</para> + + <variablelist> + <varlistentry> + <term><literal><!</literal></term> + + <listitem> + <para>Is the <emphasis>indicator</emphasis> that indicates + that this is an XML declaration. This line is declaring + the document type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>DOCTYPE</literal></term> + + <listitem> + <para>Shows that this is an XML declaration for the + document type.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>html</literal></term> + + <listitem> + <para>Names the first + <link linkend="xml-primer-elements">element</link> that + will appear in the document.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> + + <listitem> + <para>Lists the Formal Public Identifier (FPI) + <indexterm> + <primary>Formal Public Identifier</primary> + </indexterm> + for the DTD that this document conforms to. Your XML + parser will use this to find the correct DTD when + processing this document.</para> + + <para><literal>PUBLIC</literal> is not a part of the FPI, + but indicates to the XML processor how to find the DTD + referenced in the FPI. Other ways of telling the XML + parser how to find the DTD are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> + + <listitem> + <para>A local filename or an URL to find the DTD.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>></literal></term> + + <listitem> + <para>Returns to the document.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect2> + <title>Formal Public Identifiers (FPIs) + <indexterm significance="preferred"> + <primary>Formal Public Identifier</primary> + </indexterm></title> + + <note> + <para>You do not need to know this, but it is useful + background, and might help you debug problems when your XML + processor can not locate the DTD you are using.</para> + </note> + + <para>FPIs must follow a specific syntax. This syntax is as + follows:</para> + + <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> + + <variablelist> + <varlistentry> + <term><replaceable>Owner</replaceable></term> + + <listitem> + <para>This indicates the owner of the FPI.</para> + + <para>If this string starts with <quote>ISO</quote> then + this is an ISO owned FPI. For example, the FPI + <literal>"ISO 8879:1986//ENTITIES Greek + Symbols//EN"</literal> lists + <literal>ISO 8879:1986</literal> as being the owner for + the set of entities for Greek symbols. ISO 8879:1986 is + the ISO number for the SGML standard, the predecessor + (and a superset) of XML.</para> + + <para>Otherwise, this string will either look like + <literal>-//Owner</literal> + or + <literal>+//Owner</literal> + (notice the only difference is the leading + <literal>+</literal> or <literal>-</literal>).</para> + + <para>If the string starts with <literal>-</literal> then + the owner information is unregistered, with a + <literal>+</literal> it identifies it as being + registered.</para> + + <para>ISO 9070:1991 defines how registered names are + generated; it might be derived from the number of an ISO + publication, an ISBN code, or an organization code + assigned according to ISO 6523. In addition, a + registration authority could be created in order to + assign registered names. The ISO council delegated this + to the American National Standards Institute + (ANSI).</para> + + <para>Because the FreeBSD Project has not been registered + the owner string is <literal>-//FreeBSD</literal>. And + as you can see, the W3C are not a registered owner + either.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Keyword</replaceable></term> + + <listitem> + <para>There are several keywords that indicate the type of + information in the file. Some of the most common + keywords are <literal>DTD</literal>, + <literal>ELEMENT</literal>, <literal>ENTITIES</literal>, + and <literal>TEXT</literal>. <literal>DTD</literal> is + used only for DTD files, <literal>ELEMENT</literal> is + usually used for DTD fragments that contain only entity + or element declarations. <literal>TEXT</literal> is + used for XML content (text and tags).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Description</replaceable></term> + + <listitem> + <para>Any description you want to supply for the contents + of this file. This may include version numbers or any + short text that is meaningful to you and unique for the + XML system.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><replaceable>Language</replaceable></term> + + <listitem> + <para>This is an ISO two-character code that identifies + the native language for the file. <literal>EN</literal> + is used for English.</para> + </listitem> + </varlistentry> + </variablelist> + + <sect3> + <title><filename>catalog</filename> Files</title> + + <para>If you use the syntax above and process this document + using an XML processor, the processor will need to have + some way of turning the FPI into the name of the file on + your computer that contains the DTD.</para> + + <para>In order to do this it can use a catalog file. A + catalog file (typically called <filename>catalog</filename>) + contains lines that map FPIs to filenames. For example, if + the catalog file contained the line:</para> + +<!-- XXX: mention XML catalog or maybe replace this totally and only cover XML catalog --> + + <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "1.0/transitional.dtd"</programlisting> + + <para>The XML processor would know to look up the DTD from + <filename>transitional.dtd</filename> in the + <filename>1.0</filename> subdirectory of whichever directory + held the <filename>catalog</filename> file that contained + that line.</para> + + <para>Look at the contents of + <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. + This is the catalog file for the XHTML DTDs that will have + been installed as part of the <package>textproc/docproj</package> port.</para> + </sect3> + + <sect3> + <title><envar>SGML_CATALOG_FILES</envar></title> + + <para>In order to locate a <filename>catalog</filename> file, + your XML processor will need to know where to look. Many + of them feature command line parameters for specifying the + path to one or more catalogs.</para> + + <para>In addition, you can set + <envar>SGML_CATALOG_FILES</envar> to point to the files. + This environment variable should consist of a + colon-separated list of catalog files (including their full + path).</para> + + <para>Typically, you will want to include the following + files:</para> + + <itemizedlist> + <listitem> + <para><filename>/usr/local/share/xml/docbook/4.1/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/xml/html/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/xml/iso8879/catalog</filename></para> + </listitem> + + <listitem> + <para><filename>/usr/local/share/xml/jade/catalog</filename></para> + </listitem> + </itemizedlist> + + <para>You should <link linkend="xml-primer-envars">already + have done this</link>.</para> + </sect3> + </sect2> + + <sect2 xml:id="xml-primer-fpi-alternatives"> + <title>Alternatives to FPIs</title> + + <para>Instead of using an FPI to indicate the DTD that the + document conforms to (and therefore, which file on the system + contains the DTD) you can explicitly specify the name of the + file.</para> + + <para>The syntax for this is slightly different:</para> + + <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> + + <para>The <literal>SYSTEM</literal> keyword indicates that the + XML processor should locate the DTD in a system specific + fashion. This typically (but not always) means the DTD will + be provided as a filename.</para> + + <para>Using FPIs is preferred for reasons of portability. You + do not want to have to ship a copy of the DTD around with your + document, and if you used the <literal>SYSTEM</literal> + identifier then everyone would need to keep their DTDs in the + same place.</para> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-xml-escape"> + <title>Escaping Back to SGML</title> + + <para>As mentioned earlier, XML is only used when writing a DTD. + This is not strictly true. There is certain XML syntax that + you will want to be able to use within your documents. For + example, comments can be included in your document, and will be + ignored by the parser. Comments are entered using XML syntax. + Other uses for XML syntax in your document will be shown later + too.</para> + + <para>Obviously, you need some way of indicating to the XML + processor that the following content is not elements within the + document, but is XML that the parser should act upon.</para> + + <para>These sections are marked by + <literal><! ... ></literal> in your document. Everything + between these delimiters is XML syntax as you might find within + a DTD.</para> + + <para>As you may just have realized, the + <link linkend="xml-primer-doctype-declaration">DOCTYPE + declaration</link> is an example of XML syntax that you need + to include in your document…</para> + </sect1> + + <sect1 xml:id="xml-primer-comments"> + <title>Comments</title> + + <para>Comments are an XML construction, and are normally only + valid inside a DTD. However, as + <xref linkend="xml-primer-xml-escape"/> shows, it is possible + to use XML syntax within your document.</para> + + <para>The delimiter for XML comments is the string + <quote><literal>--</literal></quote>. The first occurrence of + this string opens a comment, and the second closes it.</para> + + <example> + <title>XML Generic Comment</title> + + <programlisting><!-- test comment --></programlisting> + + <programlisting> +<!‐- This is inside the comment -‐> + +<!‐- This is another comment -‐> + +<!‐- This is one way + of doing multiline comments -‐> + +<!‐- This is another way of -‐ + ‐- doing multiline comments -‐></programlisting> + </example> + + <para>If you have used XHTML before you may have been shown + different rules for comments. In particular, you may think that + the string <literal><!--</literal> opens a comment, and it is + only closed by <literal>--></literal>.</para> + + <para>This is <emphasis>not</emphasis> the case. A lot of web + browsers have broken XHTML parsers, and will accept that as + valid. However, the XML parsers used by the Documentation + Project are much stricter, and will reject documents that make + that error.</para> + + <example> + <title>Erroneous XML Comments</title> + + <programlisting> +<!‐- This is in the comment -‐ + + THIS IS OUTSIDE THE COMMENT! + + ‐- back inside the comment -‐></programlisting> + + <para>The XML parser will treat this as though it were + actually:</para> + + <programlisting><!THIS IS OUTSIDE THE COMMENT></programlisting> + + <para>This is not valid XML, and may give confusing error + messages.</para> + + <programlisting>>!‐‐‐‐‐ This is a very bad idea ‐‐‐‐‐></programlisting> + + <para>As the example suggests, <emphasis>do not</emphasis> write + comments like that.</para> + + <programlisting>>!-‐===================================================-‐></programlisting> + + <para>That is a (slightly) better approach, but it still + potentially confusing to people new to XML.</para> + </example> + + <sect2> + <title>For You to Do…</title> + + <procedure> + <step> + <para>Add some comments to + <filename>example.xml</filename>, and check that the file + still validates using <command>xmllint</command>.</para> + </step> + + <step> + <para>Add some invalid comments to + <filename>example.xml</filename>, and see the error + messages that <command>xmllint</command> gives when it + encounters an invalid comment.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-entities"> + <title>Entities</title> + + <para>Entities are a mechanism for assigning names to chunks of + content. As an XML parser processes your document, any + entities it finds are replaced by the content of the + entity.</para> + + <para>This is a good way to have re-usable, easily changeable + chunks of content in your XML documents. It is also the only + way to include one marked up file inside another using + XML.</para> + + <para>There are two types of entities which can be used in two + different situations; <emphasis>general entities</emphasis> and + <emphasis>parameter entities</emphasis>.</para> + + <sect2 xml:id="xml-primer-general-entities"> + <title>General Entities</title> + + <para>You cannot use general entities in an XML context + (although you define them in one). They can only be used in + your document. Contrast this with <link linkend="xml-primer-parameter-entities">parameter + entities</link>.</para> + + <para>Each general entity has a name. When you want to + reference a general entity (and therefore include whatever + text it represents in your document), you write + <literal>&entity-name;</literal>. + For example, suppose you had an entity called + <literal>current.version</literal> which expanded to the + current version number of your product. You could + write:</para> + + <programlisting><![CDATA[<para>The current version of our product is + ¤t.version;.</para>]]></programlisting> + + <para>When the version number changes you can simply change the + definition of the value of the general entity and reprocess + your document.</para> + + <para>You can also use general entities to enter characters that + you could not otherwise include in an XML document. For + example, <literal><</literal> and <literal>&</literal> + cannot normally appear in an XML document. When the XML + parser sees the <literal><</literal> symbol it assumes that + a tag (either a start tag or an end tag) is about to appear, + and when it sees the <literal>&</literal> symbol it + assumes the next text will be the name of an entity.</para> + + <para>Fortunately, you can use the two general entities + <literal>&lt;</literal> and <literal>&amp;</literal> + whenever you need to include one or other of these.</para> + + <para>A general entity can only be defined within an XML + context. Typically, this is done immediately after the + DOCTYPE declaration.</para> + + <example> + <title>Defining General Entities</title> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]>]]></programlisting> + + <para>Notice how the DOCTYPE declaration has been extended by + adding a square bracket at the end of the first line. The + two entities are then defined over the next two lines, + before the square bracket is closed, and then the DOCTYPE + declaration is closed.</para> + + <para>The square brackets are necessary to indicate that we + are extending the DTD indicated by the DOCTYPE + declaration.</para> + </example> + </sect2> + + <sect2 xml:id="xml-primer-parameter-entities"> + <title>Parameter Entities</title> + + <para>Like <link linkend="xml-primer-general-entities">general + entities</link>, parameter entities are used to assign names + to reusable chunks of text. However, whereas general entities + can only be used within your document, parameter entities can + only be used within an <link linkend="xml-primer-xml-escape">XML + context</link>.</para> + + <para>Parameter entities are defined in a similar way to general + entities. However, instead of using + <literal>&entity-name;</literal> + to refer to them, use + <literal>%entity-name;</literal> + <footnote><para><emphasis>P</emphasis>arameter entities use + the <emphasis>P</emphasis>ercent + symbol.</para></footnote>. The definition also includes + the <literal>%</literal> between the <literal>ENTITY</literal> + keyword and the name of the entity.</para> + + <example> + <title>Defining Parameter Entities</title> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % param.some "some"> +<!ENTITY % param.text "text"> +<!ENTITY % param.new "%param.some more %param.text"> +]>]]></programlisting> + </example> + + <para>This may not seem particularly useful. It will be.</para> + </sect2> + + <sect2> + <title>For You to Do…</title> + + <procedure> + <step> + <para>Add a general entity to + <filename>example.xml</filename>.</para> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY version "1.1"> +]> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>An Example XHTML File</title> + </head> + + <body> + <p>This is a paragraph containing some text.</p> + + <p>This paragraph contains some more text.</p> + + <p align="right">This paragraph might be right-justified.</p> + + <p>The current version of this document is: &version;</p> + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Validate the document using + <command>xmllint</command>.</para> + </step> + + <step> + <para>Load <filename>example.xml</filename> into your web + browser (you may need to copy it to + <filename>example.html</filename> before your browser + recognizes it as an XHTML document).</para> + + <para>Unless your browser is very advanced, you will not see + the entity reference <literal>&version;</literal> + replaced with the version number. Most web browsers have + very simplistic parsers which do not handle XML DTD + constructs. Furthermore, the closing <literal>]<</literal> + of the XML context are not recognized properly by browser and + will probably be rendered.</para> + </step> + + <step> + <para>The solution is to <emphasis>normalize</emphasis> your + document using an XML normalizer. The normalizer reads + in valid XML and outputs equally valid XML which has + been transformed in some way. One of the ways in which + the normalizer transforms the XML is to expand all the + entity references in the document, replacing the entities + with the text that they represent.</para> + + <para>You can use <command>xmllint</command> to do + this. It also has an option to drop the initial + DTD section so that the closing <literal>]<</literal> + does not confuse browsers:</para> + + <screen>&prompt.user; <userinput>xmllint --noent --dropdtd example.xml > example.html</userinput></screen> + + <para>You should find a normalized (i.e., entity references + expanded) copy of your document in + <filename>example.html</filename>, ready to load into your + web browser.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-include"> + <title>Using Entities to Include Files</title> + + <para>Entities (both + <link linkend="xml-primer-general-entities">general</link> and + <link linkend="xml-primer-parameter-entities">parameter</link>) + are particularly useful when used to include one file inside + another.</para> + + <sect2 xml:id="xml-primer-include-using-gen-entities"> + <title>Using General Entities to Include Files</title> + + <para>Suppose you have some content for an XML book organized + into files, one file per chapter, called + <filename>chapter1.xml</filename>, + <filename>chapter2.xml</filename>, and so forth, with a + <filename>book.xml</filename> file that will contain these + chapters.</para> + + <para>In order to use the contents of these files as the values + for your entities, you declare them with the + <literal>SYSTEM</literal> keyword. This directs the XML + parser to use the contents of the named file as the value of + the entity.</para> + + <example> + <title>Using General Entities to Include Files</title> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml"> +]> + +<html xmlns="http://www.w3.org/1999/xhtml"> + &chapter.1; + &chapter.2; + &chapter.3; +</html>]]></programlisting> + </example> + + <warning> + <para>When using general entities to include other files + within a document, the files being included + (<filename>chapter1.xml</filename>, + <filename>chapter2.xml</filename>, and so on) + <emphasis>must not</emphasis> start with a DOCTYPE + declaration. This is a syntax error because entities + are low-level constructs and they are resolved before + any parsing happens.</para> + </warning> + </sect2> + + <sect2> + <title>Using Parameter Entities to Include Files</title> + + <para>Recall that parameter entities can only be used inside an + XML context. Why then would you want to include a file + within an XML context?</para> + + <para>You can use this to ensure that you can reuse your general + entities.</para> + + <para>Suppose that you had many chapters in your document, and + you reused these chapters in two different books, each book + organizing the chapters in a different fashion.</para> + + <para>You could list the entities at the top of each book, but + this quickly becomes cumbersome to manage.</para> + + <para>Instead, place the general entity definitions inside one + file, and use a parameter entity to include that file within + your document.</para> + + <example> + <title>Using Parameter Entities to Include Files</title> + + <para>First, place your entity definitions in a separate file, + called <filename>chapters.ent</filename>. This file + contains the following:</para> + + <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml"> +<!ENTITY chapter.2 SYSTEM "chapter2.xml"> +<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting> + + <para>Now create a parameter entity to refer to the contents + of the file. Then use the parameter entity to load the file + into the document, which will then make all the general + entities available for use. Then use the general entities + as before:</para> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % chapters SYSTEM "chapters.ent"> +%chapters; +]> + +<html xmlns="http://www.w3.org/1999/xhtml"> + &chapter.1; + &chapter.2; + &chapter.3; +</html>]]></programlisting> + </example> + </sect2> + + <sect2> + <title>For You to Do…</title> + + <sect3> + <title>Use General Entities to Include Files</title> + + <procedure> + <step> + <para>Create three files, <filename>para1.xml</filename>, + <filename>para2.xml</filename>, and + <filename>para3.xml</filename>.</para> + + <para>Put content similar to the following in each + file:</para> + + <programlisting><![CDATA[<p>This is the first paragraph.</p>]]></programlisting> + </step> + + <step> + <para>Edit <filename>example.xml</filename> so that it + looks like this:</para> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"> +]> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>An Example XHTML File</title> + </head> + + <body> + <p>The current version of this document is: &version;</p> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by + normalizing <filename>example.xml</filename>.</para> + + <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> into your web + browser, and confirm that the + <filename>paran.xml</filename> + files have been included in + <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + + <sect3> + <title>Use Parameter Entities to Include Files</title> + + <note> + <para>You must have taken the previous steps first.</para> + </note> + + <procedure> + <step> + <para>Edit <filename>example.xml</filename> so that it + looks like this:</para> + + <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" +"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ +<!ENTITY % entities SYSTEM "entities.ent"> %entities; +]> + +<html xmlns="http://www.w3.org/1999/xhtml"> + <head> + <title>An Example XHTML File</title> + </head> + + <body> + <p>The current version of this document is: &version;</p> + + ¶1; + ¶2; + ¶3; + </body> +</html>]]></programlisting> + </step> + + <step> + <para>Create a new file, + <filename>entities.ent</filename>, with this + content:</para> + + <programlisting><![CDATA[<!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml">]]></programlisting> + </step> + + <step> + <para>Produce <filename>example.html</filename> by + normalizing <filename>example.xml</filename>.</para> + + <screen>&prompt.user; <userinput>xmllint --dropdtd --noent example.xml > example.html</userinput></screen> + </step> + + <step> + <para>Load <filename>example.html</filename> into your web + browser, and confirm that the + <filename>paran.xml</filename> + files have been included in + <filename>example.html</filename>.</para> + </step> + </procedure> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-marked-sections"> + <title>Marked Sections</title> + + <para>XML provides a mechanism to indicate that particular pieces + of the document should be processed in a special way. These are + termed <quote>marked sections</quote>.</para> + + <example> + <title>Structure of A Marked Section</title> + + <programlisting><![<replaceable>KEYWORD</replaceable>[ + Contents of marked section +]]></programlisting> + </example> + + <para>As you would expect, being an XML construct, a marked + section starts with <literal><!</literal>.</para> + + <para>The first square bracket begins to delimit the marked + section.</para> + + <para><replaceable>KEYWORD</replaceable> describes how this marked + section should be processed by the parser.</para> + + <para>The second square bracket indicates that the content of the + marked section starts here.</para> + + <para>The marked section is finished by closing the two square + brackets, and then returning to the document context from the + XGML context with <literal>></literal>.</para> + + <sect2> + <title>Marked Section Keywords</title> + + <sect3> + <title><literal>CDATA</literal></title> + + <para>These keywords denote the marked sections + <emphasis>content model</emphasis>, and allow you to change + it from the default.</para> + + <para>When an XML parser is processing a document it keeps + track of what is called the <quote>content + model</quote>.</para> + + <para>Briefly, the content model describes what sort of + content the parser is expecting to see, and what it will do + with it when it finds it.</para> + + <para>The content model you will probably find most + useful is <literal>CDATA</literal>.</para> + + <para><literal>CDATA</literal> is for <quote>Character + Data</quote>. If the parser is in this content model then + it is expecting to see characters, and characters only. In + this model the <literal><</literal> and + <literal>&</literal> symbols lose their special status, + and will be treated as ordinary characters.</para> + + <note> + <para>When you use <literal>CDATA</literal> + in examples of text marked up in + XML, keep in mind that the content of + <literal>CDATA</literal> is not validated. You have to + check the included XML text using other means. You + could, for example, write the example in another document, + validate the example code, and then paste it to your + <literal>CDATA</literal> content.</para> + </note> + + <!-- The nesting of CDATA within the next example is disgusting --> + <example> + <title>Using a <literal>CDATA</literal> Marked + Section</title> + + <programlisting><para>Here is an example of how you would include some text + that contained many <literal>&lt;</literal> + and <literal>&amp;</literal> symbols. The sample + text is a fragment of XHTML. The surrounding text (<para> and + <programlisting>) are from DocBook.</para> + +<programlisting> + <![CDATA[<![CDATA[ + <p>This is a sample that shows you some of the elements within + XHTML. Since the angle brackets are used so many times, it is + simpler to say the whole example is a CDATA marked section + than to use the entity names for the left and right angle + brackets throughout.</p> + + <ul> + <li>This is a listitem</li> + <li>This is a second listitem</li> + <li>This is a third listitem</li> + </ul> + + <p>This is the end of the example.</p>]]> + ]]> +</programlisting></programlisting> + + <para>If you look at the source for this document you will + see this technique used throughout.</para> + </example> + </sect3> + + <sect3> + <title><literal>INCLUDE</literal> and + <literal>IGNORE</literal></title> + + <para>If the keyword is <literal>INCLUDE</literal> then the + contents of the marked section will be processed. If the + keyword is <literal>IGNORE</literal> then the marked section + is ignored and will not be processed. It will not appear in + the output.</para> + + <example> + <title>Using <literal>INCLUDE</literal> and + <literal>IGNORE</literal> in Marked Sections</title> + + <programlisting><![INCLUDE[ + This text will be processed and included. +]]> + +<![IGNORE[ + This text will not be processed or included. +]]></programlisting> + </example> + + <para>By itself, this is not too useful. If you wanted to + remove text from your document you could cut it out, or wrap + it in comments.</para> + + <para>It becomes more useful when you realize you can use + <link linkend="xml-primer-parameter-entities">parameter + entities</link> to control this, yet this usage is limited + to entity files.</para> + + <para>For example, suppose that you produced a hard-copy + version of some documentation and an electronic version. In + the electronic version you wanted to include some extra + content that was not to appear in the hard-copy.</para> + + <para>Create an entity file that defines general entities + to include each chapter and guard these definitions with + a parameter entity that can be set to either + <literal>INCLUDE</literal> or <literal>IGNORE</literal> + to control whether the entity is defined. After these + conditional general entity definitions, place one more + definition for each general entity to set them to an + empty value. This technique makes use of the fact that + entity definitions cannot be overridden but always the + first definition takes effect. So you can control the + inclusion of your chapter with the corrsponding parameter + entity; if you set it to <literal>INCLUDE</literal>, the + first general entity definition will be read and the + second one will be ignored but if you set it to + <literal>IGNORE</literal>, the first definition will be + ignored and the second one will take effect.</para> + + <example> + <title>Using A Parameter Entity to Control a Marked + Section</title> + + <programlisting> +<!ENTITY % electronic.copy "INCLUDE"> + +<![%electronic.copy;[ +<!ENTITY chap.preface SYSTEM "preface.xml"> +]]> + +<!ENTITY chap.preface ""> +</programlisting> + + <para>When producing the hard-copy version, change the + parameter entity's definition to:</para> + + <programlisting><!ENTITY % electronic.copy "IGNORE"></programlisting> + </example> + </sect3> + </sect2> + + <sect2> + <title>For You to Do…</title> + + <procedure> + <step> + <para>Modify the <filename>entities.ent</filename> file to contain + the following:</para> + + <programlisting><!ENTITY version "1.1"> +<!ENTITY % conditional.text "IGNORE"> + +<![%conditional.text;[ +<!ENTITY para1 SYSTEM "para1.xml"> +]]> + +<!ENTITY para1 ""> + +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> + </step> + + <step> + <para>Normalize the <filename>example.xml</filename> file and notice + that the conditional text is not present on the output document. + Now if you set the parameter entity guard to <literal>INCLUDE</literal> + and regenerate the normalized document, it will appear there again. + Of course, this method makes more sense if you have more conditional + chunks that depend on the same condition, for example, whether you are + generating printed or online text.</para> + </step> + </procedure> + </sect2> + </sect1> + + <sect1 xml:id="xml-primer-conclusion"> + <title>Conclusion</title> + + <para>That is the conclusion of this XML primer. For reasons of + space and complexity several things have not been covered in + depth (or at all). However, the previous sections cover enough + XML for you to be able to follow the organization of the FDP + documentation.</para> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml index ad0cd93676..1c4d177084 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml @@ -30,12 +30,11 @@ $FreeBSD$ --> - -<chapter id="structure"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="structure"> <title>Documentation Directory Structure</title> <para>Files and directories in the - <filename class="directory">doc/</filename> tree follow a + <filename>doc/</filename> tree follow a structure meant to:</para> <orderedlist> @@ -61,12 +60,12 @@ important that the documentation tree structure does not enforce any particular defaults or cultural preferences.</para> - <sect1 id="structure-top"> + <sect1 xml:id="structure-top"> <title>The Top Level, - <filename class="directory">doc/</filename></title> + <filename>doc/</filename></title> <para>There are two types of directory under - <filename class="directory">doc/</filename>, each with very + <filename>doc/</filename>, each with very specific directory names and meanings.</para> <informaltable pgwide="1" frame="none"> @@ -81,28 +80,26 @@ <tbody> <row> <entry valign="top"> - <filename class="directory">share</filename></entry> + <filename>share</filename></entry> <entry>Contains files that are not specific to the various translations and encodings of the documentation. Contains subdirectories to further categorize the information. For example, the files that comprise the &man.make.1; infrastructure are in - <filename class="directory">share/mk</filename>, while + <filename>share/mk</filename>, while the additional <acronym>XML</acronym> support files (such as the &os; extended DocBook - <acronym>DTD</acronym>) are in <filename - class="directory">share/xml</filename>.</entry> + <acronym>DTD</acronym>) are in <filename>share/xml</filename>.</entry> </row> <row> - <entry valign="top"><filename - class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename></entry> + <entry valign="top"><filename>lang.encoding</filename></entry> <entry>One directory exists for each available translation and encoding of the documentation, for example - <filename class="directory">en_US.ISO8859-1/</filename> - and <filename class="directory">zh_TW.Big5/</filename>. + <filename>en_US.ISO8859-1/</filename> + and <filename>zh_TW.Big5/</filename>. The names are long, but by fully specifying the language and encoding we prevent any future headaches when a translation team wants to provide documentation in the @@ -115,9 +112,9 @@ </informaltable> </sect1> - <sect1 id="structure-locale"> + <sect1 xml:id="structure-locale"> <title>The - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> + <filename>lang.encoding/</filename> Directories</title> <para>These directories contain the documents themselves. The @@ -136,10 +133,10 @@ <tbody> <row> <entry valign="top"> - <filename class="directory">articles</filename></entry> + <filename>articles</filename></entry> <entry>Documentation marked up as a DocBook - <sgmltag>article</sgmltag> (or equivalent). Reasonably + <tag>article</tag> (or equivalent). Reasonably short, and broken up into sections. Normally only available as one <acronym>XHTML</acronym> file.</entry> </row> @@ -148,7 +145,7 @@ <entry valign="top"><filename>books</filename></entry> <entry>Documentation marked up as a DocBook - <sgmltag>book</sgmltag> (or equivalent). Book length, + <tag>book</tag> (or equivalent). Book length, and broken up into chapters. Normally available as both one large <acronym>XHTML</acronym> file (for people with fast connections, or who want to print it easily from a @@ -158,11 +155,10 @@ <row> <entry valign="top"> - <filename class="directory">man</filename></entry> + <filename>man</filename></entry> <entry>For translations of the system manual pages. This - directory will contain one or more <filename - class="directory">man<replaceable>n</replaceable></filename> + directory will contain one or more <filename>mann</filename> directories, corresponding to the sections that have been translated.</entry> </row> @@ -170,14 +166,13 @@ </tgroup> </informaltable> - <para>Not every <filename - class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> + <para>Not every <filename>lang.encoding</filename> directory will have all of these subdirectories. It depends on how much translation has been accomplished by that translation team.</para> </sect1> - <sect1 id="structure-document"> + <sect1 xml:id="structure-document"> <title>Document-Specific Information</title> <para>This section contains specific notes about particular @@ -192,12 +187,12 @@ using the &os; DocBook extended <acronym>DTD</acronym>.</para> <para>The Handbook is organized as a DocBook - <sgmltag>book</sgmltag>. The book is divided into - <sgmltag>part</sgmltag>s, each of which contains several - <sgmltag>chapter</sgmltag>s. <sgmltag>chapter</sgmltag>s are - further subdivided into sections (<sgmltag>sect1</sgmltag>) - and subsections (<sgmltag>sect2</sgmltag>, - <sgmltag>sect3</sgmltag>) and so on.</para> + <tag>book</tag>. The book is divided into + <tag>part</tag>s, each of which contains several + <tag>chapter</tag>s. <tag>chapter</tag>s are + further subdivided into sections (<tag>sect1</tag>) + and subsections (<tag>sect2</tag>, + <tag>sect3</tag>) and so on.</para> <sect3> <title>Physical Organization</title> @@ -228,38 +223,34 @@ <title><filename>book.xml</filename></title> <para>This is the top level document in the Handbook. It - contains the Handbook's <link - linkend="xml-primer-doctype-declaration">DOCTYPE + contains the Handbook's <link linkend="xml-primer-doctype-declaration">DOCTYPE declaration</link>, as well as the elements that describe the Handbook's structure.</para> - <para><filename>book.xml</filename> uses <link - linkend="xml-primer-parameter-entities">parameter + <para><filename>book.xml</filename> uses <link linkend="xml-primer-parameter-entities">parameter entities</link> to load in the files with the <filename>.ent</filename> extension. These files - (described later) then define <link - linkend="xml-primer-general-entities">general + (described later) then define <link linkend="xml-primer-general-entities">general entities</link> that are used throughout the rest of the Handbook.</para> </sect4> <sect4> - <title><filename - class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> + <title><filename>directory/chapter.xml</filename></title> <para>Each chapter in the Handbook is stored in a file called <filename>chapter.xml</filename> in a separate directory from the other chapters. Each directory is named after the value of the <literal>id</literal> - attribute on the <sgmltag>chapter</sgmltag> + attribute on the <tag>chapter</tag> element.</para> <para>For example, if one of the chapter files contains:</para> - <programlisting><sgmltag class="starttag">chapter id="kernelconfig"</sgmltag> + <programlisting><tag class="starttag">chapter id="kernelconfig"</tag> ... -<sgmltag class="endtag">chapter</sgmltag></programlisting> +<tag class="endtag">chapter</tag></programlisting> <para>Then it will be called <filename>chapter.xml</filename> in the @@ -277,10 +268,9 @@ stored in the same directory as <filename>book.xml</filename>, and named after the value of the <literal>id</literal> attribute on the file's - <sgmltag>chapter</sgmltag> element. Now, it is possible + <tag>chapter</tag> element. Now, it is possible to include images in each chapter. Images for each - Handbook chapter are stored within <filename - class="directory">share/images/books/handbook</filename>. + Handbook chapter are stored within <filename>share/images/books/handbook</filename>. The localized version of these images should be placed in the same directory as the <acronym>XML</acronym> sources for each chapter. Namespace collisions are diff --git a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml index a9905d4cf3..d8d48f16ae 100644 --- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<chapter id="stylesheets"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="stylesheets"> <title>Style Sheets</title> <para><acronym>XML</acronym> is concerned with content, and says @@ -51,7 +50,7 @@ <acronym>DSSSL</acronym> stylesheets, but this will probably change in the future.</para> - <sect1 id="stylesheets-css"> + <sect1 xml:id="stylesheets-css"> <title><acronym>CSS</acronym></title> <para>Cascading Style Sheets (<acronym>CSS</acronym>) are a diff --git a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml index e95a3ca560..a62fdbd2c0 100644 --- a/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/the-website/chapter.xml @@ -30,57 +30,53 @@ $FreeBSD$ --> - -<chapter id="the-website"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="the-website"> <title>The Website</title> - <sect1 id="the-website-build"> + <sect1 xml:id="the-website-build"> <title>Build the Web Pages</title> <para>Having obtained the documentation and web site source files, the web site can be built. In this example, the build directory - is <filename - class="directory"><replaceable>~/doc</replaceable></filename> + is <filename>~/doc</filename> and all the required files are already in place.</para> <para>The web site is built from the - <filename class="directory">en_US.ISO8859-1/htdocs</filename> + <filename>en_US.ISO8859-1/htdocs</filename> subdirectory of the document tree directory, - <filename class="directory">~/doc</filename> in this example. + <filename>~/doc</filename> in this example. Change to the build directory and start the build by executing <command>make all</command>.</para> - <screen>&prompt.user; <userinput><command>cd</command> ~/doc/en_US.ISO8859-1/htdocs</userinput> -&prompt.user; <userinput><command>make</command> <maketarget>all</maketarget></userinput></screen> + <screen>&prompt.user; <userinput>cd ~/doc/en_US.ISO8859-1/htdocs</userinput> +&prompt.user; <userinput>make all</userinput></screen> <tip> <para>The web site build uses the <filename>INDEX</filename> from the Ports Collection and may fail if that file or - <filename class="directory">/usr/ports</filename> is not - present. The simplest approach is to install the <ulink - url="&url.books.handbook;/ports.html#ports-tree">Ports - Collection</ulink>.</para> + <filename>/usr/ports</filename> is not + present. The simplest approach is to install the <link xlink:href="&url.books.handbook;/ports.html#ports-tree">Ports + Collection</link>.</para> </tip> </sect1> - <sect1 id="the-website-install"> + <sect1 xml:id="the-website-install"> <title>Install the Web Pages</title> <para>Run <command>make install</command>, setting - <makevar>DESTDIR</makevar> to the target directory for the web + <varname>DESTDIR</varname> to the target directory for the web site files. The files will be installed in - <filename class="directory">$DESTDIR/data</filename>, which is + <filename>$DESTDIR/data</filename>, which is expected to be the web server's document root.</para> - <para>This installation is run as the <username>root</username> + <para>This installation is run as the <systemitem class="username">root</systemitem> user because the permissions on the web server directory will not allow files to be installed by an unprivileged user. In this example, the web site files were built by user - <username>jru</username> in their home directory, <filename - class="directory">/usr/home/jru/doc</filename>.</para> + <systemitem class="username">jru</systemitem> in their home directory, <filename>/usr/home/jru/doc</filename>.</para> - <screen>&prompt.root; <userinput><command>cd</command> /home/jru/doc/en_US.ISO8859-1/htdocs</userinput> -&prompt.root; <userinput><command>env</command> <makevar>DESTDIR</makevar>=<replaceable>/usr/local/www</replaceable> <command>make</command> <maketarget>install</maketarget></userinput></screen> + <screen>&prompt.root; <userinput>cd /home/jru/doc/en_US.ISO8859-1/htdocs</userinput> +&prompt.root; <userinput>env DESTDIR=/usr/local/www make install</userinput></screen> <para>The install process will not delete any old or outdated files that existed previously in the same directory. If a new @@ -88,54 +84,52 @@ will find and delete all files that have not been updated in three days.</para> - <screen>&prompt.root; <userinput><command>find</command> <replaceable>/usr/local/www</replaceable> <option>-ctime</option> 3 <option>-delete</option></userinput></screen> + <screen>&prompt.root; <userinput>find /usr/local/www -ctime 3 -delete</userinput></screen> </sect1> - <sect1 id="the-website-env"> + <sect1 xml:id="the-website-env"> <title>Environment Variables</title> <variablelist> <varlistentry> - <term><makevar>ENGLISH_ONLY</makevar></term> + <term><varname>ENGLISH_ONLY</varname></term> <listitem> <para>If set and not empty, only the English documents will be built or installed. All translations will be ignored. E.g.:</para> - <screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen> + <screen>&prompt.root; <userinput>make ENGLISH_ONLY=YES all install</userinput></screen> <para>To unset the variable and build all pages, including - translations, set <makevar>ENGLISH_ONLY</makevar> to an + translations, set <varname>ENGLISH_ONLY</varname> to an empty value:</para> - <screen>&prompt.root; <userinput><command>make</command> <makevar>ENGLISH_ONLY=""</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget> <maketarget>clean</maketarget></userinput></screen> + <screen>&prompt.root; <userinput>make ENGLISH_ONLY="" all install clean</userinput></screen> </listitem> </varlistentry> <varlistentry> - <term><makevar>WEB_ONLY</makevar></term> + <term><varname>WEB_ONLY</varname></term> <listitem> <para>If set and not empty, only the <acronym>HTML</acronym> - pages from the <filename - class="directory">en_US.ISO8859-1/htdocs</filename> + pages from the <filename>en_US.ISO8859-1/htdocs</filename> directory will be built or installed. All other directories within - <filename class="directory">en_US.ISO8859-1</filename> + <filename>en_US.ISO8859-1</filename> (Handbook, FAQ, Tutorials) will be ignored. E.g.:</para> - <screen>&prompt.root; <userinput><command>make</command> <makevar>WEB_ONLY=YES</makevar> <maketarget>all</maketarget> <maketarget>install</maketarget></userinput></screen> + <screen>&prompt.root; <userinput>make WEB_ONLY=YES all install</userinput></screen> </listitem> </varlistentry> <varlistentry> - <term><makevar>WEB_LANG</makevar></term> + <term><varname>WEB_LANG</varname></term> <listitem> <para>If set, build or install only for the languages - specified by this variable inside the <filename - class="directory"><replaceable>~/doc</replaceable></filename> + specified by this variable inside the <filename>~/doc</filename> directory. All other languages except English will be ignored. E.g.:</para> @@ -144,8 +138,8 @@ </varlistentry> </variablelist> - <para><makevar>WEB_ONLY</makevar>, <makevar>WEB_LANG</makevar>, - and <makevar>ENGLISH_ONLY</makevar> are &man.make.1; variables + <para><varname>WEB_ONLY</varname>, <varname>WEB_LANG</varname>, + and <varname>ENGLISH_ONLY</varname> are &man.make.1; variables and can be set in <filename>/etc/make.conf</filename>, <filename>Makefile.inc</filename>, as environment variables on the command line, or in dot files.</para> diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml index 7c14882085..c6a70729e3 100644 --- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<chapter id="tools"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="tools"> <title>Tools</title> <para>Several software tools are used to manage the FreeBSD @@ -41,11 +40,11 @@ optional, adding capabilities or making the job of creating documentation less demanding.</para> - <sect1 id="tools-required"> + <sect1 xml:id="tools-required"> <title>Required Tools</title> <para>Install - <filename role="package">textproc/docproj</filename> from the + <package>textproc/docproj</package> from the Ports Collection. This <emphasis>meta-port</emphasis> installs all the applications required to do useful work with the &os; documentation. Some further notes on particular components are @@ -58,14 +57,13 @@ <para>&os; documentation uses several Document Type Definitions (<acronym>DTD</acronym>s) and sets of <acronym>XML</acronym> entities. These are all installed by the - <filename role="package">textproc/docproj</filename> + <package>textproc/docproj</package> port.</para> <variablelist> <varlistentry> <term><acronym>XHTML</acronym> <acronym>DTD</acronym> - (<filename - role="package">textproc/xhtml</filename>)</term> + (<package>textproc/xhtml</package>)</term> <listitem> <para><acronym>XHTML</acronym> is the markup language of @@ -75,8 +73,7 @@ </varlistentry> <varlistentry> - <term>DocBook <acronym>DTD</acronym> (<filename - role="package">textproc/docbook-xml-450</filename>)</term> + <term>DocBook <acronym>DTD</acronym> (<package>textproc/docbook-xml-450</package>)</term> <listitem> <para>DocBook is designed for marking up technical @@ -87,8 +84,7 @@ <varlistentry> <term>ISO 8879 entities - (<filename - role="package">textproc/iso8879</filename>)</term> + (<package>textproc/iso8879</package>)</term> <listitem> <para>Character entities from the ISO 8879:1986 standard @@ -102,7 +98,7 @@ </sect2> </sect1> - <sect1 id="tools-optional"> + <sect1 xml:id="tools-optional"> <title>Optional Tools</title> <para>These applications are not required, but can make working on @@ -116,10 +112,9 @@ <term><application>JadeTeX</application>, <application>teTeX</application> and Modular DocBook Stylesheets - (<filename role="package">print/jadetex</filename>, - <filename role="package">print/teTeX</filename> and - <filename - role="package">textproc/dsssl-docbook-modular</filename>)</term> + (<package>print/jadetex</package>, + <package>print/teTeX</package> and + <package>textproc/dsssl-docbook-modular</package>)</term> <listitem> <para><application>Jade</application>, @@ -132,14 +127,14 @@ <para>If <acronym>XHTML</acronym> and plain text output formats are adequate, then this program is not needed and the option to install it from the - <filename role="package">textproc/docproj</filename> + <package>textproc/docproj</package> configuration screen can be disabled.</para> </listitem> </varlistentry> <varlistentry> <term><application>Vim</application> - (<filename role="package">editors/vim</filename>)</term> + (<package>editors/vim</package>)</term> <listitem> <para>A popular editor for working with @@ -151,8 +146,8 @@ <varlistentry> <term><application>Emacs</application> or <application>XEmacs</application> - (<filename role="package">editors/emacs</filename> or - <filename role="package">editors/xemacs</filename>)</term> + (<package>editors/emacs</package> or + <package>editors/xemacs</package>)</term> <listitem> <para>Both of these editors include a special mode for diff --git a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml index 056b41ffce..be0b247ff9 100644 --- a/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<chapter id="translations"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="translations"> <title>Translations</title> <para>This is the FAQ for people translating the FreeBSD @@ -87,9 +86,8 @@ <answer> <para>Yes. Different translation groups have their own - mailing lists. The <ulink - url="http://www.freebsd.org/docproj/translations.html">list - of translation projects</ulink> has more information about + mailing lists. The <link xlink:href="http://www.freebsd.org/docproj/translations.html">list + of translation projects</link> has more information about the mailing lists and web sites run by each translation project.</para> </answer> @@ -137,19 +135,16 @@ copy of the FreeBSD Subversion repository (at least the documentation part). This can be done by running:</para> - <screen>&prompt.user; <userinput><command>svn</command> checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ head</userinput></screen> + <screen>&prompt.user; <userinput>svn checkout https://svn0.us-east.FreeBSD.org/doc/head/ head</userinput></screen> - <para><ulink - url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink> + <para><link xlink:href="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</link> is a public <literal>SVN</literal> server. Select the closest mirror and verify the mirror server - certificate from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> + certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror sites</link>.</para> <note> - <para>This will require the <filename - role="package">devel/subversion</filename> package to + <para>This will require the <package>devel/subversion</package> package to be installed.</para> </note> @@ -163,7 +158,7 @@ <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename>, run:</para> - <screen>&prompt.user; <userinput><command>svn</command> diff -r<replaceable>33733</replaceable>:<replaceable>33734</replaceable> <filename>en_US.ISO8859-1/books/fdp-primer/book.xml</filename></userinput></screen> + <screen>&prompt.user; <userinput>svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml</userinput></screen> </answer> </qandaentry> @@ -174,9 +169,8 @@ </question> <answer> - <para>The <ulink - url="http://www.FreeBSD.org/docproj/translations.html">Documentation - Project translations page</ulink> lists the translation + <para>The <link xlink:href="http://www.FreeBSD.org/docproj/translations.html">Documentation + Project translations page</link> lists the translation efforts that are currently known about. If others are already working on translating documentation to your language, please do not duplicate their efforts. Instead, @@ -290,7 +284,7 @@ <para><literal>sv_SE.ISO8859-1</literal> is the name of the translation, in - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> + <filename>lang.encoding</filename> form. Note the two Makefiles, which will be used to build the documentation.</para> @@ -389,8 +383,7 @@ of the entity, and a semi-colon (;).</para> <para>The entity names are defined in ISO8879, which is in the - ports tree as <filename - role="package">textproc/iso8879</filename>.</para> + ports tree as <package>textproc/iso8879</package>.</para> <para>A few examples include:</para> @@ -472,7 +465,7 @@ <para>Your translated documents should include their own $FreeBSD$ line, and change the <literal>FreeBSD Documentation Project</literal> line to - <literal>The FreeBSD <replaceable>language</replaceable> + <literal>The FreeBSD language Documentation Project</literal>.</para> <para>In addition, you should add a third line which indicates diff --git a/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml index bc725c1544..007a6cb061 100644 --- a/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml @@ -27,8 +27,7 @@ $FreeBSD$ --> - -<chapter id="working-copy"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="working-copy"> <title>The Working Copy</title> <para>The <emphasis>working copy</emphasis> is a copy of the &os; @@ -42,13 +41,12 @@ for temporary files and test versions of various output formats.</para> - <para><ulink - url="&url.books.handbook;/svn.html"><application>Subversion</application></ulink> + <para><link xlink:href="&url.books.handbook;/svn.html"><application>Subversion</application></link> is used to manage the &os; documentation files. It is installed - by <filename role="package">textproc/docproj</filename> as one of + by <package>textproc/docproj</package> as one of the required applications.</para> - <sect1 id="working-copy-doc-and-src"> + <sect1 xml:id="working-copy-doc-and-src"> <title>Documentation and Manual Pages</title> <para>&os; documentation is not just books and articles. Manual @@ -65,34 +63,33 @@ to the latest version, called <literal>head</literal>.</para> </sect1> - <sect1 id="working-copy-choosing-mirror"> + <sect1 xml:id="working-copy-choosing-mirror"> <title>Choosing a Mirror</title> <para>To increase speed and reduce download time, select a mirror - from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink> that is close to your location. + from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror sites</link> that is close to your location. Substitute the chosen mirror <acronym>URL</acronym> for the <replaceable>https://svn0.us-west.FreeBSD.org/</replaceable> used in these examples.</para> </sect1> - <sect1 id="working-copy-choosing-directory"> + <sect1 xml:id="working-copy-choosing-directory"> <title>Choosing a Directory</title> <para>&os; documentation is traditionally stored in - <filename class="directory">/usr/doc/</filename>, and system + <filename>/usr/doc/</filename>, and system source code with manual pages in - <filename class="directory">/usr/src/</filename>. These + <filename>/usr/src/</filename>. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples - that follow use <filename class="directory">~/doc</filename> - and <filename class="directory">~/src</filename>, both + that follow use <filename>~/doc</filename> + and <filename>~/src</filename>, both subdirectories of the user's home directory.</para> </sect1> - <sect1 id="working-copy-checking-out"> + <sect1 xml:id="working-copy-checking-out"> <title>Checking Out a Copy</title> <para>A download of a working copy from the repository is called @@ -101,15 +98,15 @@ copy of the latest version (<literal>head</literal>) of the main documentation tree:</para> - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org/doc/head</replaceable> <replaceable>~/doc</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/doc/head ~/doc</userinput></screen> <para>A checkout of the source code to work on manual pages is very similar:</para> - <screen>&prompt.user; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org/base/head</replaceable> <replaceable>~/src</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/base/head ~/src</userinput></screen> </sect1> - <sect1 id="working-copy-updating"> + <sect1 xml:id="working-copy-updating"> <title>Updating a Working Copy</title> <para>The documents and files in the &os; repository change daily. @@ -121,7 +118,7 @@ <command>svn update</command> on the directory containing the local working copy:</para> - <screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>svn update ~/doc</userinput></screen> <para>Get in the protective habit of using <command>svn update</command> before editing document files. @@ -132,7 +129,7 @@ the newer version from the repository.</para> </sect1> - <sect1 id="working-copy-revert"> + <sect1 xml:id="working-copy-revert"> <title>Reverting Changes</title> <para>Sometimes it turns out that changes were @@ -145,7 +142,7 @@ <screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen> </sect1> - <sect1 id="working-copy-making-diff"> + <sect1 xml:id="working-copy-making-diff"> <title>Making a Diff</title> <para>After edits to a file or group of files are completed, the @@ -155,16 +152,16 @@ by redirecting the output of <command>svn diff</command> into a file:</para> - <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput> -&prompt.user; <userinput>svn diff > <replaceable>doc-fix-spelling.diff</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>cd ~/doc</userinput> +&prompt.user; <userinput>svn diff > doc-fix-spelling.diff</userinput></screen> <para>Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree.</para> <para>If the diff file is to be submitted with the web - <quote><ulink url="&url.base;/send-pr.html">Submit a &os; - problem report</ulink></quote> interface, add a + <quote><link xlink:href="&url.base;/send-pr.html">Submit a &os; + problem report</link></quote> interface, add a <filename>.txt</filename> extension to give the earnest and simple-minded web form a clue that the contents are plain text.</para> @@ -175,19 +172,17 @@ be submitted yet, provide a list of only the files that are to be included:</para> - <screen>&prompt.user; <userinput>cd <replaceable>~/doc</replaceable></userinput> -&prompt.user; <userinput>svn diff <replaceable>disks/chapter.xml printers/chapter.xml</replaceable> > <replaceable>disks-printers.diff</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>cd ~/doc</userinput> +&prompt.user; <userinput>svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff</userinput></screen> </sect1> - <sect1 id="working-copy-subversion-references"> + <sect1 xml:id="working-copy-subversion-references"> <title><application>Subversion</application> References</title> <para>These examples show very basic usage of <application>Subversion</application>. More detail is available - in the <ulink - url="http://svnbook.red-bean.com/">Subversion Book</ulink> - and the <ulink - url="http://subversion.apache.org/docs/">Subversion - documentation</ulink>.</para> + in the <link xlink:href="http://svnbook.red-bean.com/">Subversion Book</link> + and the <link xlink:href="http://subversion.apache.org/docs/">Subversion + documentation</link>.</para> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml index d492ffde43..b461547327 100644 --- a/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml @@ -30,11 +30,10 @@ $FreeBSD$ --> - -<chapter id="writing-style"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="writing-style"> <title>Writing Style</title> - <sect1 id="writing-style-tips"> + <sect1 xml:id="writing-style-tips"> <title>Tips</title> <para>Technical documentation can be improved by consistent use of @@ -45,7 +44,7 @@ each other. Good writing consists of a balance between them.</para> - <sect2 id="writing-style-be-clear"> + <sect2 xml:id="writing-style-be-clear"> <title>Be Clear</title> <para>Clarity is extremely important. The reader may be a @@ -91,7 +90,7 @@ <quote>do this</quote>.</para> </sect2> - <sect2 id="writing-style-be-complete"> + <sect2 xml:id="writing-style-be-complete"> <title>Be Complete</title> <para>Do not make assumptions about the reader's abilities or @@ -102,7 +101,7 @@ them.</para> </sect2> - <sect2 id="writing-style-be-concise"> + <sect2 xml:id="writing-style-be-concise"> <title>Be Concise</title> <para>While features should be documented completely, sometimes @@ -115,7 +114,7 @@ </sect2> </sect1> - <sect1 id="writing-style-guidelines"> + <sect1 xml:id="writing-style-guidelines"> <title>Guidelines</title> <para>To promote consistency between the myriad authors of the @@ -219,7 +218,7 @@ </informalexample> <para>Manual page references (the second example uses - <sgmltag>citerefentry</sgmltag> with the + <tag>citerefentry</tag> with the <literal>&man.csh.1;</literal> entity):.</para> <informalexample> @@ -250,12 +249,11 @@ </varlistentry> </variablelist> - <para>For more information about writing style, see <ulink - url="http://www.bartleby.com/141/">Elements of - Style</ulink>, by William Strunk.</para> + <para>For more information about writing style, see <link xlink:href="http://www.bartleby.com/141/">Elements of + Style</link>, by William Strunk.</para> </sect1> - <sect1 id="writing-style-guide"> + <sect1 xml:id="writing-style-guide"> <title>Style Guide</title> <para>To keep the source for the documentation consistent when @@ -265,8 +263,8 @@ <sect2> <title>Letter Case</title> - <para>Tags are entered in lower case, <sgmltag>para</sgmltag>, - <emphasis>not</emphasis> <sgmltag>PARA</sgmltag>.</para> + <para>Tags are entered in lower case, <tag>para</tag>, + <emphasis>not</emphasis> <tag>PARA</tag>.</para> <para>Text that appears in SGML contexts is generally written in upper case, <literal><!ENTITY…></literal>, and @@ -276,7 +274,7 @@ <literal><!doctype…></literal>.</para> </sect2> - <sect2 id="writing-style-acronyms"> + <sect2 xml:id="writing-style-acronyms"> <title>Acronyms</title> <para>Acronyms should be defined the first time they appear in a @@ -288,10 +286,10 @@ document.</para> <para>All acronyms should be enclosed in - <sgmltag>acronym</sgmltag> tags.</para> + <tag>acronym</tag> tags.</para> </sect2> - <sect2 id="writing-style-indentation"> + <sect2 xml:id="writing-style-indentation"> <title>Indentation</title> <para>The first line in each file starts with no indentation, @@ -309,33 +307,33 @@ <para>For example, the source for this section looks like this:</para> - <programlisting><sgmltag class="starttag">chapter</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">chapter</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">sect2</sgmltag> - <sgmltag class="starttag">title</sgmltag>Indentation<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect2</tag> + <tag class="starttag">title</tag>Indentation<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>The first line in each file starts with no indentation, - <sgmltag class="starttag">emphasis</sgmltag>regardless<sgmltag class="endtag">emphasis</sgmltag> of the indentation level of - the file which might contain the current file.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">para</tag>The first line in each file starts with no indentation, + <tag class="starttag">emphasis</tag>regardless<tag class="endtag">emphasis</tag> of the indentation level of + the file which might contain the current file.<tag class="endtag">para</tag> ... - <sgmltag class="endtag">sect2</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">chapter</sgmltag></programlisting> + <tag class="endtag">sect2</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">chapter</tag></programlisting> <para>Configurations to help various text editors conform to these guidelines can be found in <xref linkend="editor-config"/>.</para> </sect2> - <sect2 id="writing-style-tag-style"> + <sect2 xml:id="writing-style-tag-style"> <title>Tag Style</title> - <sect3 id="writing-style-tag-style-spacing"> + <sect3 xml:id="writing-style-tag-style-spacing"> <title>Tag Spacing</title> <para>Tags that start at the same indent as a previous tag @@ -343,44 +341,44 @@ at the same indent as a previous tag should not:</para> <informalexample> - <programlisting><sgmltag class="starttag">article lang='en'</sgmltag> - <sgmltag class="starttag">articleinfo</sgmltag> - <sgmltag class="starttag">title</sgmltag>NIS<sgmltag class="endtag">title</sgmltag> + <programlisting><tag class="starttag">article lang='en'</tag> + <tag class="starttag">articleinfo</tag> + <tag class="starttag">title</tag>NIS<tag class="endtag">title</tag> - <sgmltag class="starttag">pubdate</sgmltag>October 1999<sgmltag class="endtag">pubdate</sgmltag> + <tag class="starttag">pubdate</tag>October 1999<tag class="endtag">pubdate</tag> - <sgmltag class="starttag">abstract</sgmltag> - <sgmltag class="starttag">para</sgmltag>... + <tag class="starttag">abstract</tag> + <tag class="starttag">para</tag>... ... - ...<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">abstract</sgmltag> - <sgmltag class="endtag">articleinfo</sgmltag> + ...<tag class="endtag">para</tag> + <tag class="endtag">abstract</tag> + <tag class="endtag">articleinfo</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> - <sgmltag class="starttag">sect1</sgmltag> - <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> + <tag class="starttag">sect1</tag> + <tag class="starttag">title</tag>...<tag class="endtag">title</tag> - <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag> - <sgmltag class="endtag">sect1</sgmltag> -<sgmltag class="endtag">article</sgmltag></programlisting> + <tag class="starttag">para</tag>...<tag class="endtag">para</tag> + <tag class="endtag">sect1</tag> +<tag class="endtag">article</tag></programlisting> </informalexample> </sect3> - <sect3 id="writing-style-tag-style-separating"> + <sect3 xml:id="writing-style-tag-style-separating"> <title>Separating Tags</title> - <para>Tags like <sgmltag>itemizedlist</sgmltag> which will + <para>Tags like <tag>itemizedlist</tag> which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves.</para> - <para>Tags like <sgmltag>para</sgmltag> and - <sgmltag>term</sgmltag> do not need other tags to contain + <para>Tags like <tag>para</tag> and + <tag>term</tag> do not need other tags to contain normal character data, and their contents begin immediately after the tag, <emphasis>on the same line</emphasis>.</para> @@ -401,7 +399,7 @@ </sect3> </sect2> - <sect2 id="writing-style-whitespace-changes"> + <sect2 xml:id="writing-style-whitespace-changes"> <title>Whitespace Changes</title> <para><emphasis>Do not commit changes @@ -421,7 +419,7 @@ ignored by translators.</para> </sect2> - <sect2 id="writing-style-nonbreaking-space"> + <sect2 xml:id="writing-style-nonbreaking-space"> <title>Non-Breaking Space</title> <para>Avoid line breaks in places where they look ugly or make @@ -459,7 +457,7 @@ GB. Hardware compression …</literallayout> </sect2> </sect1> - <sect1 id="writing-style-word-list"> + <sect1 xml:id="writing-style-word-list"> <title>Word List</title> <para>This list of words shows the correct spelling and @@ -480,16 +478,12 @@ GB. Hardware compression …</literallayout> <row> <entry>CD-ROM</entry> - <entry><sgmltag - class="starttag">acronym</sgmltag><literal>CD-ROM</literal><sgmltag - class="endtag">acronym</sgmltag></entry> + <entry><tag class="starttag">acronym</tag><literal>CD-ROM</literal><tag class="endtag">acronym</tag></entry> </row> <row> <entry>DoS (Denial of Service)</entry> - <entry><sgmltag - class="starttag">acronym</sgmltag><literal>DoS</literal><sgmltag - class="endtag">acronym</sgmltag></entry> + <entry><tag class="starttag">acronym</tag><literal>DoS</literal><tag class="endtag">acronym</tag></entry> </row> <row> @@ -535,14 +529,10 @@ GB. Hardware compression …</literallayout> <row> <entry>Subversion</entry> - <entry><sgmltag - class="starttag">application</sgmltag><literal>Subversion</literal><sgmltag - class="endtag">application</sgmltag></entry> + <entry><tag class="starttag">application</tag><literal>Subversion</literal><tag class="endtag">application</tag></entry> <entry>Do not refer to the Subversion application as <literal>SVN</literal> in upper case. To refer to the - command, use <sgmltag - class="starttag">command</sgmltag><literal>svn</literal><sgmltag - class="endtag">command</sgmltag>.</entry> + command, use <tag class="starttag">command</tag><literal>svn</literal><tag class="endtag">command</tag>.</entry> </row> <row> diff --git a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml index eded9cac18..f0894d63fe 100644 --- a/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/chapter.xml @@ -30,11 +30,10 @@ $FreeBSD$ --> - -<chapter id="xhtml-markup"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xhtml-markup"> <title><acronym>XHTML</acronym> Markup</title> - <sect1 id="xhtml-markup-introduction"> + <sect1 xml:id="xhtml-markup-introduction"> <title>Introduction</title> <para>This chapter describes usage of the <acronym>XHTML</acronym> @@ -43,7 +42,7 @@ <para><acronym>XHTML</acronym> is the <acronym>XML</acronym> version of the HyperText Markup Language, the markup language of choice on the World Wide Web. More information can be found at - <ulink url="http://www.w3.org/"></ulink>.</para> + <uri xlink:href="http://www.w3.org/">http://www.w3.org/</uri>.</para> <para><acronym>XHTML</acronym> is used to mark up pages on the &os; web site. It is usually not used to mark up other @@ -61,9 +60,8 @@ <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are available from the Ports Collection in - <filename role="package">textproc/xhtml</filename>. They are - automatically installed by the <filename - role="package">textproc/docproj</filename> port.</para> + <package>textproc/xhtml</package>. They are + automatically installed by the <package>textproc/docproj</package> port.</para> <note> <para>This is <emphasis>not</emphasis> an exhaustive list of @@ -85,7 +83,7 @@ </note> </sect1> - <sect1 id="xhtml-markup-fpi"> + <sect1 xml:id="xhtml-markup-fpi"> <title>Formal Public Identifier (<acronym>FPI</acronym>)</title> <para>There are a number of <acronym>XHTML</acronym> @@ -98,7 +96,7 @@ <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> </sect1> - <sect1 id="xhtml-markup-sectional-elements"> + <sect1 xml:id="xhtml-markup-sectional-elements"> <title>Sectional Elements</title> <para>An <acronym>XHTML</acronym> document is normally split into @@ -109,113 +107,113 @@ <emphasis>body</emphasis>, contains 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 + <para>These sections are indicated with <tag>head</tag> + and <tag>body</tag> elements respectively. These elements are contained within the top-level - <sgmltag>html</sgmltag> element.</para> + <tag>html</tag> element.</para> <example> <title>Normal <acronym>XHTML</acronym> Document Structure</title> - <programlisting><sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> - <sgmltag class="starttag">head</sgmltag> - <sgmltag class="starttag">title</sgmltag><replaceable>The Document's Title</replaceable><sgmltag class="endtag">title</sgmltag> - <sgmltag class="endtag">head</sgmltag> + <programlisting><tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag><replaceable>The Document's Title</replaceable><tag class="endtag">title</tag> + <tag class="endtag">head</tag> - <sgmltag class="starttag">body</sgmltag> + <tag class="starttag">body</tag> … - <sgmltag class="endtag">body</sgmltag> -<sgmltag class="endtag">html</sgmltag></programlisting> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> </example> </sect1> - <sect1 id="xhtml-markup-block-elements"> + <sect1 xml:id="xhtml-markup-block-elements"> <title>Block Elements</title> - <sect2 id="xhtml-markup-block-elements-headings"> + <sect2 xml:id="xhtml-markup-block-elements-headings"> <title>Headings</title> <para><acronym>XHTML</acronym> has tags to denote headings in the 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> + <tag>h1</tag>, then <tag>h2</tag>, + continuing down to <tag>h6</tag>.</para> <para>The element's content is the text of the heading.</para> <example> - <title><sgmltag>h1</sgmltag>, <sgmltag>h2</sgmltag>, + <title><tag>h1</tag>, <tag>h2</tag>, and Other Header Tags</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">h1</sgmltag>First section<sgmltag class="endtag">h1</sgmltag> + <programlisting><tag class="starttag">h1</tag>First section<tag class="endtag">h1</tag> <!-- Document introduction goes here --> -<sgmltag class="starttag">h2</sgmltag>This is the heading for the first section<sgmltag class="endtag">h2</sgmltag> +<tag class="starttag">h2</tag>This is the heading for the first section<tag class="endtag">h2</tag> <!-- Content for the first section goes here --> -<sgmltag class="starttag">h3</sgmltag>This is the heading for the first sub-section<sgmltag class="endtag">h3</sgmltag> +<tag class="starttag">h3</tag>This is the heading for the first sub-section<tag class="endtag">h3</tag> <!-- Content for the first sub-section goes here --> -<sgmltag class="starttag">h2</sgmltag>This is the heading for the second section<sgmltag class="endtag">h2</sgmltag> +<tag class="starttag">h2</tag>This is the heading for the second section<tag class="endtag">h2</tag> <!-- Content for the second section goes here --></programlisting> </example> <para>Generally, an <acronym>XHTML</acronym> page should have - one first level heading (<sgmltag>h1</sgmltag>). This can - contain many second level headings (<sgmltag>h2</sgmltag>), + one first level heading (<tag>h1</tag>). This can + contain many second level headings (<tag>h2</tag>), which can in turn contain many third level headings. Do not leave gaps in the numbering.</para> </sect2> - <sect2 id="xhtml-markup-block-elements-paragraphs"> + <sect2 xml:id="xhtml-markup-block-elements-paragraphs"> <title>Paragraphs</title> <para><acronym>XHTML</acronym> supports a single paragraph - element, <sgmltag>p</sgmltag>.</para> + element, <tag>p</tag>.</para> <example> - <title><sgmltag>p</sgmltag></title> + <title><tag>p</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>This is a paragraph. It can contain just about any - other element.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>This is a paragraph. It can contain just about any + other element.<tag class="endtag">p</tag></programlisting> </example> </sect2> - <sect2 id="xhtml-markup-block-elements-block-quotations"> + <sect2 xml:id="xhtml-markup-block-elements-block-quotations"> <title>Block Quotations</title> <para>A block quotation is an extended quotation from another document that will appear in a separate paragraph.</para> <example> - <title><sgmltag>blockquote</sgmltag></title> + <title><tag>blockquote</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>A small excerpt from the US Constitution:<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p</tag>A small excerpt from the US Constitution:<tag class="endtag">p</tag> -<sgmltag class="starttag">blockquote</sgmltag>We the People of the United States, in Order to form +<tag class="starttag">blockquote</tag>We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the - United States of America.<sgmltag class="endtag">blockquote</sgmltag></programlisting> + United States of America.<tag class="endtag">blockquote</tag></programlisting> </example> </sect2> - <sect2 id="xhtml-markup-block-elements-lists"> + <sect2 xml:id="xhtml-markup-block-elements-lists"> <title>Lists</title> <para><acronym>XHTML</acronym> can present the user with three @@ -227,79 +225,79 @@ section is the term being defined, and the second section is the definition.</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> + <para>Ordered lists are indicated by the <tag>ol</tag> + element, unordered lists by the <tag>ul</tag> + element, and definition lists by the <tag>dl</tag> element.</para> <para>Ordered and unordered lists contain listitems, indicated - by the <sgmltag>li</sgmltag> element. A listitem can + by the <tag>li</tag> element. A listitem can contain textual content, or it may be further wrapped in one - or more <sgmltag>p</sgmltag> elements.</para> + or more <tag>p</tag> elements.</para> <para>Definition lists contain definition terms - (<sgmltag>dt</sgmltag>) and definition descriptions - (<sgmltag>dd</sgmltag>). A definition term can only contain + (<tag>dt</tag>) and definition descriptions + (<tag>dd</tag>). 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><tag>ul</tag> and + <tag>ol</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>An unordered list. Listitems will probably be - preceded by bullets.<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p</tag>An unordered list. Listitems will probably be + preceded by bullets.<tag class="endtag">p</tag> -<sgmltag class="starttag">ul</sgmltag> - <sgmltag class="starttag">li</sgmltag>First item<sgmltag class="endtag">li</sgmltag> +<tag class="starttag">ul</tag> + <tag class="starttag">li</tag>First item<tag class="endtag">li</tag> - <sgmltag class="starttag">li</sgmltag>Second item<sgmltag class="endtag">li</sgmltag> + <tag class="starttag">li</tag>Second item<tag class="endtag">li</tag> - <sgmltag class="starttag">li</sgmltag>Third item<sgmltag class="endtag">li</sgmltag> -<sgmltag class="endtag">ul</sgmltag> + <tag class="starttag">li</tag>Third item<tag class="endtag">li</tag> +<tag class="endtag">ul</tag> -<sgmltag class="starttag">p</sgmltag>An ordered list, with list items consisting of multiple +<tag class="starttag">p</tag>An ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be - numbered.<sgmltag class="endtag">p</sgmltag> + numbered.<tag class="endtag">p</tag> -<sgmltag class="starttag">ol</sgmltag> - <sgmltag class="starttag">li</sgmltag><sgmltag class="starttag">p</sgmltag>This is the first item. It only has one paragraph.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">li</sgmltag> +<tag class="starttag">ol</tag> + <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first item. It only has one paragraph.<tag class="endtag">p</tag><tag class="endtag">li</tag> - <sgmltag class="starttag">li</sgmltag><sgmltag class="starttag">p</sgmltag>This is the first paragraph of the second item.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first paragraph of the second item.<tag class="endtag">p</tag> - <sgmltag class="starttag">p</sgmltag>This is the second paragraph of the second item.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">li</sgmltag> + <tag class="starttag">p</tag>This is the second paragraph of the second item.<tag class="endtag">p</tag><tag class="endtag">li</tag> - <sgmltag class="starttag">li</sgmltag><sgmltag class="starttag">p</sgmltag>This is the first and only paragraph of the third - item.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">li</sgmltag> -<sgmltag class="endtag">ol</sgmltag></programlisting> + <tag class="starttag">li</tag><tag class="starttag">p</tag>This is the first and only paragraph of the third + item.<tag class="endtag">p</tag><tag class="endtag">li</tag> +<tag class="endtag">ol</tag></programlisting> </example> <example> - <title>Definition Lists with <sgmltag>dl</sgmltag></title> + <title>Definition Lists with <tag>dl</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">dl</sgmltag> - <sgmltag class="starttag">dt</sgmltag>Term 1<sgmltag class="endtag">dt</sgmltag> + <programlisting><tag class="starttag">dl</tag> + <tag class="starttag">dt</tag>Term 1<tag class="endtag">dt</tag> - <sgmltag class="starttag">dd</sgmltag><sgmltag class="starttag">p</sgmltag>Paragraph 1 of definition 1.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 1.<tag class="endtag">p</tag> - <sgmltag class="starttag">p</sgmltag>Paragraph 2 of definition 1.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">dd</sgmltag> + <tag class="starttag">p</tag>Paragraph 2 of definition 1.<tag class="endtag">p</tag><tag class="endtag">dd</tag> - <sgmltag class="starttag">dt</sgmltag>Term 2<sgmltag class="endtag">dt</sgmltag> + <tag class="starttag">dt</tag>Term 2<tag class="endtag">dt</tag> - <sgmltag class="starttag">dd</sgmltag><sgmltag class="starttag">p</sgmltag>Paragraph 1 of definition 2.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">dd</sgmltag> + <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 2.<tag class="endtag">p</tag><tag class="endtag">dd</tag> - <sgmltag class="starttag">dt</sgmltag>Term 3<sgmltag class="endtag">dt</sgmltag> + <tag class="starttag">dt</tag>Term 3<tag class="endtag">dt</tag> - <sgmltag class="starttag">dd</sgmltag><sgmltag class="starttag">p</sgmltag>Paragraph 1 of definition 3.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">dd</sgmltag> -<sgmltag class="endtag">dl</sgmltag></programlisting> + <tag class="starttag">dd</tag><tag class="starttag">p</tag>Paragraph 1 of definition 3.<tag class="endtag">p</tag><tag class="endtag">dd</tag> +<tag class="endtag">dl</tag></programlisting> </example> </sect2> - <sect2 id="xhtml-markup-block-elements-preformatted-text"> + <sect2 xml:id="xhtml-markup-block-elements-preformatted-text"> <title>Pre-formatted Text</title> <para>Pre-formatted text is shown to the user exactly as it is @@ -307,16 +305,16 @@ and line breaks are shown exactly as they are in the file.</para> - <para>Wrap pre-formatted text in the <sgmltag>pre</sgmltag> + <para>Wrap pre-formatted text in the <tag>pre</tag> element.</para> <example> - <title><sgmltag>pre</sgmltag></title> + <title><tag>pre</tag></title> - <para>For example, the <sgmltag>pre</sgmltag> tags could be + <para>For example, the <tag>pre</tag> tags could be used to mark up an email message:</para> - <programlisting><sgmltag class="starttag">pre</sgmltag> From: nik@FreeBSD.org + <programlisting><tag class="starttag">pre</tag> From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available @@ -327,7 +325,7 @@ Comments appreciated. - N<sgmltag class="endtag">pre</sgmltag></programlisting> + N<tag class="endtag">pre</tag></programlisting> <para>Keep in mind that <literal><</literal> and <literal>&</literal> still are recognized as special @@ -341,139 +339,139 @@ </example> </sect2> - <sect2 id="xhtml-markup-block-elements-tables"> + <sect2 xml:id="xhtml-markup-block-elements-tables"> <title>Tables</title> <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 + <tag>table</tag> element. A table consists of one or + more table rows (<tag>tr</tag>), each containing one + or more cells of table data (<tag>td</tag>). 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 the <sgmltag>p</sgmltag>element is not needed.</para> + then the <tag>p</tag>element is not needed.</para> <example> - <title>Simple Use of <sgmltag>table</sgmltag></title> + <title>Simple Use of <tag>table</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>This is a simple 2x2 table.<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p</tag>This is a simple 2x2 table.<tag class="endtag">p</tag> -<sgmltag class="starttag">table</sgmltag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td</sgmltag>Top left cell<sgmltag class="endtag">td</sgmltag> +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Top left cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Top right cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> + <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td</sgmltag>Bottom left cell<sgmltag class="endtag">td</sgmltag> + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Bottom right cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> -<sgmltag class="endtag">table</sgmltag></programlisting> + <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> </example> <para>A cell can span multiple rows and columns by adding the - <sgmltag class="attribute">rowspan</sgmltag> or - <sgmltag class="attribute">colspan</sgmltag> attributes with + <tag class="attribute">rowspan</tag> or + <tag class="attribute">colspan</tag> attributes with values for the number of rows or columns to be spanned.</para> <example> <title>Using - <sgmltag class="attribute">rowspan</sgmltag></title> + <tag class="attribute">rowspan</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>One tall thin cell on the left, two short cells next to - it on the right.<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p</tag>One tall thin cell on the left, two short cells next to + it on the right.<tag class="endtag">p</tag> -<sgmltag class="starttag">table</sgmltag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td rowspan="2"</sgmltag>Long and thin<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td rowspan="2"</tag>Long and thin<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td</sgmltag>Top cell<sgmltag class="endtag">td</sgmltag> + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Top cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Bottom cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> -<sgmltag class="endtag">table</sgmltag></programlisting> + <tag class="starttag">td</tag>Bottom cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> </example> <example> <title>Using - <sgmltag class="attribute">colspan</sgmltag></title> + <tag class="attribute">colspan</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>One long cell on top, two short cells below it.<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p</tag>One long cell on top, two short cells below it.<tag class="endtag">p</tag> -<sgmltag class="starttag">table</sgmltag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td colspan="2"</sgmltag>Top cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td colspan="2"</tag>Top cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td</sgmltag>Bottom left cell<sgmltag class="endtag">td</sgmltag> + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Bottom right cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> -<sgmltag class="endtag">table</sgmltag></programlisting> + <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> </example> <example> - <title>Using <sgmltag class="attribute">rowspan</sgmltag> and - <sgmltag class="attribute">colspan</sgmltag> + <title>Using <tag class="attribute">rowspan</tag> and + <tag class="attribute">colspan</tag> Together</title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>On a 3x3 grid, the top left block is a 2x2 set of - cells merged into one. The other cells are normal.<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p</tag>On a 3x3 grid, the top left block is a 2x2 set of + cells merged into one. The other cells are normal.<tag class="endtag">p</tag> -<sgmltag class="starttag">table</sgmltag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td colspan="2" rowspan="2"</sgmltag>Top left large cell<sgmltag class="endtag">td</sgmltag> +<tag class="starttag">table</tag> + <tag class="starttag">tr</tag> + <tag class="starttag">td colspan="2" rowspan="2"</tag>Top left large cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Top right cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> + <tag class="starttag">td</tag>Top right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> - <sgmltag class="starttag">tr</sgmltag> + <tag class="starttag">tr</tag> <!-- Because the large cell on the left merges into this row, the first <td> will occur on its right --> - <sgmltag class="starttag">td</sgmltag>Middle right cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> + <tag class="starttag">td</tag>Middle right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> - <sgmltag class="starttag">tr</sgmltag> - <sgmltag class="starttag">td</sgmltag>Bottom left cell<sgmltag class="endtag">td</sgmltag> + <tag class="starttag">tr</tag> + <tag class="starttag">td</tag>Bottom left cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Bottom middle cell<sgmltag class="endtag">td</sgmltag> + <tag class="starttag">td</tag>Bottom middle cell<tag class="endtag">td</tag> - <sgmltag class="starttag">td</sgmltag>Bottom right cell<sgmltag class="endtag">td</sgmltag> - <sgmltag class="endtag">tr</sgmltag> -<sgmltag class="endtag">table</sgmltag></programlisting> + <tag class="starttag">td</tag>Bottom right cell<tag class="endtag">td</tag> + <tag class="endtag">tr</tag> +<tag class="endtag">table</tag></programlisting> </example> </sect2> </sect1> - <sect1 id="xhtml-markup-inline-elements"> + <sect1 xml:id="xhtml-markup-inline-elements"> <title>In-line Elements</title> - <sect2 id="xhtml-markup-inline-elements-emphasizing-information"> + <sect2 xml:id="xhtml-markup-inline-elements-emphasizing-information"> <title>Emphasizing Information</title> <para>Two levels of emphasis are available in - <acronym>XHTML</acronym>, <sgmltag>em</sgmltag> and - <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a - normal level of emphasis and <sgmltag>strong</sgmltag> + <acronym>XHTML</acronym>, <tag>em</tag> and + <tag>strong</tag>. <tag>em</tag> is for a + normal level of emphasis and <tag>strong</tag> indicates stronger emphasis.</para> - <para><sgmltag>em</sgmltag> is typically rendered in italic - and <sgmltag>strong</sgmltag> is rendered in bold. This is + <para><tag>em</tag> is typically rendered in italic + and <tag>strong</tag> is rendered in bold. This is not always the case, and should not be relied upon. According to best practices, web pages only hold structural and semantical information, and stylesheets are later applied to @@ -481,47 +479,47 @@ tags.</para> <example> - <title><sgmltag>em</sgmltag> and - <sgmltag>strong</sgmltag></title> + <title><tag>em</tag> and + <tag>strong</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag><sgmltag class="starttag">em</sgmltag>This<sgmltag class="endtag">em</sgmltag> has been emphasized, while - <sgmltag class="starttag">strong</sgmltag>this<sgmltag class="endtag">strong</sgmltag> has been strongly emphasized.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag><tag class="starttag">em</tag>This<tag class="endtag">em</tag> has been emphasized, while + <tag class="starttag">strong</tag>this<tag class="endtag">strong</tag> has been strongly emphasized.<tag class="endtag">p</tag></programlisting> </example> </sect2> - <sect2 id="xhtml-markup-inline-elements-fixed-pitch-text"> + <sect2 xml:id="xhtml-markup-inline-elements-fixed-pitch-text"> <title>Indicating Fixed-Pitch Text</title> <para>Content that should be rendered in a fixed pitch - (typewriter) typeface is tagged with <sgmltag>tt</sgmltag> + (typewriter) typeface is tagged with <tag>tt</tag> (for <quote>teletype</quote>).</para> <example> - <title><sgmltag>tt</sgmltag></title> + <title><tag>tt</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>Many system settings are stored in - <sgmltag class="starttag">tt</sgmltag>/etc<sgmltag class="endtag">tt</sgmltag>.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>Many system settings are stored in + <tag class="starttag">tt</tag>/etc<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> </example> </sect2> - <sect2 id="xhtml-markup-inline-elements-links"> + <sect2 xml:id="xhtml-markup-inline-elements-links"> <title>Links</title> <note> <para>Links are also inline elements.</para> </note> - <sect3 id="xhtml-markup-inline-elements-linking"> + <sect3 xml:id="xhtml-markup-inline-elements-linking"> <title>Linking to Other Documents on the Web</title> <para>A link points to the <acronym>URL</acronym> of a document on the web. The link is indicated with - <sgmltag>a</sgmltag>, and the - <sgmltag class="attribute">href</sgmltag> attribute contains + <tag>a</tag>, and the + <tag class="attribute">href</tag> attribute contains the <acronym>URL</acronym> of the target document. The content of the element becomes the link, indicated to the user by showing it in a different color or with an @@ -529,28 +527,28 @@ <example> <title>Using - <sgmltag class="starttag">a href="..."</sgmltag></title> + <tag class="starttag">a href="..."</tag></title> <para>Usage:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>More information is available at the - <sgmltag class="starttag">a href="http://www.&os;.org/"</sgmltag>&os; web site<sgmltag class="endtag">a</sgmltag>.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>More information is available at the + <tag class="starttag">a href="http://www.&os;.org/"</tag>&os; web site<tag class="endtag">a</tag>.<tag class="endtag">p</tag></programlisting> </example> <para>This link always takes the user to the top of the linked document.</para> </sect3> - <sect3 id="xhtml-markup-inline-elements-specific-parts"> + <sect3 xml:id="xhtml-markup-inline-elements-specific-parts"> <title>Linking to Specific Parts of Documents</title> <para>To link to a specific point within a document, that document must include an <emphasis>anchor</emphasis> at the desired point. Anchors are included by setting the - <sgmltag class="attribute">id</sgmltag> attribute of an + <tag class="attribute">id</tag> attribute of an element to a name. This example creates an anchor by - setting the <sgmltag class="attribute">id</sgmltag> - attribute of a <sgmltag class="element">p</sgmltag> + setting the <tag class="attribute">id</tag> + attribute of a <tag class="element">p</tag> element.</para> <example> @@ -558,8 +556,8 @@ <para>Usage:</para> - <programlisting><sgmltag class="starttag">p id="samplepara"</sgmltag>This paragraph can be referenced - in other links with the name <sgmltag class="starttag">tt</sgmltag>samplepara<sgmltag class="endtag">tt</sgmltag>.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p id="samplepara"</tag>This paragraph can be referenced + in other links with the name <tag class="starttag">tt</tag>samplepara<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> </example> <para>Links to anchors are similar to plain links, but include @@ -576,9 +574,9 @@ that specific paragraph in the document is constructed in this example.</para> - <programlisting><sgmltag class="starttag">p</sgmltag>More information can be found in the - <sgmltag class="starttag">a href="foo.html#samplepara"</sgmltag>sample paragraph<sgmltag class="endtag">a</sgmltag> of - <sgmltag class="starttag">tt</sgmltag>foo.html<sgmltag class="endtag">tt</sgmltag>.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>More information can be found in the + <tag class="starttag">a href="foo.html#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of + <tag class="starttag">tt</tag>foo.html<tag class="endtag">tt</tag>.<tag class="endtag">p</tag></programlisting> </example> <para>To link to a named anchor within the same document, omit @@ -592,9 +590,9 @@ <para>The <literal>samplepara</literal> example resides in this document. To link to it:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>More information can be found in the - <sgmltag class="starttag">a href="#samplepara"</sgmltag>sample paragraph<sgmltag class="endtag">a</sgmltag> of this - document.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>More information can be found in the + <tag class="starttag">a href="#samplepara"</tag>sample paragraph<tag class="endtag">a</tag> of this + document.<tag class="endtag">p</tag></programlisting> </example> </sect3> </sect2> diff --git a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml index 1a436f380b..b25fc313a5 100644 --- a/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/xml-primer/chapter.xml @@ -30,8 +30,7 @@ $FreeBSD$ --> - -<chapter id="xml-primer"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="xml-primer"> <title>XML Primer</title> <para>Most <acronym>FDP</acronym> documentation is written with @@ -41,11 +40,10 @@ used.</para> <para>Portions of this section were inspired by Mark Galassi's - <ulink - url="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get - Going With DocBook</ulink>.</para> + <link xlink:href="http://www.galassi.org/mark/mydocs/docbook-intro/docbook-intro.html">Get + Going With DocBook</link>.</para> - <sect1 id="xml-primer-overview"> + <sect1 xml:id="xml-primer-overview"> <title>Overview</title> <para>In the original days of computers, electronic text was @@ -108,9 +106,9 @@ <para>The previous example is actually represented in this document like this:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>To remove <sgmltag class="starttag">filename</sgmltag>/tmp/foo<sgmltag class="endtag">filename</sgmltag>, use &man.rm.1;.<sgmltag class="endtag">para</sgmltag> + <programlisting><tag class="starttag">para</tag>To remove <tag class="starttag">filename</tag>/tmp/foo<tag class="endtag">filename</tag>, use &man.rm.1;.<tag class="endtag">para</tag> -<sgmltag class="starttag">screen</sgmltag>&prompt.user; <sgmltag class="starttag">userinput</sgmltag>rm /tmp/foo<sgmltag class="endtag">userinput</sgmltag><sgmltag class="endtag">screen</sgmltag></programlisting> +<tag class="starttag">screen</tag>&prompt.user; <tag class="starttag">userinput</tag>rm /tmp/foo<tag class="endtag">userinput</tag><tag class="endtag">screen</tag></programlisting> <para>The markup is clearly separate from the content.</para> @@ -137,7 +135,7 @@ specify an <acronym>XML</acronym> grammar, or <emphasis>schema</emphasis>.</para> - <para id="xml-primer-validating">A schema is a + <para xml:id="xml-primer-validating">A schema is a <emphasis>complete</emphasis> specification of all the elements that are allowed to appear, the order in which they should appear, which elements are mandatory, which are optional, and so @@ -169,7 +167,7 @@ to write a vocabulary.</para> </sect1> - <sect1 id="xml-primer-elements"> + <sect1 xml:id="xml-primer-elements"> <title>Elements, Tags, and Attributes</title> <para>All the vocabularies written in <acronym>XML</acronym> share @@ -222,23 +220,21 @@ <para>For an element called <replaceable>element-name</replaceable> the start tag will - normally look like <sgmltag - class="starttag"><replaceable>element-name</replaceable></sgmltag>. - The corresponding closing tag for this element is <sgmltag - class="endtag"><replaceable>element-name</replaceable></sgmltag>.</para> + normally look like <tag class="starttag"><replaceable>element-name</replaceable></tag>. + The corresponding closing tag for this element is <tag class="endtag"><replaceable>element-name</replaceable></tag>.</para> <example> <title>Using an Element (Start and End Tags)</title> <para><acronym>XHTML</acronym> has an element for indicating that the content enclosed by the element is a paragraph, - called <sgmltag>p</sgmltag>.</para> + called <tag>p</tag>.</para> - <programlisting><sgmltag class="starttag">p</sgmltag>This is a paragraph. It starts with the start tag for + <programlisting><tag class="starttag">p</tag>This is a paragraph. It starts with the start tag for the 'p' element, and it will end with the end tag for the 'p' - element.<sgmltag class="endtag">p</sgmltag> + element.<tag class="endtag">p</tag> -<sgmltag class="starttag">p</sgmltag>This is another paragraph. But this one is much shorter.<sgmltag class="endtag">p</sgmltag></programlisting> +<tag class="starttag">p</tag>This is another paragraph. But this one is much shorter.<tag class="endtag">p</tag></programlisting> </example> <para>Some elements have no content. For example, in @@ -251,22 +247,22 @@ <title>Using an Element Without Content</title> <para><acronym>XHTML</acronym> has an element for indicating a - horizontal rule, called <sgmltag>hr</sgmltag>. This element + horizontal rule, called <tag>hr</tag>. This element does not wrap content, so it looks like this:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>One paragraph.<sgmltag class="endtag">p</sgmltag> -<sgmltag class="starttag">hr</sgmltag><sgmltag class="endtag">hr</sgmltag> + <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> +<tag class="starttag">hr</tag><tag class="endtag">hr</tag> -<sgmltag class="starttag">p</sgmltag>This is another paragraph. A horizontal rule separates this - from the previous paragraph.<sgmltag class="endtag">p</sgmltag></programlisting> +<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<tag class="endtag">p</tag></programlisting> <para>The shorthand version consists of a single tag:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>One paragraph.<sgmltag class="endtag">p</sgmltag> -<sgmltag class="emptytag">hr</sgmltag> + <programlisting><tag class="starttag">p</tag>One paragraph.<tag class="endtag">p</tag> +<tag class="emptytag">hr</tag> -<sgmltag class="starttag">p</sgmltag>This is another paragraph. A horizontal rule separates this - from the previous paragraph.<sgmltag class="endtag">p</sgmltag></programlisting> +<tag class="starttag">p</tag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<tag class="endtag">p</tag></programlisting> </example> <para>As shown above, elements can contain other elements. In the @@ -275,10 +271,10 @@ and so on.</para> <example> - <title>Elements Within Elements; <sgmltag>em</sgmltag></title> + <title>Elements Within Elements; <tag>em</tag></title> - <programlisting><sgmltag class="starttag">p</sgmltag>This is a simple <sgmltag class="starttag">em</sgmltag>paragraph<sgmltag class="endtag">em</sgmltag> where some - of the <sgmltag class="starttag">em</sgmltag>words<sgmltag class="endtag">em</sgmltag> have been <sgmltag class="starttag">em</sgmltag>emphasized<sgmltag class="endtag">em</sgmltag>.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>This is a simple <tag class="starttag">em</tag>paragraph<tag class="endtag">em</tag> where some + of the <tag class="starttag">em</tag>words<tag class="endtag">em</tag> have been <tag class="starttag">em</tag>emphasized<tag class="endtag">em</tag>.<tag class="endtag">p</tag></programlisting> </example> <para>The grammar consists of rules that describe which elements @@ -296,11 +292,11 @@ <para>When this document (or anyone else knowledgeable about <acronym>XML</acronym>) refers to - <quote>the <sgmltag class="starttag">p</sgmltag> tag</quote> + <quote>the <tag class="starttag">p</tag> tag</quote> they mean the literal text consisting of the three characters <literal><</literal>, <literal>p</literal>, and <literal>></literal>. But the phrase - <quote>the <sgmltag>p</sgmltag> element</quote> refers to the + <quote>the <tag>p</tag> element</quote> refers to the whole element.</para> <para>This distinction <emphasis>is</emphasis> very subtle. But @@ -316,15 +312,15 @@ <para>An element's attributes are written <emphasis>inside</emphasis> the start tag for that element, and take the form - <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> + <literal>attribute-name="attribute-value"</literal>.</para> - <para>In <acronym>XHTML</acronym>, the <sgmltag>p</sgmltag> + <para>In <acronym>XHTML</acronym>, the <tag>p</tag> element has an attribute called - <sgmltag class="attribute">align</sgmltag>, which suggests an + <tag class="attribute">align</tag>, which suggests an alignment (justification) for the paragraph to the program displaying the <acronym>XHTML</acronym>.</para> - <para>The <sgmltag class="attribute">align</sgmltag> attribute can + <para>The <tag class="attribute">align</tag> attribute can take one of four defined values, <literal>left</literal>, <literal>center</literal>, <literal>right</literal> and <literal>justify</literal>. If the attribute is not specified @@ -333,10 +329,10 @@ <example> <title>Using an Element with an Attribute</title> - <programlisting><sgmltag class="starttag">p align="left"</sgmltag>The inclusion of the align attribute - on this paragraph was superfluous, since the default is left.<sgmltag class="endtag">p</sgmltag> + <programlisting><tag class="starttag">p align="left"</tag>The inclusion of the align attribute + on this paragraph was superfluous, since the default is left.<tag class="endtag">p</tag> -<sgmltag class="starttag">p align="center"</sgmltag>This may appear in the center.<sgmltag class="endtag">p</sgmltag></programlisting> +<tag class="starttag">p align="center"</tag>This may appear in the center.<tag class="endtag">p</tag></programlisting> </example> <para>Some attributes only take specific values, such as @@ -346,7 +342,7 @@ <example> <title>Single Quotes Around Attributes</title> - <programlisting><sgmltag class="starttag">p align='right'</sgmltag>I am on the right!<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p align='right'</tag>I am on the right!<tag class="endtag">p</tag></programlisting> </example> <para>Attribute values in <acronym>XML</acronym> must be enclosed @@ -371,7 +367,7 @@ <procedure> <step> <para>Install - <filename role="package">textproc/docproj</filename> from + <package>textproc/docproj</package> from the &os; Ports Collection. This is a <emphasis>meta-port</emphasis> that downloads and installs the standard programs and supporting files needed by the @@ -385,7 +381,7 @@ <replaceable>en_US.ISO8859-1</replaceable> with the appropriate directory for the target language.</para> - <example id="xml-primer-envars"> + <example xml:id="xml-primer-envars"> <title><filename>.profile</filename>, for &man.sh.1; and &man.bash.1; Users</title> @@ -423,28 +419,28 @@ setenv SGML_CATALOG_FILES /usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/sh <para>Create <filename>example.xml</filename>, and enter this text:</para> - <programlisting><sgmltag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</sgmltag> + <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag> -<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> - <sgmltag class="starttag">head</sgmltag> - <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag> - <sgmltag class="endtag">head</sgmltag> +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> - <sgmltag class="starttag">body</sgmltag> - <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> - <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> - <sgmltag class="starttag">p align="right"</sgmltag>This paragraph might be right-justified.<sgmltag class="endtag">p</sgmltag> - <sgmltag class="endtag">body</sgmltag> -<sgmltag class="endtag">html</sgmltag></programlisting> + <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> </step> <step> <para>Try to validate this file using an <acronym>XML</acronym> parser.</para> - <para><filename role="package">textproc/docproj</filename> + <para><package>textproc/docproj</package> includes the <command>xmllint</command> <link linkend="xml-primer-validating">validating parser</link>.</para> @@ -462,8 +458,8 @@ setenv SGML_CATALOG_FILES /usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/sh <step> <para>See what happens when required elements are omitted. Delete the line with the - <sgmltag class="starttag">title</sgmltag> and - <sgmltag class="endtag">/title</sgmltag> tags, and re-run + <tag class="starttag">title</tag> and + <tag class="endtag">/title</tag> tags, and re-run the validation.</para> <screen>&prompt.user; <userinput>xmllint --valid --noout example.xml</userinput> @@ -472,7 +468,7 @@ example.xml:5: element head: validity error : Element head content does not foll <para>This shows that the validation error comes from the <replaceable>fifth</replaceable> line of the <replaceable>example.xml</replaceable> file and that the - content of the <sgmltag class="starttag">head</sgmltag> is + content of the <tag class="starttag">head</tag> is the part which does not follow the rules of the <acronym>XHTML</acronym> grammar.</para> @@ -482,13 +478,13 @@ example.xml:5: element head: validity error : Element head content does not foll </step> <step> - <para>Replace the <sgmltag>title</sgmltag> element.</para> + <para>Replace the <tag>title</tag> element.</para> </step> </procedure> </sect2> </sect1> - <sect1 id="xml-primer-doctype-declaration"> + <sect1 xml:id="xml-primer-doctype-declaration"> <title>The DOCTYPE Declaration</title> <para>The beginning of each document can specify the name of the @@ -501,7 +497,7 @@ example.xml:5: element head: validity error : Element head content does not foll version 1.0 of the <acronym>XHTML</acronym> <acronym>DTD</acronym> looks like this:</para> - <programlisting><sgmltag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</sgmltag></programlisting> + <programlisting><tag class="starttag">!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</tag></programlisting> <para>That line contains a number of different components.</para> @@ -555,8 +551,7 @@ example.xml:5: element head: validity error : Element head content does not foll <acronym>DTD</acronym> referenced in the <acronym>FPI</acronym>. Other ways of telling the <acronym>XML</acronym> parser how to find the - <acronym>DTD</acronym> are shown <link - linkend="xml-primer-fpi-alternatives">later</link>.</para> + <acronym>DTD</acronym> are shown <link linkend="xml-primer-fpi-alternatives">later</link>.</para> </listitem> </varlistentry> @@ -620,9 +615,9 @@ example.xml:5: element head: validity error : Element head content does not foll superset) of <acronym>XML</acronym>.</para> <para>Otherwise, this string will either look like - <literal>-//<replaceable>Owner</replaceable></literal> + <literal>-//Owner</literal> or - <literal>+//<replaceable>Owner</replaceable></literal> + <literal>+//Owner</literal> (notice the only difference is the leading <literal>+</literal> or <literal>-</literal>).</para> @@ -714,8 +709,7 @@ example.xml:5: element head: validity error : Element head content does not foll <filename>/usr/local/share/xml/dtd/xhtml/catalog.xml</filename>. This is the catalog file for the <acronym>XHTML</acronym> <acronym>DTD</acronym>s that were installed as part of the - <filename - role="package">textproc/docproj</filename> port.</para> + <package>textproc/docproj</package> port.</para> </sect3> <sect3> @@ -756,7 +750,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect3> </sect2> - <sect2 id="xml-primer-fpi-alternatives"> + <sect2 xml:id="xml-primer-fpi-alternatives"> <title>Alternatives to <acronym>FPI</acronym>s</title> <para>Instead of using an <acronym>FPI</acronym> to indicate the @@ -767,7 +761,7 @@ example.xml:5: element head: validity error : Element head content does not foll <para>The syntax is slightly different:</para> - <programlisting><sgmltag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</sgmltag></programlisting> + <programlisting><tag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</tag></programlisting> <para>The <literal>SYSTEM</literal> keyword indicates that the <acronym>XML</acronym> processor should locate the @@ -782,7 +776,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect2> </sect1> - <sect1 id="xml-primer-xml-escape"> + <sect1 xml:id="xml-primer-xml-escape"> <title>Escaping Back to <acronym>XML</acronym></title> <para>Some of the underlying <acronym>XML</acronym> syntax can be @@ -802,7 +796,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect1> - <sect1 id="xml-primer-comments"> + <sect1 xml:id="xml-primer-comments"> <title>Comments</title> <para>Comments are an <acronym>XML</acronym> construct, and are @@ -877,7 +871,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect2> </sect1> - <sect1 id="xml-primer-entities"> + <sect1 xml:id="xml-primer-entities"> <title>Entities</title> <para>Entities are a mechanism for assigning names to chunks of @@ -894,7 +888,7 @@ example.xml:5: element head: validity error : Element head content does not foll situations: <emphasis>general entities</emphasis> and <emphasis>parameter entities</emphasis>.</para> - <sect2 id="xml-primer-general-entities"> + <sect2 xml:id="xml-primer-general-entities"> <title>General Entities</title> <para>General entities are used to assign names to reusable @@ -904,14 +898,14 @@ example.xml:5: element head: validity error : Element head content does not foll <para>To include the text of a general entity in the document, include - <literal>&<replaceable>entity-name</replaceable>;</literal> + <literal>&entity-name;</literal> in the text. For example, consider a general entity called <literal>current.version</literal> which expands to the current version number of a product. To use it in the document, write:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>The current version of our product is - &current.version;.<sgmltag class="endtag">para</sgmltag></programlisting> + <programlisting><tag class="starttag">para</tag>The current version of our product is + &current.version;.<tag class="endtag">para</tag></programlisting> <para>When the version number changes, edit the definition of the general entity, replacing the value. Then reprocess the @@ -955,7 +949,7 @@ example.xml:5: element head: validity error : Element head content does not foll </example> </sect2> - <sect2 id="xml-primer-parameter-entities"> + <sect2 xml:id="xml-primer-parameter-entities"> <title>Parameter Entities</title> <para>Parameter entities, like @@ -968,7 +962,7 @@ example.xml:5: element head: validity error : Element head content does not foll <para>Parameter entity definitons are similar to those for general entities. However, parameter entries are included with - <literal>%<replaceable>entity-name</replaceable>;</literal>. + <literal>%entity-name;</literal>. The definition also includes the <literal>%</literal> between the <literal>ENTITY</literal> keyword and the name of the entity.</para> @@ -1004,23 +998,23 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY version "1.1"> ]> -<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> - <sgmltag class="starttag">head</sgmltag> - <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag> - <sgmltag class="endtag">head</sgmltag> +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> <!-- There may be some comments in here as well --> - <sgmltag class="starttag">body</sgmltag> - <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>This is a paragraph containing some text.<tag class="endtag">p</tag> - <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">p</tag>This paragraph contains some more text.<tag class="endtag">p</tag> - <sgmltag class="starttag">p align="right"</sgmltag>This paragraph might be right-justified.<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">p align="right"</tag>This paragraph might be right-justified.<tag class="endtag">p</tag> - <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag> - <sgmltag class="endtag">body</sgmltag> -<sgmltag class="endtag">html</sgmltag></programlisting> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> </step> <step> @@ -1068,7 +1062,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect2> </sect1> - <sect1 id="xml-primer-include"> + <sect1 xml:id="xml-primer-include"> <title>Using Entities to Include Files</title> <para>Both @@ -1077,7 +1071,7 @@ example.xml:5: element head: validity error : Element head content does not foll entities are particularly useful for including one file inside another.</para> - <sect2 id="xml-primer-include-using-gen-entities"> + <sect2 xml:id="xml-primer-include-using-gen-entities"> <title>Using General Entities to Include Files</title> <para>Consider some content for an <acronym>XML</acronym> book @@ -1104,13 +1098,13 @@ example.xml:5: element head: validity error : Element head content does not foll <!-- And so forth --> ]> -<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> <!-- Use the entities to load in the chapters --> &chapter.1; &chapter.2; &chapter.3; -<sgmltag class="endtag">html</sgmltag></programlisting> +<tag class="endtag">html</tag></programlisting> </example> <warning> @@ -1170,11 +1164,11 @@ example.xml:5: element head: validity error : Element head content does not foll %chapters; ]> -<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> &chapter.1; &chapter.2; &chapter.3; -<sgmltag class="endtag">html</sgmltag></programlisting> +<tag class="endtag">html</tag></programlisting> </example> </sect2> @@ -1192,7 +1186,7 @@ example.xml:5: element head: validity error : Element head content does not foll <para>Put content like this in each file:</para> - <programlisting><sgmltag class="starttag">p</sgmltag>This is the first paragraph.<sgmltag class="endtag">p</sgmltag></programlisting> + <programlisting><tag class="starttag">p</tag>This is the first paragraph.<tag class="endtag">p</tag></programlisting> </step> <step> @@ -1207,19 +1201,19 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY para3 SYSTEM "para3.xml"> ]> -<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> - <sgmltag class="starttag">head</sgmltag> - <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag> - <sgmltag class="endtag">head</sgmltag> +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> - <sgmltag class="starttag">body</sgmltag> - <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> &para1; &para2; &para3; - <sgmltag class="endtag">body</sgmltag> -<sgmltag class="endtag">html</sgmltag></programlisting> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> </step> <step> @@ -1232,7 +1226,7 @@ example.xml:5: element head: validity error : Element head content does not foll <step> <para>Load <filename>example.html</filename> into the web browser and confirm that the - <filename>para<replaceable>n</replaceable>.xml</filename> + <filename>paran.xml</filename> files have been included in <filename>example.html</filename>.</para> </step> @@ -1257,19 +1251,19 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY % entities SYSTEM "entities.ent"> %entities; ]> -<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> - <sgmltag class="starttag">head</sgmltag> - <sgmltag class="starttag">title</sgmltag>An Example XHTML File<sgmltag class="endtag">title</sgmltag> - <sgmltag class="endtag">head</sgmltag> +<tag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</tag> + <tag class="starttag">head</tag> + <tag class="starttag">title</tag>An Example XHTML File<tag class="endtag">title</tag> + <tag class="endtag">head</tag> - <sgmltag class="starttag">body</sgmltag> - <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag> + <tag class="starttag">body</tag> + <tag class="starttag">p</tag>The current version of this document is: &version;<tag class="endtag">p</tag> &para1; &para2; &para3; - <sgmltag class="endtag">body</sgmltag> -<sgmltag class="endtag">html</sgmltag></programlisting> + <tag class="endtag">body</tag> +<tag class="endtag">html</tag></programlisting> </step> <step> @@ -1293,7 +1287,7 @@ example.xml:5: element head: validity error : Element head content does not foll <step> <para>Load <filename>example.html</filename> into the web browser and confirm that the - <filename>para<replaceable>n</replaceable>.xml</filename> + <filename>paran.xml</filename> files have been included in <filename>example.html</filename>.</para> </step> @@ -1302,7 +1296,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect2> </sect1> - <sect1 id="xml-primer-marked-sections"> + <sect1 xml:id="xml-primer-marked-sections"> <title>Marked Sections</title> <para><acronym>XML</acronym> provides a mechanism to indicate that @@ -1334,10 +1328,10 @@ example.xml:5: element head: validity error : Element head content does not foll <acronym>XML</acronym> context with <literal>></literal>.</para> - <sect2 id="xml-primer-marked-section-keywords"> + <sect2 xml:id="xml-primer-marked-section-keywords"> <title>Marked Section Keywords</title> - <sect3 id="xml-primer-cdata"> + <sect3 xml:id="xml-primer-cdata"> <title><literal>CDATA</literal></title> <para>These keywords denote the marked sections @@ -1376,29 +1370,29 @@ example.xml:5: element head: validity error : Element head content does not foll <title>Using a <literal>CDATA</literal> Marked Section</title> - <programlisting><sgmltag class="starttag">para</sgmltag>Here is an example of how to include some text that contains - many <sgmltag class="starttag">literal</sgmltag>&lt;<sgmltag class="endtag">literal</sgmltag> and <sgmltag class="starttag">literal</sgmltag>&amp;<sgmltag class="endtag">literal</sgmltag> + <programlisting><tag class="starttag">para</tag>Here is an example of how to include some text that contains + many <tag class="starttag">literal</tag>&lt;<tag class="endtag">literal</tag> and <tag class="starttag">literal</tag>&amp;<tag class="endtag">literal</tag> symbols. The sample text is a fragment of - <sgmltag class="starttag">acronym</sgmltag>XHTML<sgmltag class="endtag">acronym</sgmltag>. The surrounding text (<sgmltag class="starttag">para</sgmltag> and - <sgmltag class="starttag">programlisting</sgmltag>) are from DocBook.<sgmltag class="endtag">para</sgmltag> + <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. The surrounding text (<tag class="starttag">para</tag> and + <tag class="starttag">programlisting</tag>) are from DocBook.<tag class="endtag">para</tag> -<sgmltag class="starttag">programlisting</sgmltag><![CDATA[<sgmltag class="starttag">p</sgmltag>This is a sample that shows some of the - elements within <sgmltag class="starttag">acronym</sgmltag>XHTML<sgmltag class="endtag">acronym</sgmltag>. Since the angle +<tag class="starttag">programlisting</tag><![CDATA[<tag class="starttag">p</tag>This is a sample that shows some of the + elements within <tag class="starttag">acronym</tag>XHTML<tag class="endtag">acronym</tag>. Since the angle brackets are used so many times, it is simpler to say the whole example is a CDATA marked section than to use the entity names for - the left and right angle brackets throughout.<sgmltag class="endtag">p</sgmltag> + the left and right angle brackets throughout.<tag class="endtag">p</tag> - <sgmltag class="starttag">ul</sgmltag> - <sgmltag class="starttag">li</sgmltag>This is a listitem<sgmltag class="endtag">li</sgmltag> - <sgmltag class="starttag">li</sgmltag>This is a second listitem<sgmltag class="endtag">li</sgmltag> - <sgmltag class="starttag">li</sgmltag>This is a third listitem<sgmltag class="endtag">li</sgmltag> - <sgmltag class="endtag">ul</sgmltag> + <tag class="starttag">ul</tag> + <tag class="starttag">li</tag>This is a listitem<tag class="endtag">li</tag> + <tag class="starttag">li</tag>This is a second listitem<tag class="endtag">li</tag> + <tag class="starttag">li</tag>This is a third listitem<tag class="endtag">li</tag> + <tag class="endtag">ul</tag> - <sgmltag class="starttag">p</sgmltag>This is the end of the example.<sgmltag class="endtag">p</sgmltag>]]><sgmltag class="endtag">programlisting</sgmltag></programlisting> + <tag class="starttag">p</tag>This is the end of the example.<tag class="endtag">p</tag>]]><tag class="endtag">programlisting</tag></programlisting> </example> </sect3> - <sect3 id="xml-primer-include-ignore"> + <sect3 xml:id="xml-primer-include-ignore"> <title><literal>INCLUDE</literal> and <literal>IGNORE</literal></title> @@ -1455,7 +1449,7 @@ example.xml:5: element head: validity error : Element head content does not foll <title>Using a Parameter Entity to Control a Marked Section</title> - <programlisting><!ENTITY % electronic.copy "INCLUDE"> + <programlisting><!ENTITY % electronic.copy "INCLUDE"> <![%electronic.copy;[ <!ENTITY chap.preface SYSTEM "preface.xml"> @@ -1507,7 +1501,7 @@ example.xml:5: element head: validity error : Element head content does not foll </sect2> </sect1> - <sect1 id="xml-primer-conclusion"> + <sect1 xml:id="xml-primer-conclusion"> <title>Conclusion</title> <para>That is the conclusion of this <acronym>XML</acronym> diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile index f2e41fc06f..fa7ad27323 100644 --- a/en_US.ISO8859-1/books/handbook/Makefile +++ b/en_US.ISO8859-1/books/handbook/Makefile @@ -39,8 +39,6 @@ DOC?= book FORMATS?= html-split -HAS_INDEX= true - INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= diff --git a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml index 5ed0a17bdd..25f376583f 100644 --- a/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - -<chapter id="advanced-networking"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="advanced-networking"> <title>Advanced Networking</title> - <sect1 id="advanced-networking-synopsis"> + <sect1 xml:id="advanced-networking-synopsis"> <title>Synopsis</title> <para>This chapter covers a number of advanced networking @@ -86,18 +85,14 @@ </itemizedlist> </sect1> - <sect1 id="network-routing"> - <sect1info> + <sect1 xml:id="network-routing"> + <info><title>Gateways and Routes</title> <authorgroup> - <author> - <firstname>Coranth</firstname> - <surname>Gryphon</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Coranth</firstname><surname>Gryphon</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Gateways and Routes</title> + <indexterm><primary>routing</primary></indexterm> <indexterm><primary>gateway</primary></indexterm> @@ -135,19 +130,19 @@ test0 0:e0:b5:36:cf:4f UHLW 5 63288 ed0 77 10.20.30.255 link#1 UHLW 1 2421 example.com link#1 UC 0 0 host1 0:e0:a8:37:8:1e UHLW 3 4601 lo0 -host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => +host2 0:e0:a8:37:8:1e UHLW 0 5 lo0 => host2.example.com link#1 UC 0 0 224 link#1 UC 0 0</screen> <indexterm><primary>default route</primary></indexterm> <para>The first two lines specify the default route, described in more detail in <xref linkend="network-routing-default"/>, - and the <hostid>localhost</hostid> route.</para> + and the <systemitem>localhost</systemitem> route.</para> <indexterm><primary>loopback device</primary></indexterm> <para>The interface (<literal>Netif</literal> column) that this routing table specifies to use for - <literal>localhost</literal> is <devicename>lo0</devicename>, + <literal>localhost</literal> is <filename>lo0</filename>, also known as the loopback device. This says to keep all traffic for this destination internal, rather than sending it out over the network.</para> @@ -156,13 +151,12 @@ host2.example.com link#1 UC 0 0 <primary>Ethernet</primary> <secondary>MAC address</secondary> </indexterm> - <para>The addresses beginning with <hostid - role="mac">0:e0:</hostid> are Ethernet hardware addresses, + <para>The addresses beginning with <systemitem class="etheraddress">0:e0:</systemitem> are Ethernet hardware addresses, also known as <acronym>MAC</acronym> addresses. &os; will - automatically identify any hosts, <hostid>test0</hostid> in + automatically identify any hosts, <systemitem>test0</systemitem> in the example, on the local Ethernet and add a route for that host over the Ethernet interface, - <devicename>ed0</devicename>. This type of route has a + <filename>ed0</filename>. This type of route has a timeout, seen in the <literal>Expire</literal> column, which is used if the host does not respond in a specific amount of time. When this happens, the route to this host will be @@ -174,9 +168,9 @@ host2.example.com link#1 UC 0 0 <indexterm><primary>subnet</primary></indexterm> <para>&os; will add subnet routes for the local subnet. - <hostid role="ipaddr">10.20.30.255</hostid> is the broadcast - address for the subnet <hostid role="ipaddr">10.20.30</hostid> - and <hostid role="domainname">example.com</hostid> is the + <systemitem class="ipaddress">10.20.30.255</systemitem> is the broadcast + address for the subnet <systemitem class="ipaddress">10.20.30</systemitem> + and <systemitem class="fqdomainname">example.com</systemitem> is the domain name associated with that subnet. The designation <literal>link#1</literal> refers to the first Ethernet card in the machine.</para> @@ -189,20 +183,19 @@ host2.example.com link#1 UC 0 0 <para>The <literal>host1</literal> line refers to the host by its Ethernet address. Since it is the sending host, &os; knows to use the loopback interface - (<devicename>lo0</devicename>) rather than the Ethernet + (<filename>lo0</filename>) rather than the Ethernet interface.</para> <para>The two <literal>host2</literal> lines represent aliases which were created using &man.ifconfig.8;. The <literal>=></literal> symbol after the - <devicename>lo0</devicename> interface says that an alias + <filename>lo0</filename> interface says that an alias has been set in addition to the loopback address. Such routes only show up on the host that supports the alias; all other hosts on the local network will have a <literal>link#1</literal> line for such routes.</para> - <para>The final line (destination subnet <hostid - role="ipaddr">224</hostid>) deals with + <para>The final line (destination subnet <systemitem class="ipaddress">224</systemitem>) deals with multicasting.</para> <para>Finally, various attributes of each route can be seen in @@ -263,7 +256,7 @@ host2.example.com link#1 UC 0 0 </informaltable> </sect2> - <sect2 id="network-routing-default"> + <sect2 xml:id="network-routing-default"> <title>Default Routes</title> <indexterm><primary>default route</primary></indexterm> @@ -301,9 +294,9 @@ host2.example.com link#1 UC 0 0 </textobject> </mediaobject> - <para>The hosts <hostid>Local1</hostid> and - <hostid>Local2</hostid> are on the local network. - <hostid>Local1</hostid> is connected to an + <para>The hosts <systemitem>Local1</systemitem> and + <systemitem>Local2</systemitem> are on the local network. + <systemitem>Local1</systemitem> is connected to an <acronym>ISP</acronym> using a <acronym>PPP</acronym> connection. This <acronym>PPP</acronym> server is connected through a local @@ -339,8 +332,8 @@ host2.example.com link#1 UC 0 0 </informaltable> <para>A common question is <quote>Why is - <hostid>T1-GW</hostid> configured as the default gateway for - <hostid>Local1</hostid>, rather than the + <systemitem>T1-GW</systemitem> configured as the default gateway for + <systemitem>Local1</systemitem>, rather than the <acronym>ISP</acronym> server it is connected to?</quote>.</para> @@ -349,16 +342,14 @@ host2.example.com link#1 UC 0 0 the local side of the connection, routes for any other machines on the <acronym>ISP</acronym>'s local network will be automatically generated. The system already knows how - to reach the <hostid>T1-GW</hostid> machine, so there is no + to reach the <systemitem>T1-GW</systemitem> machine, so there is no need for the intermediate step of sending traffic to the <acronym>ISP</acronym>'s server.</para> - <para>It is common to use the address <hostid - role="ipaddr">X.X.X.1</hostid> as the gateway address for + <para>It is common to use the address <systemitem class="ipaddress">X.X.X.1</systemitem> as the gateway address for the local network. So, if the local class C address space is - <hostid role="ipaddr">10.20.30</hostid> and the - <acronym>ISP</acronym> is using <hostid - role="ipaddr">10.9.9</hostid>, the default routes would + <systemitem class="ipaddress">10.20.30</systemitem> and the + <acronym>ISP</acronym> is using <systemitem class="ipaddress">10.9.9</systemitem>, the default routes would be:</para> <informaltable frame="none" pgwide="1"> @@ -385,7 +376,7 @@ host2.example.com link#1 UC 0 0 <para>The default route can be easily defined in <filename>/etc/rc.conf</filename>. In this example, on - <hostid>Local2</hostid>, add the following line to + <systemitem>Local2</systemitem>, add the following line to <filename>/etc/rc.conf</filename>:</para> <programlisting>defaultrouter="10.20.30.1"</programlisting> @@ -399,7 +390,7 @@ host2.example.com link#1 UC 0 0 routing tables, refer to &man.route.8;.</para> </sect2> - <sect2 id="network-dual-homed-hosts"> + <sect2 xml:id="network-dual-homed-hosts"> <title>Dual Homed Hosts</title> <indexterm><primary>dual homed hosts</primary></indexterm> @@ -427,7 +418,7 @@ host2.example.com link#1 UC 0 0 demonstrated in the next section.</para> </sect2> - <sect2 id="network-dedicated-router"> + <sect2 xml:id="network-dedicated-router"> <title>Building a Router</title> <indexterm><primary>router</primary></indexterm> @@ -456,22 +447,18 @@ host2.example.com link#1 UC 0 0 1 and 2, and <acronym>IRDP</acronym>. Support for <acronym>BGP</acronym>v4, <acronym>OSPF</acronym>v2, and other sophisticated routing protocols is available with the - <filename role="package">net/zebra</filename> package or + <package>net/zebra</package> package or port.</para> </sect2> - <sect2 id="network-static-routes"> - <sect2info> + <sect2 xml:id="network-static-routes"> + <info><title>Setting Up Static Routes</title> <authorgroup> - <author> - <firstname>Al</firstname> - <surname>Hoang</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Al</firstname><surname>Hoang</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> <!-- Feb 2004 --> - <title>Setting Up Static Routes</title> + <sect3> <title>Manual Configuration</title> @@ -510,15 +497,13 @@ host2.example.com link#1 UC 0 0 </textobject> </mediaobject> - <para>In this scenario, <hostid>RouterA</hostid> is a &os; + <para>In this scenario, <systemitem>RouterA</systemitem> is a &os; machine that is acting as a router to the rest of the - Internet. It has a default route set to <hostid - role="ipaddr">10.0.0.1</hostid> which allows it to - connect with the outside world. <hostid>RouterB</hostid> is - already configured properly as it uses <hostid - role="ipaddr">192.168.1.1</hostid> as the gateway.</para> + Internet. It has a default route set to <systemitem class="ipaddress">10.0.0.1</systemitem> which allows it to + connect with the outside world. <systemitem>RouterB</systemitem> is + already configured properly as it uses <systemitem class="ipaddress">192.168.1.1</systemitem> as the gateway.</para> - <para>The routing table on <hostid>RouterA</hostid> looks + <para>The routing table on <systemitem>RouterA</systemitem> looks something like this:</para> <screen>&prompt.user; <userinput>netstat -nr</userinput> @@ -531,18 +516,17 @@ default 10.0.0.1 UGS 0 49378 xl0 10.0.0.0/24 link#1 UC 0 0 xl0 192.168.1.0/24 link#2 UC 0 0 xl1</screen> - <para>With the current routing table, <hostid>RouterA</hostid> + <para>With the current routing table, <systemitem>RouterA</systemitem> cannot reach Internal Net 2 as it does not have a route for - <hostid role="ipaddr">192.168.2.0/24</hostid>. The + <systemitem class="ipaddress">192.168.2.0/24</systemitem>. The following command adds the Internal Net 2 network to - <hostid>RouterA</hostid>'s routing table using <hostid - role="ipaddr">192.168.1.2</hostid> as the next + <systemitem>RouterA</systemitem>'s routing table using <systemitem class="ipaddress">192.168.1.2</systemitem> as the next hop:</para> <screen>&prompt.root; <userinput>route add -net 192.168.2.0/24 192.168.1.2</userinput></screen> - <para>Now <hostid>RouterA</hostid> can reach any hosts on the - <hostid role="ipaddr">192.168.2.0/24</hostid> + <para>Now <systemitem>RouterA</systemitem> can reach any hosts on the + <systemitem class="ipaddress">192.168.2.0/24</systemitem> network.</para> </sect3> @@ -564,7 +548,7 @@ route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting> each string references a route name. This example only has one string in <literal>static_routes</literal>, <replaceable>internalnet2</replaceable>. The variable - <literal>route_<replaceable>internalnet2</replaceable></literal> + <literal>route_internalnet2</literal> contains all of the configuration parameters to &man.route.8;. This example is equivalent to the command:</para> @@ -574,8 +558,8 @@ route_internalnet2="-net 192.168.2.0/24 192.168.1.2"</programlisting> <para>Using more than one string in <literal>static_routes</literal> creates multiple static routes. The following shows an example of adding static - routes for the <hostid role="ipaddr">192.168.0.0/24</hostid> - and <hostid role="ipaddr">192.168.1.0/24</hostid> + routes for the <systemitem class="ipaddress">192.168.0.0/24</systemitem> + and <systemitem class="ipaddress">192.168.1.0/24</systemitem> networks:</para> <programlisting>static_routes="net1 net2" @@ -584,7 +568,7 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> </sect3> </sect2> - <sect2 id="network-routing-propagation"> + <sect2 xml:id="network-routing-propagation"> <title>Routing Propagation</title> <para>When an address space is assigned to a network, the @@ -608,7 +592,7 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> propagation.</para> </sect2> - <sect2 id="network-routing-troubleshooting"> + <sect2 xml:id="network-routing-troubleshooting"> <title>Troubleshooting</title> <indexterm> @@ -630,7 +614,7 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> <para>For more information, refer to &man.traceroute.8;.</para> </sect2> - <sect2 id="network-routing-multicast"> + <sect2 xml:id="network-routing-multicast"> <title>Multicast Routing</title> <indexterm> @@ -660,31 +644,22 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> which has largely been replaced by &man.pim.4; in many multicast installations. &man.mrouted.8; and the related &man.map-mbone.8; and &man.mrinfo.8; utilities are available - in the &os; Ports Collection as <filename - role="package">net/mrouted</filename>.</para> + in the &os; Ports Collection as <package>net/mrouted</package>.</para> </note> </sect2> </sect1> - <sect1 id="network-wireless"> - <sect1info> + <sect1 xml:id="network-wireless"> + <info><title>Wireless Networking</title> <authorgroup> - <author> - <othername>Loader</othername> - </author> - - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - </author> - - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - </author> + <author><personname><othername>Loader</othername></personname></author> + + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname></author> + + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> </authorgroup> - </sect1info> - <title>Wireless Networking</title> + </info> + <indexterm><primary>wireless networking</primary></indexterm> <indexterm> @@ -786,7 +761,7 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> supported for a limited set of wireless devices.</para> </sect2> - <sect2 id="network-wireless-basic"> + <sect2 xml:id="network-wireless-basic"> <title>Basic Setup</title> <sect3> @@ -825,13 +800,11 @@ route_net2="-net 192.168.1.0/24 192.168.1.1"</programlisting> changed according to the configuration. A list of available wireless drivers and supported adapters can be found in the &os; Hardware Notes, available on - the <ulink - url="http://www.FreeBSD.org/releases/index.html">Release - Information</ulink> page of the &os; website. If a + the <link xlink:href="http://www.FreeBSD.org/releases/index.html">Release + Information</link> page of the &os; website. If a native &os; driver for the wireless device does not exist, it may be possible to use the &windows; driver - with the help of the <link - linkend="config-network-ndis">NDIS</link> driver + with the help of the <link linkend="config-network-ndis">NDIS</link> driver wrapper.</para> </note> @@ -909,8 +882,8 @@ ath0: AR2413 mac 7.9 RF2413 phy 4.5</screen> frequency and probe for available access points. Only the superuser can initiate a scan:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0</userinput> +&prompt.root; <userinput>ifconfig wlan0 up scan</userinput> SSID/MESH ID BSSID CHAN RATE S:N INT CAPS dlinkap 00:13:46:49:41:76 11 54M -90:96 100 EPS WPA WME freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen> @@ -992,7 +965,7 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen> <para>One can also display the current list of known networks with:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list scan</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig wlan0 list scan</userinput></screen> <para>This information may be updated automatically by the adapter or manually with a <option>scan</option> request. @@ -1007,8 +980,7 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -83:96 100 EPS WPA</screen> <para>This section provides a simple example of how to make the wireless network adapter work in &os; without encryption. Once familiar with these concepts, it is - strongly recommend to use <link - linkend="network-wireless-wpa">WPA</link> to set up + strongly recommend to use <link linkend="network-wireless-wpa">WPA</link> to set up the wireless network.</para> <para>There are three basic steps to configure a wireless @@ -1085,8 +1057,7 @@ ifconfig_wlan0="mode <replaceable>11g</replaceable> ssid <replaceable>your_ssid_ authentication is the default setting. The next most common setup is <acronym>WPA-PSK</acronym>, also known as <acronym>WPA</acronym> Personal, which is - described in <xref - linkend="network-wireless-wpa-wpa-psk"/>.</para> + described in <xref linkend="network-wireless-wpa-wpa-psk"/>.</para> <note> <para>If using an &apple; &airport; Extreme base @@ -1108,8 +1079,7 @@ ifconfig_wlan0="authmode shared wepmode on weptxkey <replaceable>1</replaceable> with legacy devices, it is better to use <acronym>WEP</acronym> with <literal>open</literal> authentication. More information regarding - <acronym>WEP</acronym> can be found in <xref - linkend="network-wireless-wep"/>.</para> + <acronym>WEP</acronym> can be found in <xref linkend="network-wireless-wep"/>.</para> </note> </sect5> @@ -1137,9 +1107,9 @@ ifconfig_wlan0="DHCP"</programlisting> <para>Once the interface is running, use &man.ifconfig.8; to see the status of the interface - <devicename>ath0</devicename>:</para> + <filename>ath0</filename>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.1.100 netmask 0xffffff00 broadcast 192.168.1.255 @@ -1173,7 +1143,7 @@ ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceab </sect5> </sect4> - <sect4 id="network-wireless-wpa"> + <sect4 xml:id="network-wireless-wpa"> <title><acronym>WPA</acronym></title> <para>Wi-Fi Protected Access (<acronym>WPA</acronym>) is a @@ -1221,7 +1191,7 @@ ifconfig_wlan0="inet <replaceable>192.168.1.100</replaceable> netmask <replaceab More information regarding this file can be found in &man.wpa.supplicant.conf.5;.</para> - <sect5 id="network-wireless-wpa-wpa-psk"> + <sect5 xml:id="network-wireless-wpa-wpa-psk"> <title><acronym>WPA-PSK</acronym></title> <para><acronym>WPA-PSK</acronym>, also known as @@ -1284,7 +1254,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 the information in <filename>/etc/wpa_supplicant.conf</filename>:</para> - <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput> + <screen>&prompt.root; <userinput>wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf</userinput> Trying to associate with 00:11:95:c3:0d:ac (SSID='freebsdap' freq=2412 MHz) Associated with 00:11:95:c3:0d:ac WPA: Key negotiation completed with 00:11:95:c3:0d:ac [PTK=CCMP GTK=CCMP] @@ -1294,11 +1264,11 @@ CTRL-EVENT-CONNECTED - Connection to 00:11:95:c3:0d:ac completed (auth) [id=0 id to get the <acronym>IP</acronym> address from the <acronym>DHCP</acronym> server:</para> - <screen>&prompt.root; <userinput>dhclient <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>dhclient wlan0</userinput> DHCPREQUEST on wlan0 to 255.255.255.255 port 67 DHCPACK from 192.168.0.1 bound to 192.168.0.254 -- renewal in 300 seconds. -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> +&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.254 netmask 0xffffff00 broadcast 192.168.0.255 @@ -1323,8 +1293,8 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 after &man.wpa.supplicant.8; has authenticated the station:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.100</replaceable> netmask <replaceable>255.255.255.0</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 inet 192.168.0.100 netmask 255.255.255.0</userinput> +&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.100 netmask 0xffffff00 broadcast 192.168.0.255 @@ -1340,11 +1310,11 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 default gateway and the nameserver also have to be manually set:</para> - <screen>&prompt.root; <userinput>route add default <replaceable>your_default_router</replaceable></userinput> -&prompt.root; <userinput>echo "nameserver <replaceable>your_DNS_server</replaceable>" >> /etc/resolv.conf</userinput></screen> + <screen>&prompt.root; <userinput>route add default your_default_router</userinput> +&prompt.root; <userinput>echo "nameserver your_DNS_server" >> /etc/resolv.conf</userinput></screen> </sect5> - <sect5 id="network-wireless-wpa-eap-tls"> + <sect5 xml:id="network-wireless-wpa-eap-tls"> <title><acronym>WPA</acronym> with <acronym>EAP-TLS</acronym></title> @@ -1369,8 +1339,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 (<acronym>EAP-TLS</acronym>) is a well-supported wireless authentication protocol since it was the first <acronym>EAP</acronym> method to be certified - by the <ulink - url="http://www.wi-fi.org/">Wi-Fi alliance</ulink>. + by the <link xlink:href="http://www.wi-fi.org/">Wi-Fi alliance</link>. <acronym>EAP-TLS</acronym> requires three certificates to run: the certificate of the Certificate Authority (<acronym>CA</acronym>) installed on all machines, the @@ -1386,15 +1355,15 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 <filename>/etc/wpa_supplicant.conf</filename>:</para> <programlisting>network={ - ssid="freebsdap" <co id="co-tls-ssid"/> - proto=RSN <co id="co-tls-proto"/> - key_mgmt=WPA-EAP <co id="co-tls-kmgmt"/> - eap=TLS <co id="co-tls-eap"/> - identity="loader" <co id="co-tls-id"/> - ca_cert="/etc/certs/cacert.pem" <co id="co-tls-cacert"/> - client_cert="/etc/certs/clientcert.pem" <co id="co-tls-clientcert"/> - private_key="/etc/certs/clientkey.pem" <co id="co-tls-pkey"/> - private_key_passwd="freebsdmallclient" <co id="co-tls-pwd"/> + ssid="freebsdap" <co xml:id="co-tls-ssid"/> + proto=RSN <co xml:id="co-tls-proto"/> + key_mgmt=WPA-EAP <co xml:id="co-tls-kmgmt"/> + eap=TLS <co xml:id="co-tls-eap"/> + identity="loader" <co xml:id="co-tls-id"/> + ca_cert="/etc/certs/cacert.pem" <co xml:id="co-tls-cacert"/> + client_cert="/etc/certs/clientcert.pem" <co xml:id="co-tls-clientcert"/> + private_key="/etc/certs/clientkey.pem" <co xml:id="co-tls-pkey"/> + private_key_passwd="freebsdmallclient" <co xml:id="co-tls-pwd"/> }</programlisting> <calloutlist> @@ -1483,7 +1452,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 &man.ifconfig.8;.</para> </sect5> - <sect5 id="network-wireless-wpa-eap-ttls"> + <sect5 xml:id="network-wireless-wpa-eap-ttls"> <title><acronym>WPA</acronym> with <acronym>EAP-TTLS</acronym></title> @@ -1504,11 +1473,11 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP - eap=TTLS <co id="co-ttls-eap"/> - identity="test" <co id="co-ttls-id"/> - password="test" <co id="co-ttls-passwd"/> - ca_cert="/etc/certs/cacert.pem" <co id="co-ttls-cacert"/> - phase2="auth=MD5" <co id="co-ttls-pha2"/> + eap=TTLS <co xml:id="co-ttls-eap"/> + identity="test" <co xml:id="co-ttls-id"/> + password="test" <co xml:id="co-ttls-passwd"/> + ca_cert="/etc/certs/cacert.pem" <co xml:id="co-ttls-cacert"/> + phase2="auth=MD5" <co xml:id="co-ttls-pha2"/> }</programlisting> <calloutlist> @@ -1574,7 +1543,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 wme burst roaming MANUAL</screen> </sect5> - <sect5 id="network-wireless-wpa-eap-peap"> + <sect5 xml:id="network-wireless-wpa-eap-peap"> <title><acronym>WPA</acronym> with <acronym>EAP-PEAP</acronym></title> @@ -1616,12 +1585,12 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 ssid="freebsdap" proto=RSN key_mgmt=WPA-EAP - eap=PEAP <co id="co-peap-eap"/> - identity="test" <co id="co-peap-id"/> - password="test" <co id="co-peap-passwd"/> - ca_cert="/etc/certs/cacert.pem" <co id="co-peap-cacert"/> - phase1="peaplabel=0" <co id="co-peap-pha1"/> - phase2="auth=MSCHAPV2" <co id="co-peap-pha2"/> + eap=PEAP <co xml:id="co-peap-eap"/> + identity="test" <co xml:id="co-peap-id"/> + password="test" <co xml:id="co-peap-passwd"/> + ca_cert="/etc/certs/cacert.pem" <co xml:id="co-peap-cacert"/> + phase1="peaplabel=0" <co xml:id="co-peap-pha1"/> + phase2="auth=MSCHAPV2" <co xml:id="co-peap-pha2"/> }</programlisting> <calloutlist> @@ -1699,7 +1668,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 </sect5> </sect4> - <sect4 id="network-wireless-wep"> + <sect4 xml:id="network-wireless-wep"> <title><acronym>WEP</acronym></title> <para>Wired Equivalent Privacy (<acronym>WEP</acronym>) is @@ -1710,9 +1679,9 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 <para><acronym>WEP</acronym> can be set up using &man.ifconfig.8;:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.1.100</replaceable> netmask <replaceable>255.255.255.0</replaceable> \ - ssid <replaceable>my_net</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0</userinput> +&prompt.root; <userinput>ifconfig wlan0 inet 192.168.1.100 netmask 255.255.255.0 \ + ssid my_net wepmode on weptxkey 3 wepkey 3:0x3456789012</userinput></screen> <itemizedlist> <listitem> @@ -1760,7 +1729,7 @@ wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 <para>Then:</para> - <screen>&prompt.root; <userinput>wpa_supplicant -i <replaceable>wlan0</replaceable> -c /etc/wpa_supplicant.conf</userinput> + <screen>&prompt.root; <userinput>wpa_supplicant -i wlan0 -c /etc/wpa_supplicant.conf</userinput> Trying to associate with 00:13:46:49:41:76 (SSID='dlinkap' freq=2437 MHz) Associated with 00:13:46:49:41:76</screen> </sect4> @@ -1773,15 +1742,15 @@ Associated with 00:13:46:49:41:76</screen> <para><acronym>IBSS</acronym> mode, also called ad-hoc mode, is designed for point to point connections. For example, to establish an ad-hoc network between the machines - <hostid>A</hostid> and <hostid>B</hostid>, choose two + <systemitem>A</systemitem> and <systemitem>B</systemitem>, choose two <acronym>IP</acronym> addresses and a <acronym>SSID</acronym>.</para> - <para>On <hostid>A</hostid>:</para> + <para>On <systemitem>A</systemitem>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0 wlanmode adhoc</userinput> +&prompt.root; <userinput>ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap</userinput> +&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 @@ -1794,21 +1763,21 @@ Associated with 00:13:46:49:41:76</screen> <para>The <literal>adhoc</literal> parameter indicates that the interface is running in <acronym>IBSS</acronym> mode.</para> - <para><hostid>B</hostid> should now be able to detect - <hostid>A</hostid>:</para> + <para><systemitem>B</systemitem> should now be able to detect + <systemitem>A</systemitem>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode adhoc</userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0 wlanmode adhoc</userinput> +&prompt.root; <userinput>ifconfig wlan0 up scan</userinput> SSID/MESH ID BSSID CHAN RATE S:N INT CAPS freebsdap 02:11:95:c3:0d:ac 2 54M -64:-96 100 IS WME</screen> <para>The <literal>I</literal> in the output confirms that - <hostid>A</hostid> is in ad-hoc mode. Now, configure - <hostid>B</hostid> with a different <acronym>IP</acronym> + <systemitem>A</systemitem> is in ad-hoc mode. Now, configure + <systemitem>B</systemitem> with a different <acronym>IP</acronym> address:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap</userinput> +&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 @@ -1818,11 +1787,11 @@ Associated with 00:13:46:49:41:76</screen> country US ecm authmode OPEN privacy OFF txpower 21.5 scanvalid 60 protmode CTS wme burst</screen> - <para>Both <hostid>A</hostid> and <hostid>B</hostid> are now + <para>Both <systemitem>A</systemitem> and <systemitem>B</systemitem> are now ready to exchange information.</para> </sect2> - <sect2 id="network-wireless-ap"> + <sect2 xml:id="network-wireless-ap"> <title>&os; Host Access Points</title> <para>&os; can act as an Access Point (<acronym>AP</acronym>) @@ -1831,15 +1800,14 @@ Associated with 00:13:46:49:41:76</screen> be particularly useful when a &os; machine is acting as a gateway to another network such as the Internet.</para> - <sect3 id="network-wireless-ap-basic"> + <sect3 xml:id="network-wireless-ap-basic"> <title>Basic Settings</title> <para>Before configuring a &os; machine as an <acronym>AP</acronym>, the kernel must be configured with the appropriate networking support for the wireless card as well as the security protocols being used. For more - details, see <xref - linkend="network-wireless-basic"/>.</para> + details, see <xref linkend="network-wireless-basic"/>.</para> <note> <para>The <acronym>NDIS</acronym> driver wrapper for @@ -1853,8 +1821,8 @@ Associated with 00:13:46:49:41:76</screen> the wireless device supports the host-based access point mode, also known as hostap mode:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> list caps</userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0</userinput> +&prompt.root; <userinput>ifconfig wlan0 list caps</userinput> drivercaps=6f85edc1<STA,FF,TURBOP,IBSS,HOSTAP,AHDEMO,TXPMGT,SHSLOT,SHPREAMBLE,MONITOR,MBSS,WPA1,WPA2,BURST,WME,WDS,BGSCAN,TXFRAG> cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC></screen> @@ -1870,18 +1838,18 @@ cryptocaps=1f<WEP,TKIP,AES,AES_CCM,TKIPMIC></screen> during the creation of the network pseudo-device, so a previously created device must be destroyed first:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> destroy</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig wlan0 destroy</userinput></screen> <para>then regenerated with the correct option before setting the other parameters:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable> mode 11g channel 1</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0 wlanmode hostap</userinput> +&prompt.root; <userinput>ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 ssid freebsdap mode 11g channel 1</userinput></screen> <para>Use &man.ifconfig.8; again to see the status of the - <devicename>wlan0</devicename> interface:</para> + <filename>wlan0</filename> interface:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 @@ -1918,16 +1886,16 @@ ifconfig_wlan0="inet <replaceable>192.168.0.1</replaceable> netmask <replaceable a scan from another wireless machine to find the <acronym>AP</acronym>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0</userinput> +&prompt.root; <userinput>ifconfig wlan0 up scan</userinput> SSID/MESH ID BSSID CHAN RATE S:N INT CAPS freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen> <para>The client machine found the <acronym>AP</acronym> and can be associated with it:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.2</replaceable> netmask <replaceable>255.255.255.0</replaceable> ssid <replaceable>freebsdap</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 inet 192.168.0.2 netmask 255.255.255.0 ssid freebsdap</userinput> +&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:d5:43:62 inet 192.168.0.2 netmask 0xffffff00 broadcast 192.168.0.255 @@ -1947,8 +1915,7 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen> security protocol. More details regarding <acronym>WPA</acronym> and the configuration of <acronym>WPA</acronym>-based - wireless clients can be found in <xref - linkend="network-wireless-wpa"/>.</para> + wireless clients can be found in <xref linkend="network-wireless-wpa"/>.</para> <para>The &man.hostapd.8; daemon is used to deal with client authentication and key management on the @@ -1964,8 +1931,7 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen> <programlisting>hostapd_enable="YES"</programlisting> <para>Before trying to configure &man.hostapd.8;, first - configure the basic settings introduced in <xref - linkend="network-wireless-ap-basic"/>.</para> + configure the basic settings introduced in <xref linkend="network-wireless-ap-basic"/>.</para> <sect4> <title><acronym>WPA-PSK</acronym></title> @@ -1977,15 +1943,15 @@ freebsdap 00:11:95:c3:0d:ac 1 54M -66:-96 100 ES WME</screen> <para>The configuration is done in <filename>/etc/hostapd.conf</filename>:</para> - <programlisting>interface=wlan0 <co id="co-ap-wpapsk-iface"/> -debug=1 <co id="co-ap-wpapsk-dbug"/> -ctrl_interface=/var/run/hostapd <co id="co-ap-wpapsk-ciface"/> -ctrl_interface_group=wheel <co id="co-ap-wpapsk-cifacegrp"/> -ssid=freebsdap <co id="co-ap-wpapsk-ssid"/> -wpa=1 <co id="co-ap-wpapsk-wpa"/> -wpa_passphrase=freebsdmall <co id="co-ap-wpapsk-pass"/> -wpa_key_mgmt=WPA-PSK <co id="co-ap-wpapsk-kmgmt"/> -wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> + <programlisting>interface=wlan0 <co xml:id="co-ap-wpapsk-iface"/> +debug=1 <co xml:id="co-ap-wpapsk-dbug"/> +ctrl_interface=/var/run/hostapd <co xml:id="co-ap-wpapsk-ciface"/> +ctrl_interface_group=wheel <co xml:id="co-ap-wpapsk-cifacegrp"/> +ssid=freebsdap <co xml:id="co-ap-wpapsk-ssid"/> +wpa=1 <co xml:id="co-ap-wpapsk-wpa"/> +wpa_passphrase=freebsdmall <co xml:id="co-ap-wpapsk-pass"/> +wpa_key_mgmt=WPA-PSK <co xml:id="co-ap-wpapsk-kmgmt"/> +wpa_pairwise=CCMP TKIP <co xml:id="co-ap-wpapsk-pwise"/></programlisting> <calloutlist> <callout arearefs="co-ap-wpapsk-iface"> @@ -2065,7 +2031,7 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> <screen>&prompt.root; <userinput>service hostapd forcestart</userinput></screen> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 2290 inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 inet6 fe80::211:95ff:fec3:dac%ath0 prefixlen 64 scopeid 0x4 @@ -2076,11 +2042,10 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> authmode WPA2/802.11i privacy MIXED deftxkey 2 TKIP 2:128-bit txpowmax 36 protmode CTS dtimperiod 1 bintval 100</screen> <para>Once the <acronym>AP</acronym> is running, the - clients can associate with it. See <xref - linkend="network-wireless-wpa"/> for more details. + clients can associate with it. See <xref linkend="network-wireless-wpa"/> for more details. It is possible to see the stations associated with the <acronym>AP</acronym> using <command>ifconfig - <replaceable>wlan0</replaceable> list + wlan0 list sta</command>.</para> </sect4> </sect3> @@ -2100,9 +2065,9 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> configured with the correct <acronym>SSID</acronym> and <acronym>IP</acronym> address:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable> wlanmode hostap</userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> inet <replaceable>192.168.0.1</replaceable> netmask <replaceable>255.255.255.0</replaceable> \ - ssid <replaceable>freebsdap</replaceable> wepmode on weptxkey <replaceable>3</replaceable> wepkey <replaceable>3:0x3456789012</replaceable> mode 11g</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0 wlanmode hostap</userinput> +&prompt.root; <userinput>ifconfig wlan0 inet 192.168.0.1 netmask 255.255.255.0 \ + ssid freebsdap wepmode on weptxkey 3 wepkey 3:0x3456789012 mode 11g</userinput></screen> <itemizedlist> <listitem> @@ -2125,9 +2090,9 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> </itemizedlist> <para>Use &man.ifconfig.8; to see the status of the - <devicename>wlan0</devicename> interface:</para> + <filename>wlan0</filename> interface:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0</userinput> wlan0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 ether 00:11:95:c3:0d:ac inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 @@ -2140,15 +2105,14 @@ wpa_pairwise=CCMP TKIP <co id="co-ap-wpapsk-pwise"/></programlisting> <para>From another wireless machine, it is now possible to initiate a scan to find the <acronym>AP</acronym>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>ath0</replaceable></userinput> -&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> up scan</userinput> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev ath0</userinput> +&prompt.root; <userinput>ifconfig wlan0 up scan</userinput> SSID BSSID CHAN RATE S:N INT CAPS freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen> <para>In this example, the client machine found the <acronym>AP</acronym> and can associate with it using the - correct parameters. See <xref - linkend="network-wireless-wep"/> for more details.</para> + correct parameters. See <xref linkend="network-wireless-wep"/> for more details.</para> </sect3> </sect2> @@ -2167,10 +2131,8 @@ freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen> and the operating system switches automatically when the link state changes.</para> - <para>Link aggregation and failover is covered in <xref - linkend="network-aggregation"/> and an example for using - both wired and wireless connections is provided at <xref - linkend="networking-lagg-wired-and-wireless"/>.</para> + <para>Link aggregation and failover is covered in <xref linkend="network-aggregation"/> and an example for using + both wired and wireless connections is provided at <xref linkend="networking-lagg-wired-and-wireless"/>.</para> </sect2> <sect2> @@ -2214,19 +2176,17 @@ freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen> Debugging messages can be enabled in the 802.11 protocol support layer using &man.wlandebug.8;. On a &os; system prior to &os; 9.1, this program can be found in - <filename - class="directory">/usr/src/tools/tools/net80211</filename>. + <filename>/usr/src/tools/tools/net80211</filename>. For example, to enable console messages related to scanning for access points and the 802.11 protocol handshakes required to arrange communication:</para> - <screen>&prompt.root; <userinput>wlandebug -i <replaceable>ath0</replaceable> +scan+auth+debug+assoc</userinput> + <screen>&prompt.root; <userinput>wlandebug -i ath0 +scan+auth+debug+assoc</userinput> net.wlan.0.debug: 0 => 0xc80000<assoc,auth,scan></screen> <para>Many useful statistics are maintained by the 802.11 layer and <command>wlanstats</command>, found - in <filename - class="directory">/usr/src/tools/tools/net80211</filename>, + in <filename>/usr/src/tools/tools/net80211</filename>, will dump this information. These statistics should display all errors identified by the 802.11 layer. However, some errors are identified in the device drivers @@ -2242,21 +2202,16 @@ freebsdap 00:11:95:c3:0d:ac 1 54M 22:1 100 EPS</screen> </sect2> </sect1> - <sect1 id="network-bluetooth"> - <sect1info> + <sect1 xml:id="network-bluetooth"> + <info><title>Bluetooth</title> <authorgroup> - <author> - <firstname>Pav</firstname> - <surname>Lucistnik</surname> - <contrib>Written by </contrib> - <affiliation> + <author><personname><firstname>Pav</firstname><surname>Lucistnik</surname></personname><contrib>Written by </contrib><affiliation> <address><email>pav@FreeBSD.org</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - </sect1info> + </info> - <title>Bluetooth</title> + <indexterm><primary>Bluetooth</primary></indexterm> <sect2> @@ -2794,7 +2749,7 @@ Bluetooth Profile Descriptor List: <para>The <acronym>OBEX</acronym> server and client are implemented as a third-party package, <application>obexapp</application>, which is available as - <filename role="package">comms/obexapp</filename> package or + <package>comms/obexapp</package> package or port.</para> <para>The <acronym>OBEX</acronym> client is used to push and/or @@ -2824,8 +2779,7 @@ Success, response: OK, Success (0x20)</screen> <para>In order to provide the <acronym>OPUSH</acronym> service, &man.sdpd.8; must be running and a root folder, where all incoming objects will be stored, must be created. The - default path to the root folder is <filename - class="directory">/var/spool/obex</filename>. Finally, + default path to the root folder is <filename>/var/spool/obex</filename>. Finally, start the <acronym>OBEX</acronym> server on a valid <acronym>RFCOMM</acronym> channel number. The <acronym>OBEX</acronym> server will automatically register @@ -2888,7 +2842,7 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen> <para>Use the third-party package <application>hcidump</application>, which is available as a - <filename role="package">comms/hcidump</filename> package or + <package>comms/hcidump</package> package or port. This utility is similar to &man.tcpdump.1; and can be used to display the contents of Bluetooth packets on the terminal and to dump the Bluetooth packets to a @@ -2897,17 +2851,13 @@ rfcomm_sppd[94692]: Starting on /dev/ttyp6...</screen> </sect2> </sect1> - <sect1 id="network-bridging"> - <sect1info> + <sect1 xml:id="network-bridging"> + <info><title>Bridging</title> <authorgroup> - <author> - <firstname>Andrew</firstname> - <surname>Thompson</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Andrew</firstname><surname>Thompson</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </sect1info> - <title>Bridging</title> + </info> + <sect2> <title>Introduction</title> @@ -3067,8 +3017,8 @@ bridge0: flags=8802<BROADCAST,SIMPLEX,MULTICAST> metric 0 mtu 1500 &prompt.root; <userinput>ifconfig fxp1 up</userinput></screen> <para>The bridge is now forwarding Ethernet frames between - <devicename>fxp0</devicename> and - <devicename>fxp1</devicename>. Add the following lines to + <filename>fxp0</filename> and + <filename>fxp1</filename>. Add the following lines to <filename>/etc/rc.conf</filename> so the bridge is created at startup:</para> @@ -3124,8 +3074,8 @@ ifconfig_fxp1="up"</programlisting> <para><acronym>STP</acronym> can be enabled on member interfaces using &man.ifconfig.8;. For a bridge with - <devicename>fxp0</devicename> and - <devicename>fxp1</devicename> as the current interfaces, + <filename>fxp0</filename> and + <filename>fxp1</filename> as the current interfaces, enable <acronym>STP</acronym> with:</para> <screen>&prompt.root; <userinput>ifconfig bridge0 stp fxp0 stp fxp1</userinput> @@ -3167,7 +3117,7 @@ bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1 <literal>00:01:02:4b:d4:50</literal> and has a path cost of <literal>400000</literal> from this bridge. The path to the root bridge is via <literal>port 4</literal> which is - <devicename>fxp0</devicename>.</para> + <filename>fxp0</filename>.</para> </sect2> <sect2> @@ -3203,7 +3153,7 @@ bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1 connected to one of the span ports of the bridge.</para> <para>To send a copy of all frames out the interface named - <devicename>fxp4</devicename>:</para> + <filename>fxp4</filename>:</para> <screen>&prompt.root; <userinput>ifconfig bridge0 span fxp4</userinput></screen> </sect3> @@ -3235,18 +3185,16 @@ bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1 combine the bridge with <acronym>VLAN</acronym>s to create a router where customer networks are isolated without wasting <acronym>IP</acronym> address space. Consider that - <hostid role="hostname">CustomerA</hostid> is on - <literal>vlan100</literal> and <hostid - role="hostname">CustomerB</hostid> is on + <systemitem class="fqdomainname">CustomerA</systemitem> is on + <literal>vlan100</literal> and <systemitem class="fqdomainname">CustomerB</systemitem> is on <literal>vlan101</literal>. The bridge has the address - <hostid role="ipaddr">192.168.0.1</hostid> and is also an + <systemitem class="ipaddress">192.168.0.1</systemitem> and is also an Internet router.</para> <screen>&prompt.root; <userinput>ifconfig bridge0 addm vlan100 sticky vlan100 addm vlan101 sticky vlan101</userinput> &prompt.root; <userinput>ifconfig bridge0 inet 192.168.0.1/24</userinput></screen> - <para>In this example, both clients see <hostid - role="ipaddr">192.168.0.1</hostid> as their default + <para>In this example, both clients see <systemitem class="ipaddress">192.168.0.1</systemitem> as their default gateway. Since the bridge cache is sticky, one host can not spoof the <acronym>MAC</acronym> address of the other customer in order to intercept their traffic.</para> @@ -3258,7 +3206,7 @@ bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1 <screen>&prompt.root; <userinput>ifconfig bridge0 private vlan100 private vlan101</userinput></screen> <para>The customers are completely isolated from each other - and the full <hostid role="netmask">/24</hostid> address + and the full <systemitem class="netmask">/24</systemitem> address range can be allocated without subnetting.</para> </sect3> @@ -3272,8 +3220,7 @@ bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1 is removed.</para> <para>The following example sets the maximum number of - Ethernet devices for <hostid - role="hostname">CustomerA</hostid> on + Ethernet devices for <systemitem class="fqdomainname">CustomerA</systemitem> on <literal>vlan100</literal> to 10:</para> <screen>&prompt.root; <userinput>ifconfig bridge0 ifmaxaddr vlan100 10</userinput></screen> @@ -3300,10 +3247,8 @@ bridge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1 information.</para> <para>The following examples use the - <application>Net-SNMP</application> software (<filename - role="package">net-mgmt/net-snmp</filename>) to query a - bridge from a client system. The <filename - role="package">net-mgmt/bsnmptools</filename> port can + <application>Net-SNMP</application> software (<package>net-mgmt/net-snmp</package>) to query a + bridge from a client system. The <package>net-mgmt/bsnmptools</package> port can also be used. From the <acronym>SNMP</acronym> client which is running <application>Net-SNMP</application>, add the following lines to @@ -3369,17 +3314,13 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen> </sect2> </sect1> - <sect1 id="network-aggregation"> - <sect1info> + <sect1 xml:id="network-aggregation"> + <info><title>Link Aggregation and Failover</title> <authorgroup> - <author> - <firstname>Andrew</firstname> - <surname>Thompson</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Andrew</firstname><surname>Thompson</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </sect1info> - <title>Link Aggregation and Failover</title> + </info> + <indexterm><primary>lagg</primary></indexterm> <indexterm><primary>failover</primary></indexterm> @@ -3489,7 +3430,7 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen> <sect2> <title>Examples</title> - <example id="networking-lacp-aggregation-cisco"> + <example xml:id="networking-lacp-aggregation-cisco"> <title><acronym>LACP</acronym> Aggregation with a &cisco; Switch</title> @@ -3509,12 +3450,12 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen> <replaceable>FastEthernet0/2</replaceable> interfaces to channel group <replaceable>1</replaceable>:</para> - <screen><userinput>interface <replaceable>FastEthernet0/1</replaceable> - channel-group <replaceable>1</replaceable> mode active + <screen><userinput>interface FastEthernet0/1 + channel-group 1 mode active channel-protocol lacp</userinput> ! -<userinput>interface <replaceable>FastEthernet0/2</replaceable> - channel-group <replaceable>1</replaceable> mode active +<userinput>interface FastEthernet0/2 + channel-group 1 mode active channel-protocol lacp</userinput></screen> <para>Create the &man.lagg.4; interface using @@ -3523,14 +3464,14 @@ BEGEMOT-BRIDGE-MIB::begemotBridgeDefaultBridgeIf.0 s bridge2</screen> with the <acronym>IP</acronym> address of <replaceable>10.0.0.3/24</replaceable>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput> -&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput> -&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create </userinput> -&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig fxp0 up</userinput> +&prompt.root; <userinput>ifconfig fxp1 up</userinput> +&prompt.root; <userinput>ifconfig lagg0 create </userinput> +&prompt.root; <userinput>ifconfig lagg0 up laggproto lacp laggport fxp0 laggport fxp1 10.0.0.3/24</userinput></screen> <para>View the interface status by running:</para> - <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig lagg0</userinput></screen> <para>Ports marked as <emphasis>ACTIVE</emphasis> are part of the active aggregation group that has been negotiated with @@ -3574,11 +3515,11 @@ Fa0/2 SA 32768 0005.5d71.8db8 29s 0x146 0x4 0x3D</screen <programlisting>ifconfig_<replaceable>fxp0</replaceable>="up" ifconfig_<replaceable>fxp1</replaceable>="up" -cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" -ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting> +cloned_interfaces="<literal>lagg0</literal>" +ifconfig_<literal>lagg0</literal>="laggproto lacp laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.3/24</replaceable>"</programlisting> </example> - <example id="networking-lagg-failover"> + <example xml:id="networking-lagg-failover"> <title>Failover Mode</title> <para>Failover mode can be used to switch over to a secondary @@ -3591,15 +3532,15 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto lacp lag address of <replaceable>10.0.0.15/24</replaceable>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>fxp0</replaceable> up</userinput> -&prompt.root; <userinput>ifconfig <replaceable>fxp1</replaceable> up</userinput> -&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput> -&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig fxp0 up</userinput> +&prompt.root; <userinput>ifconfig fxp1 up</userinput> +&prompt.root; <userinput>ifconfig lagg0 create</userinput> +&prompt.root; <userinput>ifconfig lagg0 up laggproto failover laggport fxp0 laggport fxp1 10.0.0.15/24</userinput></screen> <para>The interface should now look something like this:</para> - <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput> + <screen>&prompt.root; <userinput>ifconfig lagg0</userinput> lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=8<VLAN_MTU> ether 00:05:5d:71:8d:b8 @@ -3623,11 +3564,11 @@ lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 150 <programlisting>ifconfig_<replaceable>fxp0</replaceable>="up" ifconfig_<replaceable>fxp1</replaceable>="up" -cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" -ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>"</programlisting> +cloned_interfaces="<literal>lagg0</literal>" +ifconfig_<literal>lagg0</literal>="laggproto failover laggport <replaceable>fxp0</replaceable> laggport <replaceable>fxp1</replaceable> <replaceable>10.0.0.15/24</replaceable>"</programlisting> </example> - <example id="networking-lagg-wired-and-wireless"> + <example xml:id="networking-lagg-wired-and-wireless"> <title>Failover Mode Between Wired and Wireless Interfaces</title> @@ -3655,7 +3596,7 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover The first step is to determine the <acronym>MAC</acronym> address of the wired interface:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable></userinput> + <screen>&prompt.root; <userinput>ifconfig bge0</userinput> bge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=19b<RXCSUM,TXCSUM,VLAN_MTU,VLAN_HWTAGGING,VLAN_HWCSUM,TSO4> ether 00:21:70:da:ae:37 @@ -3671,25 +3612,25 @@ bge0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 <acronym>MAC</acronym> address of the underlying wireless interface:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>iwn0</replaceable> ether <replaceable>00:21:70:da:ae:37</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig iwn0 ether 00:21:70:da:ae:37</userinput></screen> <para>Bring the wireless interface up, but do not set an <acronym>IP</acronym> address:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>wlan0</replaceable> create wlandev <replaceable>iwn0</replaceable> ssid <replaceable>my_router</replaceable> up</userinput></screen> + <screen>&prompt.root; <userinput>ifconfig wlan0 create wlandev iwn0 ssid my_router up</userinput></screen> <para>Bring the <replaceable>bge0</replaceable> interface up. Create the &man.lagg.4; interface with <replaceable>bge0</replaceable> as master, and failover to <replaceable>wlan0</replaceable>:</para> - <screen>&prompt.root; <userinput>ifconfig <replaceable>bge0</replaceable> up</userinput> -&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> create</userinput> -&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal> up laggproto failover laggport <replaceable>bge0</replaceable> laggport <replaceable>wlan0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig bge0 up</userinput> +&prompt.root; <userinput>ifconfig lagg0 create</userinput> +&prompt.root; <userinput>ifconfig lagg0 up laggproto failover laggport bge0 laggport wlan0</userinput></screen> <para>The interface will now look something like this:</para> - <screen>&prompt.root; <userinput>ifconfig <literal>lagg<replaceable>0</replaceable></literal></userinput> + <screen>&prompt.root; <userinput>ifconfig lagg0</userinput> lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 1500 options=8<VLAN_MTU> ether 00:21:70:da:ae:37 @@ -3702,7 +3643,7 @@ lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 150 <para>Then, start the <acronym>DHCP</acronym> client to obtain an <acronym>IP</acronym> address:</para> - <screen>&prompt.root; <userinput>dhclient <literal>lagg<replaceable>0</replaceable></literal></userinput></screen> + <screen>&prompt.root; <userinput>dhclient lagg0</userinput></screen> <para>To retain this configuration across reboots, the following entries can be added to @@ -3712,30 +3653,22 @@ lagg0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> metric 0 mtu 150 ifconfig_iwn0="ether 00:21:70:da:ae:37" wlans_iwn0="wlan0" ifconfig_wlan0="WPA" -cloned_interfaces="<literal>lagg<replaceable>0</replaceable></literal>" -ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover laggport bge0 laggport wlan0 DHCP"</programlisting> +cloned_interfaces="<literal>lagg0</literal>" +ifconfig_<literal>lagg0</literal>="laggproto failover laggport bge0 laggport wlan0 DHCP"</programlisting> </example> </sect2> </sect1> - <sect1 id="network-diskless"> - <sect1info> + <sect1 xml:id="network-diskless"> + <info><title>Diskless Operation</title> <authorgroup> - <author> - <firstname>Jean-François</firstname> - <surname>Dockès</surname> - <contrib>Updated by </contrib> - </author> + <author><personname><firstname>Jean-François</firstname><surname>Dockès</surname></personname><contrib>Updated by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Alex</firstname> - <surname>Dupre</surname> - <contrib>Reorganized and enhanced by </contrib> - </author> + <author><personname><firstname>Alex</firstname><surname>Dupre</surname></personname><contrib>Reorganized and enhanced by </contrib></author> </authorgroup> - </sect1info> - <title>Diskless Operation</title> + </info> + <indexterm><primary>diskless workstation</primary></indexterm> <indexterm><primary>diskless operation</primary></indexterm> @@ -3759,8 +3692,7 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover file system on the server. The script will probably require a little customization.</para> - <para>Standard system startup files exist in <filename - class="directory">/etc</filename> to detect and support a + <para>Standard system startup files exist in <filename>/etc</filename> to detect and support a diskless system startup.</para> <para>Swapping, if needed, can be done either to an @@ -3776,8 +3708,8 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover <itemizedlist> <listitem> <para>The diskless workstations use a shared, read-only - <filename class="directory">/</filename> and - <filename class="directory">/usr</filename>.</para> + <filename>/</filename> and + <filename>/usr</filename>.</para> <para>The root file system is a copy of a standard &os; root, with some configuration files overridden by ones @@ -3899,15 +3831,14 @@ ifconfig_<literal>lagg<replaceable>0</replaceable></literal>="laggproto failover <acronym>DHCP</acronym> requests.</para> <para><application>ISC DHCP</application> is not part of - the base system. Install the <filename - role="package">net/isc-dhcp42-server</filename> port or + the base system. Install the <package>net/isc-dhcp42-server</package> port or package.</para> <para>Once <application>ISC DHCP</application> is installed, edit its configuration file, <filename>/usr/local/etc/dhcpd.conf</filename>. Here follows a commented example for <acronym>PXE</acronym> host - <hostid>corbieres</hostid>:</para> + <systemitem>corbieres</systemitem>:</para> <programlisting>default-lease-time 600; max-lease-time 7200; @@ -3918,16 +3849,16 @@ option domain-name-servers 192.168.4.1; option routers 192.168.4.1; subnet 192.168.4.0 netmask 255.255.255.0 { - use-host-decl-names on; <co id="co-dhcp-host-name"/> + use-host-decl-names on; <co xml:id="co-dhcp-host-name"/> option subnet-mask 255.255.255.0; option broadcast-address 192.168.4.255; host corbieres { hardware ethernet 00:02:b3:27:62:df; fixed-address corbieres.example.com; - next-server 192.168.4.4; <co id="co-dhcp-next-server"/> - filename "pxeboot"; <co id="co-dhcp-filename"/> - option root-path "192.168.4.4:/data/misc/diskless"; <co id="co-dhcp-root-path"/> + next-server 192.168.4.4; <co xml:id="co-dhcp-next-server"/> + filename "pxeboot"; <co xml:id="co-dhcp-filename"/> + option root-path "192.168.4.4:/data/misc/diskless"; <co xml:id="co-dhcp-root-path"/> } }</programlisting> @@ -3937,7 +3868,7 @@ subnet 192.168.4.0 netmask 255.255.255.0 { to send the value in the <literal>host</literal> declarations as the hostname for the diskless host. An alternate way would be to add an <literal>option - host-name <replaceable>corbieres</replaceable></literal> + host-name corbieres</literal> inside the <literal>host</literal> declarations.</para> </callout> @@ -3961,7 +3892,7 @@ subnet 192.168.4.0 netmask 255.255.255.0 { <filename>pxeboot</filename>, not the kernel. There are other interesting possibilities, like loading <filename>pxeboot</filename> from a &os; CD-ROM - <filename class="directory">/boot</filename> directory. + <filename>/boot</filename> directory. Since &man.pxeboot.8; can load a <filename>GENERIC</filename> kernel, it is possible to use <acronym>PXE</acronym> to boot from a remote @@ -4024,8 +3955,7 @@ subnet 192.168.4.0 netmask 255.255.255.0 { <procedure> <step> <para>Create a directory from which &man.tftpd.8; will - serve the files, such as <filename - class="directory">/tftpboot</filename>.</para> + serve the files, such as <filename>/tftpboot</filename>.</para> </step> <step> @@ -4054,7 +3984,7 @@ subnet 192.168.4.0 netmask 255.255.255.0 { </step> </procedure> - <para>Place <filename class="directory">tftpboot</filename> + <para>Place <filename>tftpboot</filename> anywhere on the server. Make sure that the location is set in both <filename>/etc/inetd.conf</filename> and <filename>/usr/local/etc/dhcpd.conf</filename>.</para> @@ -4184,7 +4114,7 @@ cd /usr/src/etc; make distribution</programlisting> file system and creating and enabling a swap file. To create a swap file:</para> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/path/to/swapfile</replaceable> bs=1k count=1 oseek=<replaceable>100000</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/path/to/swapfile bs=1k count=1 oseek=100000</userinput></screen> <para>To enable the swap file, add the following line to <filename>/etc/rc.conf</filename>:</para> @@ -4197,8 +4127,7 @@ cd /usr/src/etc; make distribution</programlisting> <title>Miscellaneous Issues</title> <sect4> - <title>Running with a Read-only <filename - class="directory">/usr</filename></title> + <title>Running with a Read-only <filename>/usr</filename></title> <indexterm> <primary>diskless operation</primary> @@ -4208,8 +4137,7 @@ cd /usr/src/etc; make distribution</programlisting> <para>If the diskless workstation is configured to run <application>&xorg;</application>, adjust the <application>XDM</application> configuration file as it - puts the error log on <filename - class="directory">/usr</filename> by default.</para> + puts the error log on <filename>/usr</filename> by default.</para> </sect4> <sect4> @@ -4221,8 +4149,7 @@ cd /usr/src/etc; make distribution</programlisting> &man.tar.1; or &man.cpio.1;.</para> <para>In this situation, there are sometimes problems with - the special files in <filename - class="directory">/dev</filename>, due to differing + the special files in <filename>/dev</filename>, due to differing major/minor integer sizes. A solution to this problem is to export a directory from the non-&os; server, mount this directory onto a &os; machine, and use &man.devfs.5; @@ -4233,21 +4160,16 @@ cd /usr/src/etc; make distribution</programlisting> </sect2> </sect1> - <sect1 id="network-pxe-nfs"> - <sect1info> + <sect1 xml:id="network-pxe-nfs"> + <info><title>PXE Booting with an <acronym>NFS</acronym> Root File + System</title> <authorgroup> - <author> - <firstname>Craig</firstname> - <surname>Rodrigues</surname> - <affiliation> + <author><personname><firstname>Craig</firstname><surname>Rodrigues</surname></personname><affiliation> <address>rodrigc@FreeBSD.org</address> - </affiliation> - <contrib>Written by </contrib> - </author> + </affiliation><contrib>Written by </contrib></author> </authorgroup> - </sect1info> - <title>PXE Booting with an <acronym>NFS</acronym> Root File - System</title> + </info> + <para>The &intel; Preboot eXecution Environment (<acronym>PXE</acronym>) allows booting the operating system @@ -4264,10 +4186,9 @@ cd /usr/src/etc; make distribution</programlisting> loader via <acronym>TFTP</acronym>. After the host computer receives this information, it downloads the boot loader via <acronym>TFTP</acronym> and then executes the boot loader. - This is documented in section 2.2.1 of the <ulink - url="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot + This is documented in section 2.2.1 of the <link xlink:href="http://download.intel.com/design/archives/wfm/downloads/pxespec.pdf">Preboot Execution Environment (<acronym>PXE</acronym>) - Specification</ulink>. In &os;, the boot loader retrieved + Specification</link>. In &os;, the boot loader retrieved during the <acronym>PXE</acronym> process is <filename>/boot/pxeboot</filename>. After <filename>/boot/pxeboot</filename> executes, the &os; kernel is @@ -4283,8 +4204,7 @@ cd /usr/src/etc; make distribution</programlisting> <step> <para>Choose a directory which will have a &os; installation which will be <acronym>NFS</acronym> - mountable. For example, a directory such as <filename - class="directory">/b/tftpboot/FreeBSD/install</filename> + mountable. For example, a directory such as <filename>/b/tftpboot/FreeBSD/install</filename> can be used.</para> <screen>&prompt.root; <userinput>export NFSROOTDIR=/b/tftpboot/FreeBSD/install</userinput> @@ -4293,8 +4213,7 @@ cd /usr/src/etc; make distribution</programlisting> <step> <para>Enable the <acronym>NFS</acronym> server by following - the instructions in <xref - linkend="network-configuring-nfs"/>.</para> + the instructions in <xref linkend="network-configuring-nfs"/>.</para> </step> <step> @@ -4330,8 +4249,7 @@ cd /usr/src/etc; make distribution</programlisting> </step> <step> - <para>Rebuild the &os; kernel and userland (<xref - linkend="makeworld"/>):</para> + <para>Rebuild the &os; kernel and userland (<xref linkend="makeworld"/>):</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make buildworld</userinput> @@ -4353,7 +4271,7 @@ cd /usr/src/etc; make distribution</programlisting> via <acronym>PXE</acronym>:</para> <screen>&prompt.root; <userinput>tftp localhost</userinput> -tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> +tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> Received 264951 bytes in 0.1 seconds</screen> </step> @@ -4415,8 +4333,7 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro <acronym>NFS</acronym> boot and runs <filename>/etc/rc.initdiskless</filename>. Read the comments in this script to understand what is going on. In this case, - <filename class="directory">/etc</filename> and <filename - class="directory">/var</filename> need to be memory backed + <filename>/etc</filename> and <filename>/var</filename> need to be memory backed file systems so that these directories are writable but the <acronym>NFS</acronym> root directory is read-only:</para> @@ -4425,15 +4342,13 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro &prompt.root; <userinput>tar -c -v -f conf/base/etc.cpio.gz --format cpio --gzip etc</userinput> &prompt.root; <userinput>tar -c -v -f conf/base/var.cpio.gz --format cpio --gzip var</userinput></screen> - <para>When the system boots, memory file systems for <filename - class="directory">/etc</filename> and <filename - class="directory">/var</filename> will be created and + <para>When the system boots, memory file systems for <filename>/etc</filename> and <filename>/var</filename> will be created and mounted and the contents of the <filename>cpio.gz</filename> files will be copied into them.</para> </sect2> - <sect2 id="network-pxe-setting-up-dhcp"> + <sect2 xml:id="network-pxe-setting-up-dhcp"> <title>Setting up the <acronym>DHCP</acronym> Server</title> <para><acronym>PXE</acronym> requires a <acronym>TFTP</acronym> @@ -4445,8 +4360,7 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro <procedure> <step> <para>Install the <acronym>DHCP</acronym> server by - following the instructions documented at <xref - linkend="network-dhcp-server"/>. Make sure that + following the instructions documented at <xref linkend="network-dhcp-server"/>. Make sure that <filename>/etc/rc.conf</filename> and <filename>/usr/local/etc/dhcpd.conf</filename> are correctly configured.</para> @@ -4501,12 +4415,10 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro <step> - <para>Use the <filename - role="package">net/wireshark</filename> package or + <para>Use the <package>net/wireshark</package> package or port to debug the network traffic involved during the <acronym>PXE</acronym> booting process, as illustrated - in the diagram below. In <xref - linkend="network-pxe-setting-up-dhcp"/>, an example + in the diagram below. In <xref linkend="network-pxe-setting-up-dhcp"/>, an example configuration is shown where the <acronym>DHCP</acronym>, <acronym>TFTP</acronym>, and <acronym>NFS</acronym> servers are on the same machine. However, these @@ -4516,14 +4428,14 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro <title><acronym>PXE</acronym> Booting Process with <acronym>NFS</acronym> Root Mount</title> - <mediaobjectco> + <mediaobject> <imageobjectco> <areaspec units="calspair"> - <area id="co-pxenfs1" coords="2873,8133 3313,7266"/> - <area id="co-pxenfs2" coords="3519,6333 3885,5500"/> - <area id="co-pxenfs3" coords="4780,5866 5102,5200"/> - <area id="co-pxenfs4" coords="4794,4333 5102,3600"/> - <area id="co-pxenfs5" coords="3108,2666 3519,1800"/> + <area xml:id="co-pxenfs1" coords="2873,8133 3313,7266"/> + <area xml:id="co-pxenfs2" coords="3519,6333 3885,5500"/> + <area xml:id="co-pxenfs3" coords="4780,5866 5102,5200"/> + <area xml:id="co-pxenfs4" coords="4794,4333 5102,3600"/> + <area xml:id="co-pxenfs5" coords="3108,2666 3519,1800"/> </areaspec> <imageobject> <imagedata fileref="advanced-networking/pxe-nfs"/> @@ -4561,7 +4473,7 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro </callout> </calloutlist> </imageobjectco> - </mediaobjectco> + </mediaobject> </figure> </step> @@ -4575,7 +4487,7 @@ myhost.example.com:/b/tftpboot/FreeBSD/install / nfs ro configuration:</para> <screen>&prompt.root; <userinput>tftp 192.168.0.1</userinput> -tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> +tftp> <userinput>get FreeBSD/install/boot/pxeboot</userinput> Received 264951 bytes in 0.1 seconds</screen> <para>The <literal>BUGS</literal> sections in &man.tftpd.8; @@ -4609,19 +4521,15 @@ Received 264951 bytes in 0.1 seconds</screen> </sect2> </sect1> - <sect1 id="network-natd"> - <sect1info> + <sect1 xml:id="network-natd"> + <info><title>Network Address Translation</title> <authorgroup> - <author> - <firstname>Chern</firstname> - <surname>Lee</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Chern</firstname><surname>Lee</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> - <title>Network Address Translation</title> + </info> + - <sect2 id="network-natoverview"> + <sect2 xml:id="network-natoverview"> <title>Overview</title> <indexterm> @@ -4648,7 +4556,7 @@ Received 264951 bytes in 0.1 seconds</screen> Sharing.</para> </sect2> - <sect2 id="network-natsetup"> + <sect2 xml:id="network-natsetup"> <title>Setup</title> <para>Due to the diminishing <acronym>IP</acronym> address @@ -4709,7 +4617,7 @@ Received 264951 bytes in 0.1 seconds</screen> machine.</para> </sect2> - <sect2 id="network-natdloaderconfiguration"> + <sect2 xml:id="network-natdloaderconfiguration"> <title>Boot Loader Configuration</title> <indexterm> @@ -4741,7 +4649,7 @@ ipdivert_load="YES"</programlisting> </note> </sect2> - <sect2 id="network-natdkernconfiguration"> + <sect2 xml:id="network-natdkernconfiguration"> <title>Kernel Configuration</title> <indexterm> @@ -4762,19 +4670,19 @@ options IPDIVERT</programlisting> options IPFIREWALL_VERBOSE</programlisting> </sect2> - <sect2 id="network-natdsystemconfiguration"> + <sect2 xml:id="network-natdsystemconfiguration"> <title>System Startup Configuration</title> <para>To enable firewall and <acronym>NAT</acronym> support at boot time, the following must be in <filename>/etc/rc.conf</filename>:</para> - <programlisting>gateway_enable="YES" <co id="co-natd-gateway-enable"/> -firewall_enable="YES" <co id="co-natd-firewall-enable"/> -firewall_type="OPEN" <co id="co-natd-firewall-type"/> + <programlisting>gateway_enable="YES" <co xml:id="co-natd-gateway-enable"/> +firewall_enable="YES" <co xml:id="co-natd-firewall-enable"/> +firewall_type="OPEN" <co xml:id="co-natd-firewall-type"/> natd_enable="YES" -natd_interface="<replaceable>fxp0</replaceable>" <co id="co-natd-natd-interface"/> -natd_flags="" <co id="co-natd-natd-flags"/></programlisting> +natd_interface="<replaceable>fxp0</replaceable>" <co xml:id="co-natd-natd-interface"/> +natd_flags="" <co xml:id="co-natd-natd-flags"/></programlisting> <calloutlist> <callout arearefs="co-natd-gateway-enable"> @@ -4835,28 +4743,23 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <para>Each machine and interface behind the <acronym>LAN</acronym> should be assigned <acronym>IP</acronym> addresses in the private network space, - as defined by <ulink - url="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC - 1918</ulink>, and have a default gateway of the + as defined by <link xlink:href="ftp://ftp.isi.edu/in-notes/rfc1918.txt">RFC + 1918</link>, and have a default gateway of the &man.natd.8; machine's internal <acronym>IP</acronym> address.</para> - <para>For example, client <hostid>A</hostid> and - <hostid>B</hostid> behind the <acronym>LAN</acronym> have - <acronym>IP</acronym> addresses of <hostid - role="ipaddr">192.168.0.2</hostid> and <hostid - role="ipaddr">192.168.0.3</hostid>, while the &man.natd.8; + <para>For example, client <systemitem>A</systemitem> and + <systemitem>B</systemitem> behind the <acronym>LAN</acronym> have + <acronym>IP</acronym> addresses of <systemitem class="ipaddress">192.168.0.2</systemitem> and <systemitem class="ipaddress">192.168.0.3</systemitem>, while the &man.natd.8; machine's <acronym>LAN</acronym> interface has an - <acronym>IP</acronym> address of <hostid - role="ipaddr">192.168.0.1</hostid>. The default gateway - of clients <hostid>A</hostid> and <hostid>B</hostid> must be - set to that of the &man.natd.8; machine, <hostid - role="ipaddr">192.168.0.1</hostid>. The &man.natd.8; + <acronym>IP</acronym> address of <systemitem class="ipaddress">192.168.0.1</systemitem>. The default gateway + of clients <systemitem>A</systemitem> and <systemitem>B</systemitem> must be + set to that of the &man.natd.8; machine, <systemitem class="ipaddress">192.168.0.1</systemitem>. The &man.natd.8; machine's external Internet interface does not require any special modification for &man.natd.8; to work.</para> </sect2> - <sect2 id="network-natdport-redirection"> + <sect2 xml:id="network-natdport-redirection"> <title>Port Redirection</title> <para>The drawback with &man.natd.8; is that the @@ -4870,8 +4773,8 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> client.</para> <para>For example, an <acronym>IRC</acronym> server runs on - client <hostid>A</hostid> and a web server runs on client - <hostid>B</hostid>. For this to work properly, connections + client <systemitem>A</systemitem> and a web server runs on client + <systemitem>B</systemitem>. For this to work properly, connections received on ports 6667 (<acronym>IRC</acronym>) and 80 (<acronym>HTTP</acronym>) must be redirected to the respective machines.</para> @@ -4895,7 +4798,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <option>-redirect_port</option>. For example, <replaceable>tcp 192.168.0.2:2000-3000 2000-3000</replaceable> would redirect all connections received on ports 2000 to 3000 - to ports 2000 to 3000 on client <hostid>A</hostid>.</para> + to ports 2000 to 3000 on client <systemitem>A</systemitem>.</para> <para>These options can be used when directly running &man.natd.8;, placed within the @@ -4907,7 +4810,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> &man.natd.8;</para> </sect2> - <sect2 id="network-natdaddress-redirection"> + <sect2 xml:id="network-natdaddress-redirection"> <title>Address Redirection</title> <indexterm><primary>address redirection</primary></indexterm> @@ -4921,16 +4824,12 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> incoming on that particular <acronym>IP</acronym> address back to the specific <acronym>LAN</acronym> client. This is also known as static <acronym>NAT</acronym>. For example, - if <acronym>IP</acronym> addresses <hostid - role="ipaddr">128.1.1.1</hostid>, <hostid - role="ipaddr">128.1.1.2</hostid>, and <hostid - role="ipaddr">128.1.1.3</hostid> are available, <hostid - role="ipaddr">128.1.1.1</hostid> can be used as the + if <acronym>IP</acronym> addresses <systemitem class="ipaddress">128.1.1.1</systemitem>, <systemitem class="ipaddress">128.1.1.2</systemitem>, and <systemitem class="ipaddress">128.1.1.3</systemitem> are available, <systemitem class="ipaddress">128.1.1.1</systemitem> can be used as the &man.natd.8; machine's external <acronym>IP</acronym> - address, while <hostid role="ipaddr">128.1.1.2</hostid> and - <hostid role="ipaddr">128.1.1.3</hostid> are forwarded back - to <acronym>LAN</acronym> clients <hostid>A</hostid> and - <hostid>B</hostid>.</para> + address, while <systemitem class="ipaddress">128.1.1.2</systemitem> and + <systemitem class="ipaddress">128.1.1.3</systemitem> are forwarded back + to <acronym>LAN</acronym> clients <systemitem>A</systemitem> and + <systemitem>B</systemitem>.</para> <para>The <option>-redirect_address</option> syntax is as follows:</para> @@ -4976,39 +4875,26 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </sect2> </sect1> - <sect1 id="network-ipv6"> - <sect1info> + <sect1 xml:id="network-ipv6"> + <info><title><acronym>IPv6</acronym></title> <authorgroup> - <author> - <firstname>Aaron</firstname> - <surname>Kaplan</surname> - <contrib>Originally Written by </contrib> - </author> + <author><personname><firstname>Aaron</firstname><surname>Kaplan</surname></personname><contrib>Originally Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Restructured and Added by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Restructured and Added by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Brad</firstname> - <surname>Davis</surname> - <contrib>Extended by </contrib> - </author> + <author><personname><firstname>Brad</firstname><surname>Davis</surname></personname><contrib>Extended by </contrib></author> </authorgroup> - </sect1info> + </info> - <title><acronym>IPv6</acronym></title> + <para><acronym>IPv6</acronym>, also known as <acronym>IPng</acronym> <quote><acronym>IP</acronym> next generation</quote>, is the new version of the well known <acronym>IP</acronym> protocol, also known as - <acronym>IPv4</acronym>. &os; includes the <ulink - url="http://www.kame.net/">KAME</ulink> + <acronym>IPv4</acronym>. &os; includes the <link xlink:href="http://www.kame.net/">KAME</link> <acronym>IPv6</acronym> reference implementation. &os; comes with everything needed to use <acronym>IPv6</acronym>. This section focuses on getting <acronym>IPv6</acronym> configured @@ -5023,9 +4909,9 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <listitem> <para>Running out of addresses. For years the use of RFC1918 private address space - (<hostid role="ipaddr">10.0.0.0/8</hostid>, - <hostid role="ipaddr">172.16.0.0/12</hostid>, and - <hostid role="ipaddr">192.168.0.0/16</hostid>) and NAT + (<systemitem class="ipaddress">10.0.0.0/8</systemitem>, + <systemitem class="ipaddress">172.16.0.0/12</systemitem>, and + <systemitem class="ipaddress">192.168.0.0/16</systemitem>) and NAT has slowed down the exhaustion. Even though, there are very few remaining IPv4 addresses. The Internet Assigned Numbers Authority (<acronym>IANA</acronym>) has @@ -5067,8 +4953,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <itemizedlist> <listitem> - <para>Address autoconfiguration (<ulink - url="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</ulink>).</para> + <para>Address autoconfiguration (<link xlink:href="http://www.ietf.org/rfc/rfc2462.txt">RFC2462</link>).</para> </listitem> <listitem> @@ -5104,7 +4989,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <itemizedlist> <listitem> - <para><ulink url="http://www.kame.net">KAME.net</ulink></para> + <para><link xlink:href="http://www.kame.net">KAME.net</link></para> </listitem> </itemizedlist> @@ -5130,7 +5015,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <note> <para>The <acronym>IPv4</acronym> broadcast address, usually - <hostid role="ipaddr">xxx.xxx.xxx.255</hostid>, is expressed + <systemitem class="ipaddress">xxx.xxx.xxx.255</systemitem>, is expressed by multicast addresses in <acronym>IPv6</acronym>.</para> </note> @@ -5149,26 +5034,23 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <tbody> <row> - <entry><hostid role="ip6addr">::</hostid></entry> + <entry><systemitem>::</systemitem></entry> <entry>128 bits</entry> <entry>unspecified</entry> - <entry>Equivalent to <hostid - role="ipaddr">0.0.0.0</hostid> in + <entry>Equivalent to <systemitem class="ipaddress">0.0.0.0</systemitem> in <acronym>IPv4</acronym>.</entry> </row> <row> - <entry><hostid role="ip6addr">::1</hostid></entry> + <entry><systemitem>::1</systemitem></entry> <entry>128 bits</entry> <entry>loopback address</entry> - <entry>Equivalent to <hostid - role="ipaddr">127.0.0.1</hostid> in + <entry>Equivalent to <systemitem class="ipaddress">127.0.0.1</systemitem> in <acronym>IPv4</acronym>.</entry> </row> <row> - <entry><hostid - role="ip6addr">::00:xx:xx:xx:xx</hostid></entry> + <entry><systemitem>::00:xx:xx:xx:xx</systemitem></entry> <entry>96 bits</entry> <entry>embedded <acronym>IPv4</acronym></entry> <entry>The lower 32 bits are the compatible @@ -5176,8 +5058,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </row> <row> - <entry><hostid - role="ip6addr">::ff:xx:xx:xx:xx</hostid></entry> + <entry><systemitem>::ff:xx:xx:xx:xx</systemitem></entry> <entry>96 bits</entry> <entry><acronym>IPv4</acronym> mapped <acronym>IPv6</acronym> address</entry> @@ -5187,8 +5068,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </row> <row> - <entry><hostid role="ip6addr">fe80::</hostid> - <hostid - role="ip6addr">feb::</hostid></entry> + <entry><systemitem>fe80::</systemitem> - <systemitem>feb::</systemitem></entry> <entry>10 bits</entry> <entry>link-local</entry> <entry>Equivalent to the loopback address in @@ -5196,22 +5076,21 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </row> <row> - <entry><hostid role="ip6addr">fec0::</hostid> - <hostid - role="ip6addr">fef::</hostid></entry> + <entry><systemitem>fec0::</systemitem> - <systemitem>fef::</systemitem></entry> <entry>10 bits</entry> <entry>site-local</entry> <entry> </entry> </row> <row> - <entry><hostid role="ip6addr">ff::</hostid></entry> + <entry><systemitem>ff::</systemitem></entry> <entry>8 bits</entry> <entry>multicast</entry> <entry> </entry> </row> <row> - <entry><hostid role="ip6addr">001</hostid> (base + <entry><systemitem>001</systemitem> (base 2)</entry> <entry>3 bits</entry> <entry>global unicast</entry> @@ -5228,27 +5107,22 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <title>Reading <acronym>IPv6</acronym> Addresses</title> <para>The canonical form is represented as: - <hostid role="ip6addr">x:x:x:x:x:x:x:x</hostid>, with each + <systemitem>x:x:x:x:x:x:x:x</systemitem>, with each <quote>x</quote> being a 16 bit hex value. For example: - <hostid - role="ip6addr">FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</hostid>.</para> + <systemitem>FEBC:A574:382B:23C1:AA49:4592:4EFE:9982</systemitem>.</para> <para>Often an address will have long substrings of all zeros. One such substring per address can be abbreviated by <quote>::</quote>. Also, up to three leading <quote>0</quote>s per hex quad can be omitted. For example, - <hostid role="ip6addr">fe80::1</hostid> corresponds to the - canonical form <hostid - role="ip6addr">fe80:0000:0000:0000:0000:0000:0000:0001</hostid>.</para> + <systemitem>fe80::1</systemitem> corresponds to the + canonical form <systemitem>fe80:0000:0000:0000:0000:0000:0000:0001</systemitem>.</para> <para>A third form is to write the last 32 bit part in the well known (decimal) <acronym>IPv4</acronym> style with dots - (<quote>.</quote>) as separators. For example, <hostid - role="ip6addr">2002::10.0.0.1</hostid> corresponds to the - hexadecimal canonical representation <hostid - role="ip6addr">2002:0000:0000:0000:0000:0000:0a00:0001</hostid>, - which in turn is equivalent to <hostid - role="ip6addr">2002::a00:1</hostid>.</para> + (<quote>.</quote>) as separators. For example, <systemitem>2002::10.0.0.1</systemitem> corresponds to the + hexadecimal canonical representation <systemitem>2002:0000:0000:0000:0000:0000:0a00:0001</systemitem>, + which in turn is equivalent to <systemitem>2002::a00:1</systemitem>.</para> <para>Here is a sample entry from &man.ifconfig.8;:</para> @@ -5261,15 +5135,13 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> media: Ethernet autoselect (100baseTX ) status: active</programlisting> - <para><hostid - role="ip6addr">fe80::200:21ff:fe03:8e1%rl0</hostid> is an + <para><systemitem>fe80::200:21ff:fe03:8e1%rl0</systemitem> is an auto configured link-local address. It is generated from the <acronym>MAC</acronym> address as part of the auto configuration.</para> <para>For further information on the structure of - <acronym>IPv6</acronym> addresses, see <ulink - url="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</ulink>.</para> + <acronym>IPv6</acronym> addresses, see <link xlink:href="http://www.ietf.org/rfc/rfc3513.txt">RFC3513</link>.</para> </sect2> <sect2> @@ -5285,24 +5157,23 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </listitem> <listitem> - <para><ulink url="http://www.sixxs.net">SixXS</ulink> offers + <para><link xlink:href="http://www.sixxs.net">SixXS</link> offers tunnels with end-points all around the globe.</para> </listitem> <listitem> - <para><ulink url="http://www.tunnelbroker.net">Hurricane - Electric</ulink> offers tunnels with end-points all around + <para><link xlink:href="http://www.tunnelbroker.net">Hurricane + Electric</link> offers tunnels with end-points all around the globe.</para> </listitem> <listitem> - <para>Tunnel via 6-to-4 as described in <ulink - url="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</ulink>.</para> + <para>Tunnel via 6-to-4 as described in <link xlink:href="http://www.ietf.org/rfc/rfc3068.txt">RFC3068</link>.</para> </listitem> <listitem> <para>Use the - <filename role="package">net/freenet6</filename> port + <package>net/freenet6</package> port for a dial-up connection.</para> </listitem> </itemizedlist> @@ -5319,7 +5190,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <para>To automatically configure a machine on a <acronym>LAN</acronym> which acts as a client, not a router, two items are required. First to enable the - <devicename>em0</devicename> to receive the router + <filename>em0</filename> to receive the router solicitation messages, add this line to <filename>rc.conf</filename>:</para> @@ -5341,9 +5212,8 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> Configuration</title> <para>To statically assign the <acronym>IPv6</acronym> - address, <hostid - role="ip6addr">2001:db8:4672:6565:2026:5043:2d42:5344</hostid>, - to <devicename>fxp0</devicename>, add the following for + address, <systemitem>2001:db8:4672:6565:2026:5043:2d42:5344</systemitem>, + to <filename>fxp0</filename>, add the following for &os; 9.<replaceable>x</replaceable>:</para> <programlisting>ifconfig_<replaceable>fxp0</replaceable>_ipv6="inet6 2001:db8:4672:6565:2026:5043:2d42:5344 prefixlen 64"</programlisting> @@ -5359,8 +5229,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <programlisting>ipv6_ifconfig_<replaceable>fxp0</replaceable>="2001:db8:4672:6565:2026:5043:2d42:5344"</programlisting> - <para>To assign a default router of <hostid - role="ip6addr">2001:db8:4672:6565::1</hostid>, add the + <para>To assign a default router of <systemitem>2001:db8:4672:6565::1</systemitem>, add the following to <filename>/etc/rc.conf</filename>:</para> <programlisting>ipv6_defaultrouter="2001:db8:4672:6565::1"</programlisting> @@ -5377,7 +5246,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <para>The first entry lists the generic tunneling interfaces to be configured. This example configures one interface, - <devicename>gif<replaceable>0</replaceable></devicename>:</para> + <filename>gif0</filename>:</para> <programlisting>gif_interfaces="gif<replaceable>0</replaceable>"</programlisting> @@ -5432,7 +5301,7 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <para>It is important to specify the interface on which to do <acronym>IPv6</acronym> router solicitation. For example, to tell &man.rtadvd.8; to use - <devicename>fxp0</devicename>:</para> + <filename>fxp0</filename>:</para> <programlisting>rtadvd_interfaces="fxp0"</programlisting> @@ -5443,12 +5312,11 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <programlisting>fxp0:\ :addrs#1:addr="2001:471:1f11:246::":prefixlen#64:tc=ether:</programlisting> - <para>Replace <devicename>fxp0</devicename> with the interface - to be used and <hostid - role="ip6addr">2001:471:1f11:246::</hostid> with the + <para>Replace <filename>fxp0</filename> with the interface + to be used and <systemitem>2001:471:1f11:246::</systemitem> with the prefix of the allocation.</para> - <para>For a dedicated <hostid role="netmask">/64</hostid> + <para>For a dedicated <systemitem class="netmask">/64</systemitem> subnet, nothing else needs to be changed. Otherwise, change the <literal>prefixlen#</literal> to the correct value.</para> </sect2> @@ -5500,18 +5368,14 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> </sect2> </sect1> - <sect1 id="network-atm"> - <sect1info> + <sect1 xml:id="network-atm"> + <info><title>Asynchronous Transfer Mode (<acronym>ATM</acronym>)</title> <authorgroup> - <author> - <firstname>Harti</firstname> - <surname>Brandt</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Harti</firstname><surname>Brandt</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Asynchronous Transfer Mode (<acronym>ATM</acronym>)</title> + <sect2> <title>Configuring Classical <acronym>IP</acronym> over @@ -5535,13 +5399,10 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <acronym>PVC</acronym>. While this is simple to configure, it becomes impractical for a large number of machines. The following example supposes four machines in - the network, each connected to the <acronym - role="Asynchronous Transfer Mode">ATM</acronym> network - with an <acronym - role="Asynchronous Transfer Mode">ATM</acronym> adapter + the network, each connected to the <acronym role="Asynchronous Transfer Mode">ATM</acronym> network + with an <acronym role="Asynchronous Transfer Mode">ATM</acronym> adapter card. The first step is the planning of the - <acronym>IP</acronym> addresses and the <acronym - role="Asynchronous Transfer Mode">ATM</acronym> + <acronym>IP</acronym> addresses and the <acronym role="Asynchronous Transfer Mode">ATM</acronym> connections between the machines. This example uses the following:</para> @@ -5558,27 +5419,23 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <tbody> <row> - <entry><hostid>hostA</hostid></entry> - <entry><hostid - role="ipaddr">192.168.173.1</hostid></entry> + <entry><systemitem>hostA</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.1</systemitem></entry> </row> <row> - <entry><hostid>hostB</hostid></entry> - <entry><hostid - role="ipaddr">192.168.173.2</hostid></entry> + <entry><systemitem>hostB</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.2</systemitem></entry> </row> <row> - <entry><hostid>hostC</hostid></entry> - <entry><hostid - role="ipaddr">192.168.173.3</hostid></entry> + <entry><systemitem>hostC</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.3</systemitem></entry> </row> <row> - <entry><hostid>hostD</hostid></entry> - <entry><hostid - role="ipaddr">192.168.173.4</hostid></entry> + <entry><systemitem>hostD</systemitem></entry> + <entry><systemitem class="ipaddress">192.168.173.4</systemitem></entry> </row> </tbody> </tgroup> @@ -5600,38 +5457,38 @@ redirect_port tcp 192.168.0.3:80 80</programlisting> <tbody> <row> - <entry><hostid>hostA</hostid> - - <hostid>hostB</hostid></entry> + <entry><systemitem>hostA</systemitem> - + <systemitem>hostB</systemitem></entry> <entry>0.100</entry> </row> <row> - <entry><hostid>hostA</hostid> - - <hostid>hostC</hostid></entry> + <entry><systemitem>hostA</systemitem> - + <systemitem>hostC</systemitem></entry> <entry>0.101</entry> </row> <row> - <entry><hostid>hostA</hostid> - - <hostid>hostD</hostid></entry> + <entry><systemitem>hostA</systemitem> - + <systemitem>hostD</systemitem></entry> <entry>0.102</entry> </row> <row> - <entry><hostid>hostB</hostid> - - <hostid>hostC</hostid></entry> + <entry><systemitem>hostB</systemitem> - + <systemitem>hostC</systemitem></entry> <entry>0.103</entry> </row> <row> - <entry><hostid>hostB</hostid> - - <hostid>hostD</hostid></entry> + <entry><systemitem>hostB</systemitem> - + <systemitem>hostD</systemitem></entry> <entry>0.104</entry> </row> <row> - <entry><hostid>hostC</hostid> - - <hostid>hostD</hostid></entry> + <entry><systemitem>hostC</systemitem> - + <systemitem>hostD</systemitem></entry> <entry>0.105</entry> </row> </tbody> @@ -5651,9 +5508,9 @@ hostC&prompt.root; <userinput>ifconfig hatm0 192.168.173.3 up</userinput> hostD&prompt.root; <userinput>ifconfig hatm0 192.168.173.4 up</userinput></screen> <para>This example assumes that the <acronym>ATM</acronym> - interface is <devicename>hatm0</devicename> on all hosts. + interface is <filename>hatm0</filename> on all hosts. Next, the <acronym>PVC</acronym>s need to be configured on - <hostid>hostA</hostid>. This should already be configured + <systemitem>hostA</systemitem>. This should already be configured on the <acronym>ATM</acronym> switch; consult the manual for the switch on how to do this.</para> @@ -5685,7 +5542,7 @@ hostD&prompt.root; <userinput>atmconfig natm add 192.168.173.3 hatm0 0 105 llc/s <para>The same configuration can also be done via <filename>/etc/rc.conf</filename>. These lines configure - <hostid>hostA</hostid>:</para> + <systemitem>hostA</systemitem>:</para> <programlisting>network_interfaces="lo0 hatm0" ifconfig_hatm0="inet 192.168.173.1 up" @@ -5702,19 +5559,15 @@ route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting> </sect2> </sect1> - <sect1 id="carp"> - <sect1info> + <sect1 xml:id="carp"> + <info><title>Common Address Redundancy Protocol + (<acronym>CARP</acronym>)</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Common Address Redundancy Protocol - (<acronym>CARP</acronym>)</title> + <indexterm> <primary><acronym>CARP</acronym></primary> @@ -5731,8 +5584,7 @@ route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting> example provided here.</para> <para>To enable support for <acronym>CARP</acronym>, the &os; - kernel can be rebuilt as described in <xref - linkend="kernelconfig"/> with the following option:</para> + kernel can be rebuilt as described in <xref linkend="kernelconfig"/> with the following option:</para> <programlisting>device carp</programlisting> @@ -5832,19 +5684,19 @@ route_hostD="192.168.173.4 hatm0 0 102 llc/snap ubr"</programlisting> <para>The two machines should be configured identically other than their hostnames and <acronym>VHID</acronym>s. This example calls these machines - <hostid>hosta.example.org</hostid> and - <hostid>hostb.example.org</hostid> respectively. First, the + <systemitem>hosta.example.org</systemitem> and + <systemitem>hostb.example.org</systemitem> respectively. First, the required lines for a <acronym>CARP</acronym> configuration have to be added to <filename>/etc/rc.conf</filename>. Here are the lines for - <hostid>hosta.example.org</hostid>:</para> + <systemitem>hosta.example.org</systemitem>:</para> <programlisting>hostname="hosta.example.org" ifconfig_fxp0="inet 192.168.1.3 netmask 255.255.255.0" cloned_interfaces="carp0" ifconfig_carp0="vhid 1 pass testpass 192.168.1.50/24"</programlisting> - <para>On <hostid>hostb.example.org</hostid>, use the following + <para>On <systemitem>hostb.example.org</systemitem>, use the following lines:</para> <programlisting>hostname="hostb.example.org" @@ -5855,16 +5707,16 @@ ifconfig_carp0="vhid 2 pass testpass 192.168.1.51/24"</programlisting> <note> <para>It is very important that the passwords, specified by the <option>pass</option> option to &man.ifconfig.8;, are - identical. The <devicename>carp</devicename> devices will + identical. The <filename>carp</filename> devices will only listen to and accept advertisements from machines with the correct password. The <acronym>VHID</acronym> must also be unique for each machine.</para> </note> - <para>The third machine, <hostid>provider.example.org</hostid>, + <para>The third machine, <systemitem>provider.example.org</systemitem>, should be prepared so that it may handle failover from either host. This machine will require two - <devicename>carp</devicename> devices, one to handle each + <filename>carp</filename> devices, one to handle each host. The appropriate <filename>/etc/rc.conf</filename> configuration lines will be similar to the following:</para> @@ -5874,24 +5726,24 @@ cloned_interfaces="carp0 carp1" ifconfig_carp0="vhid 1 advskew 100 pass testpass 192.168.1.50/24" ifconfig_carp1="vhid 2 advskew 100 pass testpass 192.168.1.51/24"</programlisting> - <para>Having the two <devicename>carp</devicename> devices will - allow <hostid>provider.example.org</hostid> to notice and pick + <para>Having the two <filename>carp</filename> devices will + allow <systemitem>provider.example.org</systemitem> to notice and pick up the <acronym>IP</acronym> address of either machine, should it stop responding.</para> <note> <para>The default &os; kernel <emphasis>may</emphasis> have preemption enabled. If so, - <hostid>provider.example.org</hostid> may not relinquish the + <systemitem>provider.example.org</systemitem> may not relinquish the <acronym>IP</acronym> address back to the original content server. In this case, an administrator may have to manually force the <acronym>IP</acronym> back to the master. The following command should be issued on - <hostid>provider.example.org</hostid>:</para> + <systemitem>provider.example.org</systemitem>:</para> <screen>&prompt.root; <userinput>ifconfig carp0 down && ifconfig carp0 up</userinput></screen> - <para>This should be done on the <devicename>carp</devicename> + <para>This should be done on the <filename>carp</filename> interface which corresponds to the correct host.</para> </note> diff --git a/en_US.ISO8859-1/books/handbook/audit/chapter.xml b/en_US.ISO8859-1/books/handbook/audit/chapter.xml index e666e6a91e..ad51785f2a 100644 --- a/en_US.ISO8859-1/books/handbook/audit/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/audit/chapter.xml @@ -3,32 +3,23 @@ The FreeBSD Documentation Project $FreeBSD$ --> - <!-- Need more documentation on praudit, auditreduce, etc. Plus more info on the triggers from the kernel (log rotation, out of space, etc). And the /dev/audit special file if we choose to support that. Could use some coverage of integrating MAC with Event auditing and perhaps discussion on how some companies or organizations handle auditing and auditing requirements. --> - -<chapter id="audit"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="audit"> + <info><title>Security Event Auditing</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> - <author> - <firstname>Robert</firstname> - <surname>Watson</surname> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> + <author><personname><firstname>Robert</firstname><surname>Watson</surname></personname></author> </authorgroup> - </chapterinfo> + </info> - <title>Security Event Auditing</title> + - <sect1 id="audit-synopsis"> + <sect1 xml:id="audit-synopsis"> <title>Synopsis</title> <indexterm><primary>AUDIT</primary></indexterm> @@ -104,13 +95,13 @@ requirements. --> Administrators should take into account disk space requirements associated with high volume audit configurations. For example, it may be desirable to dedicate a file system to - the <filename class="directory">/var/audit</filename> tree + the <filename>/var/audit</filename> tree so that other file systems are not affected if the audit file system becomes full.</para> </warning> </sect1> - <sect1 id="audit-inline-glossary"> + <sect1 xml:id="audit-inline-glossary"> <title>Key Terms in This Chapter</title> <para>Before reading this chapter, a few key audit-related terms @@ -187,7 +178,7 @@ requirements. --> </itemizedlist> </sect1> - <sect1 id="audit-install"> + <sect1 xml:id="audit-install"> <title>Installing Audit Support</title> <para>User space support for Event Auditing is installed as part @@ -199,8 +190,7 @@ requirements. --> <programlisting>options AUDIT</programlisting> <para>Rebuild and reinstall - the kernel via the normal process explained in <xref - linkend="kernelconfig"/>.</para> + the kernel via the normal process explained in <xref linkend="kernelconfig"/>.</para> <para>Once an audit-enabled kernel is built, installed, and the system has been rebooted, enable the audit daemon by adding the @@ -214,11 +204,11 @@ requirements. --> <programlisting>service auditd start</programlisting> </sect1> - <sect1 id="audit-config"> + <sect1 xml:id="audit-config"> <title>Audit Configuration</title> <para>All configuration files for security audit are found in - <filename class="directory">/etc/security</filename>. The + <filename>/etc/security</filename>. The following files must be present before the audit daemon is started:</para> @@ -456,7 +446,7 @@ requirements. --> The first controls system-wide audit properties and policies; the second may be used to fine-tune auditing by user.</para> - <sect3 id="audit-auditcontrol"> + <sect3 xml:id="audit-auditcontrol"> <title>The <filename>audit_control</filename> File</title> <para>A number of defaults for the audit subsystem are @@ -511,7 +501,7 @@ filesz:0</programlisting> generated.</para> </sect3> - <sect3 id="audit-audituser"> + <sect3 xml:id="audit-audituser"> <title>The <filename>audit_user</filename> File</title> <para>The administrator can specify further audit requirements @@ -525,13 +515,13 @@ filesz:0</programlisting> <para>The following example <filename>audit_user</filename> audits login/logout events and successful command - execution for <username>root</username>, and audits + execution for <systemitem class="username">root</systemitem>, and audits file creation and successful command execution for - <username>www</username>. If used with the above example + <systemitem class="username">www</systemitem>. If used with the above example <filename>audit_control</filename>, the - <literal>lo</literal> entry for <username>root</username> is + <literal>lo</literal> entry for <systemitem class="username">root</systemitem> is redundant, and login/logout events will also be audited for - <username>www</username>.</para> + <systemitem class="username">www</systemitem>.</para> <programlisting>root:lo,+ex:no www:fc,+ex:no</programlisting> @@ -539,7 +529,7 @@ www:fc,+ex:no</programlisting> </sect2> </sect1> - <sect1 id="audit-administration"> + <sect1 xml:id="audit-administration"> <title>Administering the Audit Subsystem</title> <sect2> @@ -561,7 +551,7 @@ www:fc,+ex:no</programlisting> <screen>&prompt.root; <userinput>praudit /var/audit/AUDITFILE</userinput></screen> <para>Where - <filename><replaceable>AUDITFILE</replaceable></filename> is + <filename>AUDITFILE</filename> is the audit log to dump.</para> <para>Audit trails consist of a series of audit records made up @@ -594,8 +584,8 @@ trailer,133</programlisting> user ID and group ID, real user ID and group ID, process ID, session ID, port ID, and login address. Notice that the audit user ID and real user ID differ: the user - <username>robert</username> has switched to the - <username>root</username> account before running this command, + <systemitem class="username">robert</systemitem> has switched to the + <systemitem class="username">root</systemitem> account before running this command, but it is audited using the original authenticated user. Finally, the <literal>return</literal> token indicates the successful execution, and the <literal>trailer</literal> @@ -616,19 +606,18 @@ trailer,133</programlisting> <screen>&prompt.root; <userinput>auditreduce -u trhodes /var/audit/AUDITFILE | praudit</userinput></screen> <para>This will select all audit records produced for - <username>trhodes</username> stored in - <filename><replaceable>AUDITFILE</replaceable></filename>.</para> + <systemitem class="username">trhodes</systemitem> stored in + <filename>AUDITFILE</filename>.</para> </sect2> <sect2> <title>Delegating Audit Review Rights</title> - <para>Members of the <groupname>audit</groupname> group are - given permission to read audit trails in <filename - class="directory">/var/audit</filename>; by default, this - group is empty, so only the <username>root</username> user + <para>Members of the <systemitem class="groupname">audit</systemitem> group are + given permission to read audit trails in <filename>/var/audit</filename>; by default, this + group is empty, so only the <systemitem class="username">root</systemitem> user may read audit trails. Users may be added to the - <groupname>audit</groupname> group in order to delegate audit + <systemitem class="groupname">audit</systemitem> group in order to delegate audit review rights to the user. As the ability to track audit log contents provides significant insight into the behavior of users and processes, it is recommended that the delegation of @@ -651,8 +640,8 @@ trailer,133</programlisting> <screen>&prompt.root; <userinput>praudit /dev/auditpipe</userinput></screen> <para>By default, audit pipe device nodes are accessible only to - the <username>root</username> user. To make them accessible - to the members of the <groupname>audit</groupname> group, add + the <systemitem class="username">root</systemitem> user. To make them accessible + to the members of the <systemitem class="groupname">audit</systemitem> group, add a <literal>devfs</literal> rule to <filename>devfs.rules</filename>:</para> diff --git a/en_US.ISO8859-1/books/handbook/basics/chapter.xml b/en_US.ISO8859-1/books/handbook/basics/chapter.xml index 2e5a055f62..fe761d754d 100644 --- a/en_US.ISO8859-1/books/handbook/basics/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/basics/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="basics"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="basics"> <!-- <chapterinfo> <authorgroup> @@ -20,7 +19,7 @@ <title>UNIX Basics</title> - <sect1 id="basics-synopsis"> + <sect1 xml:id="basics-synopsis"> <title>Synopsis</title> <para>This chapter covers the basic commands and functionality of @@ -80,7 +79,7 @@ </itemizedlist> </sect1> - <sect1 id="consoles"> + <sect1 xml:id="consoles"> <title>Virtual Consoles and Terminals</title> <indexterm><primary>virtual consoles</primary></indexterm> @@ -99,8 +98,8 @@ login:</screen> <para>The first line contains some information about the system. The <literal>amd64</literal> indicates that the system in this example is running a 64-bit version of &os;. The hostname is - <hostid>pc3.example.org</hostid>, and - <devicename>ttyv0</devicename> indicates that this is the + <systemitem>pc3.example.org</systemitem>, and + <filename>ttyv0</filename> indicates that this is the <quote>system console</quote>. The second line is the login prompt.</para> @@ -128,7 +127,7 @@ login:</screen> the user is now logged into the &os; system console and ready to try the available commands.</para> - <sect2 id="consoles-virtual"> + <sect2 xml:id="consoles-virtual"> <title>Virtual Consoles</title> <para>While the system console can be used to interact with @@ -155,13 +154,13 @@ login:</screen> consoles. Use <keycombo><keycap>Alt</keycap><keycap>F1</keycap></keycombo> to switch to the system console - (<devicename>ttyv0</devicename>), + (<filename>ttyv0</filename>), <keycombo><keycap>Alt</keycap><keycap>F2</keycap></keycombo> to access the first virtual console - (<devicename>ttyv1</devicename>), + (<filename>ttyv1</filename>), <keycombo><keycap>Alt</keycap><keycap>F3</keycap></keycombo> to access the second virtual console - (<devicename>ttyv2</devicename>), and so on.</para> + (<filename>ttyv2</filename>), and so on.</para> <para>When switching from one console to the next, &os; takes manages the screen output. The result is an illusion of @@ -199,21 +198,20 @@ ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting> the number of available virtual consoles from eight to four, put a <literal>#</literal> in front of the last four lines representing virtual consoles - <devicename>ttyv5</devicename> through - <devicename>ttyv8</devicename>. <emphasis>Do not</emphasis> + <filename>ttyv5</filename> through + <filename>ttyv8</filename>. <emphasis>Do not</emphasis> comment out the line for the system console - <devicename>ttyv0</devicename>. Note that the last virtual - console (<devicename>ttyv8</devicename>) is used to access + <filename>ttyv0</filename>. Note that the last virtual + console (<filename>ttyv8</filename>) is used to access the graphical environment if <application>&xorg;</application> - has been installed and configured as described in <xref - linkend="x11"/>.</para> + has been installed and configured as described in <xref linkend="x11"/>.</para> <para>For a detailed description of every column in this file and the available options for the virtual consoles, refer to &man.ttys.5;.</para> </sect2> - <sect2 id="consoles-singleuser"> + <sect2 xml:id="consoles-singleuser"> <title>Single User Mode</title> <para>The &os; boot menu provides an option labelled as @@ -221,11 +219,11 @@ ttyv8 "/usr/X11R6/bin/xdm -nodaemon" xterm off secure</programlisting> the system will boot into a special mode known as <quote>single user mode</quote>. This mode is typically used to repair a system that will not boot or to reset the - <username>root</username> password when it is not known. + <systemitem class="username">root</systemitem> password when it is not known. While in single user mode, networking and other virtual consoles are not available. However, full - <username>root</username> access to the system is available, - and by default, the <username>root</username> password is not + <systemitem class="username">root</systemitem> access to the system is available, + and by default, the <systemitem class="username">root</systemitem> password is not needed. For these reasons, physical access to the keyboard is needed to boot into this mode and determining who has physical access to the keyboard is something to consider when @@ -248,20 +246,20 @@ console none unknown off secure</programlisting> that the environment itself is insecure because anyone can access the keyboard. When this line is changed to <literal>insecure</literal>, &os; will prompt for the - <username>root</username> password when a user selects to + <systemitem class="username">root</systemitem> password when a user selects to boot into single user mode.</para> <note> <para><emphasis>Be careful when changing this setting to <literal>insecure</literal></emphasis>! If the - <username>root</username> password is forgotten, booting + <systemitem class="username">root</systemitem> password is forgotten, booting into single user mode is still possible, but may be difficult for someone who is not familiar with the &os; booting process.</para> </note> </sect2> - <sect2 id="consoles-vidcontrol"> + <sect2 xml:id="consoles-vidcontrol"> <title>Changing Console Video Modes</title> <para>The &os; console default video mode may be adjusted to @@ -280,7 +278,7 @@ console none unknown off secure</programlisting> <para>The output of this command lists the video modes that are supported by the hardware. To select a new video mode, specify the mode using &man.vidcontrol.1; as the - <username>root</username> user:</para> + <systemitem class="username">root</systemitem> user:</para> <screen>&prompt.root; <userinput>vidcontrol MODE_279</userinput></screen> @@ -304,7 +302,7 @@ console none unknown off secure</programlisting> </chapterinfo> --> - <sect1 id="users-synopsis"> + <sect1 xml:id="users-synopsis"> <title>Users and Basic Account Management</title> <para>&os; allows multiple users to use the computer at the same @@ -337,7 +335,7 @@ console none unknown off secure</programlisting> </listitem> </itemizedlist> - <sect2 id="users-introduction"> + <sect2 xml:id="users-introduction"> <title>Account Types</title> <para>Since all access to the &os; system is achieved using @@ -347,7 +345,7 @@ console none unknown off secure</programlisting> <para>There are three main types of accounts: system accounts, user accounts, and the superuser account.</para> - <sect3 id="users-system"> + <sect3 xml:id="users-system"> <title>System Accounts</title> <indexterm> @@ -362,31 +360,31 @@ console none unknown off secure</programlisting> <indexterm> <primary>accounts</primary> - <secondary><username>daemon</username></secondary> + <secondary><systemitem class="username">daemon</systemitem></secondary> </indexterm> <indexterm> <primary>accounts</primary> - <secondary><username>operator</username></secondary> + <secondary><systemitem class="username">operator</systemitem></secondary> </indexterm> <para>Examples of system accounts are - <username>daemon</username>, <username>operator</username>, - <username>bind</username>, <username>news</username>, and - <username>www</username>.</para> + <systemitem class="username">daemon</systemitem>, <systemitem class="username">operator</systemitem>, + <systemitem class="username">bind</systemitem>, <systemitem class="username">news</systemitem>, and + <systemitem class="username">www</systemitem>.</para> <indexterm> <primary>accounts</primary> - <secondary><username>nobody</username></secondary> + <secondary><systemitem class="username">nobody</systemitem></secondary> </indexterm> - <para><username>nobody</username> is the generic unprivileged + <para><systemitem class="username">nobody</systemitem> is the generic unprivileged system account. However, the more services that use - <username>nobody</username>, the more files and processes + <systemitem class="username">nobody</systemitem>, the more files and processes that user will become associated with, and hence the more privileged that user becomes.</para> </sect3> - <sect3 id="users-user"> + <sect3 xml:id="users-user"> <title>User Accounts</title> <indexterm> @@ -521,10 +519,8 @@ console none unknown off secure</programlisting> <para>The home directory is the full path to a directory on the system. This is the user's starting directory when the user logs in. A common convention is to put all user - home directories under <filename - class="directory">/home/<replaceable>username</replaceable></filename> - or <filename - class="directory">/usr/home/<replaceable>username</replaceable></filename>. + home directories under <filename>/home/username</filename> + or <filename>/usr/home/username</filename>. Each user stores their personal files and subdirectories in their own home directory.</para> </listitem> @@ -544,7 +540,7 @@ console none unknown off secure</programlisting> </variablelist> </sect3> - <sect3 id="users-superuser"> + <sect3 xml:id="users-superuser"> <title>The Superuser Account</title> <indexterm> @@ -553,7 +549,7 @@ console none unknown off secure</programlisting> </indexterm> <para>The superuser account, usually called - <username>root</username>, is used to + <systemitem class="username">root</systemitem>, is used to manage the system with no limitations on privileges. For this reason, it should not be used for day-to-day tasks like sending and receiving mail, general exploration of @@ -572,16 +568,16 @@ console none unknown off secure</programlisting> irreparable data loss.</para> <para>There are several ways to become gain superuser privilege. - While one can log in as <username>root</username>, this is + While one can log in as <systemitem class="username">root</systemitem>, this is highly discouraged.</para> <para>Instead, use &man.su.1; to become the superuser. If <literal>-</literal> is specified when running this command, the user will also inherit the root user's environment. The user running this command must be in the - <groupname>wheel</groupname> group or else the command will + <systemitem class="groupname">wheel</systemitem> group or else the command will fail. The user must also know the password for the - <username>root</username> user account.</para> + <systemitem class="username">root</systemitem> user account.</para> <para>In this example, the user only becomes superuser in order to run <command>make install</command> as this step requires @@ -603,15 +599,14 @@ Password: <para>The built-in &man.su.1; framework works well for single systems or small networks with just one system administrator. - An alternative is to install the <filename - role="package">security/sudo</filename> package or port. + An alternative is to install the <package>security/sudo</package> package or port. This software provides activity logging and allows the administrator to configure which users can run which commands as the superuser.</para> </sect3> </sect2> - <sect2 id="users-modifying"> + <sect2 xml:id="users-modifying"> <title>Managing Accounts</title> <indexterm> @@ -672,7 +667,7 @@ Password: </tgroup> </table> - <sect3 id="users-adduser"> + <sect3 xml:id="users-adduser"> <title><command>adduser</command></title> <indexterm> @@ -683,8 +678,7 @@ Password: <primary><command>adduser</command></primary> </indexterm> <indexterm> - <primary><filename - class="directory">/usr/share/skel</filename></primary> + <primary><filename>/usr/share/skel</filename></primary> </indexterm> <indexterm><primary>skeleton directory</primary></indexterm> <para>The recommended program for adding new users is @@ -692,17 +686,16 @@ Password: automatically updates <filename>/etc/passwd</filename> and <filename>/etc/group</filename>. It also creates a home directory for the new user, copies in the default - configuration files from <filename - class="directory">/usr/share/skel</filename>, and can + configuration files from <filename>/usr/share/skel</filename>, and can optionally mail the new user a welcome message. This utility - must be run as the <username>superuser</username></para> + must be run as the <systemitem class="username">superuser</systemitem></para> <para>The &man.adduser.8; utility is interactive and walks through the steps for creating a new user account. As seen in Example 4.2, either input the required information or press <keycap>Return</keycap> to accept the default value shown in square brackets. In this example, the user has been invited - into the <groupname>wheel</groupname> group, which is + into the <systemitem class="groupname">wheel</systemitem> group, which is required to provide the account with superuser access. When finished, the utility will prompt to either create another user or to exit.</para> @@ -749,7 +742,7 @@ Goodbye! </note> </sect3> - <sect3 id="users-rmuser"> + <sect3 xml:id="users-rmuser"> <title><command>rmuser</command></title> <indexterm><primary><command>rmuser</command></primary></indexterm> @@ -789,14 +782,12 @@ Goodbye! <step> <para>Removes the incoming mail files belonging to the user - from <filename - class="directory">/var/mail</filename>.</para> + from <filename>/var/mail</filename>.</para> </step> <step> <para>Removes all files owned by the user from temporary - file storage areas such as <filename - class="directory">/tmp</filename>.</para> + file storage areas such as <filename>/tmp</filename>.</para> </step> <step> @@ -829,7 +820,7 @@ Removing user (jru): mailspool home passwd. </example> </sect3> - <sect3 id="users-chpass"> + <sect3 xml:id="users-chpass"> <title><command>chpass</command></title> <indexterm><primary><command>chpass</command></primary></indexterm> @@ -852,7 +843,7 @@ Removing user (jru): mailspool home passwd. <para>In Example 4.4, the superuser has typed <command>chpass jru</command> and is now viewing the fields that can be changed for this user. If - <username>jru</username> runs this command instead, only the + <systemitem class="username">jru</systemitem> runs this command instead, only the last six fields will be displayed and available for editing. This is shown in Example 4.5.</para> @@ -899,7 +890,7 @@ Other information:</screen> covered in <xref linkend="network-servers"/>.</para> </note> </sect3> - <sect3 id="users-passwd"> + <sect3 xml:id="users-passwd"> <title><command>passwd</command></title> <indexterm><primary><command>passwd</command></primary></indexterm> @@ -950,7 +941,7 @@ passwd: done</screen> </sect3> - <sect3 id="users-pw"> + <sect3 xml:id="users-pw"> <title><command>pw</command></title> <indexterm><primary><command>pw</command></primary></indexterm> @@ -965,7 +956,7 @@ passwd: done</screen> </sect3> </sect2> - <sect2 id="users-limiting"> + <sect2 xml:id="users-limiting"> <title>Limiting Users</title> <indexterm><primary>limiting users</primary></indexterm> @@ -986,8 +977,7 @@ passwd: done</screen> <indexterm><primary>disk quotas</primary></indexterm> <para>Disk quotas limit the amount of disk space available to users and provide a way to quickly check that usage without - calculating it every time. Quotas are discussed in <xref - linkend="quotas"/>.</para> + calculating it every time. Quotas are discussed in <xref linkend="quotas"/>.</para> <para>The other resource limits include ways to limit the amount of CPU, memory, and other resources a user may consume. These @@ -1002,7 +992,7 @@ passwd: done</screen> class, <literal>default</literal> by default, and each login class has a set of login capabilities associated with it. A login capability is a - <literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal> + <literal>name=value</literal> pair, where <replaceable>name</replaceable> is a well-known identifier and <replaceable>value</replaceable> is an arbitrary string which is processed accordingly depending on the @@ -1227,7 +1217,7 @@ passwd: done</screen> &man.getrlimit.2;, and &man.login.conf.5;.</para> </sect2> - <sect2 id="users-groups"> + <sect2 xml:id="users-groups"> <title>Managing Groups</title> <indexterm><primary>groups</primary></indexterm> @@ -1257,7 +1247,7 @@ passwd: done</screen> <para>The superuser can modify <filename>/etc/group</filename> using a text editor. Alternatively, &man.pw.8; can be used to add and edit groups. For example, to add a group called - <groupname>teamtwo</groupname> and then confirm that it + <systemitem class="groupname">teamtwo</systemitem> and then confirm that it exists:</para> <example> @@ -1269,10 +1259,10 @@ teamtwo:*:1100:</screen> </example> <para>In this example, <literal>1100</literal> is the - <acronym>GID</acronym> of <groupname>teamtwo</groupname>. Right - now, <groupname>teamtwo</groupname> has no members. This - command will add <username>jru</username> as a member of - <groupname>teamtwo</groupname>.</para> + <acronym>GID</acronym> of <systemitem class="groupname">teamtwo</systemitem>. Right + now, <systemitem class="groupname">teamtwo</systemitem> has no members. This + command will add <systemitem class="username">jru</systemitem> as a member of + <systemitem class="groupname">teamtwo</systemitem>.</para> <example> <title>Adding User Accounts to a New Group Using @@ -1317,9 +1307,9 @@ teamtwo:*:1100:jru,db</screen> uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen> </example> - <para>In this example, <username>jru</username> is a member of - the groups <groupname>jru</groupname> and - <groupname>teamtwo</groupname>.</para> + <para>In this example, <systemitem class="username">jru</systemitem> is a member of + the groups <systemitem class="groupname">jru</systemitem> and + <systemitem class="groupname">teamtwo</systemitem>.</para> <para>For more information about this command and the format of <filename>/etc/group</filename>, refer to &man.pw.8; and @@ -1327,7 +1317,7 @@ uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen> </sect2> </sect1> - <sect1 id="permissions"> + <sect1 xml:id="permissions"> <title>Permissions</title> <indexterm><primary>UNIX</primary></indexterm> @@ -1469,7 +1459,7 @@ total 530 <para>How does the system control permissions on devices? &os; treats most hardware devices as a file that programs can open, read, and write data to. These special device files are - stored in <filename class="directory">/dev/</filename>.</para> + stored in <filename>/dev/</filename>.</para> <para>Directories are also treated as files. They have read, write, and execute permissions. The executable bit for a @@ -1492,17 +1482,13 @@ total 530 to set them, refer to &man.chmod.1;.</para> <sect2> - <sect2info> + <info><title>Symbolic Permissions</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>Symbolic Permissions</title> + <indexterm> <primary>permissions</primary> @@ -1615,7 +1601,7 @@ total 530 <replaceable>FILE</replaceable>, and adds the execute permissions for everyone:</para> - <screen>&prompt.user; <userinput>chmod go-w,a+x <replaceable>FILE</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>chmod go-w,a+x FILE</userinput></screen> <!-- <para>Most users will not notice this, but it should be pointed @@ -1625,22 +1611,18 @@ total 530 </sect2> <sect2> - <sect2info> + <info><title>&os; File Flags</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>&os; File Flags</title> + <para>In addition to file permissions, &os; supports the use of <quote>file flags</quote>. These flags add an additional level of security and control over files, but not directories. - With file flags, even <username>root</username> can be + With file flags, even <systemitem class="username">root</systemitem> can be prevented from removing or altering files.</para> <para>File flags are modified using &man.chflags.1;. For @@ -1648,40 +1630,36 @@ total 530 <filename>file1</filename>, issue the following command:</para> - <screen>&prompt.root; <userinput>chflags sunlink <filename>file1</filename></userinput></screen> + <screen>&prompt.root; <userinput>chflags sunlink file1</userinput></screen> <para>To disable the system undeletable flag, put a <quote>no</quote> in front of the <option>sunlink</option>:</para> - <screen>&prompt.root; <userinput>chflags nosunlink <filename>file1</filename></userinput></screen> + <screen>&prompt.root; <userinput>chflags nosunlink file1</userinput></screen> <para>To view the flags of a file, use <option>-lo</option> with &man.ls.1;:</para> - <screen>&prompt.root; <userinput>ls -lo <filename>file1</filename></userinput></screen> + <screen>&prompt.root; <userinput>ls -lo file1</userinput></screen> <programlisting>-rw-r--r-- 1 trhodes trhodes sunlnk 0 Mar 1 05:54 file1</programlisting> <para>Several file flags may only be added or removed by the - <username>root</username> user. In other cases, the file + <systemitem class="username">root</systemitem> user. In other cases, the file owner may set its file flags. Refer to &man.chflags.1; and &man.chflags.2; for more information.</para> </sect2> <sect2> - <sect2info> + <info><title>The <literal>setuid</literal>, <literal>setgid</literal>, + and <literal>sticky</literal> Permissions</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>The <literal>setuid</literal>, <literal>setgid</literal>, - and <literal>sticky</literal> Permissions</title> + <para>Other than the permissions already discussed, there are three other specific settings that all administrators should @@ -1700,7 +1678,7 @@ total 530 &man.passwd.1; runs with the real user ID when a user changes their password. However, in order to update the password database, the command runs as the effective ID of the - <username>root</username> user. This allows users to change + <systemitem class="username">root</systemitem> user. This allows users to change their passwords without seeing a <errorname>Permission Denied</errorname> error.</para> @@ -1711,7 +1689,7 @@ total 530 <screen>&prompt.root; <userinput>chmod 4755 suidexample.sh</userinput></screen> <para>The permissions on - <filename><replaceable>suidexample.sh</replaceable></filename> + <filename>suidexample.sh</filename> now look like the following:</para> <programlisting>-rwsr-xr-x 1 trhodes trhodes 63 Aug 29 06:36 suidexample.sh</programlisting> @@ -1749,7 +1727,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>Although &man.passwd.1; is run as a normal user, it is using the effective <acronym>UID</acronym> of - <username>root</username>.</para> + <systemitem class="username">root</systemitem>.</para> <para>The <literal>setgid</literal> permission performs the same function as the <literal>setuid</literal> permission; @@ -1786,7 +1764,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>When the <literal>sticky bit</literal> is set on a directory, it allows file deletion only by the file owner. This is useful to prevent file deletion in public directories, - such as <filename class="directory">/tmp</filename>, by users + such as <filename>/tmp</filename>, by users who do not own the file. To utilize this permission, prefix the permission set with a one (1):</para> @@ -1803,7 +1781,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </sect2> </sect1> - <sect1 id="dirstructure"> + <sect1 xml:id="dirstructure"> <title>Directory Structure</title> <indexterm><primary>directory hierarchy</primary></indexterm> @@ -1819,13 +1797,12 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>A mount point is a directory where additional file systems can be grafted onto a parent file system (usually the root file - system). This is further described in <xref - linkend="disk-organization"/>. Standard mount points - include <filename class="directory">/usr/</filename>, - <filename class="directory">/var/</filename>, - <filename class="directory">/tmp/</filename>, - <filename class="directory">/mnt/</filename>, and - <filename class="directory">/cdrom/</filename>. These + system). This is further described in <xref linkend="disk-organization"/>. Standard mount points + include <filename>/usr/</filename>, + <filename>/var/</filename>, + <filename>/tmp/</filename>, + <filename>/mnt/</filename>, and + <filename>/cdrom/</filename>. These directories are usually referenced to entries in <filename>/etc/fstab</filename>. This file is a table of various file systems and mount points and is read by the system. @@ -1849,121 +1826,105 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </thead> <tbody valign="top"> <row> - <entry><filename class="directory">/</filename></entry> + <entry><filename>/</filename></entry> <entry>Root directory of the file system.</entry> </row> <row> - <entry><filename - class="directory">/bin/</filename></entry> + <entry><filename>/bin/</filename></entry> <entry>User utilities fundamental to both single-user and multi-user environments.</entry> </row> <row> - <entry><filename - class="directory">/boot/</filename></entry> + <entry><filename>/boot/</filename></entry> <entry>Programs and configuration files used during operating system bootstrap.</entry> </row> <row> - <entry><filename - class="directory">/boot/defaults/</filename></entry> + <entry><filename>/boot/defaults/</filename></entry> <entry>Default boot configuration files. Refer to &man.loader.conf.5; for details.</entry> </row> <row> - <entry><filename - class="directory">/dev/</filename></entry> + <entry><filename>/dev/</filename></entry> <entry>Device nodes. Refer to &man.intro.4; for details.</entry> </row> <row> - <entry><filename - class="directory">/etc/</filename></entry> + <entry><filename>/etc/</filename></entry> <entry>System configuration files and scripts.</entry> </row> <row> - <entry><filename - class="directory">/etc/defaults/</filename></entry> + <entry><filename>/etc/defaults/</filename></entry> <entry>Default system configuration files. Refer to &man.rc.8; for details.</entry> </row> <row> - <entry><filename - class="directory">/etc/mail/</filename></entry> + <entry><filename>/etc/mail/</filename></entry> <entry>Configuration files for mail transport agents such as &man.sendmail.8;.</entry> </row> <row> - <entry><filename - class="directory">/etc/namedb/</filename></entry> + <entry><filename>/etc/namedb/</filename></entry> <entry>&man.named.8; configuration files.</entry> </row> <row> - <entry><filename - class="directory">/etc/periodic/</filename></entry> + <entry><filename>/etc/periodic/</filename></entry> <entry>Scripts that run daily, weekly, and monthly, via &man.cron.8;. Refer to &man.periodic.8; for details.</entry> </row> <row> - <entry><filename - class="directory">/etc/ppp/</filename></entry> + <entry><filename>/etc/ppp/</filename></entry> <entry>&man.ppp.8; configuration files.</entry> </row> <row> - <entry><filename - class="directory">/mnt/</filename></entry> + <entry><filename>/mnt/</filename></entry> <entry>Empty directory commonly used by system administrators as a temporary mount point.</entry> </row> <row> - <entry><filename - class="directory">/proc/</filename></entry> + <entry><filename>/proc/</filename></entry> <entry>Process file system. Refer to &man.procfs.5;, &man.mount.procfs.8; for details.</entry> </row> <row> - <entry><filename - class="directory">/rescue/</filename></entry> + <entry><filename>/rescue/</filename></entry> <entry>Statically linked programs for emergency recovery as described in &man.rescue.8;.</entry> </row> <row> - <entry><filename - class="directory">/root/</filename></entry> - <entry>Home directory for the <username>root</username> + <entry><filename>/root/</filename></entry> + <entry>Home directory for the <systemitem class="username">root</systemitem> account.</entry> </row> <row> - <entry><filename - class="directory">/sbin/</filename></entry> + <entry><filename>/sbin/</filename></entry> <entry>System programs and administration utilities fundamental to both single-user and multi-user environments.</entry> </row> <row> - <entry><filename - class="directory">/tmp/</filename></entry> + <entry><filename>/tmp/</filename></entry> <entry>Temporary files which are usually <emphasis>not</emphasis> preserved across a system reboot. A memory-based file system is often mounted - at <filename class="directory">/tmp</filename>. This + at <filename>/tmp</filename>. This can be automated using the tmpmfs-related variables of &man.rc.conf.5; or with an entry in <filename>/etc/fstab</filename>; refer to @@ -1971,104 +1932,86 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </row> <row> - <entry><filename - class="directory">/usr/</filename></entry> + <entry><filename>/usr/</filename></entry> <entry>The majority of user utilities and applications.</entry> </row> <row> - <entry><filename - class="directory">/usr/bin/</filename></entry> + <entry><filename>/usr/bin/</filename></entry> <entry>Common utilities, programming tools, and applications.</entry> </row> <row> - <entry><filename - class="directory">/usr/include/</filename></entry> + <entry><filename>/usr/include/</filename></entry> <entry>Standard C include files.</entry> </row> <row> - <entry><filename - class="directory">/usr/lib/</filename></entry> + <entry><filename>/usr/lib/</filename></entry> <entry>Archive libraries.</entry> </row> <row> - <entry><filename - class="directory">/usr/libdata/</filename></entry> + <entry><filename>/usr/libdata/</filename></entry> <entry>Miscellaneous utility data files.</entry> </row> <row> - <entry><filename - class="directory">/usr/libexec/</filename></entry> + <entry><filename>/usr/libexec/</filename></entry> <entry>System daemons and system utilities executed by other programs.</entry> </row> <row> - <entry><filename - class="directory">/usr/local/</filename></entry> + <entry><filename>/usr/local/</filename></entry> <entry>Local executables and libraries. Also used as the default destination for the &os; ports framework. - Within <filename - class="directory">/usr/local</filename>, the + Within <filename>/usr/local</filename>, the general layout sketched out by &man.hier.7; for - <filename class="directory">/usr</filename> should be + <filename>/usr</filename> should be used. Exceptions are the man directory, which is - directly under <filename - class="directory">/usr/local</filename> - rather than under <filename - class="directory">/usr/local/share</filename>, - and the ports documentation is in <filename - class="directory">share/doc/<replaceable>port</replaceable></filename>.</entry> + directly under <filename>/usr/local</filename> + rather than under <filename>/usr/local/share</filename>, + and the ports documentation is in <filename>share/doc/port</filename>.</entry> </row> <row> - <entry><filename - class="directory">/usr/obj/</filename></entry> + <entry><filename>/usr/obj/</filename></entry> <entry>Architecture-specific target tree produced by - building the <filename - class="directory">/usr/src</filename> + building the <filename>/usr/src</filename> tree.</entry> </row> <row> - <entry><filename - class="directory">/usr/ports/</filename></entry> + <entry><filename>/usr/ports/</filename></entry> <entry>The &os; Ports Collection (optional).</entry> </row> <row> - <entry><filename - class="directory">/usr/sbin/</filename></entry> + <entry><filename>/usr/sbin/</filename></entry> <entry>System daemons and system utilities executed by users.</entry> </row> <row> - <entry><filename - class="directory">/usr/share/</filename></entry> + <entry><filename>/usr/share/</filename></entry> <entry>Architecture-independent files.</entry> </row> <row> - <entry><filename - class="directory">/usr/src/</filename></entry> + <entry><filename>/usr/src/</filename></entry> <entry>BSD and/or local source files.</entry> </row> <row> - <entry><filename - class="directory">/var/</filename></entry> + <entry><filename>/var/</filename></entry> <entry>Multi-purpose log, temporary, transient, and spool files. A memory-based file system is sometimes mounted at - <filename class="directory">/var</filename>. This can + <filename>/var</filename>. This can be automated using the varmfs-related variables in &man.rc.conf.5; or with an entry in <filename>/etc/fstab</filename>; refer to @@ -2076,36 +2019,31 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </row> <row> - <entry><filename - class="directory">/var/log/</filename></entry> + <entry><filename>/var/log/</filename></entry> <entry>Miscellaneous system log files.</entry> </row> <row> - <entry><filename - class="directory">/var/mail/</filename></entry> + <entry><filename>/var/mail/</filename></entry> <entry>User mailbox files.</entry> </row> <row> - <entry><filename - class="directory">/var/spool/</filename></entry> + <entry><filename>/var/spool/</filename></entry> <entry>Miscellaneous printer and mail system spooling directories.</entry> </row> <row> - <entry><filename - class="directory">/var/tmp/</filename></entry> + <entry><filename>/var/tmp/</filename></entry> <entry>Temporary files which are usually preserved across a system reboot, unless - <filename class="directory">/var</filename> is a + <filename>/var</filename> is a memory-based file system.</entry> </row> <row> - <entry><filename - class="directory">/var/yp/</filename></entry> + <entry><filename>/var/yp/</filename></entry> <entry>NIS maps.</entry> </row> </tbody> @@ -2113,7 +2051,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </informaltable></para> </sect1> - <sect1 id="disk-organization"> + <sect1 xml:id="disk-organization"> <title>Disk Organization</title> <para>The smallest unit of organization that &os; uses to find @@ -2133,8 +2071,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> directory name, followed by a forward slash, <literal>/</literal>, followed by any other directory names that are necessary. For example, if the directory - <filename class="directory">foo</filename> contains a directory - <filename class="directory">bar</filename> which contains the + <filename>foo</filename> contains a directory + <filename>bar</filename> which contains the file <filename>readme.txt</filename>, the full name, or <firstterm>path</firstterm>, to the file is <filename>foo/bar/readme.txt</filename>. Note that this is @@ -2209,9 +2147,9 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <para>Any files that are in the <literal>B1</literal> or <literal>B2</literal> directories can be reached with the path - <filename class="directory">/A1/B1</filename> or - <filename class="directory">/A1/B2</filename> as necessary. Any - files that were in <filename class="directory">/A1</filename> + <filename>/A1/B1</filename> or + <filename>/A1/B2</filename> as necessary. Any + files that were in <filename>/A1</filename> have been temporarily hidden. They will reappear if <literal>B</literal> is <firstterm>unmounted</firstterm> from <literal>A</literal>.</para> @@ -2239,8 +2177,8 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </mediaobject> <para>and the paths would be - <filename class="directory">/A2/B1</filename> and - <filename class="directory">/A2/B2</filename> + <filename>/A2/B1</filename> and + <filename>/A2/B2</filename> respectively.</para> <para>File systems can be mounted on top of one another. @@ -2310,7 +2248,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> file system can be mounted read-only, making it impossible for users to inadvertently delete or edit a critical file. Separating user-writable file systems, such as - <filename class="directory">/home</filename>, from other + <filename>/home</filename>, from other file systems allows them to be mounted <firstterm>nosuid</firstterm>. This option prevents the <firstterm>suid</firstterm>/<firstterm>guid</firstterm> bits @@ -2472,7 +2410,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> system or swap space in each partition, and decide where each file system will be mounted.</para> - <table frame="none" pgwide="1" id="basics-dev-codes"> + <table frame="none" pgwide="1" xml:id="basics-dev-codes"> <title>Disk Device Codes</title> <tgroup cols="2"> @@ -2488,34 +2426,34 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> <tbody> <row> - <entry><devicename>ad</devicename></entry> + <entry><filename>ad</filename></entry> <entry>ATAPI (IDE) disk</entry> </row> <row> - <entry><devicename>da</devicename></entry> + <entry><filename>da</filename></entry> <entry>SCSI direct access disk</entry> </row> <row> - <entry><devicename>acd</devicename></entry> + <entry><filename>acd</filename></entry> <entry>ATAPI (IDE) CDROM</entry> </row> <row> - <entry><devicename>cd</devicename></entry> + <entry><filename>cd</filename></entry> <entry>SCSI CDROM</entry> </row> <row> - <entry><devicename>fd</devicename></entry> + <entry><filename>fd</filename></entry> <entry>Floppy disk</entry> </row> </tbody> </tgroup> </table> - <example id="basics-disk-slice-part"> + <example xml:id="basics-disk-slice-part"> <title>Sample Disk, Slice, and Partition Names</title> <informaltable frame="none" pgwide="1"> @@ -2549,23 +2487,23 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </informaltable> </example> - <example id="basics-concept-disk-model"> + <example xml:id="basics-concept-disk-model"> <title>Conceptual Model of a Disk</title> <para>This diagram shows &os;'s view of the first IDE disk attached to the system. Assume that the disk is 4 GB in size, and contains two 2 GB slices (&ms-dos; partitions). The first slice contains a &ms-dos; disk, - <devicename>C:</devicename>, and the second slice contains a + <filename>C:</filename>, and the second slice contains a &os; installation. This example &os; installation has three data partitions, and a swap partition.</para> <para>The three partitions will each hold a file system. Partition <literal>a</literal> will be used for the root file system, <literal>e</literal> for the - <filename class="directory">/var/</filename> directory + <filename>/var/</filename> directory hierarchy, and <literal>f</literal> for the - <filename class="directory">/usr/</filename> directory + <filename>/usr/</filename> directory hierarchy.</para> <mediaobject> @@ -2605,28 +2543,28 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </example> </sect1> - <sect1 id="mount-unmount"> + <sect1 xml:id="mount-unmount"> <title>Mounting and Unmounting File Systems</title> <para>The file system is best visualized as a tree, rooted, as it - were, at <filename class="directory">/</filename>. - <filename class="directory">/dev</filename>, - <filename class="directory">/usr</filename>, and the other + were, at <filename>/</filename>. + <filename>/dev</filename>, + <filename>/usr</filename>, and the other directories in the root directory are branches, which may have their own branches, such as - <filename class="directory">/usr/local</filename>, and so + <filename>/usr/local</filename>, and so on.</para> <indexterm><primary>root file system</primary></indexterm> <para>There are various reasons to house some of these directories on separate file systems. - <filename class="directory">/var</filename> contains the - directories <filename class="directory">log/</filename>, - <filename class="directory">spool/</filename>, and various types + <filename>/var</filename> contains the + directories <filename>log/</filename>, + <filename>spool/</filename>, and various types of temporary files, and as such, may get filled up. Filling up the root file system is not a good idea, so splitting - <filename class="directory">/var</filename> from - <filename class="directory">/</filename> is often + <filename>/var</filename> from + <filename>/</filename> is often favorable.</para> <para>Another common reason to contain certain directory trees on @@ -2635,7 +2573,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> File System mounts, described in <xref linkend="network-nfs"/>, or CDROM drives.</para> - <sect2 id="disks-fstab"> + <sect2 xml:id="disks-fstab"> <title>The <filename>fstab</filename> File</title> <indexterm> @@ -2725,7 +2663,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> of <filename>/etc/fstab</filename> and its options.</para> </sect2> - <sect2 id="disks-mount"> + <sect2 xml:id="disks-mount"> <title>Using &man.mount.8;</title> <indexterm> @@ -2737,7 +2675,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> basic syntax is as follows:</para> <informalexample> - <screen>&prompt.root; <userinput>mount <replaceable>device</replaceable> <replaceable>mountpoint</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mount device mountpoint</userinput></screen> </informalexample> <para>This command provides many options which are described in @@ -2843,7 +2781,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </variablelist> </sect2> - <sect2 id="disks-umount"> + <sect2 xml:id="disks-umount"> <title>Using &man.umount.8;</title> <indexterm> @@ -2868,7 +2806,7 @@ root 5211 0.0 0.2 3620 1724 2 I+ 2:09AM 0:00.01 passwd</screen> </sect2> </sect1> - <sect1 id="basics-processes"> + <sect1 xml:id="basics-processes"> <title>Processes and Daemons</title> <para>&os; is a multi-tasking operating system. Each program @@ -3015,7 +2953,7 @@ Swap: 2048M Total, 2048M Free <option>-s</option>.</para> </sect2> - <sect2 id="basics-daemons"> + <sect2 xml:id="basics-daemons"> <title>Killing Processes</title> <para>One way to communicate with any running process or daemon @@ -3025,7 +2963,7 @@ Swap: 2048M Total, 2048M Free documentation. A user can only send a signal to a process they own and sending a signal to someone else's process will result in a permission denied error. The exception is the - <username>root</username> user, who can send signals to + <systemitem class="username">root</systemitem> user, who can send signals to anyone's processes.</para> <para>The operating system can also send a signal to a process. @@ -3096,8 +3034,8 @@ Swap: 2048M Total, 2048M Free <step> <para>Use &man.kill.1; to send the signal. Because - &man.inetd.8; is owned by <username>root</username>, use - &man.su.1; to become <username>root</username> + &man.inetd.8; is owned by <systemitem class="username">root</systemitem>, use + &man.su.1; to become <systemitem class="username">root</systemitem> first.</para> <screen>&prompt.user; <userinput>su</userinput> @@ -3147,7 +3085,7 @@ Swap: 2048M Total, 2048M Free </sect2> </sect1> - <sect1 id="shells"> + <sect1 xml:id="shells"> <title>Shells</title> <indexterm><primary>shells</primary></indexterm> @@ -3177,7 +3115,7 @@ Swap: 2048M Total, 2048M Free the rest of the command or filename. Consider two files called <filename>foobar</filename> and <filename>foo.bar</filename>. To delete <filename>foo.bar</filename>, type <command>rm - fo[<keycap>Tab</keycap>].[<keycap>Tab</keycap>]</command>.</para> + fo[Tab].[Tab]</command>.</para> <para>The shell should print out <command>rm foo[BEEP].bar</command>.</para> @@ -3320,7 +3258,7 @@ Swap: 2048M Total, 2048M Free <command>echo \$TERM</command> literally prints the string <literal>$TERM</literal>.</para> - <sect2 id="changing-shells"> + <sect2 xml:id="changing-shells"> <title>Changing the Shell</title> <para>The easiest way to permanently change the default shell is @@ -3344,14 +3282,14 @@ Swap: 2048M Total, 2048M Free to this file. If it is missing, add it using this command, replacing the path with the path of the shell:</para> - <screen>&prompt.root; <userinput>echo <replaceable>/usr/local/bin/bash</replaceable> >> /etc/shells</userinput></screen> + <screen>&prompt.root; <userinput>echo /usr/local/bin/bash >> /etc/shells</userinput></screen> <para>Then, rerun &man.chsh.1;.</para> </note> </sect2> </sect1> - <sect1 id="editors"> + <sect1 xml:id="editors"> <title>Text Editors</title> <indexterm><primary>text editors</primary></indexterm> @@ -3372,14 +3310,13 @@ Swap: 2048M Total, 2048M Free <para>A simple editor to learn is &man.ee.1;, which stands for easy editor. To start this editor, type <command>ee - <replaceable>filename</replaceable></command> where + filename</command> where <replaceable>filename</replaceable> is the name of the file to be edited. Once inside the editor, all of the commands for manipulating the editor's functions are listed at the top of the display. The caret (<literal>^</literal>) represents <keycap>Ctrl</keycap>, so <literal>^e</literal> expands to - <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>. + <keycombo action="simul"><keycap>Ctrl</keycap><keycap>e</keycap></keycombo>. To leave &man.ee.1;, press <keycap>Esc</keycap>, then choose the <quote>leave editor</quote> option from the main menu. The editor will prompt to save any changes if the file has been @@ -3397,8 +3334,8 @@ Swap: 2048M Total, 2048M Free <para>&os; also comes with more powerful text editors, such as &man.vi.1;, as part of the base system. Other editors, like - <filename role="package">editors/emacs</filename> and - <filename role="package">editors/vim</filename>, are part of the + <package>editors/emacs</package> and + <package>editors/vim</package>, are part of the &os; Ports Collection. These editors offer more functionality at the expense of being more complicated to learn. Learning a more powerful editor such as <application>vim</application> or @@ -3411,7 +3348,7 @@ Swap: 2048M Total, 2048M Free variable as described in <xref linkend="shells"/>.</para> </sect1> - <sect1 id="basics-devices"> + <sect1 xml:id="basics-devices"> <title>Devices and Device Nodes</title> <para>A device is a term used mostly for hardware-related @@ -3422,16 +3359,16 @@ Swap: 2048M Total, 2048M Free <filename>/var/run/dmesg.boot</filename>.</para> <para>Each device has a device name and number. For example, - <devicename>acd0</devicename> is the first IDE CD-ROM drive, - while <devicename>kbd0</devicename> represents the + <filename>acd0</filename> is the first IDE CD-ROM drive, + while <filename>kbd0</filename> represents the keyboard.</para> <para>Most devices in a &os; must be accessed through special files called device nodes, which are located in - <filename class="directory">/dev</filename>.</para> + <filename>/dev</filename>.</para> </sect1> - <sect1 id="basics-more-information"> + <sect1 xml:id="basics-more-information"> <title>Manual Pages</title> <indexterm><primary>manual pages</primary></indexterm> @@ -3442,7 +3379,7 @@ Swap: 2048M Total, 2048M Free available arguments. These manuals can be viewed using <command>man</command>:</para> - <screen>&prompt.user; <userinput>man <replaceable>command</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>man command</userinput></screen> <para>where <replaceable>command</replaceable> is the name of the command to learn about. For example, to learn more about @@ -3510,14 +3447,13 @@ Swap: 2048M Total, 2048M Free -k</command> to search for keywords in the manual page descriptions:</para> - <screen>&prompt.user; <userinput>man -k <replaceable>mail</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>man -k mail</userinput></screen> <para>This command displays a list of commands that have the keyword <quote>mail</quote> in their descriptions. This is equivalent to using &man.apropos.1;.</para> - <para>To read the descriptions for the commands in <filename - class="directory">/usr/bin</filename>, type:</para> + <para>To read the descriptions for the commands in <filename>/usr/bin</filename>, type:</para> <screen>&prompt.user; <userinput>cd /usr/bin</userinput> &prompt.user; <userinput>man -f * | more</userinput></screen> @@ -3527,7 +3463,7 @@ Swap: 2048M Total, 2048M Free <screen>&prompt.user; <userinput>cd /usr/bin</userinput> &prompt.user; <userinput>whatis * |more</userinput></screen> - <sect2 id="basics-info"> + <sect2 xml:id="basics-info"> <title>GNU Info Files</title> <indexterm> @@ -3538,8 +3474,7 @@ Swap: 2048M Total, 2048M Free the Free Software Foundation (FSF). In addition to manual pages, these programs may include hypertext documents called <literal>info</literal> files. These can be viewed using - &man.info.1; or, if <filename - role="package">editors/emacs</filename> is installed, the + &man.info.1; or, if <package>editors/emacs</package> is installed, the info mode of <application>emacs</application>.</para> <para>To use &man.info.1;, type:</para> diff --git a/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml b/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml index 2b7bdece60..f858d0e9d6 100644 --- a/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<appendix id="bibliography"> +<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="bibliography"> <title>Bibliography</title> <para>While the manual pages provide the definitive reference for @@ -15,7 +14,7 @@ no substitute for a good book on &unix; system administration and a good users' manual.</para> - <sect1 id="bibliography-freebsd"> + <sect1 xml:id="bibliography-freebsd"> <title>Books & Magazines Specific to FreeBSD</title> <para><emphasis>International books & @@ -23,10 +22,9 @@ <itemizedlist> <listitem> - <para><ulink - url="http://jdli.tw.FreeBSD.org/publication/book/freebsd2/index.htm">Using - FreeBSD</ulink> (in Traditional Chinese), published by - <ulink url="http://www.drmaster.com.tw/">Drmaster</ulink>, + <para><link xlink:href="http://jdli.tw.FreeBSD.org/publication/book/freebsd2/index.htm">Using + FreeBSD</link> (in Traditional Chinese), published by + <link xlink:href="http://www.drmaster.com.tw/">Drmaster</link>, 1997. ISBN 9-578-39435-7.</para> </listitem> @@ -34,8 +32,8 @@ <para>FreeBSD Unleashed (Simplified Chinese translation), published by - <ulink url="http://www.hzbook.com/">China Machine - Press</ulink>. ISBN 7-111-10201-0.</para> + <link xlink:href="http://www.hzbook.com/">China Machine + Press</link>. ISBN 7-111-10201-0.</para> </listitem> <listitem> @@ -46,15 +44,14 @@ <listitem> <para>FreeBSD Handbook Second Edition (Simplified Chinese - translation), published by <ulink - url="http://www.ptpress.com.cn/">Posts & Telecom - Press</ulink>. ISBN 7-115-10541-3.</para> + translation), published by <link xlink:href="http://www.ptpress.com.cn/">Posts & Telecom + Press</link>. ISBN 7-115-10541-3.</para> </listitem> <listitem> <para>FreeBSD & Windows (in Simplified Chinese), published - by <ulink url="http://www.tdpress.com/">China Railway - Publishing House</ulink>. ISBN 7-113-03845-X</para> + by <link xlink:href="http://www.tdpress.com/">China Railway + Publishing House</link>. ISBN 7-113-03845-X</para> </listitem> <listitem> @@ -69,72 +66,65 @@ </listitem> <listitem> - <para><ulink - url="http://www.shoeisha.com/book/Detail.asp?bid=650">Complete - Introduction to FreeBSD</ulink> (in Japanese), published - by <ulink url="http://www.shoeisha.co.jp/">Shoeisha Co., - Ltd</ulink>. ISBN 4-88135-473-6 P3600E.</para> + <para><link xlink:href="http://www.shoeisha.com/book/Detail.asp?bid=650">Complete + Introduction to FreeBSD</link> (in Japanese), published + by <link xlink:href="http://www.shoeisha.co.jp/">Shoeisha Co., + Ltd</link>. ISBN 4-88135-473-6 P3600E.</para> </listitem> <listitem> - <para><ulink - url="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal - UNIX Starter Kit FreeBSD</ulink> (in Japanese), published - by <ulink url="http://www.ascii.co.jp/">ASCII</ulink>. ISBN + <para><link xlink:href="http://www.ascii.co.jp/pb/book1/shinkan/detail/1322785.html">Personal + UNIX Starter Kit FreeBSD</link> (in Japanese), published + by <link xlink:href="http://www.ascii.co.jp/">ASCII</link>. ISBN 4-7561-1733-3 P3000E.</para> </listitem> <listitem> <para>FreeBSD Handbook (Japanese translation), published by - <ulink url="http://www.ascii.co.jp/">ASCII</ulink>. ISBN + <link xlink:href="http://www.ascii.co.jp/">ASCII</link>. ISBN 4-7561-1580-2 P3800E.</para> </listitem> <listitem> <para>FreeBSD mit Methode (in German), published by - <ulink url="http://www.cul.de">Computer und Literatur - Verlag</ulink>/Vertrieb Hanser, 1998. ISBN + <link xlink:href="http://www.cul.de">Computer und Literatur + Verlag</link>/Vertrieb Hanser, 1998. ISBN 3-932311-31-0.</para> </listitem> <listitem> - <para><ulink - url="http://www.mitp.de/vmi/mitp/detail/pWert/1343/"> - FreeBSD de Luxe</ulink> (in German), published by - <ulink url="http://www.mitp.de">Verlag Modere - Industrie</ulink>, 2003. ISBN 3-8266-1343-0.</para> + <para><link xlink:href="http://www.mitp.de/vmi/mitp/detail/pWert/1343/"> + FreeBSD de Luxe</link> (in German), published by + <link xlink:href="http://www.mitp.de">Verlag Modere + Industrie</link>, 2003. ISBN 3-8266-1343-0.</para> </listitem> <listitem> - <para><ulink - url="http://www.pc.mycom.co.jp/FreeBSD/install-manual.html">FreeBSD - Install and Utilization Manual</ulink> (in Japanese), + <para><link xlink:href="http://www.pc.mycom.co.jp/FreeBSD/install-manual.html">FreeBSD + Install and Utilization Manual</link> (in Japanese), published by - <ulink url="http://www.pc.mycom.co.jp/">Mainichi - Communications Inc.</ulink>, 1998. ISBN + <link xlink:href="http://www.pc.mycom.co.jp/">Mainichi + Communications Inc.</link>, 1998. ISBN 4-8399-0112-0.</para> </listitem> <listitem> <para>Onno W Purbo, Dodi Maryanto, Syahrial Hubbany, Widjil - Widodo <emphasis><ulink - url="http://maxwell.itb.ac.id/">Building Internet Server - with FreeBSD</ulink></emphasis> (in Indonesia Language), - published by <ulink url="http://www.elexmedia.co.id/">Elex - Media Komputindo</ulink>.</para> + Widodo <emphasis><link xlink:href="http://maxwell.itb.ac.id/">Building Internet Server + with FreeBSD</link></emphasis> (in Indonesia Language), + published by <link xlink:href="http://www.elexmedia.co.id/">Elex + Media Komputindo</link>.</para> </listitem> <listitem> <para>Absolute BSD: The Ultimate Guide to FreeBSD (Traditional - Chinese translation), published by <ulink - url="http://www.grandtech.com.tw/">GrandTech - Press</ulink>, 2003. ISBN 986-7944-92-5.</para> + Chinese translation), published by <link xlink:href="http://www.grandtech.com.tw/">GrandTech + Press</link>, 2003. ISBN 986-7944-92-5.</para> </listitem> <listitem> - <para><ulink - url="http://www.twbsd.org/cht/book/">The FreeBSD 6.0 - Book</ulink> (in Traditional Chinese), published by + <para><link xlink:href="http://www.twbsd.org/cht/book/">The FreeBSD 6.0 + Book</link> (in Traditional Chinese), published by Drmaster, 2006. ISBN 9-575-27878-X.</para> </listitem> </itemizedlist> @@ -144,121 +134,111 @@ <itemizedlist> <listitem> - <para><ulink url="http://www.absoluteFreeBSD.com/">Absolute + <para><link xlink:href="http://www.absoluteFreeBSD.com/">Absolute FreeBSD, 2nd Edition: The Complete Guide to - FreeBSD</ulink>, published by - <ulink url="http://www.nostarch.com/">No Starch - Press</ulink>, 2007. ISBN: 978-1-59327-151-0</para> + FreeBSD</link>, published by + <link xlink:href="http://www.nostarch.com/">No Starch + Press</link>, 2007. ISBN: 978-1-59327-151-0</para> </listitem> <listitem> - <para><ulink - url="http://www.freebsdmall.com/cgi-bin/fm/bsdcomp"> - The Complete FreeBSD</ulink>, published by - <ulink url="http://www.oreilly.com/">O'Reilly</ulink>, 2003. + <para><link xlink:href="http://www.freebsdmall.com/cgi-bin/fm/bsdcomp"> + The Complete FreeBSD</link>, published by + <link xlink:href="http://www.oreilly.com/">O'Reilly</link>, 2003. ISBN: 0596005164</para> </listitem> <listitem> - <para><ulink url="http://www.freebsd-corp-net-guide.com/">The - FreeBSD Corporate Networker's Guide</ulink>, published by - <ulink url="http://www.awl.com/aw/">Addison-Wesley</ulink>, + <para><link xlink:href="http://www.freebsd-corp-net-guide.com/">The + FreeBSD Corporate Networker's Guide</link>, published by + <link xlink:href="http://www.awl.com/aw/">Addison-Wesley</link>, 2000. ISBN: 0201704811</para> </listitem> <listitem> - <para><ulink - url="http://andrsn.stanford.edu/FreeBSD/introbook/"> + <para><link xlink:href="http://andrsn.stanford.edu/FreeBSD/introbook/"> FreeBSD: An Open-Source Operating System for Your Personal - Computer</ulink>, published by The Bit Tree Press, 2001. + Computer</link>, published by The Bit Tree Press, 2001. ISBN: 0971204500</para> </listitem> <listitem> <para>Teach Yourself FreeBSD in 24 Hours, published by - <ulink url="http://www.samspublishing.com/">Sams</ulink>, + <link xlink:href="http://www.samspublishing.com/">Sams</link>, 2002. ISBN: 0672324245</para> </listitem> <listitem> <para>FreeBSD 6 Unleashed, published by - <ulink url="http://www.samspublishing.com/">Sams</ulink>, + <link xlink:href="http://www.samspublishing.com/">Sams</link>, 2006. ISBN: 0672328755</para> </listitem> <listitem> - <para>FreeBSD: The Complete Reference, published by <ulink - url="http://books.mcgraw-hill.com">McGrawHill</ulink>, + <para>FreeBSD: The Complete Reference, published by <link xlink:href="http://books.mcgraw-hill.com">McGrawHill</link>, 2003. ISBN: 0072224096 </para> </listitem> <listitem> - <para><ulink url="http://www.bsdmag.org">BSD Magazine</ulink>, + <para><link xlink:href="http://www.bsdmag.org">BSD Magazine</link>, published by Software Press Sp. z o.o. SK. ISSN 1898-9144</para> </listitem> </itemizedlist> </sect1> - <sect1 id="bibliography-userguides"> + <sect1 xml:id="bibliography-userguides"> <title>Users' Guides</title> <itemizedlist> <listitem> - <para>Ohio State University has written a <ulink - url="http://www.cs.duke.edu/csl/docs/unix_course/">UNIX - Introductory Course</ulink> which is available online in + <para>Ohio State University has written a <link xlink:href="http://www.cs.duke.edu/csl/docs/unix_course/">UNIX + Introductory Course</link> which is available online in HTML and PostScript format.</para> - <para>An Italian <ulink - url="&url.doc.base;/it_IT.ISO8859-15/books/unix-introduction/index.html">translation</ulink> + <para>An Italian <link xlink:href="&url.doc.base;/it_IT.ISO8859-15/books/unix-introduction/index.html">translation</link> of this document is available as part of the FreeBSD Italian Documentation Project.</para> </listitem> <listitem> - <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, - Japan FreeBSD Users Group</ulink>. <ulink - url="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD - User's Reference Manual</ulink> (Japanese translation). - <ulink url="http://www.pc.mycom.co.jp/">Mainichi - Communications Inc.</ulink>, 1998. ISBN4-8399-0088-4 + <para><link xlink:href="http://www.jp.FreeBSD.org/">Jpman Project, + Japan FreeBSD Users Group</link>. <link xlink:href="http://www.pc.mycom.co.jp/FreeBSD/urm.html">FreeBSD + User's Reference Manual</link> (Japanese translation). + <link xlink:href="http://www.pc.mycom.co.jp/">Mainichi + Communications Inc.</link>, 1998. ISBN4-8399-0088-4 P3800E.</para> </listitem> <listitem> - <para><ulink url="http://www.ed.ac.uk/">Edinburgh - University</ulink> has written an <ulink - url="http://unixhelp.ed.ac.uk/">Online Guide</ulink> for + <para><link xlink:href="http://www.ed.ac.uk/">Edinburgh + University</link> has written an <link xlink:href="http://unixhelp.ed.ac.uk/">Online Guide</link> for newcomers to the UNIX environment.</para> </listitem> </itemizedlist> </sect1> - <sect1 id="bibliography-adminguides"> + <sect1 xml:id="bibliography-adminguides"> <title>Administrators' Guides</title> <itemizedlist> <listitem> - <para><ulink url="http://www.jp.FreeBSD.org/">Jpman Project, - Japan FreeBSD Users Group</ulink>. <ulink - url="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD - System Administrator's Manual</ulink> (Japanese - translation). <ulink - url="http://www.pc.mycom.co.jp/">Mainichi Communications - Inc.</ulink>, 1998. ISBN4-8399-0109-0 P3300E.</para> + <para><link xlink:href="http://www.jp.FreeBSD.org/">Jpman Project, + Japan FreeBSD Users Group</link>. <link xlink:href="http://www.pc.mycom.co.jp/FreeBSD/sam.html">FreeBSD + System Administrator's Manual</link> (Japanese + translation). <link xlink:href="http://www.pc.mycom.co.jp/">Mainichi Communications + Inc.</link>, 1998. ISBN4-8399-0109-0 P3300E.</para> </listitem> <listitem> - <para>Dreyfus, Emmanuel. <ulink - url="http://www.eyrolles.com/Informatique/Livre/9782212114638/">Cahiers - de l'Admin: BSD</ulink> 2nd Ed. (in French), Eyrolles, + <para>Dreyfus, Emmanuel. <link xlink:href="http://www.eyrolles.com/Informatique/Livre/9782212114638/">Cahiers + de l'Admin: BSD</link> 2nd Ed. (in French), Eyrolles, 2004. ISBN 2-212-11463-X</para> </listitem> </itemizedlist> </sect1> - <sect1 id="bibliography-programmers"> + <sect1 xml:id="bibliography-programmers"> <title>Programmers' Guides</title> <itemizedlist> @@ -301,16 +281,14 @@ </listitem> <listitem> - <para>Spinellis, Diomidis. <ulink - url="http://www.spinellis.gr/codereading/"><emphasis>Code - Reading: The Open Source Perspective</emphasis></ulink>. + <para>Spinellis, Diomidis. <link xlink:href="http://www.spinellis.gr/codereading/"><emphasis>Code + Reading: The Open Source Perspective</emphasis></link>. Addison-Wesley, 2003. ISBN 0-201-79940-5</para> </listitem> <listitem> - <para>Spinellis, Diomidis. <ulink - url="http://www.spinellis.gr/codequality/"><emphasis>Code - Quality: The Open Source Perspective</emphasis></ulink>. + <para>Spinellis, Diomidis. <link xlink:href="http://www.spinellis.gr/codequality/"><emphasis>Code + Quality: The Open Source Perspective</emphasis></link>. Addison-Wesley, 2006. ISBN 0-321-16607-8</para> </listitem> @@ -329,7 +307,7 @@ </itemizedlist> </sect1> - <sect1 id="bibliography-osinternals"> + <sect1 xml:id="bibliography-osinternals"> <title>Operating System Internals</title> <itemizedlist> @@ -367,8 +345,7 @@ Reading, Mass. : Addison-Wesley, 1996. ISBN 0-201-54979-4</para> - <para>(Chapter 2 of this book is available <ulink - url="&url.books.design-44bsd;/book.html">online</ulink> as + <para>(Chapter 2 of this book is available <link xlink:href="&url.books.design-44bsd;/book.html">online</link> as part of the FreeBSD Documentation Project.)</para> </listitem> @@ -413,7 +390,7 @@ </itemizedlist> </sect1> - <sect1 id="bibliography-security"> + <sect1 xml:id="bibliography-security"> <title>Security Reference</title> <itemizedlist> @@ -432,7 +409,7 @@ </itemizedlist> </sect1> - <sect1 id="bibliography-hardware"> + <sect1 xml:id="bibliography-hardware"> <title>Hardware Reference</title> <itemizedlist> @@ -452,9 +429,8 @@ <listitem> <para>Intel Corporation publishes documentation on their CPUs, - chipsets and standards on their <ulink - url="http://developer.intel.com/">developer web - site</ulink>, usually as PDF files.</para> + chipsets and standards on their <link xlink:href="http://developer.intel.com/">developer web + site</link>, usually as PDF files.</para> </listitem> <listitem> @@ -489,7 +465,7 @@ </itemizedlist> </sect1> - <sect1 id="bibliography-history"> + <sect1 xml:id="bibliography-history"> <title>&unix; History</title> <itemizedlist> @@ -502,9 +478,8 @@ <listitem> <para>Raymond, Eric S. <emphasis>The New Hacker's Dictionary, 3rd edition</emphasis>. MIT Press, 1996. ISBN - 0-262-68092-0. Also known as the <ulink - url="http://www.catb.org/~esr/jargon/html/index.html">Jargon - File</ulink></para> + 0-262-68092-0. Also known as the <link xlink:href="http://www.catb.org/~esr/jargon/html/index.html">Jargon + File</link></para> </listitem> <listitem> @@ -517,8 +492,7 @@ <para>Simon Garfinkel, Daniel Weise, Steven Strassmann. <emphasis>The UNIX-HATERS Handbook</emphasis>. IDG Books Worldwide, Inc., 1994. ISBN 1-56884-203-1. Out of print, - but available <ulink - url="http://www.simson.net/ref/ugh.pdf">online</ulink>.</para> + but available <link xlink:href="http://www.simson.net/ref/ugh.pdf">online</link>.</para> </listitem> <listitem> @@ -529,24 +503,22 @@ <listitem> <para><emphasis>The BSD family tree</emphasis>. - <ulink - url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree"></ulink> + <uri xlink:href="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree">http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree</uri> or - <ulink type="html" - url="file://localhost/usr/share/misc/bsd-family-tree"><filename>/usr/share/misc/bsd-family-tree</filename></ulink> + <link xlink:href="file://localhost/usr/share/misc/bsd-family-tree"><filename>/usr/share/misc/bsd-family-tree</filename></link> on a FreeBSD machine.</para> </listitem> <listitem> <para><emphasis>Networked Computer Science Technical Reports Library</emphasis>. - <ulink url="http://www.ncstrl.org/"></ulink></para> + <uri xlink:href="http://www.ncstrl.org/">http://www.ncstrl.org/</uri></para> </listitem> <listitem> <para><emphasis>Old BSD releases from the Computer Systems Research group (CSRG)</emphasis>. - <ulink url="http://www.mckusick.com/csrg/"></ulink>: The + <uri xlink:href="http://www.mckusick.com/csrg/">http://www.mckusick.com/csrg/</uri>: The 4CD set covers all BSD versions from 1BSD to 4.4BSD and 4.4BSD-Lite2 (but not 2.11BSD, unfortunately). The last disk also holds the final sources plus the SCCS @@ -555,7 +527,7 @@ </itemizedlist> </sect1> - <sect1 id="bibliography-journals"> + <sect1 xml:id="bibliography-journals"> <title>Magazines and Journals</title> <itemizedlist> diff --git a/en_US.ISO8859-1/books/handbook/book.xml b/en_US.ISO8859-1/books/handbook/book.xml index e23d7ec009..7c90104eb8 100644 --- a/en_US.ISO8859-1/books/handbook/book.xml +++ b/en_US.ISO8859-1/books/handbook/book.xml @@ -1,6 +1,6 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!-- The FreeBSD Documentation Project @@ -12,12 +12,11 @@ <!ENTITY % txtfiles SYSTEM "txtfiles.ent"> %txtfiles; ]> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD Handbook</title> + -<book lang='en'> - <bookinfo> - <title>FreeBSD Handbook</title> - - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> <pubdate>$FreeBSD$</pubdate> @@ -48,7 +47,7 @@ &legalnotice; - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.3ware; @@ -93,26 +92,26 @@ dated and require updating. If you are interested in helping out with this project, send email to the &a.doc;. The latest version of this document is always available from the - <ulink url="http://www.FreeBSD.org/">FreeBSD web site</ulink> + <link xlink:href="http://www.FreeBSD.org/">FreeBSD web site</link> (previous versions of this handbook can be obtained from - <ulink url="http://docs.FreeBSD.org/doc/"></ulink>). It may + <uri xlink:href="http://docs.FreeBSD.org/doc/">http://docs.FreeBSD.org/doc/</uri>). It may also be downloaded in a variety of formats and compression options from the - <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD - FTP server</ulink> or one of the numerous + <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">FreeBSD + FTP server</link> or one of the numerous <link linkend="mirrors-ftp">mirror sites</link>. If you would prefer to have a hard copy of the handbook, you can purchase one at the - <ulink url="http://www.freebsdmall.com/">FreeBSD Mall</ulink>. + <link xlink:href="http://www.freebsdmall.com/">FreeBSD Mall</link>. You may also want to - <ulink url="&url.base;/search/index.html">search the - handbook</ulink>.</para> + <link xlink:href="&url.base;/search/index.html">search the + handbook</link>.</para> </abstract> - </bookinfo> + </info> &chap.preface; - <part id="getting-started"> + <part xml:id="getting-started"> <title>Getting Started</title> <partintro> @@ -158,7 +157,7 @@ &chap.x11; </part> - <part id="common-tasks"> + <part xml:id="common-tasks"> <title>Common Tasks</title> <partintro> @@ -207,7 +206,7 @@ &chap.linuxemu; </part> - <part id="system-administration"> + <part xml:id="system-administration"> <title>System Administration</title> <partintro> @@ -238,7 +237,7 @@ &chap.dtrace; </part> - <part id="network-communication"> + <part xml:id="network-communication"> <title>Network Communication</title> <partintro> @@ -287,7 +286,7 @@ </part> - <part id="appendices"> + <part xml:id="appendices"> <title>Appendices</title> &chap.mirrors; @@ -295,7 +294,7 @@ &chap.eresources; &chap.pgpkeys; </part> - &freebsd-glossary; + &chap.freebsd-glossary; &chap.index; &chap.colophon; </book> diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.xml b/en_US.ISO8859-1/books/handbook/boot/chapter.xml index 1af00bc7cc..5dd39b3640 100644 --- a/en_US.ISO8859-1/books/handbook/boot/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/boot/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - -<chapter id="boot"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="boot"> <title>The &os; Booting Process</title> - <sect1 id="boot-synopsis"> + <sect1 xml:id="boot-synopsis"> <title>Synopsis</title> <indexterm><primary>booting</primary></indexterm> @@ -54,7 +53,7 @@ </note> </sect1> - <sect1 id="boot-introduction"> + <sect1 xml:id="boot-introduction"> <title>The Booting Problem</title> <para>Turning on a computer and starting the operating system @@ -150,12 +149,12 @@ have been configured to run on a &os; system at startup.</para> </sect1> - <sect1 id="boot-blocks"> + <sect1 xml:id="boot-blocks"> <title>The Boot Manager and Boot Stages</title> <indexterm><primary>Boot Manager</primary></indexterm> - <sect2 id="boot-boot0"> + <sect2 xml:id="boot-boot0"> <title>The Boot Manager</title> <indexterm><primary>Master Boot Record @@ -182,7 +181,7 @@ will be displayed at boot time:</para> </formalpara> - <example id="boot-boot0-example"> + <example xml:id="boot-boot0-example"> <title><filename>boot0</filename> Screenshot</title> <screen>F1 Win @@ -197,14 +196,14 @@ Default: F2</screen> existing <acronym>MBR</acronym> with the &os; <acronym>MBR</acronym>, use the following command:</para> - <screen>&prompt.root; <userinput>fdisk -B -b /boot/boot0 <replaceable>device</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>fdisk -B -b /boot/boot0 device</userinput></screen> <para>where <replaceable>device</replaceable> is the boot disk, - such as <devicename>ad0</devicename> for the first - <acronym>IDE</acronym> disk, <devicename>ad2</devicename> + such as <filename>ad0</filename> for the first + <acronym>IDE</acronym> disk, <filename>ad2</filename> for the first <acronym>IDE</acronym> disk on a second <acronym>IDE</acronym> controller, or - <devicename>da0</devicename> + <filename>da0</filename> for the first <acronym>SCSI</acronym> disk. To create a custom configuration of the <acronym>MBR</acronym>, refer to &man.boot0cfg.8;.</para> @@ -235,7 +234,7 @@ label=FreeBSD</programlisting> messages.</para> </sect2> - <sect2 id="boot-boot1"> + <sect2 xml:id="boot-boot1"> <title>Stage One, <filename>/boot/boot1</filename>, and Stage Two, <filename>/boot/boot2</filename></title> @@ -269,7 +268,7 @@ label=FreeBSD</programlisting> provides a boot configuration which is run by <filename>boot2</filename>.</para> - <example id="boot-boot2-example"> + <example xml:id="boot-boot2-example"> <title><filename>boot2</filename> Screenshot</title> <screen>>> FreeBSD/i386 BOOT @@ -281,10 +280,10 @@ boot:</screen> <filename>boot1</filename> and <filename>boot2</filename>:</para> - <screen>&prompt.root; <userinput>bsdlabel -B <replaceable>diskslice</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>bsdlabel -B diskslice</userinput></screen> <para>where <replaceable>diskslice</replaceable> is the disk and - slice to boot from, such as <devicename>ad0s1</devicename> + slice to boot from, such as <filename>ad0s1</filename> for the first slice on the first <acronym>IDE</acronym> disk.</para> @@ -292,7 +291,7 @@ boot:</screen> <title>Dangerously Dedicated Mode</title> <para>If just the disk name is used, such as - <devicename>ad0</devicename>, &man.bsdlabel.8; will create a + <filename>ad0</filename>, &man.bsdlabel.8; will create a <quote>dangerously dedicated</quote> disk, without slices. This is probably not the desired action, so double check the <replaceable>diskslice</replaceable> passed to @@ -301,7 +300,7 @@ boot:</screen> </warning> </sect2> - <sect2 id="boot-loader"> + <sect2 xml:id="boot-loader"> <title>Stage Three, <filename>/boot/loader</filename></title> <indexterm><primary>boot-loader</primary></indexterm> @@ -315,7 +314,7 @@ boot:</screen> more powerful interpreter which has a more complex command set.</para> - <sect3 id="boot-loader-flow"> + <sect3 xml:id="boot-loader-flow"> <title>Loader Program Flow</title> <para>During initialization, the loader will probe for a @@ -344,7 +343,7 @@ boot:</screen> finally boot or reboot.</para> </sect3> - <sect3 id="boot-loader-commands"> + <sect3 xml:id="boot-loader-commands"> <title>Loader Built-In Commands</title> <para>These are the most commonly used loader commands. For a @@ -365,8 +364,8 @@ boot:</screen> <varlistentry> <term>boot - <optional><replaceable>-options</replaceable></optional> - <optional><replaceable>kernelname</replaceable></optional></term> + <optional>-options</optional> + <optional>kernelname</optional></term> <listitem> <para>Immediately proceeds to boot the kernel, with any @@ -392,7 +391,7 @@ boot:</screen> <varlistentry> <term>help - <optional><replaceable>topic</replaceable></optional></term> + <optional>topic</optional></term> <listitem> <para>Shows help messages read from @@ -414,8 +413,8 @@ boot:</screen> </varlistentry> <varlistentry> - <term>load <optional><option>-t</option> - <replaceable>type</replaceable></optional> + <term>load <optional>-t + type</optional> <replaceable>filename</replaceable></term> <listitem> @@ -427,8 +426,8 @@ boot:</screen> </varlistentry> <varlistentry> - <term>ls <optional><option>-l</option></optional> - <optional><replaceable>path</replaceable></optional></term> + <term>ls <optional>-l</optional> + <optional>path</optional></term> <listitem> <para>Displays a listing of files in the given path, or @@ -440,7 +439,7 @@ boot:</screen> <varlistentry> <term>lsdev - <optional><option>-v</option></optional></term> + <optional>-v</optional></term> <listitem> <para>Lists all of the devices from which it may be @@ -451,7 +450,7 @@ boot:</screen> <varlistentry> <term>lsmod - <optional><option>-v</option></optional></term> + <optional>-v</optional></term> <listitem> <para>Displays loaded modules. If <option>-v</option> @@ -496,7 +495,7 @@ boot:</screen> </variablelist> </sect3> - <sect3 id="boot-loader-examples"> + <sect3 xml:id="boot-loader-examples"> <title>Loader Examples</title> <para>Here are some practical examples of loader usage:</para> @@ -515,7 +514,7 @@ boot:</screen> load the previous or another kernel:</para> <screen><userinput>unload</userinput> -<userinput>load <replaceable>kernel.old</replaceable></userinput></screen> +<userinput>load kernel.old</userinput></screen> <para>Use <filename>kernel.GENERIC</filename> to refer to the default kernel that comes with an installation, or @@ -530,7 +529,7 @@ boot:</screen> another kernel:</para> <screen><userinput>unload</userinput> -<userinput>set kernel="<replaceable>kernel.old</replaceable>"</userinput> +<userinput>set kernel="kernel.old"</userinput> <userinput>boot-conf</userinput></screen></note> </listitem> @@ -538,23 +537,19 @@ boot:</screen> <para>To load an automated kernel configuration script:</para> - <screen><userinput>load -t userconfig_script <replaceable>/boot/kernel.conf</replaceable></userinput></screen> + <screen><userinput>load -t userconfig_script /boot/kernel.conf</userinput></screen> </listitem> </itemizedlist> </sect3> - <sect3 id="boot-splash"> - <sect3info> + <sect3 xml:id="boot-splash"> + <info><title>Boot Time Splash Screens</title> <authorgroup> - <author> - <firstname>Joseph J.</firstname> - <surname>Barbish</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Joseph J.</firstname><surname>Barbish</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect3info> + </info> - <title>Boot Time Splash Screens</title> + <para>The splash screen creates an alternate boot screen. The splash screen hides all the boot probe messages and service @@ -570,7 +565,7 @@ boot:</screen> and configure a graphical display manager and a graphical login manager.</para> - <sect4 id="boot-splash-function"> + <sect4 xml:id="boot-splash-function"> <title>Splash Screen Function</title> <para>The splash screen function supports 256-colors in the @@ -611,21 +606,19 @@ boot:</screen> boot time, even when the splash screen is enabled.</para> <para>Sample splash screen files can be downloaded from the - gallery at <ulink - url="http://artwork.freebsdgr.org/node/3/">http://artwork.freebsdgr.org</ulink>. - By installing the <filename - role="package">sysutils/bsd-splash-changer</filename> + gallery at <link xlink:href="http://artwork.freebsdgr.org/node/3/">http://artwork.freebsdgr.org</link>. + By installing the <package>sysutils/bsd-splash-changer</package> port, splash images can be chosen from a collection randomly at each boot.</para> </sect4> - <sect4 id="boot-splash-enable"> + <sect4 xml:id="boot-splash-enable"> <title>Enabling the Splash Screen Function</title> <para>The splash screen <filename>.bmp</filename>, <filename>.pcx</filename>, or <filename>.bin</filename> image has to be placed on the root partition, for example - in <filename class="directory">/boot</filename>.</para> + in <filename>/boot</filename>.</para> <para>For the default boot display resolution of 256-colors and 320 by 200 pixels or less, edit @@ -647,7 +640,7 @@ bitmap_load="YES" bitmap_name="<replaceable>/boot/splash.bmp</replaceable>"</programlisting> <para>This example assumes that - <filename><replaceable>/boot/splash.bmp</replaceable></filename> + <filename>/boot/splash.bmp</filename> is used for the splash screen. To use a <acronym>PCX</acronym> file, use the following statements, plus the <literal>vesa_load="YES"</literal> line, @@ -658,8 +651,7 @@ bitmap_load="YES" bitmap_name="<replaceable>/boot/splash.pcx</replaceable>"</programlisting> <para>Beginning with &os; 8.3, another option is to use - ASCII art in <ulink - url="https://en.wikipedia.org/wiki/TheDraw">TheDraw</ulink> + ASCII art in <link xlink:href="https://en.wikipedia.org/wiki/TheDraw">TheDraw</link> format.</para> <programlisting>splash_txt="YES" @@ -670,9 +662,9 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> <quote>splash</quote> as shown in the above example. It can be anything as long as it is one of the supported types such as, - <filename><replaceable>splash_640x400</replaceable>.bmp</filename> + <filename>splash_640x400.bmp</filename> or - <filename><replaceable>bluewave</replaceable>.pcx</filename>.</para> + <filename>bluewave.pcx</filename>.</para> <para>Other interesting <filename>loader.conf</filename> options include:</para> @@ -710,7 +702,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> </sect2> </sect1> - <sect1 id="boot-kernel"> + <sect1 xml:id="boot-kernel"> <title>Kernel Interaction During Boot</title> <indexterm> @@ -719,12 +711,11 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> </indexterm> <para>Once the kernel is loaded by either the default loader - (<xref linkend="boot-loader"/>) or by boot2 (<xref - linkend="boot-boot1"/>), which bypasses the loader, it + (<xref linkend="boot-loader"/>) or by boot2 (<xref linkend="boot-boot1"/>), which bypasses the loader, it examines any boot flags and adjusts its behavior as necessary.</para> - <sect2 id="boot-kernel-bootflags"> + <sect2 xml:id="boot-kernel-bootflags"> <title>Kernel Boot Flags</title> <indexterm> @@ -734,7 +725,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> <para>Here are the more common boot flags:</para> - <variablelist id="boot-kernel-bootflags-list"> + <variablelist xml:id="boot-kernel-bootflags-list"> <varlistentry> <term><option>-a</option></term> @@ -792,19 +783,15 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> </sect1> - <sect1 id="device-hints"> - <sect1info> + <sect1 xml:id="device-hints"> + <info><title>Device Hints</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- 18 OCT 2002 --> - </sect1info> + + </info> - <title>Device Hints</title> + <indexterm> <primary>device.hints</primary> @@ -817,8 +804,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> are used by device drivers for device configuration.</para> <para>Device hints may also be specified at the Stage 3 boot - loader prompt, as demonstrated in <xref - linkend="boot-loader"/>. + loader prompt, as demonstrated in <xref linkend="boot-loader"/>. Variables can be added using <command>set</command>, removed with <command>unset</command>, and viewed <command>show</command>. Variables set in @@ -834,11 +820,11 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> <quote>#</quote> as comment markers. Lines are constructed as follows:</para> - <screen><userinput>hint.driver.unit.keyword="<replaceable>value</replaceable>"</userinput></screen> + <screen><userinput>hint.driver.unit.keyword="value"</userinput></screen> <para>The syntax for the Stage 3 boot loader is:</para> - <screen><userinput>set hint.driver.unit.keyword=<replaceable>value</replaceable></userinput></screen> + <screen><userinput>set hint.driver.unit.keyword=value</userinput></screen> <para>where <literal>driver</literal> is the device driver name, <literal>unit</literal> is the device driver unit number, and @@ -888,7 +874,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> &man.kenv.1;, &man.loader.conf.5;, and &man.loader.8;.</para> </sect1> - <sect1 id="boot-init"> + <sect1 xml:id="boot-init"> <title>Init: Process Control Initialization</title> <indexterm> @@ -901,7 +887,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> in the <envar>init_path</envar> variable in <command>loader</command>.</para> - <sect2 id="boot-autoreboot"> + <sect2 xml:id="boot-autoreboot"> <title>Automatic Reboot Sequence</title> <para>The automatic reboot sequence makes sure that the file @@ -912,7 +898,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> administrator can resolve the problem directly.</para> </sect2> - <sect2 id="boot-singleuser"> + <sect2 xml:id="boot-singleuser"> <title>Single-User Mode</title> <indexterm><primary>single-user mode</primary></indexterm> @@ -929,10 +915,10 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> <para>If the system <literal>console</literal> is set to <literal>insecure</literal> in <filename>/etc/ttys</filename>, - the system will prompt for the <username>root</username> + the system will prompt for the <systemitem class="username">root</systemitem> password before initiating single-user mode.</para> - <example id="boot-insecure-console"> + <example xml:id="boot-insecure-console"> <title>An Insecure Console in <filename>/etc/ttys</filename></title> @@ -947,14 +933,14 @@ console none unknown off insecure</programlisting> <para>An <literal>insecure</literal> console means that physical security to the console is considered to be insecure, so only someone who knows the - <username>root</username> password may use single-user mode. + <systemitem class="username">root</systemitem> password may use single-user mode. Thus, to add this measure of security, choose <literal>insecure</literal>, instead of the default of <literal>secure</literal>.</para> </note> </sect2> - <sect2 id="boot-multiuser"> + <sect2 xml:id="boot-multiuser"> <title>Multi-User Mode</title> <indexterm><primary>multi-user mode</primary></indexterm> @@ -965,7 +951,7 @@ console none unknown off insecure</programlisting> multi-user mode, in which it starts the resource configuration of the system.</para> - <sect3 id="boot-rc"> + <sect3 xml:id="boot-rc"> <title>Resource Configuration</title> <indexterm><primary>rc files</primary></indexterm> @@ -987,7 +973,7 @@ console none unknown off insecure</programlisting> </sect2> </sect1> - <sect1 id="boot-shutdown"> + <sect1 xml:id="boot-shutdown"> <title>Shutdown Sequence</title> <indexterm> @@ -1005,8 +991,8 @@ console none unknown off insecure</programlisting> that support power management, use <command>shutdown -p now</command> to turn the power off immediately. To reboot a &os; system, use <command>shutdown -r now</command>. One must - be <username>root</username> or a member of - <groupname>operator</groupname> in order to run + be <systemitem class="username">root</systemitem> or a member of + <systemitem class="groupname">operator</systemitem> in order to run &man.shutdown.8;. One can also use &man.halt.8; and &man.reboot.8;. Refer to their manual pages and to &man.shutdown.8; for more information.</para> diff --git a/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml b/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml index 70e676e6c6..2b56d5f85a 100644 --- a/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/bsdinstall/chapter.xml @@ -4,43 +4,27 @@ $FreeBSD$ --> - -<chapter id="bsdinstall"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="bsdinstall"> + <info><title>Installing &os; 9.<replaceable>X</replaceable> and + Later</title> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Restructured, reorganized, and parts - rewritten by </contrib> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured, reorganized, and parts + rewritten by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Randy</firstname> - <surname>Pratt</surname> - <contrib>The sysinstall walkthrough, screenshots, and general - copy by </contrib> - </author> + <author><personname><firstname>Randy</firstname><surname>Pratt</surname></personname><contrib>The sysinstall walkthrough, screenshots, and general + copy by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Gavin</firstname> - <surname>Atkinson</surname> - <contrib>Updated for bsdinstall by </contrib> - </author> - - <author> - <firstname>Warren</firstname> - <surname>Block</surname> - </author> + <author><personname><firstname>Gavin</firstname><surname>Atkinson</surname></personname><contrib>Updated for bsdinstall by </contrib></author> + + <author><personname><firstname>Warren</firstname><surname>Block</surname></personname></author> </authorgroup> - </chapterinfo> + </info> - <title>Installing &os; 9.<replaceable>X</replaceable> and - Later</title> + - <sect1 id="bsdinstall-synopsis"> + <sect1 xml:id="bsdinstall-synopsis"> <title>Synopsis</title> <indexterm><primary>installation</primary></indexterm> @@ -52,8 +36,7 @@ <application>sysinstall</application> for installation. This chapter describes the use of <application>bsdinstall</application>. The use of - <application>sysinstall</application> is covered in <xref - linkend="install"/>.</para> + <application>sysinstall</application> is covered in <xref linkend="install"/>.</para> <para>After reading this chapter, you will know:</para> @@ -99,10 +82,10 @@ </note> </sect1> - <sect1 id="bsdinstall-hardware"> + <sect1 xml:id="bsdinstall-hardware"> <title>Hardware Requirements</title> - <sect2 id="bsdinstall-hardware-minimal"> + <sect2 xml:id="bsdinstall-hardware-minimal"> <title>Minimal Configuration</title> <para>The minimal configuration to install &os; varies with the @@ -111,8 +94,7 @@ <para>A summary of this information is given in the following sections. Depending on the method you choose to install &os;, you may also need a supported CDROM drive, and in some cases a - network adapter. This will be covered by <xref - linkend="bsdinstall-installation-media"/>.</para> + network adapter. This will be covered by <xref linkend="bsdinstall-installation-media"/>.</para> <sect3> <title>&os;/&arch.i386;</title> @@ -170,9 +152,8 @@ <title>&os;/&arch.sparc64;</title> <para>Systems supported by &os;/&arch.sparc64; are listed at - the <ulink - url="http://www.freebsd.org/platforms/sparc.html"> - FreeBSD/sparc64</ulink> Project.</para> + the <link xlink:href="http://www.freebsd.org/platforms/sparc.html"> + FreeBSD/sparc64</link> Project.</para> <para>A dedicated disk is required for &os;/&arch.sparc64;. It is not possible to share a disk with another operating @@ -180,20 +161,19 @@ </sect3> </sect2> - <sect2 id="bsdinstall-hardware-supported"> + <sect2 xml:id="bsdinstall-hardware-supported"> <title>Supported Hardware</title> <para>Hardware architectures and devices supported by a &os; release are listed in the Hardware Notes file. Usually named <filename>HARDWARE.TXT</filename>, the file is located in the root directory of the release media. Copies of the supported - hardware list are also available on the <ulink - url="http://www.FreeBSD.org/releases/index.html">Release - Information</ulink> page of the &os; web site.</para> + hardware list are also available on the <link xlink:href="http://www.FreeBSD.org/releases/index.html">Release + Information</link> page of the &os; web site.</para> </sect2> </sect1> - <sect1 id="bsdinstall-pre"> + <sect1 xml:id="bsdinstall-pre"> <title>Pre-Installation Tasks</title> <sect2> @@ -206,7 +186,7 @@ undone.</para> </sect2> - <sect2 id="bsdinstall-where"> + <sect2 xml:id="bsdinstall-where"> <title>Decide Where to Install &os;</title> <para>If &os; will be the only operating system installed, and @@ -215,7 +195,7 @@ with other operating systems, an understanding of disk layout is useful during the installation.</para> - <sect3 id="bsdinstall-where-i386"> + <sect3 xml:id="bsdinstall-where-i386"> <title>Disk Layouts for &os;/&arch.i386; and &os;/&arch.amd64;</title> @@ -238,8 +218,7 @@ <para>The <firstterm>GUID Partition Table</firstterm> (<acronym role="GUID Partition Table">GPT</acronym>) is a - newer and simpler method of partitioning a disk. <acronym - role="GUID Partition Table">GPT</acronym> is far more + newer and simpler method of partitioning a disk. <acronym role="GUID Partition Table">GPT</acronym> is far more versatile than the traditional MBR partition table. Common <acronym>GPT</acronym> implementations allow up to 128 partitions per disk, eliminating the need for inconvenient @@ -249,13 +228,11 @@ <para>Some older operating systems like &windows; XP are not compatible with the <acronym>GPT</acronym> partition scheme. If &os; will be sharing a disk with - such an operating system, <acronym role="Master Boot - Record">MBR</acronym> partitioning is required.</para> + such an operating system, <acronym role="Master Boot Record">MBR</acronym> partitioning is required.</para> </warning> <para>&os;'s standard boot loader requires either a primary or - <acronym>GPT</acronym> partition. (See <xref - linkend="boot"/> for more information about the &os; + <acronym>GPT</acronym> partition. (See <xref linkend="boot"/> for more information about the &os; booting process.) If all of the primary or <acronym>GPT</acronym> partitions are already in use, one must be freed for &os;.</para> @@ -268,12 +245,10 @@ user interface will be used. Third-party application software requires more space.</para> - <para>A variety of <ulink - url="http://en.wikipedia.org/wiki/List_of_disk_partitioning_software"> - free and commercial partition resizing tools</ulink> are - available. <ulink - url="http://gparted.sourceforge.net/livecd.php">GParted - Live</ulink> is a free Live CD which includes the <application>GParted</application> + <para>A variety of <link xlink:href="http://en.wikipedia.org/wiki/List_of_disk_partitioning_software"> + free and commercial partition resizing tools</link> are + available. <link xlink:href="http://gparted.sourceforge.net/livecd.php">GParted + Live</link> is a free Live CD which includes the <application>GParted</application> partition editor. <application>GParted</application> is also included with many other Linux Live CD distributions.</para> @@ -292,14 +267,14 @@ <para>A &windows; computer has a single 40 GB disk that has been split into two 20 GB partitions. &windows; - calls them <devicename>C:</devicename> and - <devicename>D:</devicename>. The - <devicename>C:</devicename> partition contains 10 GB - of data, and the <devicename>D:</devicename> partition + calls them <filename>C:</filename> and + <filename>D:</filename>. The + <filename>C:</filename> partition contains 10 GB + of data, and the <filename>D:</filename> partition contains 5 GB of data.</para> - <para>Moving the data from <devicename>D:</devicename> to - <devicename>C:</devicename> frees up the second partition + <para>Moving the data from <filename>D:</filename> to + <filename>C:</filename> frees up the second partition to be used for &os;.</para> </example> @@ -309,7 +284,7 @@ <para>A &windows; computer has a single 40 GB disk and one large partition using the whole disk. &windows; shows this 40 GB partition as a single - <devicename>C:</devicename>. 15 GB of space is being + <filename>C:</filename>. 15 GB of space is being used. The goal is to end up with &windows; in a 20 GB partition, and have another 20 GB partition for &os;.</para> @@ -340,7 +315,7 @@ </sect3> </sect2> - <sect2 id="bsdinstall-collect-network-information"> + <sect2 xml:id="bsdinstall-collect-network-information"> <title>Collect Network Information</title> <para>Some &os; installation methods need a network connection @@ -348,8 +323,7 @@ cable or DSL modem with an Ethernet interface), the installer will request some information about the network.</para> - <para><firstterm><acronym role="Dynamic Host Configuration - Protocol">DHCP</acronym></firstterm> is commonly used to + <para><firstterm><acronym role="Dynamic Host Configuration Protocol">DHCP</acronym></firstterm> is commonly used to provide automatic network configuration. If <acronym>DHCP</acronym> is not available, this network information must be obtained from the local network @@ -389,19 +363,17 @@ release of &os; is as stable as possible, bugs occasionally creep into the process. On very rare occasions those bugs affect the installation process. As these problems are - discovered and fixed, they are noted in the <ulink - url="&url.base;/releases/&rel.current;R/errata.html">FreeBSD - Errata</ulink> on the &os; web site. Check the errata before + discovered and fixed, they are noted in the <link xlink:href="&url.base;/releases/&rel.current;R/errata.html">FreeBSD + Errata</link> on the &os; web site. Check the errata before installing to make sure that there are no problems that might affect the installation.</para> <para>Information and errata for all the releases can be found - on the <ulink url="&url.base;/releases/index.html">release - information</ulink> section of the <ulink - url="&url.base;/index.html">&os; web site</ulink>.</para> + on the <link xlink:href="&url.base;/releases/index.html">release + information</link> section of the <link xlink:href="&url.base;/index.html">&os; web site</link>.</para> </sect2> - <sect2 id="bsdinstall-installation-media"> + <sect2 xml:id="bsdinstall-installation-media"> <title>Prepare the Installation Media</title> <para>A &os; installation is started by booting the computer @@ -418,8 +390,8 @@ during the install by only downloading required files.</para> <para>Copies of &os; installation media are available at the - <ulink url="&url.base;/where.html#download">&os; web - site</ulink>.</para> + <link xlink:href="&url.base;/where.html#download">&os; web + site</link>.</para> <tip> <para>If you already have a copy of &os; on CDROM, DVD, or USB @@ -434,22 +406,21 @@ <para>To create a bootable memory stick, follow these steps:</para> - <procedure id="bsdinstall-installation-media-memory-stick"> + <procedure xml:id="bsdinstall-installation-media-memory-stick"> <step> <title>Acquire the Memory Stick Image</title> <para>Memory stick images for &os; 9.0-RELEASE and later can be downloaded from the - <filename class="directory">ISO-IMAGES/</filename> + <filename>ISO-IMAGES/</filename> directory at - <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>version</replaceable>/&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</literal>. + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/arch/arch/ISO-IMAGES/version/&os;-version-RELEASE-arch-memstick.img</literal>. Replace <replaceable>arch</replaceable> and <replaceable>version</replaceable> with the architecture and the version number which you want to install, respectively. For example, the memory stick images for &os;/&arch.i386; 9.0-RELEASE are - available from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/9.0/&os;-9.0-RELEASE-&arch.i386;-memstick.img"></ulink>.</para> + available from <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/9.0/&os;-9.0-RELEASE-&arch.i386;-memstick.img">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/9.0/&os;-9.0-RELEASE-&arch.i386;-memstick.img</uri>.</para> <tip> <para>A different directory path is used for @@ -460,8 +431,7 @@ </tip> <para>The memory stick image has a <filename>.img</filename> - extension. The <filename - class="directory">ISO-IMAGES/</filename> directory + extension. The <filename>ISO-IMAGES/</filename> directory contains a number of different images, and the one needed depends on the version of &os; being installed, and in some cases, the target hardware.</para> @@ -480,8 +450,7 @@ <title>Using &os; to Write the Image</title> <warning> - <para>The example below shows <filename - class="devicefile">/dev/da0</filename> as the target + <para>The example below shows <filename>/dev/da0</filename> as the target device where the image will be written. Be very careful that the correct device is used as the output target, or you may destroy existing data.</para> @@ -498,7 +467,7 @@ written directly to the target device with &man.dd.1;:</para> - <screen>&prompt.root; <userinput>dd if=&os;-9.0-RELEASE-&arch.i386;-memstick.img of=/dev/<replaceable>da0</replaceable> bs=64k</userinput></screen> + <screen>&prompt.root; <userinput>dd if=&os;-9.0-RELEASE-&arch.i386;-memstick.img of=/dev/da0 bs=64k</userinput></screen> </step> </procedure> @@ -518,8 +487,7 @@ <para><application>Image Writer for &windows;</application> is a free application that can correctly write an image file to a memory stick. - Download it from <ulink - url="https://launchpad.net/win32-image-writer/"></ulink> + Download it from <uri xlink:href="https://launchpad.net/win32-image-writer/">https://launchpad.net/win32-image-writer/</uri> and extract it into a folder.</para> </step> @@ -553,7 +521,7 @@ </sect2> </sect1> - <sect1 id="bsdinstall-start"> + <sect1 xml:id="bsdinstall-start"> <title>Starting the Installation</title> <important> @@ -572,10 +540,10 @@ commit your changes?</literallayout> point, and no damage will be done.</para> </important> - <sect2 id="bsdinstall-starting"> + <sect2 xml:id="bsdinstall-starting"> <title>Booting</title> - <sect3 id="bsdinstall-starting-i386"> + <sect3 xml:id="bsdinstall-starting-i386"> <title>Booting on &i386; and &arch.amd64;</title> <procedure> @@ -594,8 +562,7 @@ commit your changes?</literallayout> <step> <para>Configure your machine to boot from either the CDROM or from USB, depending on the media being used for the - installation. <acronym role="Basic Input/Output - System">BIOS</acronym> configurations allow the + installation. <acronym role="Basic Input/Output System">BIOS</acronym> configurations allow the selection of a specific boot device. Most systems also provide for selecting a boot device during startup, typically by pressing <keycap>F10</keycap>, @@ -622,9 +589,8 @@ commit your changes?</literallayout> <listitem> <para>Your particular <acronym>BIOS</acronym> does not - support booting from the desired media. The <ulink - url="http://www.plop.at/en/bootmanager.html">Plop - Boot Manager</ulink> can be used to boot older + support booting from the desired media. The <link xlink:href="http://www.plop.at/en/bootmanager.html">Plop + Boot Manager</link> can be used to boot older computers from CD or USB media.</para> </listitem> </orderedlist> @@ -661,14 +627,12 @@ Loading /boot/defaults/loader.conf <step> <para>The &os; boot loader is displayed:</para> - <figure id="bsdinstall-boot-loader-menu"> + <figure xml:id="bsdinstall-boot-loader-menu"> <title>&os; Boot Loader Menu</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-boot-loader-menu" - /> + <imagedata fileref="bsdinstall/bsdinstall-boot-loader-menu"/> </imageobject> </mediaobject> </figure> @@ -697,14 +661,14 @@ Loading /boot/defaults/loader.conf <keycap>O</keycap> <keycap>F</keycap> </keycombo> - on non-&apple; keyboards. At the <prompt>0 ></prompt> + on non-&apple; keyboards. At the <prompt>0 ></prompt> prompt, enter</para> <screen><userinput>boot cd:,\ppc\loader cd:0</userinput></screen> <para>For Xserves without keyboards, see - <ulink url="http://support.apple.com/kb/TA26930">&apple;'s - support web site</ulink> about booting into Open + <link xlink:href="http://support.apple.com/kb/TA26930">&apple;'s + support web site</link> about booting into Open Firmware.</para> </sect3> @@ -714,8 +678,7 @@ Loading /boot/defaults/loader.conf <para>Most &sparc64; systems are set up to boot automatically from disk. To install &os;, you need to boot over the network or from a CDROM, which requires you to break into - the <acronym role="Programmable Read Only - Memory">PROM</acronym> (OpenFirmware).</para> + the <acronym role="Programmable Read Only Memory">PROM</acronym> (OpenFirmware).</para> <para>To do this, reboot the system, and wait until the boot message appears. It depends on the model, but should look @@ -728,19 +691,16 @@ Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> <para>If your system proceeds to boot from disk at this point, you need to press - <keycombo - action="simul"><keycap>L1</keycap><keycap>A</keycap></keycombo> + <keycombo action="simul"><keycap>L1</keycap><keycap>A</keycap></keycombo> or - <keycombo - action="simul"><keycap>Stop</keycap><keycap>A</keycap></keycombo> + <keycombo action="simul"><keycap>Stop</keycap><keycap>A</keycap></keycombo> on the keyboard, or send a <command>BREAK</command> over the serial console (using for example <command>~#</command> in - &man.tip.1; or &man.cu.1;) to get to the <acronym - role="Programmable Read Only Memory">PROM</acronym> + &man.tip.1; or &man.cu.1;) to get to the <acronym role="Programmable Read Only Memory">PROM</acronym> prompt. It looks like this:</para> - <screen><prompt>ok </prompt><co id="bsdinstall-prompt-single"/> -<prompt>ok {0} </prompt><co id="bsdinstall-prompt-smp"/></screen> + <screen><prompt>ok </prompt><co xml:id="bsdinstall-prompt-single"/> +<prompt>ok {0} </prompt><co xml:id="bsdinstall-prompt-smp"/></screen> <calloutlist> <callout arearefs="bsdinstall-prompt-single"> @@ -762,7 +722,7 @@ Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> </sect2> - <sect2 id="bsdinstall-view-probe"> + <sect2 xml:id="bsdinstall-view-probe"> <title>Reviewing the Device Probe Results</title> <para>The last few hundred lines that have been displayed on @@ -776,12 +736,11 @@ Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> <para>Do this now, to review the text that scrolled off the screen when the kernel was carrying out the device probes. - You will see text similar to <xref - linkend="bsdinstall-dev-probe"/>, although the precise text + You will see text similar to <xref linkend="bsdinstall-dev-probe"/>, although the precise text will differ depending on the devices that you have in your computer.</para> - <figure id="bsdinstall-dev-probe"> + <figure xml:id="bsdinstall-dev-probe"> <title>Typical Device Probe Results</title> <screen>Copyright (c) 1992-2011 The FreeBSD Project. @@ -935,8 +894,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>Check the probe results carefully to make sure that &os; found all the devices you expected. If a device was not - found, then it will not be listed. <link - linkend="kernelconfig-custom-kernel">Kernel modules</link> allows + found, then it will not be listed. <link linkend="kernelconfig-custom-kernel">Kernel modules</link> allows you to add in support for devices which are not in the <filename>GENERIC</filename> kernel.</para> @@ -947,13 +905,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> to simply access a &os; shell. Use the arrow keys to choose an option, and <keycap>Enter</keycap> to select.</para> - <figure id="bsdinstall-choose-mode"> + <figure xml:id="bsdinstall-choose-mode"> <title>Selecting Installation Media Mode</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-choose-mode" - /> + <imagedata fileref="bsdinstall/bsdinstall-choose-mode"/> </imageobject> </mediaobject> </figure> @@ -963,7 +920,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </sect2> </sect1> - <sect1 id="using-bsdinstall"> + <sect1 xml:id="using-bsdinstall"> <title>Introducing <application>bsdinstall</application></title> <para><application>bsdinstall</application> is a text-based &os; @@ -972,10 +929,9 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <note> <para>&a.kmoore.email;'s <application>pc-sysinstall</application> is - included with <ulink url="http://pcbsd.org">PC-BSD</ulink>, - and can also be used to <ulink - url="http://wiki.pcbsd.org/index.php/Use_PC-BSD_Installer_to_Install_FreeBSD"> - install &os;</ulink>. Although sometimes confused with + included with <link xlink:href="http://pcbsd.org">PC-BSD</link>, + and can also be used to <link xlink:href="http://wiki.pcbsd.org/index.php/Use_PC-BSD_Installer_to_Install_FreeBSD"> + install &os;</link>. Although sometimes confused with <application>bsdinstall</application>, the two are not related.</para> </note> @@ -985,21 +941,19 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <keycap>Tab</keycap>, <keycap>Space</keycap>, and other keys.</para> - <sect2 id="bsdinstall-keymap"> + <sect2 xml:id="bsdinstall-keymap"> <title>Selecting the Keymap Menu</title> <para>Depending on the system console being used, <application>bsdinstall</application> may initially prompt to select a non-default keyboard layout.</para> - <figure id="bsdinstall-keymap-select-default"> + <figure xml:id="bsdinstall-keymap-select-default"> <title>Keymap Selection</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-keymap-select-default" - /> + <imagedata fileref="bsdinstall/bsdinstall-keymap-select-default"/> </imageobject> </mediaobject> </figure> @@ -1009,13 +963,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> Otherwise, this selection menu will not be displayed, and a default keyboard mapping will be used.</para> - <figure id="bsdinstall-config-keymap"> + <figure xml:id="bsdinstall-config-keymap"> <title>Selecting Keyboard Menu</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-config-keymap" - /> + <imagedata fileref="bsdinstall/bsdinstall-config-keymap"/> </imageobject> </mediaobject> </figure> @@ -1032,43 +985,40 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </note> </sect2> - <sect2 id="bsdinstall-hostname"> + <sect2 xml:id="bsdinstall-hostname"> <title>Setting the Hostname</title> <para>Next, <application>bsdinstall</application> will prompt for the hostname to be given to the newly installed system.</para> - <figure id="bsdinstall-config-hostname"> + <figure xml:id="bsdinstall-config-hostname"> <title>Setting the Hostname</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-config-hostname" - /> + <imagedata fileref="bsdinstall/bsdinstall-config-hostname"/> </imageobject> </mediaobject> </figure> <para>The entered hostname should be a fully-qualified hostname, such as - <hostid role="fqdn">machine3.example.com</hostid></para> + <systemitem class="fqdomainname">machine3.example.com</systemitem></para> </sect2> - <sect2 id="bsdinstall-components"> + <sect2 xml:id="bsdinstall-components"> <title>Selecting Components to Install</title> <para>Next, <application>bsdinstall</application> will prompt to select optional components to install.</para> - <figure id="bsdinstall-config-components"> + <figure xml:id="bsdinstall-config-components"> <title>Selecting Components to Install</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-config-components" - /> + <imagedata fileref="bsdinstall/bsdinstall-config-components"/> </imageobject> </mediaobject> </figure> @@ -1142,7 +1092,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </sect2> </sect1> - <sect1 id="bsdinstall-netinstall"> + <sect1 xml:id="bsdinstall-netinstall"> <title>Installing from the Network</title> <para>The <emphasis>bootonly</emphasis> installation media does @@ -1151,13 +1101,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> files must be retrieved over a network connection as they are needed.</para> - <figure id="bsdinstall-netinstall-notify"> + <figure xml:id="bsdinstall-netinstall-notify"> <title>Installing from the Network</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-netinstall-files" - /> + <imagedata fileref="bsdinstall/bsdinstall-netinstall-files"/> </imageobject> </mediaobject> </figure> @@ -1170,14 +1119,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> retrieved more quickly when the mirror is close to the target computer, and installation time will be reduced.</para> - <figure id="bsdinstall-netinstall-mirror"> + <figure xml:id="bsdinstall-netinstall-mirror"> <title>Choosing a Mirror</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-netinstall-mirrorselect" - /> + <imagedata fileref="bsdinstall/bsdinstall-netinstall-mirrorselect"/> </imageobject> </mediaobject> </figure> @@ -1186,7 +1133,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> were located on local media.</para> </sect1> - <sect1 id="bsdinstall-partitioning"> + <sect1 xml:id="bsdinstall-partitioning"> <title>Allocating Disk Space</title> <para>There are three ways to allocate disk space for &os;. @@ -1197,32 +1144,28 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> programs like &man.gpart.8;, &man.fdisk.8;, and &man.bsdlabel.8; can be used directly.</para> - <figure id="bsdinstall-part-guided-manual"> + <figure xml:id="bsdinstall-part-guided-manual"> <title>Selecting Guided or Manual Partitioning</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-part-guided-manual" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-guided-manual"/> </imageobject> </mediaobject> </figure> - <sect2 id="bsdinstall-part-guided"> + <sect2 xml:id="bsdinstall-part-guided"> <title>Guided Partitioning</title> <para>If multiple disks are connected, choose the one where &os; is to be installed.</para> - <figure id="bsdinstall-part-guided-disk"> + <figure xml:id="bsdinstall-part-guided-disk"> <title>Selecting from Multiple Disks</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-part-guided-disk" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-guided-disk"/> </imageobject> </mediaobject> </figure> @@ -1235,14 +1178,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <guibutton>[ Partition ]</guibutton> creates a partition layout in unused space on the disk.</para> - <figure id="bsdinstall-part-entire-part"> + <figure xml:id="bsdinstall-part-entire-part"> <title>Selecting Entire Disk or Partition</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-part-entire-part" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-entire-part"/> </imageobject> </mediaobject> </figure> @@ -1257,50 +1198,45 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> correct, select <guibutton>[ Finish ]</guibutton> to continue with the installation.</para> - <figure id="bsdinstall-part-review"> + <figure xml:id="bsdinstall-part-review"> <title>Review Created Partitions</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-part-review" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-review"/> </imageobject> </mediaobject> </figure> </sect2> - <sect2 id="bsdinstall-part-manual"> + <sect2 xml:id="bsdinstall-part-manual"> <title>Manual Partitioning</title> <para>Manual partitioning goes straight to the partition editor.</para> - <figure id="bsdinstall-part-manual-create"> + <figure xml:id="bsdinstall-part-manual-create"> <title>Manually Create Partitions</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-part-manual-create" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-manual-create"/> </imageobject> </mediaobject> </figure> - <para>Highlighting a drive (<devicename>ada0</devicename> in + <para>Highlighting a drive (<filename>ada0</filename> in this example) and selecting <guibutton>[ Create ]</guibutton> displays a menu for choosing the type of <firstterm>partitioning scheme</firstterm>.</para> - <figure id="bsdinstall-part-manual-partscheme"> + <figure xml:id="bsdinstall-part-manual-partscheme"> <title>Manually Create Partitions</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-part-manual-partscheme" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-manual-partscheme"/> </imageobject> </mediaobject> </figure> @@ -1326,10 +1262,9 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <tbody> <row> <entry>APM</entry> - <entry><ulink - url="http://support.apple.com/kb/TA21692">Apple + <entry><link xlink:href="http://support.apple.com/kb/TA21692">Apple Partition Map, used by &powerpc; - &macintosh;.</ulink></entry> + &macintosh;.</link></entry> </row> <row> @@ -1341,24 +1276,21 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <row> <entry>GPT</entry> - <entry><ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Table.</ulink></entry> + <entry><link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Table.</link></entry> </row> <row> <entry>MBR</entry> - <entry><ulink - url="http://en.wikipedia.org/wiki/Master_boot_record">Master - Boot Record.</ulink></entry> + <entry><link xlink:href="http://en.wikipedia.org/wiki/Master_boot_record">Master + Boot Record.</link></entry> </row> <row> <entry>PC98</entry> - <entry><ulink - url="http://en.wikipedia.org/wiki/Pc9801">MBR + <entry><link xlink:href="http://en.wikipedia.org/wiki/Pc9801">MBR variant, used by NEC PC-98 - computers.</ulink></entry> + computers.</link></entry> </row> <row> @@ -1374,14 +1306,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> created, selecting <guibutton>[ Create ]</guibutton> again will create new partitions.</para> - <figure id="bsdinstall-part-manual-addpart"> + <figure xml:id="bsdinstall-part-manual-addpart"> <title>Manually Create Partitions</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-part-manual-addpart" - /> + <imagedata fileref="bsdinstall/bsdinstall-part-manual-addpart"/> </imageobject> </mediaobject> </figure> @@ -1464,7 +1394,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> lab's computer, for example.</para> </tip> - <example id="bsdinstall-part-manual-splitfs"> + <example xml:id="bsdinstall-part-manual-splitfs"> <title>Creating Traditional Split Filesystem Partitions</title> @@ -1512,7 +1442,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <row> <entry><literal>freebsd-swap</literal></entry> <entry><literal>4G</literal></entry> - <entry></entry> + <entry/> <entry><literal>exswap</literal></entry> </row> @@ -1548,20 +1478,18 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </sect2> </sect1> - <sect1 id="bsdinstall-final-warning"> + <sect1 xml:id="bsdinstall-final-warning"> <title>Committing to the Installation</title> <para>This is the last chance for aborting the installation to prevent changes to the hard drive.</para> - <figure id="bsdinstall-final-confirmation"> + <figure xml:id="bsdinstall-final-confirmation"> <title>Final Confirmation</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-final-confirmation" - /> + <imagedata fileref="bsdinstall/bsdinstall-final-confirmation"/> </imageobject> </mediaobject> </figure> @@ -1588,13 +1516,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> download the required distribution files.</para> <!-- XXXGA: What does it do if fetch fails? --> - <figure id="bsdinstall-distfile-fetching"> + <figure xml:id="bsdinstall-distfile-fetching"> <title>Fetching Distribution Files</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-distfile-fetching" - /> + <imagedata fileref="bsdinstall/bsdinstall-distfile-fetching"/> </imageobject> </mediaobject> </figure> @@ -1603,14 +1530,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> to ensure they have not been corrupted during download or misread from the installation media.</para> - <figure id="bsdinstall-distfile-verify"> + <figure xml:id="bsdinstall-distfile-verify"> <title>Verifying Distribution Files</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-distfile-verifying" - /> + <imagedata fileref="bsdinstall/bsdinstall-distfile-verifying"/> </imageobject> </mediaobject> </figure> @@ -1618,14 +1543,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>Finally, the verified distribution files are extracted to the disk.</para> - <figure id="bsdinstall-distfile-extract"> + <figure xml:id="bsdinstall-distfile-extract"> <title>Extracting Distribution Files</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-distfile-extracting" - /> + <imagedata fileref="bsdinstall/bsdinstall-distfile-extracting"/> </imageobject> </mediaobject> </figure> @@ -1636,7 +1559,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <xref linkend="bsdinstall-post"/>).</para> </sect1> - <sect1 id="bsdinstall-post"> + <sect1 xml:id="bsdinstall-post"> <title>Post-Installation</title> <para>Configuration of various options follows a successful @@ -1644,23 +1567,21 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> re-entering the configuration options from the final menu before booting into the newly installed &os; system.</para> - <sect2 id="bsdinstall-post-root"> - <title>Setting the <username>root</username> Password</title> + <sect2 xml:id="bsdinstall-post-root"> + <title>Setting the <systemitem class="username">root</systemitem> Password</title> - <para>The <username>root</username> password must be set. Note + <para>The <systemitem class="username">root</systemitem> password must be set. Note that while entering the password, the characters being typed are not displayed on the screen. After the password has been entered, it must be entered again. This helps prevent typing errors.</para> - <figure id="bsdinstall-post-set-root-passwd"> - <title>Setting the <username>root</username> Password</title> + <figure xml:id="bsdinstall-post-set-root-passwd"> + <title>Setting the <systemitem class="username">root</systemitem> Password</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-post-root-passwd" - /> + <imagedata fileref="bsdinstall/bsdinstall-post-root-passwd"/> </imageobject> </mediaobject> </figure> @@ -1669,7 +1590,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> installation will continue.</para> </sect2> - <sect2 id="bsdinstall-config-network-dev"> + <sect2 xml:id="bsdinstall-config-network-dev"> <title>Configuring Network Interfaces</title> <note> @@ -1681,19 +1602,17 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>A list of all the network interfaces found on the computer is shown next. Select one to be configured.</para> - <figure id="bsdinstall-configure-net-interface"> + <figure xml:id="bsdinstall-configure-net-interface"> <title>Choose a Network Interface</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface" - /> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface"/> </imageobject> </mediaobject> </figure> - <sect3 id="bsdinstall-configure-net-wireless"> + <sect3 xml:id="bsdinstall-configure-net-wireless"> <title>Configuring a Wireless Network Interface</title> <para>If a wireless network interface is chosen, wireless @@ -1702,13 +1621,11 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>Wireless networks are identified by a Service Set Identifier, or <acronym role="Service Set Identifier"> - SSID</acronym>. The <acronym role="Service Set - Identifier">SSID</acronym> is a short, unique name given to + SSID</acronym>. The <acronym role="Service Set Identifier">SSID</acronym> is a short, unique name given to each network.</para> <para>Most wireless networks encrypt transmitted data to - protect information from unauthorized viewing. <acronym - role="Wi-Fi Protected Access II">WPA2</acronym> encryption + protect information from unauthorized viewing. <acronym role="Wi-Fi Protected Access II">WPA2</acronym> encryption is strongly recommended. Older encryption types, like <acronym role="Wired Equivalent Privacy">WEP</acronym>, offer very little security.</para> @@ -1716,13 +1633,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>The first step in connecting to a wireless network is to scan for wireless access points.</para> - <figure id="bsdinstall-wireless-scan"> + <figure xml:id="bsdinstall-wireless-scan"> <title>Scanning for Wireless Access Points</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-wireless-scan"/> + <imagedata fileref="bsdinstall/bsdinstall-configure-wireless-scan"/> </imageobject> </mediaobject> </figure> @@ -1730,40 +1646,35 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para><acronym role="Service Set Identifiers">SSIDs</acronym> found during the scan are listed, followed by a description of the encryption types available for that network. If the - desired <acronym role="Service Set - Identifier">SSID</acronym> does not appear in the list, + desired <acronym role="Service Set Identifier">SSID</acronym> does not appear in the list, select <guibutton>[ Rescan ]</guibutton> to scan again. If the desired network still does not appear, check for problems with antenna connections or try moving the computer closer to the access point. Rescan after each change is made.</para> - <figure id="bsdinstall-wireless-accesspoints"> + <figure xml:id="bsdinstall-wireless-accesspoints"> <title>Choosing a Wireless Network</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-wireless-accesspoints"/> + <imagedata fileref="bsdinstall/bsdinstall-configure-wireless-accesspoints"/> </imageobject> </mediaobject> </figure> <para>The encryption information for connecting to the selected wireless network is entered after selecting the - network. With <acronym role="Wi-Fi Protected Access - II">WPA2</acronym>, only a password (also known as the - Pre-Shared Key, or <acronym role="Pre-Shared - Key">PSK</acronym>) is needed. Characters typed into the + network. With <acronym role="Wi-Fi Protected Access II">WPA2</acronym>, only a password (also known as the + Pre-Shared Key, or <acronym role="Pre-Shared Key">PSK</acronym>) is needed. Characters typed into the input box are shown as asterisks for security.</para> - <figure id="bsdinstall-wireless-wpa2"> + <figure xml:id="bsdinstall-wireless-wpa2"> <title>WPA2 Setup</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-wireless-wpa2setup"/> + <imagedata fileref="bsdinstall/bsdinstall-configure-wireless-wpa2setup"/> </imageobject> </mediaobject> </figure> @@ -1773,26 +1684,24 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> information.</para> </sect3> - <sect3 id="bsdinstall-ipv4"> + <sect3 xml:id="bsdinstall-ipv4"> <title>Configuring IPv4 Networking</title> <para>Choose whether IPv4 networking is to be used. This is the most common type of network connection.</para> - <figure id="bsdinstall-configure-net-ipv4"> + <figure xml:id="bsdinstall-configure-net-ipv4"> <title>Choose IPv4 Networking</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4"/> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4"/> </imageobject> </mediaobject> </figure> <para>There are two methods of IPv4 configuration. - <firstterm><acronym role="Dynamic Host Configuration - Protocol">DHCP</acronym></firstterm> will automatically + <firstterm><acronym role="Dynamic Host Configuration Protocol">DHCP</acronym></firstterm> will automatically configure the network interface correctly, and is the preferred method. <firstterm>Static</firstterm> configuration requires manual entry of network @@ -1805,40 +1714,36 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> from the network administrator or service provider.</para> </note> - <sect4 id="bsdinstall-net-ipv4-dhcp-config"> + <sect4 xml:id="bsdinstall-net-ipv4-dhcp-config"> <title>IPv4 DHCP Network Configuration</title> <para>If a DHCP server is available, select <guibutton>[ Yes ]</guibutton> to automatically configure the network interface.</para> - <figure id="bsdinstall-net-ipv4-dhcp"> + <figure xml:id="bsdinstall-net-ipv4-dhcp"> <title>Choose IPv4 DHCP Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-dhcp" - /> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-dhcp"/> </imageobject> </mediaobject> </figure> </sect4> - <sect4 id="bsdinstall-net-ipv4-static-config"> + <sect4 xml:id="bsdinstall-net-ipv4-static-config"> <title>IPv4 Static Network Configuration</title> <para>Static configuration of the network interface requires entry of some IPv4 information.</para> - <figure id="bsdinstall-net-ipv4-static"> + <figure xml:id="bsdinstall-net-ipv4-static"> <title>IPv4 Static Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-static" - /> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface-ipv4-static"/> </imageobject> </mediaobject> </figure> @@ -1870,7 +1775,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </sect4> </sect3> - <sect3 id="bsdinstall-ipv6"> + <sect3 xml:id="bsdinstall-ipv6"> <title>Configuring IPv6 Networking</title> <para>IPv6 is a newer method of network configuration. If @@ -1878,61 +1783,54 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <guibutton>[ Yes ]</guibutton> to select it.</para> - <figure id="bsdinstall-net-ipv6"> + <figure xml:id="bsdinstall-net-ipv6"> <title>Choose IPv6 Networking</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6"/> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6"/> </imageobject> </mediaobject> </figure> <para>IPv6 also has two methods of configuration. - <firstterm><acronym role="StateLess Address - AutoConfiguration">SLAAC</acronym> </firstterm>, or + <firstterm><acronym role="StateLess Address AutoConfiguration">SLAAC</acronym> </firstterm>, or <emphasis>StateLess Address AutoConfiguration</emphasis>, will automatically configure the network interface correctly. <firstterm>Static</firstterm> configuration requires manual entry of network information.</para> - <sect4 id="bsdinstall-net-ipv6-slaac-config"> + <sect4 xml:id="bsdinstall-net-ipv6-slaac-config"> <title>IPv6 Stateless Address Autoconfiguration</title> <para><acronym>SLAAC</acronym> allows an IPv6 network component to request autoconfiguration information from a - local router. See <ulink - url="http://tools.ietf.org/html/rfc4862">RFC4862</ulink> + local router. See <link xlink:href="http://tools.ietf.org/html/rfc4862">RFC4862</link> for more information.</para> - <figure id="bsdinstall-net-ipv6-slaac"> + <figure xml:id="bsdinstall-net-ipv6-slaac"> <title>Choose IPv6 SLAAC Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface-slaac" - /> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface-slaac"/> </imageobject> </mediaobject> </figure> </sect4> - <sect4 id="bsdinstall-net-ipv6-static-config"> + <sect4 xml:id="bsdinstall-net-ipv6-static-config"> <title>IPv6 Static Network Configuration</title> <para>Static configuration of the network interface requires entry of the IPv6 configuration information.</para> - <figure id="bsdinstall-net-ipv6-static"> + <figure xml:id="bsdinstall-net-ipv6-static"> <title>IPv6 Static Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6-static" - /> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-interface-ipv6-static"/> </imageobject> </mediaobject> </figure> @@ -1958,13 +1856,11 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </sect4> </sect3> - <sect3 id="bsdinstall-net-dns"> - <title>Configuring <acronym role="Domain Name - System">DNS</acronym></title> + <sect3 xml:id="bsdinstall-net-dns"> + <title>Configuring <acronym role="Domain Name System">DNS</acronym></title> <para>The <firstterm>Domain Name System</firstterm> (or - <emphasis><acronym role="Domain Name - System">DNS</acronym></emphasis>) Resolver converts + <emphasis><acronym role="Domain Name System">DNS</acronym></emphasis>) Resolver converts hostnames to and from network addresses. If <acronym>DHCP</acronym> or <acronym>SLAAC</acronym> was used to autoconfigure the network interface, the Resolver @@ -1975,20 +1871,19 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <acronym>DNS</acronym> servers. At least one <acronym>DNS</acronym> server is required.</para> - <figure id="bsdinstall-net-dns-config"> + <figure xml:id="bsdinstall-net-dns-config"> <title>DNS Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-configure-network-ipv4-dns"/> + <imagedata fileref="bsdinstall/bsdinstall-configure-network-ipv4-dns"/> </imageobject> </mediaobject> </figure> </sect3> </sect2> - <sect2 id="bsdinstall-timezone"> + <sect2 xml:id="bsdinstall-timezone"> <title>Setting the Time Zone</title> <para>Setting the time zone for your machine will allow it to @@ -1999,14 +1894,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> time zone of the United States. Your selections will vary according to your geographical location.</para> - <figure id="bsdinstall-local-utc"> + <figure xml:id="bsdinstall-local-utc"> <title>Select Local or UTC Clock</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-set-clock-local-utc" - /> + <imagedata fileref="bsdinstall/bsdinstall-set-clock-local-utc"/> </imageobject> </mediaobject> </figure> @@ -2019,13 +1912,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <guibutton>[ No ]</guibutton> to choose the more commonly-used local time.</para> - <figure id="bsdinstall-timezone-region"> + <figure xml:id="bsdinstall-timezone-region"> <title>Select a Region</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-timezone-region" - /> + <imagedata fileref="bsdinstall/bsdinstall-timezone-region"/> </imageobject> </mediaobject> </figure> @@ -2033,14 +1925,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>The appropriate region is selected using the arrow keys and then pressing <keycap>Enter</keycap>.</para> - <figure id="bsdinstall-timezone-country"> + <figure xml:id="bsdinstall-timezone-country"> <title>Select a Country</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-timezone-country" - /> + <imagedata fileref="bsdinstall/bsdinstall-timezone-country"/> </imageobject> </mediaobject> </figure> @@ -2048,13 +1938,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>Select the appropriate country using the arrow keys and press <keycap>Enter</keycap>.</para> - <figure id="bsdinstall-timezone-zone"> + <figure xml:id="bsdinstall-timezone-zone"> <title>Select a Time Zone</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-timezone-zone" - /> + <imagedata fileref="bsdinstall/bsdinstall-timezone-zone"/> </imageobject> </mediaobject> </figure> @@ -2062,14 +1951,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>The appropriate time zone is selected using the arrow keys and pressing <keycap>Enter</keycap>.</para> - <figure id="bsdinstall-timezone-confirmation"> + <figure xml:id="bsdinstall-timezone-confirmation"> <title>Confirm Time Zone</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-timezone-confirm" - /> + <imagedata fileref="bsdinstall/bsdinstall-timezone-confirm"/> </imageobject> </mediaobject> </figure> @@ -2079,19 +1966,18 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> with the post-installation configuration.</para> </sect2> - <sect2 id="bsdinstall-sysconf"> + <sect2 xml:id="bsdinstall-sysconf"> <title>Selecting Services to Enable</title> <para>Additional system services which will be started at boot can be enabled. All of these services are optional.</para> - <figure id="bsdinstall-config-serv"> + <figure xml:id="bsdinstall-config-serv"> <title>Selecting Additional Services to Enable</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-config-services" - /> + <imagedata fileref="bsdinstall/bsdinstall-config-services"/> </imageobject> </mediaobject> </figure> @@ -2123,7 +2009,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </itemizedlist> </sect2> - <sect2 id="bsdinstall-crashdump"> + <sect2 xml:id="bsdinstall-crashdump"> <title>Enabling Crash Dumps</title> <para><application>bsdinstall</application> will prompt if crash @@ -2134,52 +2020,48 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> enable crash dumps, or <guibutton>[ No ]</guibutton> to proceed without crash dumps enabled.</para> - <figure id="bsdinstall-config-crashdump"> + <figure xml:id="bsdinstall-config-crashdump"> <title>Enabling Crash Dumps</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-config-crashdump" - /> + <imagedata fileref="bsdinstall/bsdinstall-config-crashdump"/> </imageobject> </mediaobject> </figure> </sect2> - <sect2 id="bsdinstall-addusers"> + <sect2 xml:id="bsdinstall-addusers"> <title>Add Users</title> <para>Adding at least one user during the installation allows the system to be used without being logged in as - <username>root</username>. When logged in as - <username>root</username>, there are essentially no limits or + <systemitem class="username">root</systemitem>. When logged in as + <systemitem class="username">root</systemitem>, there are essentially no limits or protection on what can be done. Logging in as a normal user is safer and more secure.</para> <para>Select <guibutton>[ Yes ]</guibutton> to add new users.</para> - <figure id="bsdinstall-add-user1"> + <figure xml:id="bsdinstall-add-user1"> <title>Add User Accounts</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-adduser1" - /> + <imagedata fileref="bsdinstall/bsdinstall-adduser1"/> </imageobject> </mediaobject> </figure> <para>Enter the information for the user to be added.</para> - <figure id="bsdinstall-add-user2"> + <figure xml:id="bsdinstall-add-user2"> <title>Enter User Information</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-adduser2" - /> + <imagedata fileref="bsdinstall/bsdinstall-adduser2"/> </imageobject> </mediaobject> </figure> @@ -2209,7 +2091,7 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> </listitem> <listitem> - <para><literal>Invite <replaceable>user</replaceable> into + <para><literal>Invite user into other groups?</literal> - Additional groups to which the user will be added as a member.</para> </listitem> @@ -2274,13 +2156,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> everything is correct, enter <literal>yes</literal> to create the new user.</para> - <figure id="bsdinstall-add-user3"> + <figure xml:id="bsdinstall-add-user3"> <title>Exit User and Group Management</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-adduser3" - /> + <imagedata fileref="bsdinstall/bsdinstall-adduser3"/> </imageobject> </mediaobject> </figure> @@ -2294,20 +2175,18 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> see <xref linkend="users-synopsis"/>.</para> </sect2> - <sect2 id="bsdinstall-final-conf"> + <sect2 xml:id="bsdinstall-final-conf"> <title>Final Configuration</title> <para>After everything has been installed and configured, a final chance is provided to modify settings.</para> - <figure id="bsdinstall-final-config"> + <figure xml:id="bsdinstall-final-config"> <title>Final Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-finalconfiguration" - /> + <imagedata fileref="bsdinstall/bsdinstall-finalconfiguration"/> </imageobject> </mediaobject> </figure> @@ -2357,14 +2236,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>After any final configuration is complete, select <guibutton>Exit</guibutton> to leave the installation.</para> - <figure id="bsdinstall-final-modification-shell"> + <figure xml:id="bsdinstall-final-modification-shell"> <title>Manual Configuration</title> <mediaobject> <imageobject> - <imagedata - fileref="bsdinstall/bsdinstall-final-modification-shell" - /> + <imagedata fileref="bsdinstall/bsdinstall-final-modification-shell"/> </imageobject> </mediaobject> </figure> @@ -2377,13 +2254,12 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <guibutton>[ No ]</guibutton> to proceed to the last step of the installation.</para> - <figure id="bsdinstall-final-main"> + <figure xml:id="bsdinstall-final-main"> <title>Complete the Installation</title> <mediaobject> <imageobject> - <imagedata fileref="bsdinstall/bsdinstall-mainexit" - /> + <imagedata fileref="bsdinstall/bsdinstall-mainexit"/> </imageobject> </mediaobject> </figure> @@ -2399,10 +2275,10 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> computer may boot from it again.</para> </sect2> - <sect2 id="bsdinstall-freebsdboot"> + <sect2 xml:id="bsdinstall-freebsdboot"> <title>&os; Booting and Shutdown</title> - <sect3 id="bsdinstall-freebsdboot-i386"> + <sect3 xml:id="bsdinstall-freebsdboot-i386"> <title>&os;/&arch.i386; Booting</title> <para>As &os; boots, many informational messages are @@ -2418,8 +2294,8 @@ Trying to mount root from cd9660:/dev/iso9660/FREEBSD_INSTALL [ro]...</screen> <para>At the <prompt>login:</prompt> prompt, enter the username added during the installation, - <username>asample</username> in the example. Avoid logging - in as <username>root</username> except when + <systemitem class="username">asample</systemitem> in the example. Avoid logging + in as <systemitem class="username">root</systemitem> except when necessary.</para> <para>The scroll-back buffer examined above is limited in @@ -2605,15 +2481,15 @@ login:</screen> </sect3> </sect2> - <sect2 id="bsdinstall-shutdown"> + <sect2 xml:id="bsdinstall-shutdown"> <title>&os; Shutdown</title> <para>Proper shutdown of a &os; computer helps protect data and even hardware from damage. Do not just turn off the power. - If the user is a member of the <groupname>wheel</groupname> + If the user is a member of the <systemitem class="groupname">wheel</systemitem> group, become the superuser by typing <command>su</command> at - the command line and entering the <username>root</username> - password. Otherwise, log in as <username>root</username> and + the command line and entering the <systemitem class="username">root</systemitem> + password. Otherwise, log in as <systemitem class="username">root</systemitem> and use <command>shutdown -p now</command>. The system will close down cleanly and turn itself off.</para> @@ -2628,7 +2504,7 @@ login:</screen> </sect2> </sect1> - <sect1 id="bsdinstall-install-trouble"> + <sect1 xml:id="bsdinstall-install-trouble"> <title>Troubleshooting</title> <indexterm> @@ -2646,9 +2522,8 @@ login:</screen> impossible for probing to be 100% reliable, however, there are a few things you can do if it fails.</para> - <para>Check the <ulink - url="http://www.FreeBSD.org/releases/index.html">Hardware - Notes</ulink> document for your version of &os; to make sure + <para>Check the <link xlink:href="http://www.FreeBSD.org/releases/index.html">Hardware + Notes</link> document for your version of &os; to make sure your hardware is supported.</para> <para>If your hardware is supported and you still experience @@ -2721,7 +2596,7 @@ login:</screen> </sect2> </sect1> - <sect1 id="using-live-cd"> + <sect1 xml:id="using-live-cd"> <title>Using the Live CD</title> <para>A live CD of &os; is available on the same CD as the main diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent index d5cd395e7f..0bcc64c5d7 100644 --- a/en_US.ISO8859-1/books/handbook/chapters.ent +++ b/en_US.ISO8859-1/books/handbook/chapters.ent @@ -63,7 +63,7 @@ <!ENTITY chap.eresources.www.index.inc SYSTEM "eresources.xml.www.index.inc"> <!ENTITY chap.eresources.www.inc SYSTEM "eresources.xml.www.inc"> <!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.xml"> - <!ENTITY chap.freebsd-glossary "&freebsd-glossary;"> - <!ENTITY chap.index SYSTEM "index.xml"> + <!ENTITY chap.freebsd-glossary SYSTEM "../../share/xml/glossary.ent"> + <!ENTITY chap.index "<index xmlns='http://docbook.org/ns/docbook'/>"> <!ENTITY chap.colophon SYSTEM "colophon.xml"> diff --git a/en_US.ISO8859-1/books/handbook/colophon.xml b/en_US.ISO8859-1/books/handbook/colophon.xml index 0d93d9bb66..82b3cfd603 100644 --- a/en_US.ISO8859-1/books/handbook/colophon.xml +++ b/en_US.ISO8859-1/books/handbook/colophon.xml @@ -4,15 +4,14 @@ $FreeBSD$ --> - -<colophon id='colophon'> +<colophon xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="colophon"> <para>This book is the combined work of hundreds of contributors to <quote>The FreeBSD Documentation Project</quote>. The text is authored in XML according to the DocBook DTD and is formatted from XML into many different presentation formats using XSLT. The printed version of this document would not be possible without Donald Knuth's - <application>&tex;</application> typesetting language, Leslie + &tex; typesetting language, Leslie Lamport's <application>LaTeX</application>, or Sebastian Rahtz's <application>JadeTeX</application> macro package.</para> </colophon> diff --git a/en_US.ISO8859-1/books/handbook/config/chapter.xml b/en_US.ISO8859-1/books/handbook/config/chapter.xml index 004f4205fc..a45ad7beb9 100644 --- a/en_US.ISO8859-1/books/handbook/config/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/config/chapter.xml @@ -4,35 +4,22 @@ $FreeBSD$ --> - -<chapter id="config-tuning"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="config-tuning"> + <info><title>Configuration and Tuning</title> <authorgroup> - <author> - <firstname>Chern</firstname> - <surname>Lee</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Chern</firstname><surname>Lee</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Mike</firstname> - <surname>Smith</surname> - <contrib>Based on a tutorial written by </contrib> - </author> + <author><personname><firstname>Mike</firstname><surname>Smith</surname></personname><contrib>Based on a tutorial written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Matt</firstname> - <surname>Dillon</surname> - <contrib>Also based on tuning(7) written by </contrib> - </author> + <author><personname><firstname>Matt</firstname><surname>Dillon</surname></personname><contrib>Also based on tuning(7) written by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Configuration and Tuning</title> + - <sect1 id="config-synopsis"> + <sect1 xml:id="config-synopsis"> <title>Synopsis</title> <indexterm><primary>system configuration</primary></indexterm> @@ -53,8 +40,7 @@ <listitem> <para>The basics of <filename>rc.conf</filename> configuration - and <filename - class="directory">/usr/local/etc/rc.d</filename> startup + and <filename>/usr/local/etc/rc.d</filename> startup scripts.</para> </listitem> @@ -68,8 +54,7 @@ </listitem> <listitem> - <para>How to use the various configuration files in <filename - class="directory">/etc</filename>.</para> + <para>How to use the various configuration files in <filename>/etc</filename>.</para> </listitem> <listitem> @@ -86,8 +71,7 @@ <itemizedlist> <listitem> - <para>Understand &unix; and &os; basics (<xref - linkend="basics"/>).</para> + <para>Understand &unix; and &os; basics (<xref linkend="basics"/>).</para> </listitem> <listitem> @@ -97,7 +81,7 @@ </itemizedlist> </sect1> - <sect1 id="configtuning-initial"> + <sect1 xml:id="configtuning-initial"> <title>Initial Configuration</title> <sect2> @@ -105,13 +89,13 @@ <indexterm><primary>partition layout</primary></indexterm> <indexterm> - <primary><filename class="directory">/etc</filename></primary> + <primary><filename>/etc</filename></primary> </indexterm> <indexterm> - <primary><filename class="directory">/var</filename></primary> + <primary><filename>/var</filename></primary> </indexterm> <indexterm> - <primary><filename class="directory">/usr</filename></primary> + <primary><filename>/usr</filename></primary> </indexterm> <sect3> @@ -122,38 +106,35 @@ faster from the outer tracks to the inner. Thus, smaller and heavier-accessed file systems should be closer to the outside of the drive, while larger partitions like - <filename class="directory">/usr</filename> should be placed + <filename>/usr</filename> should be placed toward the inner parts of the disk. It is a good idea to - create partitions in an order similar to: <filename - class="directory">/</filename>, swap, - <filename class="directory">/var</filename>, and - <filename class="directory">/usr</filename>.</para> + create partitions in an order similar to: <filename>/</filename>, swap, + <filename>/var</filename>, and + <filename>/usr</filename>.</para> <para>The size of the - <filename class="directory">/var</filename> partition + <filename>/var</filename> partition reflects the intended machine's usage. This partition is used to hold mailboxes, log files, and printer spools. Mailboxes and log files can grow to unexpected sizes depending on the number of users and how long log files are kept. On average, most users rarely need more than - about a gigabyte of free disk space in <filename - class="directory">/var</filename>.</para> + about a gigabyte of free disk space in <filename>/var</filename>.</para> <note> <para>Sometimes, a lot of disk space is required in - <filename class="directory">/var/tmp</filename>. When + <filename>/var/tmp</filename>. When new software is installed with &man.pkg.add.1;, the packaging tools extract a temporary copy of the packages - under <filename class="directory">/var/tmp</filename>. + under <filename>/var/tmp</filename>. Large software packages, like <application>Firefox</application>, <application>OpenOffice</application> or <application>LibreOffice</application> may be tricky to - install if there is not enough disk space under <filename - class="directory">/var/tmp</filename>.</para> + install if there is not enough disk space under <filename>/var/tmp</filename>.</para> </note> - <para>The <filename class="directory">/usr</filename> + <para>The <filename>/usr</filename> partition holds many of the files which support the system, including the &os; Ports Collection and system source code. At least 2 gigabytes is recommended for this @@ -166,13 +147,13 @@ <note> <para>The <literal>Auto-defaults</literal> partition sizer used by &man.sysinstall.8; will sometimes select smaller - than adequate <filename class="directory">/var</filename> - and <filename class="directory">/</filename> partitions. + than adequate <filename>/var</filename> + and <filename>/</filename> partitions. Partition wisely and generously.</para> </note> </sect3> - <sect3 id="swap-design"> + <sect3 xml:id="swap-design"> <title>Swap Partition</title> <indexterm><primary>swap sizing</primary></indexterm> @@ -210,12 +191,9 @@ fine, but there are several reasons why this is a bad idea. First, each partition has different operational characteristics and separating them allows the file system - to tune accordingly. For example, the root and <filename - class="directory">/usr</filename> partitions are + to tune accordingly. For example, the root and <filename>/usr</filename> partitions are read-mostly, with few writes, while a lot of reads and - writes could occur in <filename - class="directory">/var</filename> and <filename - class="directory">/var/tmp</filename>.</para> + writes could occur in <filename>/var</filename> and <filename>/var/tmp</filename>.</para> <para>By properly partitioning a system, fragmentation introduced in the smaller write heavy partitions will not @@ -225,8 +203,7 @@ the most. While I/O performance in the larger partitions may be needed, shifting them more toward the edge of the disk will not lead to a significant performance - improvement over moving <filename - class="directory">/var</filename> to the edge. Finally, + improvement over moving <filename>/var</filename> to the edge. Finally, there are safety concerns. A smaller, neater root partition which is mostly read-only has a greater chance of surviving a bad crash.</para> @@ -234,7 +211,7 @@ </sect2> </sect1> - <sect1 id="configtuning-core-configuration"> + <sect1 xml:id="configtuning-core-configuration"> <title>Core Configuration</title> <indexterm> @@ -298,7 +275,7 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> </tip> </sect1> - <sect1 id="configtuning-appconfig"> + <sect1 xml:id="configtuning-appconfig"> <title>Application Configuration</title> <para>Typically, installed applications have their own @@ -309,8 +286,7 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> <indexterm><primary>/usr/local/etc</primary></indexterm> - <para>Typically, these files are installed in <filename - class="directory">/usr/local/etc</filename>. In the case + <para>Typically, these files are installed in <filename>/usr/local/etc</filename>. In the case where an application has a large number of configuration files, a subdirectory will be created to hold them.</para> @@ -322,8 +298,7 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> files.</para> <para>For example, consider the contents of the directory - <filename - class="directory">/usr/local/etc/apache</filename>:</para> + <filename>/usr/local/etc/apache</filename>:</para> <literallayout class="monospaced">-rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf -rw-r--r-- 1 root wheel 2184 May 20 1998 access.conf.default @@ -342,26 +317,22 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> this changed file.</para> </sect1> - <sect1 id="configtuning-starting-services"> - <sect1info> + <sect1 xml:id="configtuning-starting-services"> + <info><title>Starting Services</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Starting Services</title> + <indexterm><primary>services</primary></indexterm> <para>Many users install third party software on &os; from the Ports Collection and require the installed services to be started upon system initialization. Services, such as - <filename role="package">mail/postfix</filename> or - <filename role="package">www/apache22</filename> are just two + <package>mail/postfix</package> or + <package>www/apache22</package> are just two of the many software packages which may be started during system initialization. This section explains the procedures available for starting third party software.</para> @@ -374,8 +345,7 @@ ifconfig_fxp0="inet 10.1.1.1/8"</programlisting> <para>Now that &os; includes <filename>rc.d</filename>, configuration of application startup is easier and provides - more features. Using the key words discussed in <xref - linkend="configtuning-rcd"/>, applications can be set to + more features. Using the key words discussed in <xref linkend="configtuning-rcd"/>, applications can be set to start after certain other services and extra flags can be passed through <filename>/etc/rc.conf</filename> in place of hard coded flags in the start up script. A basic script may @@ -445,18 +415,13 @@ run_rc_command "$1"</programlisting> </sect2> </sect1> - <sect1 id="configtuning-cron"> - <sect1info> + <sect1 xml:id="configtuning-cron"> + <info><title>Configuring &man.cron.8;</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - <!-- 20 May 2003 --> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> - <title>Configuring &man.cron.8;</title> + </info> + <indexterm><primary>cron</primary> <secondary>configuration</secondary></indexterm> @@ -464,7 +429,7 @@ run_rc_command "$1"</programlisting> <para>One of the most useful utilities in &os; is &man.cron.8;. This utility runs in the background and regularly checks <filename>/etc/crontab</filename> for tasks to execute and - searches <filename class="directory">/var/cron/tabs</filename> + searches <filename>/var/cron/tabs</filename> for custom &man.crontab.5; files. These files store information about specific functions which &man.cron.8; is supposed to perform at certain times.</para> @@ -482,19 +447,19 @@ run_rc_command "$1"</programlisting> <note> <para>User crontabs allow individual users to schedule tasks - without the need for <username>root</username> privileges. + without the need for <systemitem class="username">root</systemitem> privileges. Commands in a user's crontab run with the permissions of the user who owns the crontab.</para> - <para>The <username>root</username> user can have a user + <para>The <systemitem class="username">root</systemitem> user can have a user <filename>crontab</filename> just like any other user. The - <username>root</username> user <filename>crontab</filename> + <systemitem class="username">root</systemitem> user <filename>crontab</filename> is separate from the system <filename>crontab</filename>, <filename>/etc/crontab</filename>. Because the system <filename>crontab</filename> invokes the specified commands as - <username>root</username>, there is usually no need to create + <systemitem class="username">root</systemitem>, there is usually no need to create a user <filename>crontab</filename> for - <username>root</username>.</para> + <systemitem class="username">root</systemitem>.</para> </note> <para>Here is a sample entry from @@ -503,14 +468,14 @@ run_rc_command "$1"</programlisting> <programlisting># /etc/crontab - root's crontab for FreeBSD # # $FreeBSD$ -# <co id="co-comments"/> +# <co xml:id="co-comments"/> # SHELL=/bin/sh -PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/> +PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co xml:id="co-env"/> # -#minute hour mday month wday who command <co id="co-field-descr"/> +#minute hour mday month wday who command <co xml:id="co-field-descr"/> # -*/5 * * * * root /usr/libexec/atrun <co id="co-main"/></programlisting> +*/5 * * * * root /usr/libexec/atrun <co xml:id="co-main"/></programlisting> <calloutlist> <callout arearefs="co-comments"> @@ -562,7 +527,7 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/> <literal>*</literal> characters mean <quote>first-last</quote>, and can be interpreted as <emphasis>every</emphasis> time. In this example, - &man.atrun.8; is invoked by <username>root</username> + &man.atrun.8; is invoked by <systemitem class="username">root</systemitem> every five minutes, regardless of the day or month.</para> <para>Commands can have any number of flags passed to them; @@ -577,7 +542,7 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/> exists in the system &man.crontab.5;. This field should be omitted for individual user &man.crontab.5; files.</para> - <sect2 id="configtuning-installcrontab"> + <sect2 xml:id="configtuning-installcrontab"> <title>Installing a Crontab</title> <important> @@ -586,9 +551,8 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/> <filename>/etc/crontab</filename>. Instead, use an editor and &man.cron.8; will notice that the file has changed and immediately begin using the updated version. - See <ulink - url="&url.books.faq;/admin.html#root-not-found-cron-errors"> - this FAQ entry</ulink> for more information.</para> + See <link xlink:href="&url.books.faq;/admin.html#root-not-found-cron-errors"> + this FAQ entry</link> for more information.</para> </important> <para>To install a freshly written user &man.crontab.5;, use @@ -616,23 +580,18 @@ PATH=/etc:/bin:/sbin:/usr/bin:/usr/sbin <co id="co-env"/> </sect2> </sect1> - <sect1 id="configtuning-rcd"> - <sect1info> + <sect1 xml:id="configtuning-rcd"> + <info><title>Using &man.rc.8; Under &os;</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - <!-- 16 May 2003 --> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Using &man.rc.8; Under &os;</title> + <para>In 2002, &os; integrated the NetBSD &man.rc.8; system for system initialization. The files listed in - <filename class="directory">/etc/rc.d</filename> provide basic + <filename>/etc/rc.d</filename> provide basic services which can be controlled with the <option>start</option>, <option>stop</option>, and <option>restart</option> options to &man.service.8;. For @@ -687,7 +646,7 @@ sshd_enable="YES" <note> <para>The <literal># sshd</literal> line is output from the - above command, not a <username>root</username> console.</para> + above command, not a <systemitem class="username">root</systemitem> console.</para> </note> <para>To determine whether or not a service is running, use @@ -764,25 +723,19 @@ sshd is running as pid 433.</screen> systems.</para> <para>Additional information can be found in &man.rc.8; and - &man.rc.subr.8;. Refer to <ulink - url="&url.articles.rc-scripting;">this article</ulink> for + &man.rc.subr.8;. Refer to <link xlink:href="&url.articles.rc-scripting;">this article</link> for instructions on how to create custom &man.rc.8; scripts.</para> </sect1> - <sect1 id="config-network-setup"> - <sect1info> + <sect1 xml:id="config-network-setup"> + <info><title>Setting Up Network Interface Cards</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Contributed by </contrib> - <!-- 6 October 2002 --> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Setting Up Network Interface Cards</title> + <indexterm> <primary>network cards</primary> @@ -810,7 +763,7 @@ sshd is running as pid 433.</screen> <para>If the <acronym>NIC</acronym> is supported, determine the name of the &os; driver for the <acronym>NIC</acronym>. Refer to <filename>/usr/src/sys/conf/NOTES</filename> and - <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename> + <filename>/usr/src/sys/arch/conf/NOTES</filename> for the list of <acronym>NIC</acronym> drivers with some information about the supported chipsets. When in doubt, read the manual page of the driver as it will provide more @@ -859,17 +812,16 @@ dc1: [ITHREAD]</screen> <para>Alternatively, statically compile support for the <acronym>NIC</acronym> into a custom kernel. Refer to <filename>/usr/src/sys/conf/NOTES</filename>, - <filename>/usr/src/sys/<replaceable>arch</replaceable>/conf/NOTES</filename> + <filename>/usr/src/sys/arch/conf/NOTES</filename> and the manual page of the driver to determine which line to add to the custom kernel configuration file. For more - information about recompiling the kernel, refer to <xref - linkend="kernelconfig"/>. If the + information about recompiling the kernel, refer to <xref linkend="kernelconfig"/>. If the <acronym>NIC</acronym> was detected at boot, the kernel does not need to be recompiled.</para> </listitem> </itemizedlist> - <sect3 id="config-network-ndis"> + <sect3 xml:id="config-network-ndis"> <title>Using &windows; <acronym>NDIS</acronym> Drivers</title> <indexterm><primary><acronym>NDIS</acronym></primary></indexterm> @@ -935,17 +887,17 @@ linuxemu/chapter.xml --> &os;/amd64, a &windows; 64-bit driver is needed.</para> <para>The next step is to compile the driver binary into a - loadable kernel module. As <username>root</username>, use + loadable kernel module. As <systemitem class="username">root</systemitem>, use &man.ndisgen.8;:</para> - <screen>&prompt.root; <userinput>ndisgen <replaceable>/path/to/W32DRIVER.INF</replaceable> <replaceable>/path/to/W32DRIVER.SYS</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ndisgen /path/to/W32DRIVER.INF /path/to/W32DRIVER.SYS</userinput></screen> <para>This command is interactive and prompts for any extra information it requires. A new kernel module will be generated in the current directory. Use &man.kldload.8; to load the new module:</para> - <screen>&prompt.root; <userinput>kldload <replaceable>./W32DRIVER_SYS.ko</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>kldload ./W32DRIVER_SYS.ko</userinput></screen> <para>In addition to the generated kernel module, the <filename>ndis.ko</filename> and @@ -971,13 +923,12 @@ ndis0: Ethernet address: 0a:b1:2c:d3:4e:f5 ndis0: 11b rates: 1Mbps 2Mbps 5.5Mbps 11Mbps ndis0: 11g rates: 6Mbps 9Mbps 12Mbps 18Mbps 36Mbps 48Mbps 54Mbps</screen> - <para>From here, <devicename>ndis0</devicename> can be + <para>From here, <filename>ndis0</filename> can be configured like any other <acronym>NIC</acronym>.</para> <para>To configure the system to load the &man.ndis.4; modules at boot time, copy the generated module, - <filename>W32DRIVER_SYS.ko</filename>, to <filename - class="directory">/boot/modules</filename>. Then, add the + <filename>W32DRIVER_SYS.ko</filename>, to <filename>/boot/modules</filename>. Then, add the following line to <filename>/boot/loader.conf</filename>:</para> @@ -1026,17 +977,17 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <itemizedlist> <listitem> - <para><devicename>dc0</devicename>: The first Ethernet + <para><filename>dc0</filename>: The first Ethernet interface.</para> </listitem> <listitem> - <para><devicename>dc1</devicename>: The second Ethernet + <para><filename>dc1</filename>: The second Ethernet interface.</para> </listitem> <listitem> - <para><devicename>lo0</devicename>: The loopback + <para><filename>lo0</filename>: The loopback device.</para> </listitem> </itemizedlist> @@ -1044,11 +995,11 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <para>&os; uses the driver name followed by the order in which the card is detected at boot to name the <acronym>NIC</acronym>. For example, - <devicename>sis2</devicename> is the third + <filename>sis2</filename> is the third <acronym>NIC</acronym> on the system using the &man.sis.4; driver.</para> - <para>In this example, <devicename>dc0</devicename> is up and + <para>In this example, <filename>dc0</filename> is up and running. The key indicators are:</para> <orderedlist> @@ -1059,33 +1010,29 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <listitem> <para>The card has an Internet (<literal>inet</literal>) - address, <hostid - role="ipaddr">192.168.1.3</hostid>.</para> + address, <systemitem class="ipaddress">192.168.1.3</systemitem>.</para> </listitem> <listitem> <para>It has a valid subnet mask - (<literal>netmask</literal>), where <hostid - role="netmask">0xffffff00</hostid> is the same as - <hostid role="netmask">255.255.255.0</hostid>.</para> + (<literal>netmask</literal>), where <systemitem class="netmask">0xffffff00</systemitem> is the same as + <systemitem class="netmask">255.255.255.0</systemitem>.</para> </listitem> <listitem> - <para>It has a valid broadcast address, <hostid - role="ipaddr">192.168.1.255</hostid>.</para> + <para>It has a valid broadcast address, <systemitem class="ipaddress">192.168.1.255</systemitem>.</para> </listitem> <listitem> <para>The <acronym>MAC</acronym> address of the card - (<literal>ether</literal>) is <hostid - role="mac">00:a0:cc:da:da:da</hostid>.</para> + (<literal>ether</literal>) is <systemitem class="etheraddress">00:a0:cc:da:da:da</systemitem>.</para> </listitem> <listitem> <para>The physical media selection is on autoselection mode (<literal>media: Ethernet autoselect (100baseTX <full-duplex>)</literal>). In this example, - <devicename>dc1</devicename> is configured to run with + <filename>dc1</filename> is configured to run with <literal>10baseT/UTP</literal> media. For more information on available media types for a driver, refer to its manual page.</para> @@ -1094,7 +1041,7 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <listitem> <para>The status of the link (<literal>status</literal>) is <literal>active</literal>, indicating that the carrier - signal is detected. For <devicename>dc1</devicename>, the + signal is detected. For <filename>dc1</filename>, the <literal>status: no carrier</literal> status is normal when an Ethernet cable is not plugged into the card.</para> @@ -1112,7 +1059,7 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <para>it would indicate the card has not been configured.</para> - <para>The card must be configured as <username>root</username>. + <para>The card must be configured as <systemitem class="username">root</systemitem>. The <acronym>NIC</acronym> configuration can be performed from the command line with &man.ifconfig.8; but will not persist after a reboot unless the configuration is also added @@ -1123,8 +1070,8 @@ lo0: flags=8049<UP,LOOPBACK,RUNNING,MULTICAST> metric 0 mtu 16384 <programlisting>ifconfig_dc0="inet 192.168.1.3 netmask 255.255.255.0" ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlisting> - <para>Replace <devicename>dc0</devicename> and - <devicename>dc1</devicename> and the <acronym>IP</acronym> + <para>Replace <filename>dc0</filename> and + <filename>dc1</filename> and the <acronym>IP</acronym> address information with the correct values for the system. Refer to the man page for the driver, &man.ifconfig.8;, and &man.rc.conf.5; for more details about the allowed options and @@ -1147,8 +1094,8 @@ ifconfig_dc1="inet 10.0.0.1 netmask 255.255.255.0 media 10baseT/UTP"</programlis access to the Internet is needed, manually configure the default gateway and the nameserver:</para> - <screen>&prompt.root; <userinput>echo 'defaultrouter="<replaceable>your_default_router</replaceable>"' >> /etc/rc.conf</userinput> -&prompt.root; <userinput>echo 'nameserver <replaceable>your_DNS_server</replaceable>' >> /etc/resolv.conf</userinput></screen> + <screen>&prompt.root; <userinput>echo 'defaultrouter="your_default_router"' >> /etc/rc.conf</userinput> +&prompt.root; <userinput>echo 'nameserver your_DNS_server' >> /etc/resolv.conf</userinput></screen> </note> </sect2> @@ -1282,7 +1229,7 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> </sect2> </sect1> - <sect1 id="configtuning-virtual-hosts"> + <sect1 xml:id="configtuning-virtual-hosts"> <title>Virtual Hosts</title> <indexterm><primary>virtual hosts</primary></indexterm> @@ -1303,7 +1250,7 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> <programlisting>ifconfig_fxp0_alias0="inet xxx.xxx.xxx.xxx netmask xxx.xxx.xxx.xxx"</programlisting> <para>Alias entries must start with - <literal>alias<replaceable>0</replaceable></literal> using a + <literal>alias0</literal> using a sequential number such as <literal>alias0</literal>, <literal>alias1</literal>, and so on. The configuration process will stop at the first @@ -1314,27 +1261,27 @@ round-trip min/avg/max/stddev = 0.700/0.729/0.766/0.025 ms</screen> represents the network's netmask. Any other addresses which fall within this network must have a netmask of all <literal>1</literal>s, expressed as either - <hostid role="netmask">255.255.255.255</hostid> or - <hostid role="netmask">0xffffffff</hostid>.</para> + <systemitem class="netmask">255.255.255.255</systemitem> or + <systemitem class="netmask">0xffffffff</systemitem>.</para> <para>For example, consider the case where the - <devicename>fxp0</devicename> interface is connected to two - networks: <hostid role="ipaddr">10.1.1.0</hostid> with a - netmask of <hostid role="netmask">255.255.255.0</hostid> and - <hostid role="ipaddr">202.0.75.16</hostid> with a netmask of - <hostid role="netmask">255.255.255.240</hostid>. The system + <filename>fxp0</filename> interface is connected to two + networks: <systemitem class="ipaddress">10.1.1.0</systemitem> with a + netmask of <systemitem class="netmask">255.255.255.0</systemitem> and + <systemitem class="ipaddress">202.0.75.16</systemitem> with a netmask of + <systemitem class="netmask">255.255.255.240</systemitem>. The system is to be configured to appear in the ranges - <hostid role="ipaddr">10.1.1.1</hostid> through - <hostid role="ipaddr">10.1.1.5</hostid> and - <hostid role="ipaddr">202.0.75.17</hostid> through - <hostid role="ipaddr">202.0.75.20</hostid>. Only the first + <systemitem class="ipaddress">10.1.1.1</systemitem> through + <systemitem class="ipaddress">10.1.1.5</systemitem> and + <systemitem class="ipaddress">202.0.75.17</systemitem> through + <systemitem class="ipaddress">202.0.75.20</systemitem>. Only the first address in a given network range should have a real netmask. - All the rest (<hostid role="ipaddr">10.1.1.2</hostid> through - <hostid role="ipaddr">10.1.1.5</hostid> and - <hostid role="ipaddr">202.0.75.18</hostid> through - <hostid role="ipaddr">202.0.75.20</hostid>) must be configured + All the rest (<systemitem class="ipaddress">10.1.1.2</systemitem> through + <systemitem class="ipaddress">10.1.1.5</systemitem> and + <systemitem class="ipaddress">202.0.75.18</systemitem> through + <systemitem class="ipaddress">202.0.75.20</systemitem>) must be configured with a netmask of - <hostid role="netmask">255.255.255.255</hostid>.</para> + <systemitem class="netmask">255.255.255.255</systemitem>.</para> <para>The following <filename>/etc/rc.conf</filename> entries configure the adapter correctly for this scenario:</para> @@ -1350,19 +1297,15 @@ ifconfig_fxp0_alias6="inet 202.0.75.19 netmask 255.255.255.255" ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting> </sect1> - <sect1 id="configtuning-syslog"> - <sect1info> + <sect1 xml:id="configtuning-syslog"> + <info><title>Configuring the System Logger, + <command>syslogd</command></title> <authorgroup> - <author> - <firstname>Niclas</firstname> - <surname>Zeising</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Niclas</firstname><surname>Zeising</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Configuring the System Logger, - <command>syslogd</command></title> + <indexterm><primary>system logging</primary></indexterm> <indexterm><primary>syslog</primary></indexterm> @@ -1379,8 +1322,7 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting> system logger, &man.syslogd.8;, and how to perform log rotation and log management using &man.newsyslog.8;. Focus will be on setting up and using &man.syslogd.8; on a local machine. For - more advanced setups using a separate loghost, see <xref - linkend="network-syslogd"/>.</para> + more advanced setups using a separate loghost, see <xref linkend="network-syslogd"/>.</para> <sect2> <title>Using <command>syslogd</command></title> @@ -1443,15 +1385,15 @@ ifconfig_fxp0_alias7="inet 202.0.75.20 netmask 255.255.255.255"</programlisting> # separators. If you are sharing this file between systems, you # may want to use only tabs as field separators here. # Consult the syslog.conf(5) manpage. -*.err;kern.warning;auth.notice;mail.crit /dev/console <co id="co-syslog-many-match"/> +*.err;kern.warning;auth.notice;mail.crit /dev/console <co xml:id="co-syslog-many-match"/> *.notice;authpriv.none;kern.debug;lpr.info;mail.crit;news.err /var/log/messages security.* /var/log/security auth.info;authpriv.info /var/log/auth.log -mail.info /var/log/maillog <co id="co-syslog-one-match"/> +mail.info /var/log/maillog <co xml:id="co-syslog-one-match"/> lpr.info /var/log/lpd-errs ftp.info /var/log/xferlog cron.* /var/log/cron -*.=debug /var/log/debug.log <co id="co-syslog-comparison"/> +*.=debug /var/log/debug.log <co xml:id="co-syslog-comparison"/> *.emerg * # uncomment this to log all writes to /dev/console to /var/log/console.log #console.info /var/log/console.log @@ -1464,7 +1406,7 @@ cron.* /var/log/cron # news.crit /var/log/news/news.crit # news.err /var/log/news/news.err # news.notice /var/log/news/news.notice -!ppp <co id="co-syslog-prog-spec"/> +!ppp <co xml:id="co-syslog-prog-spec"/> *.* /var/log/ppp.log !*</programlisting> @@ -1476,7 +1418,7 @@ cron.* /var/log/cron <literal>auth.notice</literal> and <literal>mail.crit</literal>, and send these log messages to the console - (<devicename>/dev/console</devicename>).</para> + (<filename>/dev/console</filename>).</para> </callout> <callout arearefs="co-syslog-one-match"> @@ -1642,11 +1584,11 @@ cron.* /var/log/cron </sect2> </sect1> - <sect1 id="configtuning-configfiles"> + <sect1 xml:id="configtuning-configfiles"> <title>Configuration Files</title> <sect2> - <title><filename class="directory">/etc</filename> + <title><filename>/etc</filename> Layout</title> <para>There are a number of directories in which configuration @@ -1659,58 +1601,50 @@ cron.* /var/log/cron <tbody> <row> - <entry><filename - class="directory">/etc</filename></entry> + <entry><filename>/etc</filename></entry> <entry>Generic system-specific configuration information.</entry> </row> <row> - <entry><filename - class="directory">/etc/defaults</filename></entry> + <entry><filename>/etc/defaults</filename></entry> <entry>Default versions of system configuration files.</entry> </row> <row> - <entry><filename - class="directory">/etc/mail</filename></entry> + <entry><filename>/etc/mail</filename></entry> <entry>Extra &man.sendmail.8; configuration and other <acronym>MTA</acronym> configuration files.</entry> </row> <row> - <entry><filename - class="directory">/etc/ppp</filename></entry> + <entry><filename>/etc/ppp</filename></entry> <entry>Configuration for both user- and kernel-ppp programs.</entry> </row> <row> - <entry><filename - class="directory">/etc/namedb</filename></entry> + <entry><filename>/etc/namedb</filename></entry> <entry>Default location for &man.named.8; data. Normally <filename>named.conf</filename> and zone files are stored here.</entry> </row> <row> - <entry><filename - class="directory">/usr/local/etc</filename></entry> + <entry><filename>/usr/local/etc</filename></entry> <entry>Configuration files for installed applications. May contain per-application subdirectories.</entry> </row> <row> - <entry><filename - class="directory">/usr/local/etc/rc.d</filename></entry> + <entry><filename>/usr/local/etc/rc.d</filename></entry> <entry>&man.rc.8; scripts for installed applications.</entry> </row> <row> - <entry><filename - class="directory">/var/db</filename></entry> + <entry><filename>/var/db</filename></entry> <entry>Automatically generated system-specific database files, such as the package database and the &man.locate.1; database.</entry> @@ -1852,7 +1786,7 @@ nameserver 147.11.100.30</programlisting> </sect2> </sect1> - <sect1 id="configtuning-sysctl"> + <sect1 xml:id="configtuning-sysctl"> <title>Tuning with &man.sysctl.8;</title> <indexterm><primary>sysctl</primary></indexterm> @@ -1896,7 +1830,7 @@ kern.maxfiles: 2088 -> 5000</screen> more information, refer to &man.sysctl.conf.5; and <xref linkend="configtuning-sysctlconf"/>.</para> - <sect2 id="configtuning-sysctlconf"> + <sect2 xml:id="configtuning-sysctlconf"> <title><filename>sysctl.conf</filename></title> <indexterm><primary>sysctl.conf</primary></indexterm> @@ -1922,18 +1856,13 @@ kern.logsigexit=0 security.bsd.see_other_uids=0</programlisting> </sect2> - <sect2 id="sysctl-readonly"> - <sect2info> + <sect2 xml:id="sysctl-readonly"> + <info><title>&man.sysctl.8; Read-only</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - <!-- 31 January 2003 --> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> - <title>&man.sysctl.8; Read-only</title> + </info> + <para>In some cases it may be desirable to modify read-only &man.sysctl.8; values, which will require a reboot of the @@ -1954,7 +1883,7 @@ device_probe_and_attach: cbb0 attach returned 12</screen> </sect2> </sect1> - <sect1 id="configtuning-disk"> + <sect1 xml:id="configtuning-disk"> <title>Tuning Disks</title> <para>The following section will discuss various tuning @@ -2131,7 +2060,7 @@ device_probe_and_attach: cbb0 attach returned 12</screen> </sect3> </sect2> - <sect2 id="soft-updates"> + <sect2 xml:id="soft-updates"> <title>Soft Updates</title> <indexterm><primary>Soft Updates</primary></indexterm> @@ -2301,7 +2230,7 @@ device_probe_and_attach: cbb0 attach returned 12</screen> </sect2> </sect1> - <sect1 id="configtuning-kernel-limits"> + <sect1 xml:id="configtuning-kernel-limits"> <title>Tuning Kernel Limits</title> <indexterm> @@ -2309,10 +2238,10 @@ device_probe_and_attach: cbb0 attach returned 12</screen> <secondary>kernel limits</secondary> </indexterm> - <sect2 id="file-process-limits"> + <sect2 xml:id="file-process-limits"> <title>File/Process Limits</title> - <sect3 id="kern-maxfiles"> + <sect3 xml:id="kern-maxfiles"> <title><varname>kern.maxfiles</varname></title> <indexterm> @@ -2427,7 +2356,7 @@ device_probe_and_attach: cbb0 attach returned 12</screen> </sect3> </sect2> - <sect2 id="nmbclusters"> + <sect2 xml:id="nmbclusters"> <title>Network Limits</title> <para>The <literal>NMBCLUSTERS</literal> kernel configuration @@ -2612,7 +2541,7 @@ kern.maxvnodes: 100000</screen> </sect2> </sect1> - <sect1 id="adding-swap-space"> + <sect1 xml:id="adding-swap-space"> <title>Adding Swap Space</title> <para>Sometimes a system requires more swap space. There are @@ -2621,10 +2550,9 @@ kern.maxvnodes: 100000</screen> on an existing partition.</para> <para>For information on how to encrypt swap space, which options - exist, and why it should be done, refer to <xref - linkend="swap-encrypting"/>.</para> + exist, and why it should be done, refer to <xref linkend="swap-encrypting"/>.</para> - <sect2 id="new-drive-swap"> + <sect2 xml:id="new-drive-swap"> <title>Swap on a New or Existing Hard Drive</title> <para>Adding a new hard drive for swap gives better performance @@ -2637,7 +2565,7 @@ kern.maxvnodes: 100000</screen> <para>Use &man.swapon.8; to add a swap partition to the system. For example:</para> - <screen>&prompt.root; <userinput>swapon<replaceable> /dev/ada1s1b</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>swapon /dev/ada1s1b</userinput></screen> <warning> <para>It is possible to use any partition not currently @@ -2657,7 +2585,7 @@ kern.maxvnodes: 100000</screen> <filename>/etc/fstab</filename>.</para> </sect2> - <sect2 id="nfs-swap"> + <sect2 xml:id="nfs-swap"> <title>Swapping over <literal>NFS</literal></title> <para>Swapping over <literal>NFS</literal> is only recommended @@ -2667,7 +2595,7 @@ kern.maxvnodes: 100000</screen> on &man.nfsd.8;.</para> </sect2> - <sect2 id="create-swapfile"> + <sect2 xml:id="create-swapfile"> <title>Swapfiles</title> <para>To create a swap file, specify its size. The following @@ -2723,22 +2651,15 @@ kern.maxvnodes: 100000</screen> </sect2> </sect1> - <sect1 id="acpi-overview"> - <sect1info> + <sect1 xml:id="acpi-overview"> + <info><title>Power and Resource Management</title> <authorgroup> - <author> - <firstname>Hiten</firstname> - <surname>Pandya</surname> - <contrib>Written by </contrib> - </author> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - </author> + <author><personname><firstname>Hiten</firstname><surname>Pandya</surname></personname><contrib>Written by </contrib></author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname></author> </authorgroup> - </sect1info> + </info> - <title>Power and Resource Management</title> + <para>It is important to utilize hardware resources in an efficient manner. Before the Advanced Configuration and Power @@ -2757,7 +2678,7 @@ kern.maxvnodes: 100000</screen> <acronym>ACPI</acronym>. References will be provided for further reading.</para> - <sect2 id="acpi-intro"> + <sect2 xml:id="acpi-intro"> <title>What Is ACPI?</title> <indexterm> @@ -2780,7 +2701,7 @@ kern.maxvnodes: 100000</screen> direct successor to <acronym>APM</acronym>.</para> </sect2> - <sect2 id="acpi-old-spec"> + <sect2 xml:id="acpi-old-spec"> <title>Shortcomings of Advanced Power Management</title> <para>The <acronym>APM</acronym> facility controls the power @@ -2827,7 +2748,7 @@ kern.maxvnodes: 100000</screen> &man.apm.4;.</para> </sect2> - <sect2 id="acpi-config"> + <sect2 xml:id="acpi-config"> <title>Configuring <acronym>ACPI</acronym></title> <para>The &man.acpi.4; driver is loaded by default at start @@ -2868,29 +2789,18 @@ kern.maxvnodes: 100000</screen> </sect2> </sect1> - <sect1 id="ACPI-debug"> - <sect1info> + <sect1 xml:id="ACPI-debug"> + <info><title>Using and Debugging &os; <acronym>ACPI</acronym></title> <authorgroup> - <author> - <firstname>Nate</firstname> - <surname>Lawson</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Nate</firstname><surname>Lawson</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Peter</firstname> - <surname>Schultz</surname> - <contrib>With contributions from </contrib> - </author> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - </author> + <author><personname><firstname>Peter</firstname><surname>Schultz</surname></personname><contrib>With contributions from </contrib></author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname></author> </authorgroup> - </sect1info> + </info> - <title>Using and Debugging &os; <acronym>ACPI</acronym></title> + <indexterm> <primary>ACPI</primary> @@ -2913,7 +2823,7 @@ kern.maxvnodes: 100000</screen> cause of problems and in debugging and developing a solution.</para> - <sect2 id="ACPI-submitdebug"> + <sect2 xml:id="ACPI-submitdebug"> <title>Submitting Debugging Information</title> <note> @@ -2923,8 +2833,8 @@ kern.maxvnodes: 100000</screen> </note> <para>When submitting a problem, send the following information - to <ulink url="mailto:freebsd-acpi@FreeBSD.org"> - freebsd-acpi@FreeBSD.org</ulink>:</para> + to <link xlink:href="mailto:freebsd-acpi@FreeBSD.org"> + freebsd-acpi@FreeBSD.org</link>:</para> <itemizedlist> <listitem> @@ -2960,7 +2870,7 @@ kern.maxvnodes: 100000</screen> very large. Generate a copy of the <acronym>ASL</acronym> by running this command:</para> - <screen>&prompt.root; <userinput>acpidump -dt > <replaceable>name</replaceable>-<replaceable>system</replaceable>.asl</userinput></screen> + <screen>&prompt.root; <userinput>acpidump -dt > name-system.asl</userinput></screen> <para>Substitute the login name for <replaceable>name</replaceable> and manufacturer/model for @@ -2980,7 +2890,7 @@ kern.maxvnodes: 100000</screen> it is likely that the problem has been reported before.</para> </sect2> - <sect2 id="ACPI-background"> + <sect2 xml:id="ACPI-background"> <title>Background</title> <indexterm> @@ -3015,17 +2925,14 @@ kern.maxvnodes: 100000</screen> <acronym>ACPI</acronym> subsystem. For &os;, &intel; has provided an interpreter (<acronym>ACPI-CA</acronym>) that is shared with &linux; and NetBSD. The path to the - <acronym>ACPI-CA</acronym> source code is <filename - class="directory">src/sys/contrib/dev/acpica</filename>. + <acronym>ACPI-CA</acronym> source code is <filename>src/sys/contrib/dev/acpica</filename>. The glue code that allows <acronym>ACPI-CA</acronym> to work - on &os; is in <filename - class="directory">src/sys/dev/acpica/Osd</filename>. + on &os; is in <filename>src/sys/dev/acpica/Osd</filename>. Finally, drivers that implement various - <acronym>ACPI</acronym> devices are found in <filename - class="directory">src/sys/dev/acpica</filename>.</para> + <acronym>ACPI</acronym> devices are found in <filename>src/sys/dev/acpica</filename>.</para> </sect2> - <sect2 id="ACPI-comprob"> + <sect2 xml:id="ACPI-comprob"> <title>Common Problems</title> <indexterm> @@ -3242,7 +3149,7 @@ hw.acpi.s4bios: 0</screen> </sect3> </sect2> - <sect2 id="ACPI-aslanddump"> + <sect2 xml:id="ACPI-aslanddump"> <title><acronym>ASL</acronym>, &man.acpidump.8;, and <acronym>IASL</acronym></title> @@ -3284,7 +3191,7 @@ hw.acpi.s4bios: 0</screen> <screen>&prompt.root; <userinput>iasl your.asl</userinput></screen> </sect2> - <sect2 id="ACPI-fixasl"> + <sect2 xml:id="ACPI-fixasl"> <title>Fixing the <acronym>ASL</acronym></title> <indexterm> @@ -3324,8 +3231,8 @@ hw.acpi.s4bios: 0</screen> <para>Some <acronym>AML</acronym> versions assume the user is running &windows;. To override this, set - <literal>hw.acpi.osname=<replaceable>"Windows - 2001"</replaceable></literal> in + <literal>hw.acpi.osname="Windows + 2001"</literal> in <filename>/boot/loader.conf</filename>, using the strings in the <acronym>ASL</acronym>.</para> </sect3> @@ -3367,11 +3274,11 @@ hw.acpi.s4bios: 0</screen> acpi_dsdt_name="/boot/DSDT.aml"</programlisting> <para>Be sure to copy <filename>DSDT.aml</filename> to - <filename class="directory">/boot</filename>.</para> + <filename>/boot</filename>.</para> </sect3> </sect2> - <sect2 id="ACPI-debugoutput"> + <sect2 xml:id="ACPI-debugoutput"> <title>Getting Debugging Output from <acronym>ACPI</acronym></title> @@ -3413,8 +3320,7 @@ acpi_dsdt_name="/boot/DSDT.aml"</programlisting> && make clean && make ACPI_DEBUG=1</userinput></screen> - <para>Install <filename>acpi.ko</filename> in <filename - class="directory">/boot/kernel</filename> and add the + <para>Install <filename>acpi.ko</filename> in <filename>/boot/kernel</filename> and add the desired level and layer to <filename>/boot/loader.conf</filename>. This example enables debug messages for all <acronym>ACPI-CA</acronym> components @@ -3435,7 +3341,7 @@ debug.acpi.level="ACPI_LV_ERROR"</programlisting> <filename>/boot/loader.conf</filename>.</para> </sect2> - <sect2 id="ACPI-References"> + <sect2 xml:id="ACPI-References"> <title>References</title> <para>More information about <acronym>ACPI</acronym> may be @@ -3448,19 +3354,17 @@ debug.acpi.level="ACPI_LV_ERROR"</programlisting> <listitem> <para>The <acronym>ACPI</acronym> Mailing List Archives - <ulink - url="http://lists.freebsd.org/pipermail/freebsd-acpi/"></ulink></para> + <uri xlink:href="http://lists.freebsd.org/pipermail/freebsd-acpi/">http://lists.freebsd.org/pipermail/freebsd-acpi/</uri></para> </listitem> <listitem> <para>The old <acronym>ACPI</acronym> Mailing List Archives - <ulink - url="http://home.jp.FreeBSD.org/mail-list/acpi-jp/"></ulink></para> + <uri xlink:href="http://home.jp.FreeBSD.org/mail-list/acpi-jp/">http://home.jp.FreeBSD.org/mail-list/acpi-jp/</uri></para> </listitem> <listitem> <para>The <acronym>ACPI</acronym> 2.0 Specification - <ulink url="http://acpi.info/spec.htm"></ulink></para> + <uri xlink:href="http://acpi.info/spec.htm">http://acpi.info/spec.htm</uri></para> </listitem> <listitem> @@ -3470,10 +3374,9 @@ debug.acpi.level="ACPI_LV_ERROR"</programlisting> </listitem> <listitem> - <para><ulink - url="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt"> + <para><link xlink:href="http://www.cpqlinux.com/acpi-howto.html#fix_broken_dsdt"> <acronym>DSDT</acronym> debugging - resource</ulink>.</para> + resource</link>.</para> </listitem> </itemizedlist> </sect2> diff --git a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml index 8f7638c6fe..17e54a11f0 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml @@ -4,47 +4,29 @@ $FreeBSD$ --> - -<chapter id="updating-upgrading"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="updating-upgrading"> + <info><title>Updating and Upgrading &os;</title> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Restructured, reorganized, and parts updated - by </contrib> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured, reorganized, and parts updated + by </contrib></author> <!-- Mar 2000 --> </authorgroup> <authorgroup> - <author> - <firstname>Jordan</firstname> - <surname>Hubbard</surname> - <contrib>Original work by </contrib> - </author> - - <author> - <firstname>Poul-Henning</firstname> - <surname>Kamp</surname> - </author> - - <author> - <firstname>John</firstname> - <surname>Polstra</surname> - </author> - - <author> - <firstname>Nik</firstname> - <surname>Clayton</surname> - </author> + <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Original work by </contrib></author> + + <author><personname><firstname>Poul-Henning</firstname><surname>Kamp</surname></personname></author> + + <author><personname><firstname>John</firstname><surname>Polstra</surname></personname></author> + + <author><personname><firstname>Nik</firstname><surname>Clayton</surname></personname></author> </authorgroup> - <!-- with feedback from various others --> - </chapterinfo> + + </info> - <title>Updating and Upgrading &os;</title> + - <sect1 id="updating-upgrading-synopsis"> + <sect1 xml:id="updating-upgrading-synopsis"> <title>Synopsis</title> <para>&os; is under constant development between releases. Some @@ -98,8 +80,7 @@ <itemizedlist> <listitem> - <para>Properly set up the network connection (<xref - linkend="advanced-networking"/>).</para> + <para>Properly set up the network connection (<xref linkend="advanced-networking"/>).</para> </listitem> <listitem> @@ -111,29 +92,21 @@ <note> <para>Throughout this chapter, <command>svn</command> is used to obtain and update &os; sources. To use it, first install the - <filename role="package">devel/subversion</filename> port or + <package>devel/subversion</package> port or package.</para> </note> </sect1> - <sect1 id="updating-upgrading-freebsdupdate"> - <sect1info> + <sect1 xml:id="updating-upgrading-freebsdupdate"> + <info><title>&os; Update</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Colin</firstname> - <surname>Percival</surname> - <contrib>Based on notes provided by </contrib> - </author> + <author><personname><firstname>Colin</firstname><surname>Percival</surname></personname><contrib>Based on notes provided by </contrib></author> </authorgroup> - </sect1info> - <title>&os; Update</title> + </info> + <indexterm><primary>Updating and Upgrading</primary></indexterm> <indexterm> @@ -160,15 +133,14 @@ releases currently supported by the security team. Before updating to a new release, its release announcement should be reviewed as it contains important information pertinent to the - release. Release announcements are available from <ulink - url="http://www.FreeBSD.org/releases/"></ulink>.</para> + release. Release announcements are available from <uri xlink:href="http://www.FreeBSD.org/releases/">http://www.FreeBSD.org/releases/</uri>.</para> </note> <para>If a <command>crontab</command> utilizing the features of &man.freebsd-update.8; exists, it must be disabled before the following operation is started.</para> - <sect2 id="freebsdupdate-config-file"> + <sect2 xml:id="freebsdupdate-config-file"> <title>The Configuration File</title> <para>Some users may wish to tweak the default configuration @@ -186,7 +158,7 @@ Components src world kernel</programlisting> as those available during installation. For instance, adding <literal>world/games</literal> would allow game patches to be applied. Using <literal>src/bin</literal> would allow the - source code in <filename class="directory">src/bin</filename> + source code in <filename>src/bin</filename> to be updated.</para> <para>The best option is to leave this at the default as @@ -200,8 +172,8 @@ Components src world kernel</programlisting> IgnorePaths</programlisting> <para>To leave specified directories, such as - <filename class="directory">/bin</filename> or - <filename class="directory">/sbin</filename>, untouched during + <filename>/bin</filename> or + <filename>/sbin</filename>, untouched during the update process, add their paths to this statement. This option may be used to prevent <command>freebsd-update</command> from overwriting local @@ -230,7 +202,7 @@ MergeChanges /etc/ /var/named/etc/</programlisting> similar to &man.mergemaster.8;, but with fewer options. Merges are either accepted, open an editor, or <command>freebsd-update</command> will abort. When in doubt, - backup <filename class="directory">/etc</filename> and just + backup <filename>/etc</filename> and just accept the merges. See <xref linkend="mergemaster"/> for more information about <command>mergemaster</command>.</para> @@ -258,7 +230,7 @@ MergeChanges /etc/ /var/named/etc/</programlisting> list.</para> </sect2> - <sect2 id="freebsdupdate-security-patches"> + <sect2 xml:id="freebsdupdate-security-patches"> <title>Security Patches</title> <para>&os; security patches may be downloaded and installed @@ -281,7 +253,7 @@ MergeChanges /etc/ /var/named/etc/</programlisting> <command>freebsd-update</command> will only check if updates exist. If patches exist, they will automatically be downloaded to the local disk but will not be applied. The - <username>root</username> user will be sent an email so that + <systemitem class="username">root</systemitem> user will be sent an email so that they may be reviewed and manually installed.</para> <para>If anything goes wrong, <command>freebsd-update</command> @@ -301,14 +273,14 @@ MergeChanges /etc/ /var/named/etc/</programlisting> finishes installing the rest of the updates. However, <command>freebsd-update</command> will detect and update the <filename>GENERIC</filename> kernel if - <filename class="directory">/boot/GENERIC</filename> exists, + <filename>/boot/GENERIC</filename> exists, even if it is not the current running kernel of the system.</para> <note> <para>It is a good idea to always keep a copy of the <filename>GENERIC</filename> kernel in - <filename class="directory">/boot/GENERIC</filename>. It + <filename>/boot/GENERIC</filename>. It will be helpful in diagnosing a variety of problems, and in performing version upgrades using <command>freebsd-update</command> as described in @@ -341,7 +313,7 @@ MergeChanges /etc/ /var/named/etc/</programlisting> </note> </sect2> - <sect2 id="freebsdupdate-upgrade"> + <sect2 xml:id="freebsdupdate-upgrade"> <title>Major and Minor Version Upgrades</title> <para>Upgrades from one minor version of &os; to another, like @@ -357,7 +329,7 @@ MergeChanges /etc/ /var/named/etc/</programlisting> party applications. It is recommended that all installed ports either be removed and re-installed or upgraded after a major version upgrade using a utility such as - <filename role="package">ports-mgmt/portmaster</filename>. A + <package>ports-mgmt/portmaster</package>. A brute-force rebuild of all installed applications can be accomplished with this command:</para> @@ -365,24 +337,23 @@ MergeChanges /etc/ /var/named/etc/</programlisting> <para>This will ensure everything will be re-installed correctly. Note that setting the - <makevar>BATCH</makevar> environment variable to + <varname>BATCH</varname> environment variable to <literal>yes</literal> will answer <literal>yes</literal> to any prompts during this process, removing the need for manual intervention during the build process.</para> - <sect3 id="freebsd-update-custom-kernel"> + <sect3 xml:id="freebsd-update-custom-kernel"> <title>Dealing with Custom Kernels</title> <para>If a custom kernel is in use, the upgrade process is slightly more involved, and the procedure varies depending on the version of &os;.</para> - <sect4 id="freebsd-update-custom-kernel-8x"> + <sect4 xml:id="freebsd-update-custom-kernel-8x"> <title>Custom Kernels with &os; 8.X</title> <para>A copy of the <filename>GENERIC</filename> kernel is - needed, and should be placed in <filename - class="directory">/boot/GENERIC</filename>. If the + needed, and should be placed in <filename>/boot/GENERIC</filename>. If the <filename>GENERIC</filename> kernel is not present in the system, it may be obtained using one of the following methods:</para> @@ -390,11 +361,9 @@ MergeChanges /etc/ /var/named/etc/</programlisting> <itemizedlist> <listitem> <para>If a custom kernel has only been built once, the - kernel in <filename - class="directory">/boot/kernel.old</filename> is + kernel in <filename>/boot/kernel.old</filename> is actually <filename>GENERIC</filename>. Rename this - directory to <filename - class="directory">/boot/GENERIC</filename>.</para> + directory to <filename>/boot/GENERIC</filename>.</para> </listitem> <listitem> @@ -404,15 +373,13 @@ MergeChanges /etc/ /var/named/etc/</programlisting> using the following commands:</para> <screen>&prompt.root; <userinput>mount /cdrom</userinput> -&prompt.root; <userinput>cd /cdrom/<replaceable>X.Y-RELEASE</replaceable>/kernels</userinput> +&prompt.root; <userinput>cd /cdrom/X.Y-RELEASE/kernels</userinput> &prompt.root; <userinput>./install.sh GENERIC</userinput></screen> - <para>Replace <filename - class="directory"><replaceable>X.Y-RELEASE</replaceable></filename> + <para>Replace <filename>X.Y-RELEASE</filename> with the actual version of the release being used. The <filename>GENERIC</filename> kernel will be - installed in <filename - class="directory">/boot/GENERIC</filename> by + installed in <filename>/boot/GENERIC</filename> by default.</para> </listitem> @@ -440,18 +407,16 @@ MergeChanges /etc/ /var/named/etc/</programlisting> is not required at this stage.</para> </sect4> - <sect4 id="freebsd-update-custom-kernel-9x"> + <sect4 xml:id="freebsd-update-custom-kernel-9x"> <title>Custom Kernels with &os; 9.X and Later</title> <itemizedlist> <listitem> <para>If a custom kernel has only been built once, the kernel in - <filename - class="directory">/boot/kernel.old</filename> + <filename>/boot/kernel.old</filename> is actually the <literal>GENERIC</literal> kernel. - Rename this directory to <filename - class="directory">/boot/kernel</filename>.</para> + Rename this directory to <filename>/boot/kernel</filename>.</para> </listitem> <listitem> @@ -488,7 +453,7 @@ MergeChanges /etc/ /var/named/etc/</programlisting> </sect4> </sect3> - <sect3 id="freebsdupdate-using"> + <sect3 xml:id="freebsdupdate-using"> <title>Performing the Upgrade</title> <para>Major and minor version upgrades may be performed by @@ -548,7 +513,7 @@ before running "/usr/sbin/freebsd-update install"</screen> The results of every successful merge will be shown to the user as the process continues. A failed or ignored merge will cause the process to abort. Users may wish to make a - backup of <filename class="directory">/etc</filename> and + backup of <filename>/etc</filename> and manually merge important files, such as <filename>master.passwd</filename> or <filename>group</filename> at a later time.</para> @@ -569,7 +534,7 @@ before running "/usr/sbin/freebsd-update install"</screen> this point, the machine must be rebooted. If the system is running with a custom kernel, use &man.nextboot.8; to set the kernel for the next boot to the updated - <filename class="directory">/boot/GENERIC</filename>:</para> + <filename>/boot/GENERIC</filename>:</para> <screen>&prompt.root; <userinput>nextboot -k GENERIC</userinput></screen> @@ -609,15 +574,14 @@ before running "/usr/sbin/freebsd-update install"</screen> </note> </sect3> - <sect3 id="freebsdupdate-portsrebuild"> + <sect3 xml:id="freebsdupdate-portsrebuild"> <title>Rebuilding Ports After a Major Version Upgrade</title> <para>After a major version upgrade, all third party software needs to be rebuilt and re-installed. This is required as installed software may depend on libraries which have been removed during the upgrade process. This process can be - automated using <filename - role="package">ports-mgmt/portmaster</filename>:</para> + automated using <package>ports-mgmt/portmaster</package>:</para> <screen>&prompt.root; <userinput>portmaster -f</userinput></screen> @@ -636,7 +600,7 @@ before running "/usr/sbin/freebsd-update install"</screen> </sect3> </sect2> - <sect2 id="freebsdupdate-system-comparison"> + <sect2 xml:id="freebsdupdate-system-comparison"> <title>System State Comparison</title> <para><command>freebsd-update</command> can be used to test the @@ -650,7 +614,7 @@ before running "/usr/sbin/freebsd-update install"</screen> <warning> <para>While the command name is <acronym>IDS</acronym> it is not a replacement for a real intrusion detection system such - as <filename role="package">security/snort</filename>. As + as <package>security/snort</package>. As <command>freebsd-update</command> stores data on disk, the possibility of tampering is evident. While this possibility may be reduced using <varname>kern.securelevel</varname> and @@ -693,24 +657,16 @@ before running "/usr/sbin/freebsd-update install"</screen> </sect2> </sect1> - <sect1 id="updating-upgrading-portsnap"> - <sect1info> + <sect1 xml:id="updating-upgrading-portsnap"> + <info><title>Portsnap: a Ports Collection Update Tool</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Colin</firstname> - <surname>Percival</surname> - <contrib>Based on notes provided by </contrib> - </author> + <author><personname><firstname>Colin</firstname><surname>Percival</surname></personname><contrib>Based on notes provided by </contrib></author> </authorgroup> - </sect1info> - <title>Portsnap: a Ports Collection Update Tool</title> + </info> + <indexterm><primary>Updating and Upgrading</primary></indexterm> <indexterm> @@ -780,10 +736,10 @@ Fetching 133 new ports or files... done.</screen> <para>This command downloads the latest version of the Ports Collection and updates the local version under - <filename class="directory">/usr/ports</filename>.</para> + <filename>/usr/ports</filename>.</para> </sect1> - <sect1 id="updating-upgrading-documentation"> + <sect1 xml:id="updating-upgrading-documentation"> <title>Updating the Documentation Set</title> <indexterm><primary>Updating and Upgrading</primary></indexterm> @@ -795,13 +751,12 @@ Fetching 133 new ports or files... done.</screen> <para>Documentation is an integral part of the &os; operating system. While an up-to-date version of the &os; Documentation - Set is always available on the <ulink - url="http://www.freebsd.org/doc/">&os; web site</ulink>, + Set is always available on the <link xlink:href="http://www.freebsd.org/doc/">&os; web site</link>, some users might have slow or no permanent network connectivity. There are several ways to update the local copy of documentation with the latest &os; Documentation Set.</para> - <sect2 id="dsvn-doc"> + <sect2 xml:id="dsvn-doc"> <title>Using <application>Subversion</application> to Update the Documentation</title> @@ -818,14 +773,13 @@ Fetching 133 new ports or files... done.</screen> <listitem> <para>Download a copy of the documentation source at - <filename class="directory">/usr/doc</filename>, using + <filename>/usr/doc</filename>, using <application>svn</application>.</para> </listitem> <listitem> <para>Rebuild the &os; documentation from its source, and - install it under <filename - class="directory">/usr/share/doc</filename>.</para> + install it under <filename>/usr/share/doc</filename>.</para> </listitem> <listitem> @@ -838,7 +792,7 @@ Fetching 133 new ports or files... done.</screen> </itemizedlist> </sect2> - <sect2 id="installing-documentation-toolchain"> + <sect2 xml:id="installing-documentation-toolchain"> <title>Installing <application>svn</application> and the Documentation Toolchain</title> @@ -851,13 +805,12 @@ Fetching 133 new ports or files... done.</screen> <para>The required tools, including <application>svn</application>, are available in the - <filename role="package">textproc/docproj</filename> meta-port + <package>textproc/docproj</package> meta-port developed by the &os; Documentation Project.</para> <note> <para>When no &postscript; or PDF documentation required, one - might consider installing the <filename - role="package">textproc/docproj-nojadetex</filename> port + might consider installing the <package>textproc/docproj-nojadetex</package> port instead. This version of the documentation toolchain includes everything except the <application>teTeX</application> typesetting engine. @@ -867,17 +820,16 @@ Fetching 133 new ports or files... done.</screen> </note> </sect2> - <sect2 id="updating-documentation-sources"> + <sect2 xml:id="updating-documentation-sources"> <title>Updating the Documentation Sources</title> <para>In this example, <application>svn</application> is used to fetch a clean copy of the documentation sources from the western US mirror using the HTTPS protocol:</para> - <screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/doc/head /usr/doc</userinput></screen> + <screen>&prompt.root; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/doc/head /usr/doc</userinput></screen> - <para>Select the closest mirror from the available <link - linkend="svn-mirrors">Subversion mirror sites</link>.</para> + <para>Select the closest mirror from the available <link linkend="svn-mirrors">Subversion mirror sites</link>.</para> <para>The initial download of the documentation sources may take a while. Let it run until it completes.</para> @@ -885,7 +837,7 @@ Fetching 133 new ports or files... done.</screen> <para>Future updates of the documentation sources may be fetched by running:</para> - <screen>&prompt.root; <userinput>svn update <filename class="directory">/usr/doc</filename></userinput></screen> + <screen>&prompt.root; <userinput>svn update /usr/doc</userinput></screen> <para>After checking out the sources, an alternative way of updating the documentation is supported by the @@ -896,7 +848,7 @@ Fetching 133 new ports or files... done.</screen> &prompt.root; <userinput>make update</userinput></screen> </sect2> - <sect2 id="updating-documentation-options"> + <sect2 xml:id="updating-documentation-options"> <title>Tunable Options of the Documentation Sources</title> <para>The updating and build system of the &os; documentation @@ -910,7 +862,7 @@ Fetching 133 new ports or files... done.</screen> <variablelist> <varlistentry> - <term><makevar>DOC_LANG</makevar></term> + <term><varname>DOC_LANG</varname></term> <listitem> <para>The list of languages and encodings to build and @@ -920,7 +872,7 @@ Fetching 133 new ports or files... done.</screen> </varlistentry> <varlistentry> - <term><makevar>FORMATS</makevar></term> + <term><varname>FORMATS</varname></term> <listitem> <para>A single format or a list of output formats to be @@ -932,12 +884,11 @@ Fetching 133 new ports or files... done.</screen> </varlistentry> <varlistentry> - <term><makevar>DOCDIR</makevar></term> + <term><varname>DOCDIR</varname></term> <listitem> <para>Where to install the documentation. It defaults to - <filename - class="directory">/usr/share/doc</filename>.</para> + <filename>/usr/share/doc</filename>.</para> </listitem> </varlistentry> </variablelist> @@ -948,21 +899,20 @@ Fetching 133 new ports or files... done.</screen> <para>For more <command>make</command> variables supported by the build system of the &os; documentation, refer to the - <ulink url="&url.doc.langbase;/books/fdp-primer">&os; + <link xlink:href="&url.doc.langbase;/books/fdp-primer">&os; Documentation Project Primer for New - Contributors</ulink>.</para> + Contributors</link>.</para> </sect2> - <sect2 id="updating-installed-documentation"> + <sect2 xml:id="updating-installed-documentation"> <title>Installing the &os; Documentation from Source</title> <para>Once an up-to-date snapshot of the documentation sources - has been fetched to <filename - class="directory">/usr/doc</filename>, everything is + has been fetched to <filename>/usr/doc</filename>, everything is ready for an update of the installed documentation.</para> <para>A full update of all the languages defined in - <makevar>DOC_LANG</makevar> may be performed by typing:</para> + <varname>DOC_LANG</varname> may be performed by typing:</para> <screen>&prompt.root; <userinput>cd /usr/doc</userinput> &prompt.root; <userinput>make install clean</userinput></screen> @@ -970,35 +920,30 @@ Fetching 133 new ports or files... done.</screen> <para>If an update of only a specific language is desired, &man.make.1; can be invoked in a language specific subdirectory of - <filename class="directory">/usr/doc</filename>:</para> + <filename>/usr/doc</filename>:</para> <screen>&prompt.root; <userinput>cd /usr/doc/en_US.ISO8859-1</userinput> &prompt.root; <userinput>make update install clean</userinput></screen> <para>The output formats that will be installed may be specified - by setting <makevar>FORMATS</makevar>:</para> + by setting <varname>FORMATS</varname>:</para> <screen>&prompt.root; <userinput>cd /usr/doc</userinput> &prompt.root; <userinput>make FORMATS='html html-split' install clean</userinput></screen> <para>For information on editing and submitting corrections to - the documentation, refer to the <ulink - url="&url.books.fdp-primer;">&os; Documentation - Project Primer for New Contributors</ulink>.</para> + the documentation, refer to the <link xlink:href="&url.books.fdp-primer;">&os; Documentation + Project Primer for New Contributors</link>.</para> </sect2> - <sect2 id="doc-ports"> - <sect2info> + <sect2 xml:id="doc-ports"> + <info><title>Using Documentation Ports</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Based on the work of </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Based on the work of </contrib></author> </authorgroup> - </sect2info> + </info> - <title>Using Documentation Ports</title> + <indexterm><primary>Updating and Upgrading</primary></indexterm> @@ -1035,11 +980,10 @@ Fetching 133 new ports or files... done.</screen> supported by a set of <emphasis>documentation ports</emphasis>, updated by the &a.doceng; on a monthly basis. These are listed in the &os; Ports Collection, - under the <ulink - url="http://www.freshports.org/docs/">docs</ulink> + under the <link xlink:href="http://www.freshports.org/docs/">docs</link> category.</para> - <sect3 id="doc-ports-install-make"> + <sect3 xml:id="doc-ports-install-make"> <title>Building and Installing Documentation Ports</title> <para>The documentation ports use the ports building framework @@ -1062,39 +1006,34 @@ Fetching 133 new ports or files... done.</screen> <itemizedlist> <listitem> - <para>The <quote>master port</quote>, <filename - role="package">misc/freebsd-doc-en</filename>, + <para>The <quote>master port</quote>, <package>misc/freebsd-doc-en</package>, which installs all of the English documentation ports.</para> </listitem> <listitem> - <para>The <quote>all in one port</quote>, <filename - role="package">misc/freebsd-doc-all</filename>, + <para>The <quote>all in one port</quote>, <package>misc/freebsd-doc-all</package>, builds and installs all documentation in all available languages.</para> </listitem> <listitem> <para>There is a <quote>slave port</quote> for each - translation, such as <filename - role="package">misc/freebsd-doc-hu</filename> for the + translation, such as <package>misc/freebsd-doc-hu</package> for the Hungarian-language documents.</para> </listitem> </itemizedlist> <para>For example, to build and install the English documentation in split <acronym>HTML</acronym> format, - similar to the format used on <ulink - url="http://www.FreeBSD.org"></ulink>, to - <filename - class="directory">/usr/local/share/doc/freebsd</filename>, + similar to the format used on <uri xlink:href="http://www.FreeBSD.org">http://www.FreeBSD.org</uri>, to + <filename>/usr/local/share/doc/freebsd</filename>, install the following port</para> <screen>&prompt.root; <userinput>cd /usr/ports/misc/freebsd-doc-en</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <sect4 id="doc-ports-options"> + <sect4 xml:id="doc-ports-options"> <title>Common Knobs and Options</title> <para>There are many options for modifying the default @@ -1102,7 +1041,7 @@ Fetching 133 new ports or files... done.</screen> <variablelist> <varlistentry> - <term><makevar>WITH_HTML</makevar></term> + <term><varname>WITH_HTML</varname></term> <listitem> <para>Builds the HTML format with a single HTML file @@ -1114,7 +1053,7 @@ Fetching 133 new ports or files... done.</screen> </varlistentry> <varlistentry> - <term><makevar>WITH_PDF</makevar></term> + <term><varname>WITH_PDF</varname></term> <listitem> <para>Builds the &adobe; Portable Document Format @@ -1126,20 +1065,19 @@ Fetching 133 new ports or files... done.</screen> </varlistentry> <varlistentry> - <term><makevar>DOCBASE</makevar></term> + <term><varname>DOCBASE</varname></term> <listitem> <para>Specifies where to install the documentation. - It defaults to <filename - class="directory">/usr/local/share/doc/freebsd</filename>.</para> + It defaults to <filename>/usr/local/share/doc/freebsd</filename>.</para> <note> <para>The default target directory differs from the directory used <application>svn</application>. This is because ports are usually installed within - <filename class="directory">/usr/local</filename>. + <filename>/usr/local</filename>. This can be overridden by using - <makevar>PREFIX</makevar>.</para> + <varname>PREFIX</varname>.</para> </note> </listitem> </varlistentry> @@ -1153,7 +1091,7 @@ Fetching 133 new ports or files... done.</screen> </sect4> </sect3> - <sect3 id="doc-ports-install-package"> + <sect3 xml:id="doc-ports-install-package"> <title>Using Documentation Packages</title> <para>Building the documentation ports from source, as @@ -1185,7 +1123,7 @@ Fetching 133 new ports or files... done.</screen> <note> <para>Packages use a format that differs from the corresponding port's name: - <literal><replaceable>lang</replaceable>-freebsd-doc</literal>, + <literal>lang-freebsd-doc</literal>, where <replaceable>lang</replaceable> is the short format of the language code, such as <literal>hu</literal> for Hungarian, or <literal>zh_cn</literal> for Simplified @@ -1193,13 +1131,13 @@ Fetching 133 new ports or files... done.</screen> </note> </sect3> - <sect3 id="doc-ports-update"> + <sect3 xml:id="doc-ports-update"> <title>Updating Documentation Ports</title> <para>Documentation ports can be updated like any other port. For example, the following command updates the installed Hungarian documentation using - <filename role="package">ports-mgmt/portmaster</filename> + <package>ports-mgmt/portmaster</package> by using packages only:</para> <screen>&prompt.root; <userinput>portmaster -PP hu-freebsd-doc</userinput></screen> @@ -1207,7 +1145,7 @@ Fetching 133 new ports or files... done.</screen> </sect2> </sect1> - <sect1 id="current-stable"> + <sect1 xml:id="current-stable"> <title>Tracking a Development Branch</title> <indexterm><primary>-CURRENT</primary></indexterm> @@ -1219,7 +1157,7 @@ Fetching 133 new ports or files... done.</screen> respective tree. &os.current; will be discussed first, then &os.stable;.</para> - <sect2 id="current"> + <sect2 xml:id="current"> <title>Staying Current with &os;</title> <para>&os.current; is the <quote>bleeding edge</quote> of &os; @@ -1334,8 +1272,7 @@ Fetching 133 new ports or files... done.</screen> <orderedlist> <listitem> - <para>Use <link - linkend="svn">svn</link><indexterm> + <para>Use <link linkend="svn">svn</link><indexterm> <primary>Subversion</primary> </indexterm> <indexterm> @@ -1347,25 +1284,22 @@ Fetching 133 new ports or files... done.</screen> branch. This is the recommended method, providing access to &os; development as it occurs. Checkout the -CURRENT code from the <literal>head</literal> - branch of one of the <link - linkend="svn-mirrors">Subversion mirror + branch of one of the <link linkend="svn-mirrors">Subversion mirror sites</link>. Due to the size of the repository, it is recommended that only desired subtrees be checked out.</para> </listitem> <listitem> - <para>Use the <application><link - linkend="ctm">CTM</link></application><indexterm> + <para>Use the <application>CTM</application><indexterm> <primary>-CURRENT</primary> <secondary>Syncing with CTM</secondary> </indexterm> facility. If you have bad connectivity such as high price connections or only email access, <application>CTM</application> is an option, but it is not as reliable as <application> - <link linkend="svn">Subversion</link></application>. - For this reason, <application><link - linkend="svn">Subversion</link></application> + Subversion</application>. + For this reason, <application>Subversion</application> is the recommended method for any system with Internet connectivity.</para> </listitem> @@ -1405,7 +1339,7 @@ Fetching 133 new ports or files... done.</screen> </sect3> </sect2> - <sect2 id="stable"> + <sect2 xml:id="stable"> <title>Staying Stable with &os;</title> <sect3> @@ -1440,8 +1374,7 @@ Fetching 133 new ports or files... done.</screen> <footnote> <para>For a complete description of the current security - policy for old releases of FreeBSD, refer to <ulink - url="&url.base;/security/">http://www.FreeBSD.org/security/</ulink>.</para></footnote>.</para> + policy for old releases of FreeBSD, refer to <link xlink:href="&url.base;/security/">http://www.FreeBSD.org/security/</link>.</para></footnote>.</para> <para>While the &os.stable; branch should compile and run at all times, this cannot be guaranteed. While code is @@ -1498,11 +1431,9 @@ Fetching 133 new ports or files... done.</screen> <listitem> <para>To install a new system running monthly - snapshots built from &os.stable;, refer to <ulink - url="&url.base;/snapshots/">Snapshots</ulink> for more + snapshots built from &os.stable;, refer to <link xlink:href="&url.base;/snapshots/">Snapshots</link> for more information. Alternatively, it is possible to install - the most recent &os.stable; release from the <link - linkend="mirrors">mirror sites</link> and follow the + the most recent &os.stable; release from the <link linkend="mirrors">mirror sites</link> and follow the instructions below to upgrade the system to the most up-to-date &os.stable; source code.</para> @@ -1520,8 +1451,8 @@ Fetching 133 new ports or files... done.</screen> providing access to &os; development as it occurs. Branch names include <literal>head</literal> for the current development head, and branches identified in - <ulink url="&url.base;/releng/">the release - engineering page</ulink>, such as + <link xlink:href="&url.base;/releng/">the release + engineering page</link>, such as <literal>stable/9</literal><indexterm> <primary>-STABLE</primary> <secondary>syncing with @@ -1529,8 +1460,7 @@ Fetching 133 new ports or files... done.</screen> </indexterm> or <literal>releng/9.2</literal>. URL prefixes for <application>Subversion</application> checkout of - the base system are shown in <link - linkend="svn-mirrors">Subversion mirror + the base system are shown in <link linkend="svn-mirrors">Subversion mirror sites</link>. Because of the size of the repository, it is recommended that only desired subtrees be checked @@ -1538,8 +1468,7 @@ Fetching 133 new ports or files... done.</screen> </listitem> <listitem> - <para>Consider using <application><link - linkend="ctm">CTM</link></application><indexterm> + <para>Consider using <application>CTM</application><indexterm> <primary>-STABLE</primary> <secondary>syncing with CTM</secondary> </indexterm> if you do not have a fast connection to @@ -1567,14 +1496,12 @@ Fetching 133 new ports or files... done.</screen> </sect2> </sect1> - <sect1 id="synching"> + <sect1 xml:id="synching"> <title>Synchronizing Source</title> <para>There are various ways of using an Internet or email connection to stay up-to-date with any given area, or all areas, - of the &os; project sources. The primary services are <link - linkend="svn">Subversion</link> and <link - linkend="ctm">CTM</link>.</para> + of the &os; project sources. The primary services are <link linkend="svn">Subversion</link> and <link linkend="ctm">CTM</link>.</para> <warning> <para>While it is possible to update only parts of the source @@ -1629,7 +1556,7 @@ Fetching 133 new ports or files... done.</screen> it all with <application>CTM</application>.</para> </sect1> - <sect1 id="makeworld"> + <sect1 xml:id="makeworld"> <title>Rebuilding <quote>world</quote></title> <indexterm> @@ -1689,7 +1616,7 @@ Fetching 133 new ports or files... done.</screen> used instead.</para> </warning> - <sect2 id="canonical-build"> + <sect2 xml:id="canonical-build"> <title>The Canonical Way to Update Your System</title> <para>Before updating the system, read @@ -1739,10 +1666,10 @@ Fetching 133 new ports or files... done.</screen> </itemizedlist> <para>These first two issues are the basis for the - core <maketarget>buildworld</maketarget>, - <maketarget>buildkernel</maketarget>, - <maketarget>installkernel</maketarget>, - <maketarget>installworld</maketarget> sequence described in + core <buildtarget>buildworld</buildtarget>, + <buildtarget>buildkernel</buildtarget>, + <buildtarget>installkernel</buildtarget>, + <buildtarget>installworld</buildtarget> sequence described in the following paragraphs. Other reasons for using these steps are listed below:</para> @@ -1778,27 +1705,26 @@ Fetching 133 new ports or files... done.</screen> <orderedlist> <listitem> <para><command>make - <maketarget>buildworld</maketarget></command></para> + buildworld</command></para> <para>This first compiles the new compiler and a few related tools, then uses the new compiler to compile the rest of the new world. The result ends up in - <filename class="directory">/usr/obj</filename>.</para> + <filename>/usr/obj</filename>.</para> </listitem> <listitem> <para><command>make - <maketarget>buildkernel</maketarget></command></para> + buildkernel</command></para> <para>This uses the <emphasis>new</emphasis> compiler - residing in <filename - class="directory">/usr/obj</filename> in order to + residing in <filename>/usr/obj</filename> in order to protect against compiler-kernel mismatches.</para> </listitem> <listitem> <para><command>make - <maketarget>installkernel</maketarget></command></para> + installkernel</command></para> <para>Place the new kernel and kernel modules onto the disk, making it possible to boot with the newly updated @@ -1816,7 +1742,7 @@ Fetching 133 new ports or files... done.</screen> <listitem> <para><command>mergemaster - <option>-p</option></command></para> + -p</command></para> <para>This does some initial configuration file updates in preparation for the new world. For instance, it may add @@ -1824,17 +1750,17 @@ Fetching 133 new ports or files... done.</screen> password database. This is often necessary when new groups or special system-user accounts have been added since the last update, so that the - <maketarget>installworld</maketarget> step will be able to + <buildtarget>installworld</buildtarget> step will be able to use the newly installed system user or system group names without problems.</para> </listitem> <listitem> <para><command>make - <maketarget>installworld</maketarget></command></para> + installworld</command></para> <para>Copies the world - from <filename class="directory">/usr/obj</filename>. The + from <filename>/usr/obj</filename>. The new kernel and new world are now installed on disk.</para> </listitem> @@ -1847,7 +1773,7 @@ Fetching 133 new ports or files... done.</screen> <listitem> <para><command>make - <maketarget>delete-old</maketarget></command></para> + delete-old</command></para> <para>This target deletes old (obsolete) files. This is important because sometimes they cause problems if left on @@ -1866,7 +1792,7 @@ Fetching 133 new ports or files... done.</screen> <listitem> <para><command>make - <maketarget>delete-old-libs</maketarget></command></para> + delete-old-libs</command></para> <para>Remove any obsolete libraries to avoid conflicts with newer ones. Make sure that all ports have been rebuilt @@ -1879,7 +1805,7 @@ Fetching 133 new ports or files... done.</screen> 9.1, may not need this procedure since it is less likely to run into serious mismatches between compiler, kernel, userland, and configuration files. The approach of - <command>make <maketarget>world</maketarget></command> + <command>make world</command> followed by building and installing a new kernel might work well enough for minor updates.</para> @@ -1910,13 +1836,13 @@ Fetching 133 new ports or files... done.</screen> <note> <para>There are a few rare cases when an extra run of <command>mergemaster -p</command> is needed before the - <maketarget>buildworld</maketarget> step. These are + <buildtarget>buildworld</buildtarget> step. These are described in <filename>UPDATING</filename>. In general, though, this step can safely be omitted when not updating across one or more major &os; versions.</para> </note> - <para>After <maketarget>installkernel</maketarget> finishes + <para>After <buildtarget>installkernel</buildtarget> finishes successfully, boot into single user mode using <command>boot -s</command> from the loader prompt.</para> @@ -1950,7 +1876,7 @@ Fetching 133 new ports or files... done.</screen> </warning> </sect2> - <sect2 id="src-updating"> + <sect2 xml:id="src-updating"> <title>Read <filename>/usr/src/UPDATING</filename></title> <para>Before updating, read @@ -1969,7 +1895,7 @@ Fetching 133 new ports or files... done.</screen> </important> </sect2> - <sect2 id="make-conf"> + <sect2 xml:id="make-conf"> <title>Check <filename>/etc/make.conf</filename></title> <indexterm> @@ -1992,7 +1918,7 @@ Fetching 133 new ports or files... done.</screen> programs, or building the &os; operating system.</para> </sect2> - <sect2 id="src-conf"> + <sect2 xml:id="src-conf"> <title>Check <filename>/etc/src.conf</filename></title> <indexterm> @@ -2010,10 +1936,10 @@ Fetching 133 new ports or files... done.</screen> are unexpected or subtle interactions.</para> </sect2> - <sect2 id="updating-etc"> + <sect2 xml:id="updating-etc"> <title>Update the Files in <filename>/etc</filename></title> - <para><filename class="directory">/etc</filename> contains a + <para><filename>/etc</filename> contains a large part of the system's configuration information, as well as scripts that are run at system startup. Some of these scripts change between &os; versions.</para> @@ -2032,14 +1958,14 @@ Fetching 133 new ports or files... done.</screen> <para>The solution is to run &man.mergemaster.8; in pre-buildworld mode with <option>-p</option>. This compares only those files that are essential for the success of - <maketarget>buildworld</maketarget> or - <maketarget>installworld</maketarget>.</para> + <buildtarget>buildworld</buildtarget> or + <buildtarget>installworld</buildtarget>.</para> <tip> <para>To check which files are owned by the group being renamed or deleted:</para> - <screen>&prompt.root; <userinput>find / -group <replaceable>GID</replaceable> -print</userinput></screen> + <screen>&prompt.root; <userinput>find / -group GID -print</userinput></screen> <para>This command will show all files owned by group <replaceable>GID</replaceable>, which can be either a group @@ -2047,7 +1973,7 @@ Fetching 133 new ports or files... done.</screen> </tip> </sect2> - <sect2 id="makeworld-singleuser"> + <sect2 xml:id="makeworld-singleuser"> <title>Drop to Single User Mode</title> <indexterm><primary>single-user mode</primary></indexterm> @@ -2064,8 +1990,8 @@ Fetching 133 new ports or files... done.</screen> mode, and then drop into single user mode for the installation. With this method, hold off on the following steps until the build has completed. Drop to single user mode - in order to run <maketarget>installkernel</maketarget> or - <maketarget>installworld</maketarget>.</para> + in order to run <buildtarget>installkernel</buildtarget> or + <buildtarget>installworld</buildtarget>.</para> <para>To enter single user mode from a running system:</para> @@ -2098,7 +2024,7 @@ Fetching 133 new ports or files... done.</screen> </note> </sect2> - <sect2 id="cleaning-usr-obj"> + <sect2 xml:id="cleaning-usr-obj"> <title>Remove <filename>/usr/obj</filename></title> <para>As parts of the system are rebuilt, they are, by default, @@ -2119,7 +2045,7 @@ Fetching 133 new ports or files... done.</screen> &prompt.root; <userinput>rm -rf *</userinput></screen> </sect2> - <sect2 id="updating-upgrading-compilebase"> + <sect2 xml:id="updating-upgrading-compilebase"> <title>Recompile the Base System</title> <sect3> @@ -2144,17 +2070,16 @@ Script started, output file is /var/tmp/mw.out &prompt.root; <userinput>exit</userinput> Script done, …</screen> - <para><emphasis>Do not</emphasis> save the output in <filename - class="directory">/tmp</filename> as this directory may be + <para><emphasis>Do not</emphasis> save the output in <filename>/tmp</filename> as this directory may be cleared at next reboot. A better place to save the file is - <filename class="directory">/var/tmp</filename> or in - <username>root</username>'s home directory.</para> + <filename>/var/tmp</filename> or in + <systemitem class="username">root</systemitem>'s home directory.</para> </sect3> - <sect3 id="make-buildworld"> + <sect3 xml:id="make-buildworld"> <title>Compile the Base System</title> - <para>While in <filename class="directory">/usr/src</filename> + <para>While in <filename>/usr/src</filename> type:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> @@ -2168,7 +2093,7 @@ Script done, …</screen> <para>The general format of the command is as follows:</para> - <screen>&prompt.root; <userinput>make -<replaceable>x</replaceable> -D<replaceable>VARIABLE</replaceable> <replaceable>target</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make -x -DVARIABLE target</userinput></screen> <para>In this example, <option>-<replaceable>x</replaceable></option> is an option @@ -2182,7 +2107,7 @@ Script done, …</screen> in <filename>/etc/make.conf</filename>, and this provides another way of setting them. For example:</para> - <screen>&prompt.root; <userinput>make -DNO_PROFILE <replaceable>target</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make -DNO_PROFILE target</userinput></screen> <para>is another way of specifying that profiled libraries should not be built, and corresponds with the</para> @@ -2204,41 +2129,41 @@ Script done, …</screen> <para>Most of the time, no parameters need to be passed to &man.make.1; and the command looks like this:</para> - <screen>&prompt.root; <userinput>make <replaceable>target</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make target</userinput></screen> <para>Where <replaceable>target</replaceable> is one of many build options. The first target should always be - <makevar>buildworld</makevar>.</para> + <varname>buildworld</varname>.</para> - <para>As the names imply, <maketarget>buildworld</maketarget> + <para>As the names imply, <buildtarget>buildworld</buildtarget> builds a complete new tree under <filename>/usr/obj</filename> and - <maketarget>installworld</maketarget> installs this tree on + <buildtarget>installworld</buildtarget> installs this tree on the current machine.</para> <para>Having separate options is useful for two reasons. First, it allows for a <quote>self hosted</quote> build that does not affect any components of a running system. Because - of this, <maketarget>buildworld</maketarget> can be run on a + of this, <buildtarget>buildworld</buildtarget> can be run on a machine running in multi-user mode with no fear of ill-effects. It is still recommended that - <maketarget>installworld</maketarget> be run in part in + <buildtarget>installworld</buildtarget> be run in part in single user mode, though.</para> <para>Secondly, it allows NFS mounts to be used to upgrade multiple machines on a network. If order to upgrade three - machines, <hostid>A</hostid>, <hostid>B</hostid> and - <hostid>C</hostid>, run <command>make buildworld</command> + machines, <systemitem>A</systemitem>, <systemitem>B</systemitem> and + <systemitem>C</systemitem>, run <command>make buildworld</command> and <command>make installworld</command> on - <hostid>A</hostid>. <hostid>B</hostid> and - <hostid>C</hostid> should then NFS mount + <systemitem>A</systemitem>. <systemitem>B</systemitem> and + <systemitem>C</systemitem> should then NFS mount <filename>/usr/src</filename> and - <filename>/usr/obj</filename> from <hostid>A</hostid>, and + <filename>/usr/obj</filename> from <systemitem>A</systemitem>, and run <command>make installworld</command> to install the - results of the build on <hostid>B</hostid> and - <hostid>C</hostid>.</para> + results of the build on <systemitem>B</systemitem> and + <systemitem>C</systemitem>.</para> - <para>Although the <maketarget>world</maketarget> target still + <para>Although the <buildtarget>world</buildtarget> target still exists, users are strongly encouraged not to use it.</para> <para>Instead, run:</para> @@ -2282,7 +2207,7 @@ Script done, …</screen> </sect3> </sect2> - <sect2 id="new-kernel"> + <sect2 xml:id="new-kernel"> <title>Compile and Install a New Kernel</title> <indexterm> @@ -2313,11 +2238,11 @@ Script done, …</screen> <note> <para>To build a custom kernel with an existing customized configuration file, use - <literal>KERNCONF=<replaceable>MYKERNEL</replaceable></literal>:</para> + <literal>KERNCONF=MYKERNEL</literal>:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput> -&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> +&prompt.root; <userinput>make buildkernel KERNCONF=MYKERNEL</userinput> +&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen> </note> @@ -2325,27 +2250,26 @@ Script done, …</screen> above 1 <emphasis>and</emphasis> <literal>noschg</literal> or similar flags have been set on the kernel binary, drop into single user mode to use - <maketarget>installkernel</maketarget>. Otherwise, both these + <buildtarget>installkernel</buildtarget>. Otherwise, both these commands can be run from multi user mode without problems. See &man.init.8; for details about <varname>kern.securelevel</varname> and &man.chflags.1; for details about the various file flags.</para> </sect2> - <sect2 id="new-kernel-singleuser"> + <sect2 xml:id="new-kernel-singleuser"> <title>Reboot into Single User Mode</title> <indexterm><primary>single-user mode</primary></indexterm> <para>Reboot into single user mode to test that the new kernel - works using the instructions in <xref - linkend="makeworld-singleuser"/>.</para> + works using the instructions in <xref linkend="makeworld-singleuser"/>.</para> </sect2> - <sect2 id="make-installworld"> + <sect2 xml:id="make-installworld"> <title>Install the New System Binaries</title> - <para>Next, use <maketarget>installworld</maketarget> to install + <para>Next, use <buildtarget>installworld</buildtarget> to install the new system binaries:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput> @@ -2356,7 +2280,7 @@ Script done, …</screen> <command>make buildworld</command>, specify the same variables to <command>make installworld</command>. However, <option>-j</option> must never be used with - <maketarget>installworld</maketarget>.</para> + <buildtarget>installworld</buildtarget>.</para> <para>For example, if you ran:</para> @@ -2372,14 +2296,14 @@ Script done, …</screen> </note> </sect2> - <sect2 id="post-installworld-updates"> + <sect2 xml:id="post-installworld-updates"> <title>Update Files Not Updated by <command>make installworld</command></title> <para>Remaking the world will not update certain directories, - such as <filename class="directory">/etc</filename>, - <filename class="directory">/var</filename> and - <filename class="directory">/usr</filename>, with + such as <filename>/etc</filename>, + <filename>/var</filename> and + <filename>/usr</filename>, with new or changed configuration files.</para> <para>The simplest way to update the files in these directories @@ -2387,17 +2311,13 @@ Script done, …</screen> of <filename>/etc</filename> in case anything goes wrong.</para> - <sect3 id="mergemaster"> - <sect3info> + <sect3 xml:id="mergemaster"> + <info><title><command>mergemaster</command></title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect3info> - <title><command>mergemaster</command></title> + </info> + <indexterm> <primary> @@ -2407,9 +2327,9 @@ Script done, …</screen> <para>&man.mergemaster.8; is a Bourne script to aid in determining the differences between the configuration files - in <filename class="directory">/etc</filename>, and the + in <filename>/etc</filename>, and the configuration files in the source tree - <filename class="directory">/usr/src/etc</filename>. This + <filename>/usr/src/etc</filename>. This is the recommended solution for keeping the system configuration files up to date with those located in the source tree.</para> @@ -2473,12 +2393,12 @@ Script done, …</screen> <para>To perform the update manually instead, do not just copy over the files from - <filename class="directory">/usr/src/etc</filename> to - <filename class="directory">/etc</filename> and expect it to + <filename>/usr/src/etc</filename> to + <filename>/etc</filename> and expect it to work. Some files must be <quote>installed</quote> first as - <filename class="directory">/usr/src/etc</filename> + <filename>/usr/src/etc</filename> <emphasis>is not</emphasis> a copy of what - <filename class="directory">/etc</filename> should look + <filename>/etc</filename> should look like. In addition, some files that should be in <filename>/etc</filename> are not in <filename>/usr/src/etc</filename>.</para> @@ -2497,7 +2417,7 @@ Script done, …</screen> <filename>/etc</filename></title> <para>It is recommended to first copy the existing - <filename class="directory">/etc</filename> somewhere + <filename>/etc</filename> somewhere safe, like so:</para> <screen>&prompt.root; <userinput>cp -Rp /etc /etc.old</userinput></screen> @@ -2508,7 +2428,7 @@ Script done, …</screen> </warning> <para>Build a temporary set of directories into which the new - <filename class="directory">/etc</filename> and other files + <filename>/etc</filename> and other files can be installed:</para> <screen>&prompt.root; <userinput>mkdir /var/tmp/root</userinput> @@ -2517,8 +2437,7 @@ Script done, …</screen> <para>This will build the necessary directory structure and install the files. A lot of the subdirectories that have - been created under <filename - class="directory">/var/tmp/root</filename> are empty and + been created under <filename>/var/tmp/root</filename> are empty and should be deleted. The simplest way to do this is to:</para> @@ -2530,14 +2449,13 @@ Script done, …</screen> the warnings about the directories that are not empty.</para> - <para><filename class="directory">/var/tmp/root</filename> now + <para><filename>/var/tmp/root</filename> now contains all the files that should be placed in appropriate - locations below <filename class="directory">/</filename>. + locations below <filename>/</filename>. Go through each of these files, determining how they differ from the system's existing files.</para> - <para>Some of the files installed into <filename - class="directory">/var/tmp/root</filename> have a + <para>Some of the files installed into <filename>/var/tmp/root</filename> have a leading <quote>.</quote>. Make sure to use <command>ls -a</command> in order to catch them.</para> @@ -2554,23 +2472,22 @@ Script done, …</screen> <tip> <title>Name the New Root Directory - (<filename class="directory">/var/tmp/root</filename>) + (<filename>/var/tmp/root</filename>) with a Time Stamp, so You Can Easily Compare Differences Between Versions</title> <para>Frequently rebuilding world entails frequently - updating <filename class="directory">/etc</filename> + updating <filename>/etc</filename> as well, which can be a bit of a chore.</para> <para>To speed up this process, use the following procedure to keep a copy of the last set of changed files - that were merged into <filename - class="directory">/etc</filename>.</para> + that were merged into <filename>/etc</filename>.</para> <procedure> <step> <para>Make the world as normal. When updating - <filename class="directory">/etc</filename> and the + <filename>/etc</filename> and the other directories, give the target directory a name based on the current date:</para> @@ -2604,17 +2521,16 @@ Script done, …</screen> &prompt.root; <userinput>diff -r root-20130214 root-20130221</userinput></screen> <para>Typically, this will be a much smaller set of - differences than those between <filename - class="directory">/var/tmp/root-20130221/etc</filename> - and <filename class="directory">/etc</filename>. + differences than those between <filename>/var/tmp/root-20130221/etc</filename> + and <filename>/etc</filename>. Because the set of differences is smaller, it is easier to migrate those changes across into - <filename class="directory">/etc</filename>.</para> + <filename>/etc</filename>.</para> </step> <step> <para>When finished, remove the older of the two - <filename class="directory">/var/tmp/root-*</filename> + <filename>/var/tmp/root-*</filename> directories:</para> <screen>&prompt.root; <userinput>rm -rf /var/tmp/root-20130214</userinput></screen> @@ -2622,8 +2538,7 @@ Script done, …</screen> <step> <para>Repeat this process whenever merging - in changes to <filename - class="directory">/etc</filename>.</para> + in changes to <filename>/etc</filename>.</para> </step> </procedure> @@ -2635,17 +2550,13 @@ Script done, …</screen> </sect3> </sect2> - <sect2 id="make-delete-old"> - <sect2info> + <sect2 xml:id="make-delete-old"> + <info><title>Deleting Obsolete Files and Directories</title> <authorgroup> - <author> - <firstname>Anton</firstname> - <surname>Shterenlikht</surname> - <contrib>Based on notes provided by </contrib> - </author> + <author><personname><firstname>Anton</firstname><surname>Shterenlikht</surname></personname><contrib>Based on notes provided by </contrib></author> </authorgroup> - </sect2info> - <title>Deleting Obsolete Files and Directories</title> + </info> + <indexterm> <primary>Deleting obsolete files and directories</primary> @@ -2669,7 +2580,7 @@ Script done, …</screen> during the system upgrade process.</para> <para>After the - <command>make <maketarget>installworld</maketarget></command> + <command>make installworld</command> and the subsequent <command>mergemaster</command> have finished successfully, check for obsolete files and libraries as follows:</para> @@ -2690,7 +2601,7 @@ Script done, …</screen> <para>A prompt is displayed before deleting each obsolete file. To skip the prompt and let the system remove these files automatically, use - <makevar>BATCH_DELETE_OLD_FILES</makevar>:</para> + <varname>BATCH_DELETE_OLD_FILES</varname>:</para> <screen>&prompt.root; <userinput>make -DBATCH_DELETE_OLD_FILES delete-old</userinput></screen> @@ -2700,7 +2611,7 @@ Script done, …</screen> <screen>&prompt.root; <userinput>yes|make delete-old</userinput></screen> </sect2> - <sect2 id="updating-upgrading-rebooting"> + <sect2 xml:id="updating-upgrading-rebooting"> <title>Rebooting</title> <para>Verify that everything appears to be in the right place, @@ -2709,7 +2620,7 @@ Script done, …</screen> <screen>&prompt.root; <userinput>shutdown -r now</userinput></screen> </sect2> - <sect2 id="make-delete-old-libs"> + <sect2 xml:id="make-delete-old-libs"> <title>Deleting obsolete libraries</title> <warning> @@ -2720,15 +2631,14 @@ Script done, …</screen> true for old libraries. In most cases, the programs, ports, or libraries that used the old library need to be recompiled before <command>make - <maketarget>delete-old-libs</maketarget></command> is + delete-old-libs</command> is executed.</para> </warning> <para>Utilities for checking shared library dependencies are available from the Ports Collection in - <filename role="package">sysutils/libchk</filename> or - <filename - role="package">sysutils/bsdadminscripts</filename>.</para> + <package>sysutils/libchk</package> or + <package>sysutils/bsdadminscripts</package>.</para> <para>Obsolete shared libraries can conflict with newer libraries, causing messages like these:</para> @@ -2745,7 +2655,7 @@ Script done, …</screen> /usr/local/lib/libXext.so was installed by package libXext-1.1.1,1</screen> <para>Then deinstall, rebuild and reinstall the port. - <filename role="package">ports-mgmt/portmaster</filename> can + <package>ports-mgmt/portmaster</package> can be used to automate this process. After all ports are rebuilt and no longer use the old libraries, delete the old libraries using the following command:</para> @@ -2758,15 +2668,14 @@ Script done, …</screen> <para>If things went slightly wrong, it is easy to rebuild a particular piece of the system. For example, if <filename>/etc/magic</filename> was accidentally deleted as - part of the upgrade or merge of <filename - class="directory">/etc</filename>, &man.file.1; will stop + part of the upgrade or merge of <filename>/etc</filename>, &man.file.1; will stop working. To fix this, run:</para> <screen>&prompt.root; <userinput>cd /usr/src/usr.bin/file</userinput> &prompt.root; <userinput>make all install</userinput></screen> </sect2> - <sect2 id="updating-questions"> + <sect2 xml:id="updating-questions"> <title>Questions</title> <qandaset> @@ -2836,19 +2745,19 @@ Script done, …</screen> <qandaentry> <question> - <para>Can <filename class="directory">/usr/obj</filename> + <para>Can <filename>/usr/obj</filename> be removed when finished?</para> </question> <answer> <para>The short answer is yes.</para> - <para><filename class="directory">/usr/obj</filename> + <para><filename>/usr/obj</filename> contains all the object files that were produced during the compilation phase. Normally, one of the first steps in the <command>make buildworld</command> process is to remove this directory and start afresh. Keeping - <filename class="directory">/usr/obj</filename> around + <filename>/usr/obj</filename> around when finished makes little sense, and its removal frees up a approximately 2 GB of disk space.</para> @@ -2919,9 +2828,8 @@ Building everything.. </listitem> <listitem> - <para>Put <filename - class="directory">/usr/src</filename> and - <filename class="directory">/usr/obj</filename> + <para>Put <filename>/usr/src</filename> and + <filename>/usr/obj</filename> on separate file systems held on separate disks. If possible, put these disks on separate disk controllers.</para> @@ -2948,7 +2856,7 @@ Building everything.. <listitem> <para>The file system holding - <filename class="directory">/usr/src</filename> can + <filename>/usr/src</filename> can be mounted or remounted with <option>noatime</option>. This prevents the file system from recording the @@ -2958,17 +2866,15 @@ Building everything.. <screen>&prompt.root; <userinput>mount -u -o noatime /usr/src</userinput></screen> <warning> - <para>This example assumes <filename - class="directory">/usr/src</filename> is on its + <para>This example assumes <filename>/usr/src</filename> is on its own file system. If it is part of - <filename class="directory">/usr</filename>, then + <filename>/usr</filename>, then use that file system mount point instead.</para> </warning> </listitem> <listitem> - <para>The file system holding <filename - class="directory">/usr/obj</filename> can be + <para>The file system holding <filename>/usr/obj</filename> can be mounted or remounted with <option>async</option> so that disk writes happen asynchronously. The write completes immediately, and the data is written @@ -2983,8 +2889,7 @@ Building everything.. file system will be in an unrecoverable state when the machine restarts.</para> - <para>If <filename - class="directory">/usr/obj</filename> is the + <para>If <filename>/usr/obj</filename> is the only directory on this file system, this is not a problem. If you have other, valuable data on the same file system, ensure that there are verified @@ -2994,8 +2899,7 @@ Building everything.. <screen>&prompt.root; <userinput>mount -u -o async /usr/obj</userinput></screen> <warning> - <para>If <filename - class="directory">/usr/obj</filename> is + <para>If <filename>/usr/obj</filename> is not on its own file system, replace it in the example with the name of the appropriate mount point.</para> @@ -3036,18 +2940,14 @@ Building everything.. </sect2> </sect1> - <sect1 id="small-lan"> - <sect1info> + <sect1 xml:id="small-lan"> + <info><title>Tracking for Multiple Machines</title> <authorgroup> - <author> - <firstname>Mike</firstname> - <surname>Meyer</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Mike</firstname><surname>Meyer</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Tracking for Multiple Machines</title> + <indexterm> <primary>NFS</primary> @@ -3061,7 +2961,7 @@ Building everything.. the rest of the machines mount that work via NFS. This section outlines a method of doing so.</para> - <sect2 id="small-lan-preliminaries"> + <sect2 xml:id="small-lan-preliminaries"> <title>Preliminaries</title> <para>First, identify a set of machines which will run the @@ -3080,12 +2980,12 @@ Building everything.. machine, but need not be.</para> <para>All the machines in this build set need to mount - <filename class="directory">/usr/obj</filename> and - <filename class="directory">/usr/src</filename> from the same + <filename>/usr/obj</filename> and + <filename>/usr/src</filename> from the same machine, and at the same point. Ideally, those directories are on two different drives on the build machine, but they can be NFS mounted on that machine as well. For multiple - build sets, <filename class="directory">/usr/src</filename> + build sets, <filename>/usr/src</filename> should be on one build machine, and NFS mounted on the rest.</para> @@ -3095,25 +2995,24 @@ Building everything.. the build machine must build all the parts of the base system that any machine in the build set is going to install. Also, each build machine should have its kernel name set with - <makevar>KERNCONF</makevar> in + <varname>KERNCONF</varname> in <filename>/etc/make.conf</filename>, and the build machine - should list them all in <makevar>KERNCONF</makevar>, listing + should list them all in <varname>KERNCONF</varname>, listing its own kernel first. The build machine must have the kernel configuration files for each machine in - <filename - class="directory">/usr/src/sys/<replaceable>arch</replaceable>/conf</filename> + <filename>/usr/src/sys/arch/conf</filename> if it is going to build their kernels.</para> </sect2> - <sect2 id="small-lan-base-system"> + <sect2 xml:id="small-lan-base-system"> <title>The Base System</title> <para>On the build machine, build the kernel and world as described in <xref linkend="make-buildworld"/>, but do not install anything. After the build has finished, go to the test machine, and install the built kernel. If this machine - mounts <filename class="directory">/usr/src</filename> and - <filename class="directory">/usr/obj</filename> via NFS, + mounts <filename>/usr/src</filename> and + <filename>/usr/obj</filename> via NFS, enable the network and mount these directories after rebooting to single user mode. The easiest way to do this is to boot to multi-user, then run <command>shutdown now</command> to go to @@ -3128,21 +3027,20 @@ Building everything.. set.</para> </sect2> - <sect2 id="small-lan-ports"> + <sect2 xml:id="small-lan-ports"> <title>Ports</title> <para>The same ideas can be used for the ports tree. The first - critical step is to mount <filename - class="directory">/usr/ports</filename> from the same + critical step is to mount <filename>/usr/ports</filename> from the same machine to all the machines in the build set. Then, configure <filename>/etc/make.conf</filename> properly to share - distfiles. Set <makevar>DISTDIR</makevar> to a common shared + distfiles. Set <varname>DISTDIR</varname> to a common shared directory that is writable by whichever user - <username>root</username> is mapped to by the NFS mounts. - Each machine should set <makevar>WRKDIRPREFIX</makevar> to a + <systemitem class="username">root</systemitem> is mapped to by the NFS mounts. + Each machine should set <varname>WRKDIRPREFIX</varname> to a local build directory. Finally, if the system is to build and - distribute packages, set <makevar>PACKAGES</makevar> to a - directory similar to <makevar>DISTDIR</makevar>.</para> + distribute packages, set <varname>PACKAGES</varname> to a + directory similar to <varname>DISTDIR</varname>.</para> </sect2> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/handbook/desktop/chapter.xml b/en_US.ISO8859-1/books/handbook/desktop/chapter.xml index ac7256323f..324e6b6760 100644 --- a/en_US.ISO8859-1/books/handbook/desktop/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/desktop/chapter.xml @@ -3,8 +3,7 @@ The FreeBSD Documentation Project $FreeBSD$ --> - -<chapter id="desktop"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="desktop"> <!-- <chapterinfo> <authorgroup> @@ -19,7 +18,7 @@ <title>Desktop Applications</title> - <sect1 id="desktop-synopsis"> + <sect1 xml:id="desktop-synopsis"> <title>Synopsis</title> <para>While &os; is popular as a server for its performance and @@ -33,9 +32,8 @@ <note> <para>Users who prefer to install a pre-built desktop version of FreeBSD rather than configuring one from scratch should - refer to the <ulink - url="http://www.pcbsd.org/">pcbsd.org - website.</ulink></para> + refer to the <link xlink:href="http://www.pcbsd.org/">pcbsd.org + website.</link></para> </note> <para>As &os; features <link linkend="linuxemu">&linux; binary @@ -65,56 +63,49 @@ <entry>Browser</entry> <entry><application>Firefox</application></entry> <entry><literal>firefox</literal></entry> - <entry><filename - role="package">www/firefox</filename></entry> + <entry><package>www/firefox</package></entry> </row> <row> <entry>Browser</entry> <entry><application>Opera</application></entry> <entry><literal>opera</literal></entry> - <entry><filename - role="package">www/opera</filename></entry> + <entry><package>www/opera</package></entry> </row> <row> <entry>Browser</entry> <entry><application>Konqueror</application></entry> <entry><literal>kde4-baseapps</literal></entry> - <entry><filename - role="package">x11/kde4-baseapps</filename></entry> + <entry><package>x11/kde4-baseapps</package></entry> </row> <row> <entry>Browser</entry> <entry><application>Chromium</application></entry> <entry><literal>chromium</literal></entry> - <entry><filename - role="package">www/chromium</filename></entry> + <entry><package>www/chromium</package></entry> </row> <row> <entry>Productivity</entry> <entry><application>Calligra</application></entry> <entry><literal>calligra</literal></entry> - <entry><filename - role="package">editors/calligra</filename></entry> + <entry><package>editors/calligra</package></entry> </row> <row> <entry>Productivity</entry> <entry><application>AbiWord</application></entry> <entry><literal>abiword</literal></entry> - <entry><filename - role="package">editors/abiword</filename></entry> + <entry><package>editors/abiword</package></entry> </row> <row> <entry>Productivity</entry> <entry><application>The GIMP</application></entry> <entry><literal>gimp</literal></entry> - <entry><filename - role="package">graphics/gimp</filename></entry> + <entry><package>graphics/gimp</package></entry> </row> <row> @@ -122,16 +113,14 @@ <entry><application>Apache OpenOffice</application></entry> <entry><literal>openoffice</literal></entry> - <entry><filename - role="package">editors/openoffice-4</filename></entry> + <entry><package>editors/openoffice-4</package></entry> </row> <row> <entry>Productivity</entry> <entry><application>LibreOffice</application></entry> <entry><literal>libreoffice</literal></entry> - <entry><filename - role="package">editors/libreoffice</filename></entry> + <entry><package>editors/libreoffice</package></entry> </row> <row> @@ -139,56 +128,49 @@ <entry><application>&acrobat.reader;</application></entry> <entry><literal>no package due to license restriction</literal></entry> - <entry><filename - role="package">print/acroread9</filename></entry> + <entry><package>print/acroread9</package></entry> </row> <row> <entry>Document Viewer</entry> <entry><application>gv</application></entry> <entry><literal>gv</literal></entry> - <entry><filename - role="package">print/gv</filename></entry> + <entry><package>print/gv</package></entry> </row> <row> <entry>Document Viewer</entry> <entry><application>Xpdf</application></entry> <entry><literal>xpdf</literal></entry> - <entry><filename - role="package">graphics/xpdf</filename></entry> + <entry><package>graphics/xpdf</package></entry> </row> <row> <entry>Document Viewer</entry> <entry><application>GQview</application></entry> <entry><literal>gqview</literal></entry> - <entry><filename - role="package">graphics/gqview</filename></entry> + <entry><package>graphics/gqview</package></entry> </row> <row> <entry>Finance</entry> <entry><application>GnuCash</application></entry> <entry><literal>gnucash</literal></entry> - <entry><filename - role="package">finance/gnucash</filename></entry> + <entry><package>finance/gnucash</package></entry> </row> <row> <entry>Finance</entry> <entry><application>Gnumeric</application></entry> <entry><literal>gnumeric</literal></entry> - <entry><filename - role="package">math/gnumeric</filename></entry> + <entry><package>math/gnumeric</package></entry> </row> <row> <entry>Finance</entry> <entry><application>KMyMoney</application></entry> <entry><literal>kmymoney-kde4</literal></entry> - <entry><filename - role="package">finance/kmymoney-kde4</filename></entry> + <entry><package>finance/kmymoney-kde4</package></entry> </row> </tbody> </tgroup> @@ -203,8 +185,7 @@ </listitem> <listitem> - <para>Install X and a window manager as described in <xref - linkend="x11"/>.</para> + <para>Install X and a window manager as described in <xref linkend="x11"/>.</para> </listitem> <listitem> @@ -217,7 +198,7 @@ environment, refer to <xref linkend="multimedia"/>.</para> </sect1> - <sect1 id="desktop-browsers"> + <sect1 xml:id="desktop-browsers"> <title>Browsers</title> <indexterm> @@ -226,8 +207,7 @@ </indexterm> <para>&os; does not come with a pre-installed web browser. - Instead, the <ulink - url="http://www.FreeBSD.org/ports/www.html">www</ulink> + Instead, the <link xlink:href="http://www.FreeBSD.org/ports/www.html">www</link> category of the Ports Collection contains many browsers which can be installed as a package or compiled from the Ports Collection.</para> @@ -238,10 +218,7 @@ for more information on how to set up these complete desktops.</para> - <para>Some light-weight browsers include <filename - role="package">www/dillo2</filename>, <filename - role="package">www/links</filename>, and <filename - role="package">www/w3m</filename>.</para> + <para>Some light-weight browsers include <package>www/dillo2</package>, <package>www/links</package>, and <package>www/w3m</package>.</para> <para>This section demonstrates how to install the following popular web browsers and indicates if the application is @@ -317,27 +294,23 @@ <screen>&prompt.root; <userinput>pkg_add -r firefox-esr</userinput></screen> - <para>Localized versions are available in <filename - role="package">www/firefox-i18n</filename> and <filename - role="package">www/firefox-esr-i18n</filename>.</para> + <para>Localized versions are available in <package>www/firefox-i18n</package> and <package>www/firefox-esr-i18n</package>.</para> <para>The Ports Collection can instead be used to compile the desired version of <application>Firefox</application> from - source code. This example builds <filename - role="package">www/firefox</filename>, where + source code. This example builds <package>www/firefox</package>, where <literal>firefox</literal> can be replaced with the ESR or localized version to install.</para> <screen>&prompt.root; <userinput>cd /usr/ports/www/firefox</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <sect3 id="moz-java-plugin"> + <sect3 xml:id="moz-java-plugin"> <title>Firefox and &java; Plugin</title> <para>The installation of <application>Firefox</application> does not include &java; - support. However, <filename - role="package">java/icedtea-web</filename> provides a free + support. However, <package>java/icedtea-web</package> provides a free software web browser plugin for running Java applets. It can be installed as a package. To alternately compile the port:</para> @@ -363,7 +336,7 @@ $HOME/.mozilla/plugins/</userinput></screen> </sect3> - <sect3 id="moz-flash-plugin"> + <sect3 xml:id="moz-flash-plugin"> <title>Firefox and &adobe; &flash; Plugin</title> @@ -381,17 +354,14 @@ <procedure> <step> - <para>Install the <filename - role="package">www/nspluginwrapper</filename> port. + <para>Install the <package>www/nspluginwrapper</package> port. Due to licensing restrictions, a package is not available. - This port requires <filename - role="package">emulators/linux_base-f10</filename> which + This port requires <package>emulators/linux_base-f10</package> which is a large port.</para> </step> <step> - <para>Install the <filename - role="package">www/linux-f10-flashplugin11</filename> + <para>Install the <package>www/linux-f10-flashplugin11</package> port. Due to licensing restrictions, a package is not available.</para> </step> @@ -400,8 +370,7 @@ <screen>&prompt.root; <userinput>ln -s /usr/local/lib/npapi/linux-f10-flashplugin/libflashplayer.so \ /usr/local/lib/browser_plugins/</userinput></screen> - <para>Create the <filename - class="directory">/usr/local/lib/browser_plugins</filename> + <para>Create the <filename>/usr/local/lib/browser_plugins</filename> directory if it is not already present.</para> </step> @@ -425,7 +394,7 @@ </procedure> </sect3> - <sect3 id="moz-swfdec-flash-plugin"> + <sect3 xml:id="moz-swfdec-flash-plugin"> <title>Firefox and Swfdec &flash; Plugin</title> <para><application>Swfdec</application> is a decoder and @@ -480,11 +449,9 @@ <literal>opera</literal>.</para> <para>To install &adobe; &flash; plugin support, first compile - the <filename - role="package">www/linux-f10-flashplugin11</filename> port, + the <package>www/linux-f10-flashplugin11</package> port, as a package is not available due to licensing restrictions. - Then install either the <filename - role="package">www/opera-linuxplugins</filename> port + Then install either the <package>www/opera-linuxplugins</package> port or package. This example compiles both applications from ports:</para> @@ -500,8 +467,7 @@ all the currently available plugins.</para> <para>To add the <application>&java;</application> plugin, - follow the instructions in <xref - linkend="moz-java-plugin"/>.</para> + follow the instructions in <xref linkend="moz-java-plugin"/>.</para> </sect2> <sect2> @@ -513,15 +479,14 @@ <para><application>Konqueror</application> is more than a web browser as it is also a file manager and a multimedia - viewer. It is included in the <filename - role="package">x11/kde4-baseapps</filename> package or + viewer. It is included in the <package>x11/kde4-baseapps</package> package or port.</para> <para><application>Konqueror</application> supports WebKit as well as its own KHTML. WebKit is a rendering engine used by many modern browsers including Chromium. To use WebKit with <application>Konqueror</application> on &os;, install the - <filename role="package">www/kwebkitpart</filename> package + <package>www/kwebkitpart</package> package or port. This example compiles the port:</para> <screen>&prompt.root; <userinput>cd /usr/ports/www/kwebkitpart</userinput> @@ -538,8 +503,7 @@ <para><application>Konqueror</application> also supports <application>&flash;</application>. A <quote>How To</quote> guide for getting <application>&flash;</application> support - on <application>Konqueror</application> is available at <ulink - url="http://freebsd.kde.org/howtos/konqueror-flash.php"></ulink>.</para> + on <application>Konqueror</application> is available at <uri xlink:href="http://freebsd.kde.org/howtos/konqueror-flash.php">http://freebsd.kde.org/howtos/konqueror-flash.php</uri>.</para> </sect2> <sect2> @@ -574,7 +538,7 @@ <filename>/usr/local/bin/chromium</filename>.</para> </note> - <sect3 id="chromium-java-plugin"> + <sect3 xml:id="chromium-java-plugin"> <title>Chromium and &java; Plugin</title> <para>The installation of @@ -597,7 +561,7 @@ /usr/local/share/chromium/plugins/</userinput></screen> </sect3> - <sect3 id="chromium-flash-plugin"> + <sect3 xml:id="chromium-flash-plugin"> <title>Chromium and &adobe; &flash; Plugin</title> <para>Configuring <application>Chromium</application> and @@ -610,7 +574,7 @@ </sect2> </sect1> - <sect1 id="desktop-productivity"> + <sect1 xml:id="desktop-productivity"> <title>Productivity</title> <para>When it comes to productivity, new users often look for an @@ -704,8 +668,7 @@ and <application>Karbon</application> is used to draw graphical documents.</para> - <para>In &os;, <filename - role="package">editors/calligra</filename> can be installed + <para>In &os;, <package>editors/calligra</package> can be installed as a package or a port. To install the package:</para> <screen>&prompt.root; <userinput>pkg_add -r calligra</userinput></screen> @@ -770,8 +733,7 @@ <screen>&prompt.root; <userinput>cd /usr/ports/graphics/gimp</userinput> &prompt.root; <userinput>make install clean</userinput></screen> - <para>The graphics category (<ulink - url="http://www.FreeBSD.org/ports/graphics.html">freebsd.org/ports/graphics.html</ulink>) + <para>The graphics category (<link xlink:href="http://www.FreeBSD.org/ports/graphics.html">freebsd.org/ports/graphics.html</link>) of the Ports Collection contains several <application>GIMP</application>-related plugins, help files, and user manuals.</para> @@ -812,10 +774,8 @@ OpenOffice</application> is stable and runs natively on &windows;, &solaris;, &linux;, &os;, and &macos; X. More information about <application>Apache - OpenOffice</application> can be found at <ulink - url="http://openoffice.org/">openoffice.org</ulink>. For - &os; specific information refer to <ulink - url="http://porting.openoffice.org/freebsd/">porting.openoffice.org/freebsd/</ulink>.</para> + OpenOffice</application> can be found at <link xlink:href="http://openoffice.org/">openoffice.org</link>. For + &os; specific information refer to <link xlink:href="http://porting.openoffice.org/freebsd/">porting.openoffice.org/freebsd/</link>.</para> <para>To install the <application>Apache OpenOffice</application> package:</para> @@ -825,14 +785,13 @@ <para>Once the package is installed, type the following command to launch <application>Apache OpenOffice</application>:</para> - <screen>&prompt.user; <userinput>openoffice-<replaceable>X.Y.Z</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>openoffice-X.Y.Z</userinput></screen> <para>where <replaceable>X.Y.Z</replaceable> is the version number of the installed version of <application>Apache OpenOffice</application>. The first time <application>Apache OpenOffice</application> launches, some - questions will be asked and a <filename - class="directory">.openoffice.org</filename> folder will + questions will be asked and a <filename>.openoffice.org</filename> folder will be created in the user's home directory.</para> <para>If the desired <application>Apache @@ -847,7 +806,7 @@ <para>To build a localized version, replace the previous command with:</para> - <screen>&prompt.root; <userinput>make LOCALIZED_LANG=<replaceable>your_language</replaceable> install clean</userinput></screen> + <screen>&prompt.root; <userinput>make LOCALIZED_LANG=your_language install clean</userinput></screen> <para>Replace <replaceable>your_language</replaceable> with the correct @@ -870,8 +829,7 @@ </indexterm> <para><application>LibreOffice</application> is a free software - office suite developed by <ulink - url="http://www.documentfoundation.org/">documentfoundation.org</ulink>. + office suite developed by <link xlink:href="http://www.documentfoundation.org/">documentfoundation.org</link>. It is compatible with other major office suites and available on a variety of platforms. It is a rebranded fork of <application>OpenOffice.org</application> and includes @@ -892,16 +850,14 @@ natively on &windows;, &linux;, &os;, and &macos; X. More information about <application>LibreOffice </application> can be found at - <ulink - url="http://www.libreoffice.org/">libreoffice.org</ulink>.</para> + <link xlink:href="http://www.libreoffice.org/">libreoffice.org</link>.</para> <para>To install the English version of the <application>LibreOffice</application> package:</para> <screen>&prompt.root; <userinput>pkg_add -r libreoffice</userinput></screen> - <para>The editors category (<ulink - url="http://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html</ulink>) + <para>The editors category (<link xlink:href="http://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html</link>) of the Ports Collection contains several localizations for <application>LibreOffice</application>. When installing a localized package, replace <literal>libreoffice</literal> @@ -913,7 +869,7 @@ <screen>&prompt.user; <userinput>libreoffice</userinput></screen> <para>During the first launch, some questions will be asked - and a <filename class="directory">.libreoffice</filename> + and a <filename>.libreoffice</filename> folder will be created in the user's home directory.</para> <para>If the desired <application>LibreOffice</application> @@ -929,14 +885,13 @@ <para>To build a localized version, <application>cd</application> into the port directory of the desired language. Supported languages can be found - in the editors category (<ulink - url="http://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html</ulink>) + in the editors category (<link xlink:href="http://www.FreeBSD.org/ports/editors.html">freebsd.org/ports/editors.html</link>) of the Ports Collection.</para> </note> </sect2> </sect1> - <sect1 id="desktop-viewers"> + <sect1 xml:id="desktop-viewers"> <title>Document Viewers</title> <para>Some new document formats have gained popularity since @@ -1006,8 +961,7 @@ is also available for &os;. Due to licensing restrictions, a package is not available, meaning that this application must be compiled from ports. Several localizations are - available from the print category (<ulink - url="http://www.FreeBSD.org/ports/print.html">freebsd.org/ports/print.html</ulink>) + available from the print category (<link xlink:href="http://www.FreeBSD.org/ports/print.html">freebsd.org/ports/print.html</link>) of the Ports Collection.</para> <para>This command installs the English version of @@ -1118,14 +1072,13 @@ </sect2> </sect1> - <sect1 id="desktop-finance"> + <sect1 xml:id="desktop-finance"> <title>Finance</title> <para>For managing personal finances on a &os; desktop, some powerful and easy-to-use applications can be installed. Some are compatible with widespread file formats, such as the formats - used by <application><trademark - class="registered">Quicken</trademark></application> and + used by <application>Quicken</application> and <application>Excel</application>.</para> <para>This section covers these programs:</para> diff --git a/en_US.ISO8859-1/books/handbook/disks/chapter.xml b/en_US.ISO8859-1/books/handbook/disks/chapter.xml index 59b56fbbaa..eda4426892 100644 --- a/en_US.ISO8859-1/books/handbook/disks/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/disks/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - -<chapter id="disks"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="disks"> <title>Storage</title> - <sect1 id="disks-synopsis"> + <sect1 xml:id="disks-synopsis"> <title>Synopsis</title> <para>This chapter covers the use of disks in &os;. This @@ -72,13 +71,13 @@ </itemizedlist> </sect1> - <sect1 id="disks-naming"> + <sect1 xml:id="disks-naming"> <title>Device Names</title> <para>The following is a list of physical storage devices supported in &os; and their associated device names.</para> - <table id="disk-naming-physical-table" frame="none"> + <table xml:id="disk-naming-physical-table" frame="none"> <title>Physical Disk Naming Conventions</title> <tgroup cols="2"> @@ -165,19 +164,15 @@ </table> </sect1> - <sect1 id="disks-adding"> - <sect1info> + <sect1 xml:id="disks-adding"> + <info><title>Adding Disks</title> <authorgroup> - <author> - <firstname>David</firstname> - <surname>O'Brien</surname> - <contrib>Originally contributed by </contrib> - </author> + <author><personname><firstname>David</firstname><surname>O'Brien</surname></personname><contrib>Originally contributed by </contrib></author> </authorgroup> - <!-- 26 Apr 1998 --> - </sect1info> + + </info> - <title>Adding Disks</title> + <indexterm> <primary>disks</primary> @@ -189,12 +184,12 @@ has a single drive. First, turn off the computer and install the drive in the computer following the instructions of the computer, controller, and drive manufacturers. Reboot - the system and become <username>root</username>.</para> + the system and become <systemitem class="username">root</systemitem>.</para> <para>Inspect <filename>/var/run/dmesg.boot</filename> to ensure the new disk was found. In this example, the newly added <acronym>SATA</acronym> drive will appear as - <devicename>ada1</devicename>.</para> + <filename>ada1</filename>.</para> <indexterm><primary>partitions</primary></indexterm> <indexterm> @@ -202,9 +197,8 @@ </indexterm> <para>For this example, a single large partition will be created - on the new disk. The <ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table"> - <acronym>GPT</acronym></ulink> partitioning scheme will be + on the new disk. The <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"> + <acronym>GPT</acronym></link> partitioning scheme will be used in preference to the older and less versatile <acronym>MBR</acronym> scheme.</para> @@ -247,19 +241,15 @@ <screen>&prompt.root; <userinput>mount /newdisk</userinput></screen> </sect1> - <sect1 id="usb-disks"> - <sect1info> + <sect1 xml:id="usb-disks"> + <info><title>USB Storage Devices</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- Jul 2004 --> - </sect1info> + + </info> - <title>USB Storage Devices</title> + <indexterm> <primary>USB</primary> @@ -322,7 +312,7 @@ da0: <Generic Traveling Disk 1.11> Removable Direct Access SCSI-2 device da0: 1.000MB/s transfers da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen> - <para>The brand, device node (<devicename>da0</devicename>), and + <para>The brand, device node (<filename>da0</filename>), and other details will differ according to the device.</para> <para>Since the USB device is seen as a SCSI one, @@ -347,8 +337,8 @@ da0: 126MB (258048 512 byte sectors: 64H 32S/T 126C)</screen> <para>To make the device mountable as a normal user, one solution is to make all users of the device a member of the - <groupname>operator</groupname> group using &man.pw.8;. - Next, ensure that the <groupname>operator</groupname> group is + <systemitem class="groupname">operator</systemitem> group using &man.pw.8;. + Next, ensure that the <systemitem class="groupname">operator</systemitem> group is able to read and write the device by adding these lines to <filename>/etc/devfs.rules</filename>:</para> @@ -362,9 +352,9 @@ add path 'da*' mode 0660 group operator</programlisting> <programlisting>add path 'da[3-9]*' mode 0660 group operator</programlisting> <para>This will exclude the first three SCSI disks - (<devicename>da0</devicename> to - <devicename>da2</devicename>)from belonging to the - <groupname>operator</groupname> group.</para> + (<filename>da0</filename> to + <filename>da2</filename>)from belonging to the + <systemitem class="groupname">operator</systemitem> group.</para> </note> <para>Next, enable the &man.devfs.rules.5; ruleset in @@ -385,23 +375,22 @@ add path 'da*' mode 0660 group operator</programlisting> <para>The final step is to create a directory where the file system is to be mounted. This directory needs to be owned by the user that is to mount the file system. One way to do that - is for <username>root</username> to create a subdirectory - owned by that user as <filename - class="directory">/mnt/<replaceable>username</replaceable></filename>. + is for <systemitem class="username">root</systemitem> to create a subdirectory + owned by that user as <filename>/mnt/username</filename>. In the following example, replace <replaceable>username</replaceable> with the login name of the user and <replaceable>usergroup</replaceable> with the user's primary group:</para> - <screen>&prompt.root; <userinput>mkdir /mnt/<replaceable>username</replaceable></userinput> -&prompt.root; <userinput>chown <replaceable>username</replaceable>:<replaceable>usergroup</replaceable> /mnt/<replaceable>username</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mkdir /mnt/username</userinput> +&prompt.root; <userinput>chown username:usergroup /mnt/username</userinput></screen> <para>Suppose a USB thumbdrive is plugged in, and a device <filename>/dev/da0s1</filename> appears. If the device is preformatted with a FAT file system, it can be mounted using:</para> - <screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/<replaceable>username</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mount -t msdosfs -o -m=644,-M=755 /dev/da0s1 /mnt/username</userinput></screen> <para>Before the device can be unplugged, it <emphasis>must</emphasis> be unmounted first. After device @@ -427,20 +416,15 @@ umass0: detached</screen> </sect2> </sect1> - <sect1 id="creating-cds"> - <sect1info> + <sect1 xml:id="creating-cds"> + <info><title>Creating and Using CD Media</title> <authorgroup> - <author> - <firstname>Mike</firstname> - <surname>Meyer</surname> - <contrib>Contributed by </contrib> - <!-- mwm@mired.org --> - </author> + <author><personname><firstname>Mike</firstname><surname>Meyer</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- Apr 2001 --> - </sect1info> + + </info> - <title>Creating and Using CD Media</title> + <indexterm> <primary>CD-ROMs</primary> @@ -476,11 +460,10 @@ umass0: detached</screen> that do not support those extensions.</para> <indexterm> - <primary><filename - role="package">sysutils/cdrtools</filename></primary> + <primary><package>sysutils/cdrtools</package></primary> </indexterm> - <para>The <filename role="package">sysutils/cdrtools</filename> + <para>The <package>sysutils/cdrtools</package> port includes &man.mkisofs.8;, a program that can be used to produce a data file containing an ISO 9660 file system. It has options that support various extensions, and is described @@ -493,37 +476,34 @@ umass0: detached</screen> <para>Which tool to use to burn the CD depends on whether the CD burner is ATAPI or something else. ATAPI CD burners use - <command><link linkend="burncd">burncd</link></command> + <command>burncd</command> which is part of the base system. SCSI and USB CD burners - should use <command><link - linkend="cdrecord">cdrecord</link></command> from the - <filename role="package">sysutils/cdrtools</filename> port. - It is also possible to use <command><link - linkend="cdrecord">cdrecord</link></command> and other tools - for SCSI drives on ATAPI hardware with the <link - linkend="atapicam">ATAPI/CAM module</link>.</para> + should use <command>cdrecord</command> from the + <package>sysutils/cdrtools</package> port. + It is also possible to use <command>cdrecord</command> and other tools + for SCSI drives on ATAPI hardware with the <link linkend="atapicam">ATAPI/CAM module</link>.</para> <para>For CD burning software with a graphical user interface, consider <application>X-CD-Roast</application> or <application>K3b</application>. These tools are available as packages or from the - <filename role="package">sysutils/xcdroast</filename> and - <filename role="package">sysutils/k3b</filename> ports. + <package>sysutils/xcdroast</package> and + <package>sysutils/k3b</package> ports. <application>X-CD-Roast</application> and <application>K3b</application> require the <link linkend="atapicam">ATAPI/CAM module</link> with ATAPI hardware.</para> </sect2> - <sect2 id="mkisofs"> + <sect2 xml:id="mkisofs"> <title><application>mkisofs</application></title> - <para>The <filename role="package">sysutils/cdrtools</filename> + <para>The <package>sysutils/cdrtools</package> port also installs &man.mkisofs.8;, which produces an ISO 9660 file system that is an image of a directory tree in the &unix; file system name space. The simplest usage is:</para> - <screen>&prompt.root; <userinput>mkisofs -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/tree</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mkisofs -o imagefile.iso /path/to/tree</userinput></screen> <indexterm> <primary>file systems</primary> @@ -575,24 +555,21 @@ umass0: detached</screen> loaders, like the one used by the &os; distribution disks, do not use emulation mode. In this case, <option>-no-emul-boot</option> should be used. So, if - <filename class="directory">/tmp/myboot</filename> holds a - bootable &os; system with the boot image in <filename - class="directory">/tmp/myboot/boot/cdboot</filename>, this + <filename>/tmp/myboot</filename> holds a + bootable &os; system with the boot image in <filename>/tmp/myboot/boot/cdboot</filename>, this command would produce the image of an ISO 9660 file system as <filename>/tmp/bootable.iso</filename>:</para> <screen>&prompt.root; <userinput>mkisofs -R -no-emul-boot -b boot/cdboot -o /tmp/bootable.iso /tmp/myboot</userinput></screen> - <para>If <devicename>md</devicename> is configured in the + <para>If <filename>md</filename> is configured in the kernel, the file system can be mounted as a memory disk with:</para> <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f /tmp/bootable.iso -u 0</userinput> &prompt.root; <userinput>mount -t cd9660 /dev/md0 /mnt</userinput></screen> - <para>One can then verify that <filename - class="directory">/mnt</filename> and <filename - class="directory">/tmp/myboot</filename> are + <para>One can then verify that <filename>/mnt</filename> and <filename>/tmp/myboot</filename> are identical.</para> <para>There are many other options available for @@ -600,7 +577,7 @@ umass0: detached</screen> &man.mkisofs.8; for details.</para> </sect2> - <sect2 id="burncd"> + <sect2 xml:id="burncd"> <title><application>burncd</application></title> <indexterm> @@ -613,7 +590,7 @@ umass0: detached</screen> installed as <filename>/usr/sbin/burncd</filename>. Usage is very simple, as it has few options:</para> - <screen>&prompt.root; <userinput>burncd -f <replaceable>cddevice</replaceable> data <replaceable>imagefile.iso</replaceable> fixate</userinput></screen> + <screen>&prompt.root; <userinput>burncd -f cddevice data imagefile.iso fixate</userinput></screen> <para>This command will burn a copy of <replaceable>imagefile.iso</replaceable> on @@ -623,14 +600,13 @@ umass0: detached</screen> and write audio data.</para> </sect2> - <sect2 id="cdrecord"> + <sect2 xml:id="cdrecord"> <title><application>cdrecord</application></title> <para>For systems without an ATAPI CD burner, <command>cdrecord</command> can be used to burn CDs. <command>cdrecord</command> is not part of the base system and - must be installed from either the <filename - role="package">sysutils/cdrtools</filename> package or port. + must be installed from either the <package>sysutils/cdrtools</package> package or port. Changes to the base system can cause binary versions of this program to fail, possibly resulting in a <quote>coaster</quote>. It is recommended to either upgrade @@ -642,7 +618,7 @@ umass0: detached</screen> usage is simple. Burning an ISO 9660 image is done with:</para> - <screen>&prompt.root; <userinput>cdrecord dev=<replaceable>device</replaceable> <replaceable>imagefile.iso</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cdrecord dev=device imagefile.iso</userinput></screen> <para>The tricky part of using <command>cdrecord</command> is finding the <option>dev</option> to use. To find the proper @@ -685,7 +661,7 @@ scsibus1: controlling the write speed.</para> </sect2> - <sect2 id="duplicating-audiocds"> + <sect2 xml:id="duplicating-audiocds"> <title>Duplicating Audio CDs</title> <para>To duplicate an audio CD, extract the audio data from the @@ -707,11 +683,10 @@ scsibus1: <para>Use <command>cdrecord</command> to write the <filename>.wav</filename> files:</para> - <screen>&prompt.user; <userinput>cdrecord -v dev=<replaceable>2,0</replaceable> -dao -useinfo *.wav</userinput></screen> + <screen>&prompt.user; <userinput>cdrecord -v dev=2,0 -dao -useinfo *.wav</userinput></screen> <para>Make sure that <replaceable>2,0</replaceable> is set - appropriately, as described in <xref - linkend="cdrecord"/>.</para> + appropriately, as described in <xref linkend="cdrecord"/>.</para> </step> </procedure> @@ -729,7 +704,7 @@ scsibus1: <step> <para>The ATAPI CD driver makes each track available as - <filename>/dev/acd<replaceable>d</replaceable>t<replaceable>nn</replaceable></filename>, + <filename>/dev/acddtnn</filename>, where <replaceable>d</replaceable> is the drive number, and <replaceable>nn</replaceable> is the track number written with two decimal digits, prefixed with zero as @@ -760,19 +735,19 @@ scsibus1: files, and that <command>burncd</command> should fixate the disk when finished:</para> - <screen>&prompt.root; <userinput>burncd -f <replaceable>/dev/acd0</replaceable> audio track1.cdr track2.cdr <replaceable>...</replaceable> fixate</userinput></screen> + <screen>&prompt.root; <userinput>burncd -f /dev/acd0 audio track1.cdr track2.cdr ... fixate</userinput></screen> </step> </procedure> </sect2> - <sect2 id="imaging-cd"> + <sect2 xml:id="imaging-cd"> <title>Duplicating Data CDs</title> <para>It is possible to copy a data CD to an image file that is functionally equivalent to the image file created with &man.mkisofs.8;, and then use it to duplicate any data CD. The example given here assumes that the CD-ROM device is - <devicename>acd0</devicename>. Substitute the correct CD-ROM + <filename>acd0</filename>. Substitute the correct CD-ROM device.</para> <screen>&prompt.root; <userinput>dd if=/dev/acd0 of=file.iso bs=2048</userinput></screen> @@ -781,7 +756,7 @@ scsibus1: described above.</para> </sect2> - <sect2 id="mounting-cd"> + <sect2 xml:id="mounting-cd"> <title>Using Data CDs</title> <para>It is possible to mount and read the data on a standard @@ -799,7 +774,7 @@ scsibus1: <literal>ISO9660</literal> by specifying <option>-t cd9660</option> to &man.mount.8;. For example, to mount the CD-ROM device, <filename>/dev/cd0</filename>, - under <filename class="directory">/mnt</filename>, + under <filename>/mnt</filename>, use:</para> <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen> @@ -843,8 +818,7 @@ scsibus1: <para>Sometimes, a SCSI CD-ROM may be missed because it did not have enough time to answer the bus reset. To resolve this,add - the following option to the kernel configuration and <link - linkend="kernelconfig-building">rebuild the + the following option to the kernel configuration and <link linkend="kernelconfig-building">rebuild the kernel</link>.</para> <programlisting>options SCSI_DELAY=15000</programlisting> @@ -854,7 +828,7 @@ scsibus1: bus reset.</para> </sect2> - <sect2 id="rawdata-cd"> + <sect2 xml:id="rawdata-cd"> <title>Burning Raw Data CDs</title> <para>It is possible to burn a file directly to CD, without @@ -876,18 +850,14 @@ scsibus1: described above.</para> </sect2> - <sect2 id="atapicam"> - <sect2info> + <sect2 xml:id="atapicam"> + <info><title>Using the ATAPI/CAM Driver</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>Using the ATAPI/CAM Driver</title> + <indexterm> <primary>CD burner</primary> @@ -896,8 +866,7 @@ scsibus1: <para>This driver allows ATAPI devices, such as CD/DVD drives, to be accessed through the SCSI subsystem, and so allows the - use of applications like <filename - role="package">sysutils/cdrdao</filename> or + use of applications like <package>sysutils/cdrdao</package> or &man.cdrecord.1;.</para> <para>To use this driver, add the following line to @@ -937,12 +906,12 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>The drive can now be accessed via the <filename>/dev/cd0</filename> device name. For example, to - mount a CD-ROM on <filename class="directory">/mnt</filename>, + mount a CD-ROM on <filename>/mnt</filename>, type the following:</para> - <screen>&prompt.root; <userinput>mount -t cd9660 <replaceable>/dev/cd0</replaceable> /mnt</userinput></screen> + <screen>&prompt.root; <userinput>mount -t cd9660 /dev/cd0 /mnt</userinput></screen> - <para>As <username>root</username>, run the following command + <para>As <systemitem class="username">root</systemitem>, run the following command to get the SCSI address of the burner:</para> <screen>&prompt.root; <userinput>camcontrol devlist</userinput> @@ -957,26 +926,18 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> </sect1> - <sect1 id="creating-dvds"> - <sect1info> + <sect1 xml:id="creating-dvds"> + <info><title>Creating and Using DVD Media</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Andy</firstname> - <surname>Polyakov</surname> - <contrib>With inputs from </contrib> - </author> + <author><personname><firstname>Andy</firstname><surname>Polyakov</surname></personname><contrib>With inputs from </contrib></author> </authorgroup> - <!-- Feb 2004 --> - </sect1info> + + </info> - <title>Creating and Using DVD Media</title> + <indexterm> <primary>DVD</primary> @@ -997,8 +958,8 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <listitem> <para>DVD-R: This was the first DVD recordable format available. The DVD-R standard is defined by the - <ulink url="http://www.dvdforum.com/forum.shtml">DVD - Forum</ulink>. This format is write once.</para> + <link xlink:href="http://www.dvdforum.com/forum.shtml">DVD + Forum</link>. This format is write once.</para> </listitem> <listitem> @@ -1018,8 +979,8 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <listitem> <para>DVD+RW: This is a rewritable format defined by - the <ulink url="http://www.dvdrw.com/">DVD+RW - Alliance</ulink>. A DVD+RW can be rewritten about 1000 + the <link xlink:href="http://www.dvdrw.com/">DVD+RW + Alliance</link>. A DVD+RW can be rewritten about 1000 times.</para> </listitem> @@ -1048,8 +1009,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <title>Configuration</title> <para>To perform DVD recording, use &man.growisofs.1;. This - command is part of the <filename - role="package">sysutils/dvd+rw-tools</filename> utilities + command is part of the <package>sysutils/dvd+rw-tools</package> utilities which support all DVD media types.</para> <para>These tools use the SCSI subsystem to access the devices, @@ -1067,13 +1027,11 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>Before attempting to use <application>dvd+rw-tools</application>, consult the - <ulink - url="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">Hardware - Compatibility Notes</ulink>.</para> + <link xlink:href="http://fy.chalmers.se/~appro/linux/DVD+RW/hcn.html">Hardware + Compatibility Notes</link>.</para> <note> - <para>For a graphical user interface, consider using <filename - role="package">sysutils/k3b</filename> which provides a + <para>For a graphical user interface, consider using <package>sysutils/k3b</package> which provides a user friendly interface to &man.growisofs.1; and many other burning tools.</para> </note> @@ -1082,17 +1040,16 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <sect2> <title>Burning Data DVDs</title> - <para>Since &man.growisofs.1; is a front-end to <link - linkend="mkisofs">mkisofs</link>, it will invoke + <para>Since &man.growisofs.1; is a front-end to <link linkend="mkisofs">mkisofs</link>, it will invoke &man.mkisofs.8; to create the file system layout and perform the write on the DVD. This means that an image of the data does not need to be created before the burning process.</para> <para>To burn to a DVD+R or a DVD-R the data in - <filename class="directory">/path/to/data</filename>, + <filename>/path/to/data</filename>, use the following command:</para> - <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z /dev/cd0 -J -R /path/to/data</userinput></screen> <para>In this example, <option>-J -R</option> is passed to &man.mkisofs.8; to create an ISO 9660 file system with Joliet @@ -1110,7 +1067,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To burn a pre-mastered image, such as <replaceable>imagefile.iso</replaceable>, use:</para> - <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -dvd-compat -Z /dev/cd0=imagefile.iso</userinput></screen> <para>The write speed should be detected and automatically set according to the media and the drive being used. To force the @@ -1131,22 +1088,20 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To create this type of ISO file:</para> - <screen>&prompt.user; <userinput>mkisofs -R -J -udf -iso-level 3 -o <replaceable>imagefile.iso</replaceable> <replaceable>/path/to/data</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mkisofs -R -J -udf -iso-level 3 -o imagefile.iso /path/to/data</userinput></screen> <para>To burn files directly to a disk:</para> - <screen>&prompt.root; <userinput>growisofs -dvd-compat -udf -iso-level 3 -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -dvd-compat -udf -iso-level 3 -Z /dev/cd0 -J -R /path/to/data</userinput></screen> <para>When an ISO image already contains large files, no additional options are required for &man.growisofs.1; to burn that image on a disk.</para> - <para>Be sure to use an up-to-date version of <filename - role="package">sysutils/cdrtools</filename>, which + <para>Be sure to use an up-to-date version of <package>sysutils/cdrtools</package>, which contains &man.mkisofs.8;, as an older version may not contain large files support. If the latest version does - not work, install <filename - role="package">sysutils/cdrtools-devel</filename> and read + not work, install <package>sysutils/cdrtools-devel</package> and read its &man.mkisofs.8;.</para> </note> </sect2> @@ -1162,18 +1117,16 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>A DVD-Video is a specific file layout based on the ISO 9660 and micro-UDF (M-UDF) specifications. Since DVD-Video presents a specific data structure hierarchy, a particular - program such as <filename - role="package">multimedia/dvdauthor</filename> is needed to + program such as <package>multimedia/dvdauthor</package> is needed to author the DVD.</para> <para>If an image of the DVD-Video file system already exists, it can be burned in the same way as any other image. If <command>dvdauthor</command> was used to make the DVD and the - result is in <filename - class="directory">/path/to/video</filename>, the following + result is in <filename>/path/to/video</filename>, the following command should be used to burn the DVD-Video:</para> - <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -dvd-video <replaceable>/path/to/video</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -dvd-video /path/to/video</userinput></screen> <para><option>-dvd-video</option> is passed to &man.mkisofs.8; to instruct it to create a DVD-Video file system layout. @@ -1195,7 +1148,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c appropriate. However, it is possible to use <command>dvd+rw-format</command> to format the DVD+RW:</para> - <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dvd+rw-format /dev/cd0</userinput></screen> <para>Only perform this operation once and keep in mind that only virgin DVD+RW medias need to be formatted. Once @@ -1206,7 +1159,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c first. Instead, write over the previous recording like this:</para> - <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/newdata</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -J -R /path/to/newdata</userinput></screen> <para>The DVD+RW format supports appending data to a previous recording. This operation consists of merging a new session @@ -1218,7 +1171,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>For example, to append data to a DVD+RW, use the following:</para> - <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -M /dev/cd0 -J -R /path/to/nextdata</userinput></screen> <para>The same &man.mkisofs.8; options used to burn the initial session should be used during next writes.</para> @@ -1231,7 +1184,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To blank the media, use:</para> - <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable>=<replaceable>/dev/zero</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0=/dev/zero</userinput></screen> </sect2> <sect2> @@ -1253,7 +1206,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To blank a DVD-RW in sequential mode:</para> - <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dvd+rw-format -blank=full /dev/cd0</userinput></screen> <note> <para>A full blanking using <option>-blank=full</option> will @@ -1262,7 +1215,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c be recorded in Disk-At-Once (DAO) mode. To burn the DVD-RW in DAO mode, use the command:</para> - <screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z <replaceable>/dev/cd0</replaceable>=<replaceable>imagefile.iso</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -use-the-force-luke=dao -Z /dev/cd0=imagefile.iso</userinput></screen> <para>Since &man.growisofs.1; automatically attempts to detect fast blanked media and engage DAO write, @@ -1277,7 +1230,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To write data on a sequential DVD-RW, use the same instructions as for the other DVD formats:</para> - <screen>&prompt.root; <userinput>growisofs -Z <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/data</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -Z /dev/cd0 -J -R /path/to/data</userinput></screen> <para>To append some data to a previous recording, use <option>-M</option> with &man.growisofs.1;. However, if data @@ -1295,11 +1248,11 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To put a DVD-RW in restricted overwrite format, the following command must be used:</para> - <screen>&prompt.root; <userinput>dvd+rw-format <replaceable>/dev/cd0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dvd+rw-format /dev/cd0</userinput></screen> <para>To change back to sequential format, use:</para> - <screen>&prompt.root; <userinput>dvd+rw-format -blank=full <replaceable>/dev/cd0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dvd+rw-format -blank=full /dev/cd0</userinput></screen> </sect2> <sect2> @@ -1315,7 +1268,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c session on a DVD+R, DVD-R, or DVD-RW in sequential format, will add a new session to the disc:</para> - <screen>&prompt.root; <userinput>growisofs -M <replaceable>/dev/cd0</replaceable> -J -R <replaceable>/path/to/nextdata</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>growisofs -M /dev/cd0 -J -R /path/to/nextdata</userinput></screen> <para>Using this command with a DVD+RW or a DVD-RW in restricted overwrite mode will append data while merging the new session @@ -1338,16 +1291,14 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To obtain more information about a DVD, use <command>dvd+rw-mediainfo - <replaceable>/dev/cd0</replaceable></command> while the disc + /dev/cd0</command> while the disc in the specified drive.</para> <para>More information about <application>dvd+rw-tools</application> can be found in - &man.growisofs.1;, on the <ulink - url="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools - web site</ulink>, and in the <ulink - url="http://lists.debian.org/cdwrite/">cdwrite mailing - list</ulink> archives.</para> + &man.growisofs.1;, on the <link xlink:href="http://fy.chalmers.se/~appro/linux/DVD+RW/">dvd+rw-tools + web site</link>, and in the <link xlink:href="http://lists.debian.org/cdwrite/">cdwrite mailing + list</link> archives.</para> <note> <para>When creating a problem report related to the use of @@ -1356,7 +1307,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </note> </sect2> - <sect2 id="creating-dvd-ram"> + <sect2 xml:id="creating-dvd-ram"> <title>Using a DVD-RAM</title> <indexterm> @@ -1383,11 +1334,11 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c it can be used. In this example, the whole disk space will be formatted with a standard UFS2 file system:</para> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>/dev/acd0</replaceable> bs=2k count=1</userinput> -&prompt.root; <userinput>bsdlabel -Bw <replaceable>acd0</replaceable></userinput> -&prompt.root; <userinput>newfs <replaceable>/dev/acd0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>dd if=/dev/zero of=/dev/acd0 bs=2k count=1</userinput> +&prompt.root; <userinput>bsdlabel -Bw acd0</userinput> +&prompt.root; <userinput>newfs /dev/acd0</userinput></screen> - <para>The DVD device, <devicename>acd0</devicename>, must be + <para>The DVD device, <filename>acd0</filename>, must be changed according to the configuration.</para> </sect3> @@ -1397,7 +1348,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>Once the DVD-RAM has been formatted, it can be mounted as a normal hard drive:</para> - <screen>&prompt.root; <userinput>mount <replaceable>/dev/acd0</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mount /dev/acd0 /mnt</userinput></screen> <para>Once mounted, the DVD-RAM will be both readable and writeable.</para> @@ -1405,27 +1356,19 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> </sect1> - <sect1 id="floppies"> - <sect1info> + <sect1 xml:id="floppies"> + <info><title>Creating and Using Floppy Disks</title> <authorgroup> - <author> - <firstname>Julio</firstname> - <surname>Merino</surname> - <contrib>Original work by </contrib> - </author> + <author><personname><firstname>Julio</firstname><surname>Merino</surname></personname><contrib>Original work by </contrib></author> </authorgroup> - <!-- 24 Dec 2001 --> + <authorgroup> - <author> - <firstname>Martin</firstname> - <surname>Karlsson</surname> - <contrib>Rewritten by </contrib> - </author> + <author><personname><firstname>Martin</firstname><surname>Karlsson</surname></personname><contrib>Rewritten by </contrib></author> </authorgroup> - <!-- 27 Apr 2003 --> - </sect1info> + + </info> - <title>Creating and Using Floppy Disks</title> + <para>Storing data on floppy disks is sometimes useful, for example when one does not have any other removable storage media @@ -1443,9 +1386,9 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <title>The Device</title> <para>Floppy disks are accessed through entries in - <filename class="directory">/dev</filename>, just like other + <filename>/dev</filename>, just like other devices. To access the raw floppy disk, simply use - <filename>/dev/fd<replaceable>N</replaceable></filename>.</para> + <filename>/dev/fdN</filename>.</para> </sect3> <sect3> @@ -1517,12 +1460,12 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <para>To use the floppy, mount it with &man.mount.msdosfs.8;. One can also use - <filename role="package">emulators/mtools</filename> from the + <package>emulators/mtools</package> from the Ports Collection.</para> </sect2> </sect1> - <sect1 id="backups-tapebackups"> + <sect1 xml:id="backups-tapebackups"> <title>Creating and Using Data Tapes</title> <indexterm><primary>tape media</primary></indexterm> @@ -1534,7 +1477,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c uses SCSI, such as LTO and older devices such as DAT. There is limited support for SATA and USB tape drives.</para> - <sect2 id="tapes-sa0"> + <sect2 xml:id="tapes-sa0"> <title>Serial Access with &man.sa.4;</title> <indexterm> @@ -1542,20 +1485,20 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </indexterm> <para>&os; uses the &man.sa.4; driver, providing - <devicename>/dev/sa0</devicename>, - <devicename>/dev/nsa0</devicename>, and - <devicename>/dev/esa0</devicename>. In normal use, only - <devicename>/dev/sa0</devicename> is needed. - <devicename>/dev/nsa0</devicename> is the same physical drive - as <devicename>/dev/sa0</devicename> but does not rewind the + <filename>/dev/sa0</filename>, + <filename>/dev/nsa0</filename>, and + <filename>/dev/esa0</filename>. In normal use, only + <filename>/dev/sa0</filename> is needed. + <filename>/dev/nsa0</filename> is the same physical drive + as <filename>/dev/sa0</filename> but does not rewind the tape after writing a file. This allows writing more than one - file to a tape. Using <devicename>/dev/esa0</devicename> + file to a tape. Using <filename>/dev/esa0</filename> ejects the tape after the device is closed, if applicable.</para> </sect2> <sect2> - <title id="tapes-mt">Controlling the Tape Drive with + <title xml:id="tapes-mt">Controlling the Tape Drive with &man.mt.1;</title> <indexterm> @@ -1575,13 +1518,13 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> <sect2> - <title id="tapes-tar">Using &man.tar.1; to Read and + <title xml:id="tapes-tar">Using &man.tar.1; to Read and Write Tape Backups</title> <para>An example of writing a single file to tape using &man.tar.1;:</para> - <screen>&prompt.root; <userinput>tar cvf /dev/sa0 <replaceable>file</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>tar cvf /dev/sa0 file</userinput></screen> <para>Recovering files from a &man.tar.1; archive on tape into the current directory:</para> @@ -1590,11 +1533,10 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> <sect2> - <title id="tapes-dumprestore">Using &man.dump.8; and + <title xml:id="tapes-dumprestore">Using &man.dump.8; and &man.restore.8; to Create and Restore Backups</title> - <para>A simple backup of <filename - class="directory">/usr</filename> with &man.dump.8;:</para> + <para>A simple backup of <filename>/usr</filename> with &man.dump.8;:</para> <screen>&prompt.root; <userinput>dump -0aL -b64 -f /dev/nsa0 /usr</userinput></screen> @@ -1605,7 +1547,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> <sect2> - <title id="tapes-othersofware">Other Tape Software</title> + <title xml:id="tapes-othersofware">Other Tape Software</title> <para>Higher-level programs are available to simplify tape backup. The most popular are @@ -1617,19 +1559,15 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> </sect1> - <sect1 id="backup-strategies"> - <sect1info> + <sect1 xml:id="backup-strategies"> + <info><title>Backup Strategies</title> <authorgroup> - <author> - <firstname>Lowell</firstname> - <surname>Gilbert</surname> - <contrib>Original work by </contrib> - </author> + <author><personname><firstname>Lowell</firstname><surname>Gilbert</surname></personname><contrib>Original work by </contrib></author> </authorgroup> - <!-- 3 Dec 2005 --> - </sect1info> + + </info> - <title>Backup Strategies</title> + <para>The first requirement in devising a backup plan is to make sure that all of the following problems are covered:</para> @@ -1679,8 +1617,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <listitem> <para>Copies of whole file systems or disks which can be - created with a periodic <filename - role="package">net/rsync</filename> of the whole machine. + created with a periodic <package>net/rsync</package> of the whole machine. This is generally most useful in networks with unique requirements. For general protection against disk failure, this is usually inferior to <acronym>RAID</acronym>. For @@ -1713,7 +1650,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c against, and how each will be handled.</para> </sect1> - <sect1 id="backup-basics"> + <sect1 xml:id="backup-basics"> <title>Backup Basics</title> <para>The major backup programs built into &os; are @@ -1746,17 +1683,15 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c but rather writes the raw data blocks that comprise files and directories. When used to extract data, <command>restore</command> stores temporary - files in <filename class="directory">/tmp/</filename> by - default. When using a recovery disk with a small <filename - class="directory">/tmp</filename>, set + files in <filename>/tmp/</filename> by + default. When using a recovery disk with a small <filename>/tmp</filename>, set <envar>TMPDIR</envar> to a directory with more free space in order for the restore to succeed.</para> <note> <para>If <command>dump</command> is used on the root - directory, it will not back up <filename - class="directory">/home</filename>, - <filename class="directory">/usr</filename> or many other + directory, it will not back up <filename>/home</filename>, + <filename>/usr</filename> or many other directories since these are typically mount points for other file systems or symbolic links into those file systems.</para> @@ -1783,9 +1718,9 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c be suitable to use on the remote computer. For example, to <command>rdump</command> from a &os; computer to an Exabyte tape drive connected to a host called - <hostid>komodo</hostid>, use:</para> + <systemitem>komodo</systemitem>, use:</para> - <screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1</userinput></screen> + <screen>&prompt.root; <userinput>/sbin/rdump 0dsbfu 54000 13000 126 komodo:/dev/nsa8 /dev/da0a 2>&1</userinput></screen> <para>There are security implications to allowing <filename>.rhosts</filename> authentication, so use @@ -1833,9 +1768,9 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <indexterm><primary><command>tar</command></primary></indexterm> <para>To <command>tar</command> to an Exabyte tape drive - connected to a host called <hostid>komodo</hostid>:</para> + connected to a host called <systemitem>komodo</systemitem>:</para> - <screen>&prompt.root; <userinput>tar cf - . | rsh komodo dd of=<replaceable>tape-device</replaceable> obs=20b</userinput></screen> + <screen>&prompt.root; <userinput>tar cf - . | rsh komodo dd of=tape-device obs=20b</userinput></screen> <para>When backing up over an insecure network, instead use <command>ssh</command>.</para> @@ -1866,10 +1801,10 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c across the network, use a pipeline and <command>ssh</command> to send the data to a remote tape drive.</para> - <screen>&prompt.root; <userinput>for f in <replaceable>directory_list; do</replaceable></userinput> + <screen>&prompt.root; <userinput>for f in directory_list; do</userinput> <userinput>find $f >> backup.list</userinput> <userinput>done</userinput> -&prompt.root; <userinput>cpio -v -o --format=newc < backup.list | ssh <replaceable>user</replaceable>@<replaceable>host</replaceable> "cat > <replaceable>backup_device</replaceable>"</userinput></screen> +&prompt.root; <userinput>cpio -v -o --format=newc < backup.list | ssh user@host "cat > backup_device"</userinput></screen> <para>Where <replaceable>directory_list</replaceable> is the list of directories to back up, @@ -1903,7 +1838,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <command>cpio</command> than <command>tar</command>.</para> </sect2> - <sect2 id="backups-programs-amanda"> + <sect2 xml:id="backups-programs-amanda"> <title><application>Amanda</application></title> <indexterm> @@ -1961,7 +1896,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c files.</para> <para><quote>Do nothing</quote> is the correct backup method for - <filename class="directory">/usr/obj</filename> and other + <filename>/usr/obj</filename> and other directory trees that can be exactly recreated by the computer. An example is the files that comprise the HTML or &postscript; version of this Handbook. These document formats have been @@ -1990,9 +1925,8 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c unwritable files, devices, files that change size during the backup, files that are created/deleted during the backup and more. She presented the results at LISA V in Oct. 1991. See - <ulink - url="http://www.coredumps.de/doc/dump/zwicky/testdump.doc.html">torture-testing - Backup and Archive Programs</ulink>.</para> + <link xlink:href="http://www.coredumps.de/doc/dump/zwicky/testdump.doc.html">torture-testing + Backup and Archive Programs</link>.</para> </sect2> <sect2> @@ -2020,8 +1954,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c &man.restore.8;, &man.fdisk.8;, &man.bsdlabel.8;, &man.newfs.8;, &man.mount.8;, and more. The livefs CD image for &os;/&arch.i386; &rel2.current;-RELEASE is - available from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso"></ulink>.</para> + available from <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-livefs.iso</uri>.</para> <note> <para>Livefs CD images are not available for @@ -2030,8 +1963,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c images may be used to recover a system. The <quote>memstick</quote> image for &os;/&arch.i386; &rel.current;-RELEASE is available - from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img"></ulink>.</para> + from <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/&arch.i386;/ISO-IMAGES/&rel.current;/&os;-&rel.current;-RELEASE-&arch.i386;-memstick.img</uri>.</para> </note> <para>Third, create backup tapes regularly. Any changes that @@ -2072,8 +2004,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <guimenuitem>CD-ROM/DVD -- Use the live filesystem CD-ROM/DVD</guimenuitem>. <command>restore</command> and the other needed programs - are located in <filename - class="directory">/mnt2/rescue</filename>.</para> + are located in <filename>/mnt2/rescue</filename>.</para> <para>Recover each file system separately.</para> @@ -2108,17 +2039,13 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c </sect2> </sect1> - <sect1 id="disks-virtual"> - <sect1info> + <sect1 xml:id="disks-virtual"> + <info><title>Network, Memory, and File-Backed File Systems</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Reorganized and enhanced by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Reorganized and enhanced by </contrib></author> </authorgroup> - </sect1info> - <title>Network, Memory, and File-Backed File Systems</title> + </info> + <indexterm><primary>virtual disks</primary></indexterm> <indexterm> @@ -2149,7 +2076,7 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c for the user.</para> </note> - <sect2 id="disks-mdconfig"> + <sect2 xml:id="disks-mdconfig"> <title>File-Backed File System</title> <indexterm> @@ -2175,8 +2102,8 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <title>Using <command>mdconfig</command> to Mount an Existing File System Image</title> - <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>diskimage</replaceable> -u <replaceable>0</replaceable></userinput> -&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mdconfig -a -t vnode -f diskimage -u 0</userinput> +&prompt.root; <userinput>mount /dev/md0 /mnt</userinput></screen> </example> <para>To create a new file system image with @@ -2186,18 +2113,18 @@ cd0: Attempt to query device size failed: NOT READY, Medium not present - tray c <title>Creating a New File-Backed Disk with <command>mdconfig</command></title> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput> + <screen>&prompt.root; <userinput>dd if=/dev/zero of=newimage bs=1k count=5k</userinput> 5120+0 records in 5120+0 records out -&prompt.root; <userinput>mdconfig -a -t vnode -f <replaceable>newimage</replaceable> -u <replaceable>0</replaceable></userinput> -&prompt.root; <userinput>bsdlabel -w md<replaceable>0</replaceable> auto</userinput> -&prompt.root; <userinput>newfs md<replaceable>0</replaceable>a</userinput> +&prompt.root; <userinput>mdconfig -a -t vnode -f newimage -u 0</userinput> +&prompt.root; <userinput>bsdlabel -w md0 auto</userinput> +&prompt.root; <userinput>newfs md0a</userinput> /dev/md0a: 5.0MB (10224 sectors) block size 16384, fragment size 2048 using 4 cylinder groups of 1.25MB, 80 blks, 192 inodes. super-block backups (for fsck -b #) at: 160, 2720, 5280, 7840 -&prompt.root; <userinput>mount /dev/md<replaceable>0</replaceable>a <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>mount /dev/md0a /mnt</userinput> +&prompt.root; <userinput>df /mnt</userinput> Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0a 4710 4 4330 0% /mnt</screen> </example> @@ -2206,7 +2133,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <option>-u</option>, &man.mdconfig.8; uses the &man.md.4; automatic allocation to select an unused device. The name of the allocated unit will be output to stdout, such - as <devicename>md4</devicename>. Refer to &man.mdconfig.8; + as <filename>md4</filename>. Refer to &man.mdconfig.8; for more details about.</para> <para>While &man.mdconfig.8; is useful, it takes several @@ -2221,11 +2148,11 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <title>Configure and Mount a File-Backed Disk with <command>mdmfs</command></title> - <screen>&prompt.root; <userinput>dd if=/dev/zero of=<replaceable>newimage</replaceable> bs=1k count=<replaceable>5</replaceable>k</userinput> + <screen>&prompt.root; <userinput>dd if=/dev/zero of=newimage bs=1k count=5k</userinput> 5120+0 records in 5120+0 records out -&prompt.root; <userinput>mdmfs -F <replaceable>newimage</replaceable> -s <replaceable>5</replaceable>m md<replaceable>0</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>mdmfs -F newimage -s 5m md0 /mnt</userinput> +&prompt.root; <userinput>df /mnt</userinput> Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md0 4718 4 4338 0% /mnt</screen> </example> @@ -2236,7 +2163,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on about &man.mdmfs.8;, refer to its manual page.</para> </sect2> - <sect2 id="disks-md-freebsd5"> + <sect2 xml:id="disks-md-freebsd5"> <title>Memory-Based File System</title> <indexterm> @@ -2258,15 +2185,15 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <title>Creating a New Memory-Based Disk with <command>mdconfig</command></title> - <screen>&prompt.root; <userinput>mdconfig -a -t swap -s <replaceable>5</replaceable>m -u <replaceable>1</replaceable></userinput> -&prompt.root; <userinput>newfs -U md<replaceable>1</replaceable></userinput> + <screen>&prompt.root; <userinput>mdconfig -a -t swap -s 5m -u 1</userinput> +&prompt.root; <userinput>newfs -U md1</userinput> /dev/md1: 5.0MB (10240 sectors) block size 16384, fragment size 2048 using 4 cylinder groups of 1.27MB, 81 blks, 192 inodes. with soft updates super-block backups (for fsck -b #) at: 160, 2752, 5344, 7936 -&prompt.root; <userinput>mount /dev/md<replaceable>1</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> +&prompt.root; <userinput>mount /dev/md1 /mnt</userinput> +&prompt.root; <userinput>df /mnt</userinput> Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md1 4718 4 4338 0% /mnt</screen> </example> @@ -2275,8 +2202,8 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <title>Creating a New Memory-Based Disk with <command>mdmfs</command></title> - <screen>&prompt.root; <userinput>mdmfs -s <replaceable>5</replaceable>m md<replaceable>2</replaceable> <replaceable>/mnt</replaceable></userinput> -&prompt.root; <userinput>df <replaceable>/mnt</replaceable></userinput> + <screen>&prompt.root; <userinput>mdmfs -s 5m md2 /mnt</userinput> +&prompt.root; <userinput>df /mnt</userinput> Filesystem 1K-blocks Used Avail Capacity Mounted on /dev/md2 4846 2 4458 0% /mnt</screen> </example> @@ -2299,7 +2226,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <para>For example, to detach and free all resources used by <filename>/dev/md4</filename>:</para> - <screen>&prompt.root; <userinput>mdconfig -d -u <replaceable>4</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mdconfig -d -u 4</userinput></screen> <para>It is possible to list information about configured &man.md.4; devices by running @@ -2307,19 +2234,15 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on </sect2> </sect1> - <sect1 id="snapshots"> - <sect1info> + <sect1 xml:id="snapshots"> + <info><title>File System Snapshots</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- 15 JUL 2002 --> - </sect1info> + + </info> - <title>File System Snapshots</title> + <indexterm> <primary>file systems</primary> @@ -2348,7 +2271,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on allows them to be removed.</para> <para>Snapshots are created using &man.mount.8;. To place a - snapshot of <filename class="directory">/var</filename> in the + snapshot of <filename>/var</filename> in the file <filename>/var/snapshot/snap</filename>, use the following command:</para> @@ -2360,7 +2283,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <screen>&prompt.root; <userinput>mksnap_ffs /var /var/snapshot/snap</userinput></screen> <para>One can find snapshot files on a file system, such as - <filename class="directory">/var</filename>, using + <filename>/var</filename>, using &man.find.1;:</para> <screen>&prompt.root; <userinput>find /var -flags snapshot</userinput></screen> @@ -2400,9 +2323,8 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on </listitem> </itemizedlist> - <para>The frozen <filename class="directory">/var</filename> is - now available through <filename - class="directory">/mnt</filename>. Everything will initially + <para>The frozen <filename>/var</filename> is + now available through <filename>/mnt</filename>. Everything will initially be in the same state it was during the snapshot creation time. The only exception is that any earlier snapshots will appear as zero length files. To unmount the snapshot, use:</para> @@ -2413,10 +2335,10 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <para>For more information about <option>softupdates</option> and file system snapshots, including technical papers, visit Marshall Kirk McKusick's website at - <ulink url="http://www.mckusick.com/"></ulink>.</para> + <uri xlink:href="http://www.mckusick.com/">http://www.mckusick.com/</uri>.</para> </sect1> - <sect1 id="quotas"> + <sect1 xml:id="quotas"> <title>File System Quotas</title> <indexterm> @@ -2445,8 +2367,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <para>The <filename>GENERIC</filename> kernel does not have this enabled by default, so a custom kernel must be - compiled in order to use disk quotas. Refer to <xref - linkend="kernelconfig"/> for more information on + compiled in order to use disk quotas. Refer to <xref linkend="kernelconfig"/> for more information on kernel configuration.</para> <para>Next, enable disk quotas in @@ -2588,7 +2509,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on &man.edquota.8;. First, assign the desired quota limit to a user, then run <command>edquota -p protouser startuid-enduid</command>. For example, if - <username>test</username> has the desired quota limits, the + <systemitem class="username">test</systemitem> has the desired quota limits, the following command will duplicate those quota limits for UIDs 10,000 through 19,999:</para> @@ -2625,8 +2546,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on <indexterm><primary>grace period</primary></indexterm> <para>In this example, the user is currently 15 kbytes over the - soft limit of 50 kbytes on <filename - class="directory">/usr</filename> and has 5 days of grace + soft limit of 50 kbytes on <filename>/usr</filename> and has 5 days of grace period left. The asterisk <literal>*</literal> indicates that the user is currently over the quota limit.</para> @@ -2634,7 +2554,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on space on will not show in the output of &man.quota.1;, even if the user has a quota limit assigned for that file system. Use <option>-v</option> to display those file systems, such as - <filename class="directory">/usr/var</filename> in the above + <filename>/usr/var</filename> in the above example.</para> </sect2> @@ -2660,22 +2580,17 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on </sect2> </sect1> - <sect1 id="disks-encrypting"> - <sect1info> + <sect1 xml:id="disks-encrypting"> + <info><title>Encrypting Disk Partitions</title> <authorgroup> - <author> - <firstname>Lucky</firstname> - <surname>Green</surname> - <contrib>Contributed by </contrib> - <affiliation> + <author><personname><firstname>Lucky</firstname><surname>Green</surname></personname><contrib>Contributed by </contrib><affiliation> <address><email>shamrock@cypherpunks.to</email></address> - </affiliation> - </author> + </affiliation></author> </authorgroup> - <!-- 11 MARCH 2003 --> - </sect1info> + + </info> - <title>Encrypting Disk Partitions</title> + <indexterm> <primary>disks</primary> @@ -2683,8 +2598,7 @@ Filesystem 1K-blocks Used Avail Capacity Mounted on </indexterm> <para>&os; offers excellent online protections against - unauthorized data access. File permissions and <link - linkend="mac">Mandatory Access Control</link> (MAC) help + unauthorized data access. File permissions and <link linkend="mac">Mandatory Access Control</link> (MAC) help prevent unauthorized users from accessing data while the operating system is active and the computer is powered up. However, the permissions enforced by the operating system are @@ -2736,10 +2650,10 @@ Password:</screen> <para>The following example demonstrates adding a new hard drive to a system that will hold a single encrypted partition. This partition will be mounted as - <filename class="directory">/private</filename>. + <filename>/private</filename>. <application>gbde</application> can also be used to encrypt - <filename class="directory">/home</filename> and - <filename class="directory">/var/mail</filename>, but this + <filename>/home</filename> and + <filename>/var/mail</filename>, but this requires more complex instructions which exceed the scope of this introduction.</para> @@ -2750,8 +2664,8 @@ Password:</screen> <para>Install the new drive to the system as explained in <xref linkend="disks-adding"/>. For the purposes of this example, a new hard drive partition has been - added as <devicename>/dev/ad4s1c</devicename> and - <devicename>/dev/ad0s1<replaceable>*</replaceable></devicename> + added as <filename>/dev/ad4s1c</filename> and + <filename>/dev/ad0s1*</filename> represents the existing standard &os; partitions.</para> <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> @@ -2808,9 +2722,8 @@ sector_size = 2048 <application>gbde</application> to protect data depends entirely on the quality of the passphrase. For tips on how to select a secure passphrase that is easy to - remember, see the <ulink - url="http://world.std.com/~reinhold/diceware.html">Diceware - Passphrase</ulink> website.</para> + remember, see the <link xlink:href="http://world.std.com/~reinhold/diceware.html">Diceware + Passphrase</link> website.</para> <para><command>gbde init</command>creates a lock file for the <application>gbde</application> partition. In this @@ -2845,8 +2758,8 @@ sector_size = 2048 that was selected during the initialization of the encrypted partition. The new encrypted device will appear in - <filename class="directory">/dev</filename> as - <devicename>/dev/device_name.bde</devicename>:</para> + <filename>/dev</filename> as + <filename>/dev/device_name.bde</filename>:</para> <screen>&prompt.root; <userinput>ls /dev/ad*</userinput> /dev/ad0 /dev/ad0s1b /dev/ad0s1e /dev/ad4s1 @@ -2869,7 +2782,7 @@ sector_size = 2048 <para>&man.newfs.8; must be performed on an attached <application>gbde</application> partition which is identified by a - <filename><replaceable>*</replaceable>.bde</filename> + <filename>*.bde</filename> extension to the device name.</para> </note> </step> @@ -2912,7 +2825,7 @@ Filesystem Size Used Avail Capacity Mounted on <para>After each boot, any encrypted file systems must be re-attached to the kernel, checked for errors, and mounted, before the file systems can be used. The required commands - must be executed as <username>root</username>.</para> + must be executed as <systemitem class="username">root</systemitem>.</para> <procedure> <step> @@ -2991,7 +2904,7 @@ gbde_lockdir="/etc/gbde"</programlisting> <para>&man.sysinstall.8; is incompatible with <application>gbde</application>-encrypted devices. All - <devicename><replaceable>*</replaceable>.bde</devicename> + <filename>*.bde</filename> devices must be detached from the kernel before starting &man.sysinstall.8; or it will crash during its initial probing for devices. To detach the encrypted device used in @@ -3003,18 +2916,14 @@ gbde_lockdir="/etc/gbde"</programlisting> </sect2> <sect2> - <sect2info> + <info><title>Disk Encryption with <command>geli</command></title> <authorgroup> - <author> - <firstname>Daniel</firstname> - <surname>Gerzo</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- Date of writing: 28 November 2005 --> - </sect2info> + + </info> - <title>Disk Encryption with <command>geli</command></title> + <para>An alternative cryptographic GEOM class is available through &man.geli.8;. <command>geli</command> differs from @@ -3103,7 +3012,7 @@ device crypto</programlisting> <para>The following example describes how to generate a key file which will be used as part of the master key for the encrypted provider mounted under - <filename class="directory">/private</filename>. The key + <filename>/private</filename>. The key file will provide some random data used to encrypt the master key. The master key will also be protected by a passphrase. The provider's sector size will be 4kB. @@ -3117,8 +3026,8 @@ device crypto</programlisting> <para>The master key will be protected with a passphrase and the data source for the key file will be - <devicename>/dev/random</devicename>. The sector size of - the provider <devicename>/dev/da2.eli</devicename> will be + <filename>/dev/random</filename>. The sector size of + the provider <filename>/dev/da2.eli</filename> will be 4kB.</para> <screen>&prompt.root; <userinput>dd if=/dev/random of=/root/da2.key bs=64 count=1</userinput> @@ -3144,7 +3053,7 @@ Reenter new passphrase:</screen> Enter passphrase:</screen> <para>The new plaintext device will be named - <filename>/dev/<replaceable>da2</replaceable>.eli</filename>.</para> + <filename>/dev/da2.eli</filename>.</para> <screen>&prompt.root; <userinput>ls /dev/da2*</userinput> /dev/da2 /dev/da2.eli</screen> @@ -3174,7 +3083,7 @@ Filesystem Size Used Avail Capacity Mounted on <title>Unmounting and Detaching the Provider</title> <para>Once the work on the encrypted partition is done, and - the <filename class="directory">/private</filename> + the <filename>/private</filename> partition is no longer needed, it is prudent to consider unmounting and detaching the <command>geli</command> encrypted partition from the kernel:</para> @@ -3200,7 +3109,7 @@ Filesystem Size Used Avail Capacity Mounted on <programlisting>geli_devices="da2" geli_da2_flags="-p -k /root/da2.key"</programlisting> - <para>This configures <devicename>/dev/da2</devicename> as a + <para>This configures <filename>/dev/da2</filename> as a <command>geli</command> provider of which the master key file is located in <filename>/root/da2.key</filename>. <command>geli</command> will not use a passphrase when @@ -3218,18 +3127,14 @@ geli_da2_flags="-p -k /root/da2.key"</programlisting> </sect2> </sect1> - <sect1 id="swap-encrypting"> - <sect1info> + <sect1 xml:id="swap-encrypting"> + <info><title>Encrypting Swap Space</title> <authorgroup> - <author> - <firstname>Christian</firstname> - <surname>Brüffer</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Christian</firstname><surname>Brüffer</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Encrypting Swap Space</title> + <indexterm> <primary>swap</primary> @@ -3253,7 +3158,7 @@ geli_da2_flags="-p -k /root/da2.key"</programlisting> <note> <para>For the remainder of this section, - <devicename>ad0s1b</devicename> will be the swap + <filename>ad0s1b</filename> will be the swap partition.</para> </note> @@ -3262,7 +3167,7 @@ geli_da2_flags="-p -k /root/da2.key"</programlisting> overwrite the current swap parition with random garbage, execute the following command:</para> - <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/<replaceable>ad0s1b</replaceable> bs=1m</userinput></screen> + <screen>&prompt.root; <userinput>dd if=/dev/random of=/dev/ad0s1b bs=1m</userinput></screen> <sect2> <title>Swap Encryption with &man.gbde.8;</title> @@ -3324,38 +3229,21 @@ Device 1K-blocks Used Avail Capacity </sect2> </sect1> - <sect1 id="disks-hast"> - <sect1info> + <sect1 xml:id="disks-hast"> + <info><title>Highly Available Storage (HAST)</title> <authorgroup> - <author> - <firstname>Daniel</firstname> - <surname>Gerzo</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Freddie</firstname> - <surname>Cash</surname> - <contrib>With inputs from </contrib> - </author> - <author> - <firstname>Pawel Jakub</firstname> - <surname>Dawidek</surname> - </author> - <author> - <firstname>Michael W.</firstname> - <surname>Lucas</surname> - </author> - <author> - <firstname>Viktor</firstname> - <surname>Petersson</surname> - </author> + <author><personname><firstname>Freddie</firstname><surname>Cash</surname></personname><contrib>With inputs from </contrib></author> + <author><personname><firstname>Pawel Jakub</firstname><surname>Dawidek</surname></personname></author> + <author><personname><firstname>Michael W.</firstname><surname>Lucas</surname></personname></author> + <author><personname><firstname>Viktor</firstname><surname>Petersson</surname></personname></author> </authorgroup> - <!-- Date of writing: 26 February 2011 --> - </sect1info> + + </info> - <title>Highly Available Storage (HAST)</title> + <indexterm> <primary>HAST</primary> @@ -3404,28 +3292,24 @@ Device 1K-blocks Used Avail Capacity <itemizedlist> <listitem> - <para>Understand &unix; and <link - linkend="basics">&os; basics</link>.</para> + <para>Understand &unix; and <link linkend="basics">&os; basics</link>.</para> </listitem> <listitem> - <para>Know how to <link - linkend="config-tuning">configure</link> network + <para>Know how to <link linkend="config-tuning">configure</link> network interfaces and other core &os; subsystems.</para> </listitem> <listitem> - <para>Have a good understanding of <link - linkend="network-communication">&os; + <para>Have a good understanding of <link linkend="network-communication">&os; networking</link>.</para> </listitem> </itemizedlist> <para>The <acronym>HAST</acronym> project was sponsored by The - &os; Foundation with support from <ulink - url="http://www.omc.net/">OMCnet Internet Service - GmbH</ulink> and <ulink url="http://www.transip.nl/">TransIP - BV</ulink>.</para> + &os; Foundation with support from <link xlink:href="http://www.omc.net/">OMCnet Internet Service + GmbH</link> and <link xlink:href="http://www.transip.nl/">TransIP + BV</link>.</para> </sect2> <sect2> @@ -3515,7 +3399,7 @@ Device 1K-blocks Used Avail Capacity <para><acronym>HAST</acronym> operates synchronously on a block level, making it transparent to file systems and applications. <acronym>HAST</acronym> provides regular GEOM providers in - <filename class="directory">/dev/hast/</filename> for use by + <filename>/dev/hast/</filename> for use by other tools or applications, thus there is no difference between using <acronym>HAST</acronym>-provided devices and raw disks or partitions.</para> @@ -3609,18 +3493,17 @@ Device 1K-blocks Used Avail Capacity <literal>primary</literal>-<literal>secondary</literal> operation using <acronym>HAST</acronym> to replicate the data between the two. The nodes will be called - <literal><replaceable>hasta</replaceable></literal> with an IP + <literal>hasta</literal> with an IP address of <replaceable>172.16.0.1</replaceable> and - <literal><replaceable>hastb</replaceable></literal> with an IP + <literal>hastb</literal> with an IP of address <replaceable>172.16.0.2</replaceable>. Both nodes will have a dedicated hard drive - <devicename>/dev/<replaceable>ad6</replaceable></devicename> + <filename>/dev/ad6</filename> of the same size for <acronym>HAST</acronym> operation. The <acronym>HAST</acronym> pool, sometimes also referred to as a - resource or the GEOM provider in <filename - class="directory">/dev/hast/</filename>, will be + resource or the GEOM provider in <filename>/dev/hast/</filename>, will be called - <filename><replaceable>test</replaceable></filename>.</para> + <filename>test</filename>.</para> <para>Configuration of <acronym>HAST</acronym> is done using <filename>/etc/hast.conf</filename>. This file should be the @@ -3671,13 +3554,13 @@ Device 1K-blocks Used Avail Capacity administrator, or software like <application>Heartbeat</application>, using &man.hastctl.8;. On the primary node, - <literal><replaceable>hasta</replaceable></literal>, issue + <literal>hasta</literal>, issue this command:</para> <screen>&prompt.root; <userinput>hastctl role primary test</userinput></screen> <para>Similarly, run this command on the secondary node, - <literal><replaceable>hastb</replaceable></literal>:</para> + <literal>hastb</literal>:</para> <screen>&prompt.root; <userinput>hastctl role secondary test</userinput></screen> @@ -3704,10 +3587,10 @@ Device 1K-blocks Used Avail Capacity <para>The next step is to create a filesystem on the - <devicename>/dev/hast/<replaceable>test</replaceable></devicename> + <filename>/dev/hast/test</filename> GEOM provider and mount it. This must be done on the <literal>primary</literal> node, as - <filename>/dev/hast/<replaceable>test</replaceable></filename> + <filename>/dev/hast/test</filename> appears only on the <literal>primary</literal> node. Creating the filesystem can take a few minutes, depending on the size of the hard drive:</para> @@ -3743,7 +3626,7 @@ Device 1K-blocks Used Avail Capacity <acronym>CARP</acronym> on both nodes of the cluster according to the documentation available in <xref linkend="carp"/>. After setup, each node will - have its own <devicename>carp0</devicename> interface with a + have its own <filename>carp0</filename> interface with a shared IP address of <replaceable>172.16.0.254</replaceable>. The primary <acronym>HAST</acronym> node of the cluster must be the @@ -3791,7 +3674,7 @@ notify 30 { <screen>&prompt.root; <userinput>service devd restart</userinput></screen> - <para>When the <devicename>carp0</devicename> interface state + <para>When the <filename>carp0</filename> interface state changes by going up or down , the system generates a notification, allowing the &man.devd.8; subsystem to run an arbitrary script, in this case @@ -3828,7 +3711,7 @@ case "$1" in # Wait for any "hastd secondary" processes to stop for disk in ${resources}; do - while $( pgrep -lf "hastd: ${disk} \(secondary\)" > /dev/null 2>&1 ); do + while $( pgrep -lf "hastd: ${disk} \(secondary\)" > /dev/null 2>&1 ); do sleep 1 done @@ -3876,7 +3759,7 @@ case "$1" in umount -f /hast/${disk} fi sleep $delay - hastctl role secondary ${disk} 2>&1 + hastctl role secondary ${disk} 2>&1 if [ $? -ne 0 ]; then logger -p $log -t $name "Unable to switch role to secondary for resource ${disk}." exit 1 @@ -3935,7 +3818,7 @@ esac</programlisting> <para>More detailed information with additional examples can be found in the - <ulink url="http://wiki.FreeBSD.org/HAST">HAST Wiki</ulink> + <link xlink:href="http://wiki.FreeBSD.org/HAST">HAST Wiki</link> page.</para> </sect3> </sect2> @@ -3963,7 +3846,7 @@ esac</programlisting> foreground.</para> </sect3> - <sect3 id="disks-hast-sb"> + <sect3 xml:id="disks-hast-sb"> <title>Recovering from the Split-brain Condition</title> <para><literal>Split-brain</literal> is when the nodes of the diff --git a/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml b/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml index 398a5d73ba..a4ff233717 100644 --- a/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/dtrace/chapter.xml @@ -6,26 +6,24 @@ using other debugging (like -x in shell scripts). But then I realized that, over time and while DTrace becomes better supported, that might make this chapter too large. --> - <!-- The FreeBSD Documentation Project $FreeBSD$ --> - -<chapter id="dtrace"> - <chapterinfo> +<!-- XXXTR: Should probably put links and resources here. I'm + nervous about this chapter as it may require a partial + re-write and large modification once DTrace is complete, but + at least we can get everyone started ... --> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="dtrace"> + <info><title>&dtrace;</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>&dtrace;</title> + - <sect1 id="dtrace-synopsis"> + <sect1 xml:id="dtrace-synopsis"> <title>Synopsis</title> <indexterm><primary>&dtrace;</primary></indexterm> @@ -102,7 +100,7 @@ that might make this chapter too large. </warning> </sect1> - <sect1 id="dtrace-implementation"> + <sect1 xml:id="dtrace-implementation"> <title>Implementation Differences</title> <para>While the &dtrace; in &os; is very similar to that found @@ -133,11 +131,11 @@ that might make this chapter too large. allows tracing <function>malloc()</function> by type in the &os; kernel.</para> - <para>Only <username>root</username> may use &dtrace; on &os;. + <para>Only <systemitem class="username">root</systemitem> may use &dtrace; on &os;. This is related to security differences, &solaris; has a few low level security checks which do not yet exist in &os;. As - such, the <devicename>/dev/dtrace/dtrace</devicename> is - strictly limited to <username>root</username> users only.</para> + such, the <filename>/dev/dtrace/dtrace</filename> is + strictly limited to <systemitem class="username">root</systemitem> users only.</para> <para>Finally, the &dtrace; software falls under &sun;'s <acronym>CDDL</acronym> license. The <literal>Common @@ -145,8 +143,7 @@ that might make this chapter too large. see the <filename>/usr/src/cddl/contrib/opensolaris/OPENSOLARIS.LICENSE</filename> or view it online at - <ulink - url="http://www.opensolaris.org/os/licensing"></ulink>.</para> + <uri xlink:href="http://www.opensolaris.org/os/licensing">http://www.opensolaris.org/os/licensing</uri>.</para> <para>This license means that a &os; kernel with the &dtrace; options is still <acronym>BSD</acronym> licensed; however @@ -154,7 +151,7 @@ that might make this chapter too large. distributed in binary form, or the binaries are loaded.</para> </sect1> - <sect1 id="dtrace-enable"> + <sect1 xml:id="dtrace-enable"> <title>Enabling &dtrace; Support</title> <para>To enable support for &dtrace;, add the following lines to @@ -205,20 +202,20 @@ options DDB_CTF</programlisting> into memory, support for the Korn shell should be added. This is needed as the &dtrace;Toolkit has several utilities written in <command>ksh</command>. Install the - <filename role="package">shells/ksh93</filename>. It is also + <package>shells/ksh93</package>. It is also possible to run these tools under - <filename role="package">shells/pdksh</filename> or - <filename role="package">shells/mksh</filename>.</para> + <package>shells/pdksh</package> or + <package>shells/mksh</package>.</para> <para>Finally, obtain the current &dtrace;Toolkit. If you are running FreeBSD 10, you will find the &dtrace;Toolkit in <filename>/usr/share/dtrace</filename>. Otherwise, you can install the &dtrace;Toolkit using the - <filename role="package">sysutils/DTraceToolkit</filename> + <package>sysutils/DTraceToolkit</package> port.</para> </sect1> - <sect1 id="dtrace-using"> + <sect1 xml:id="dtrace-using"> <title>Using &dtrace;</title> <para>Before making use of &dtrace; functionality, the &dtrace; @@ -386,7 +383,7 @@ Elapsed Times for processes csh, of time.</para> </sect1> - <sect1 id="dtrace-language"> + <sect1 xml:id="dtrace-language"> <title>The D Language</title> <para>The &dtrace; Toolkit includes many scripts in the special @@ -394,12 +391,6 @@ Elapsed Times for processes csh, language</quote> by &sun; documentation, and it is very similar to C++. An in depth discussion of the language is beyond the scope of this document. It is extensively discussed - at <ulink - url="http://wikis.oracle.com/display/DTrace/Documentation"></ulink>.</para> + at <uri xlink:href="http://wikis.oracle.com/display/DTrace/Documentation">http://wikis.oracle.com/display/DTrace/Documentation</uri>.</para> </sect1> </chapter> - - <!-- XXXTR: Should probably put links and resources here. I'm - nervous about this chapter as it may require a partial - re-write and large modification once DTrace is complete, but - at least we can get everyone started ... --> diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml index 77ca4417de..d29ea432a0 100644 --- a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<appendix id="eresources"> +<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="eresources"> <title>Resources on the Internet</title> <para>The rapid pace of &os; progress makes print media @@ -22,7 +21,7 @@ not mentioned here to the &a.doc; so that they may also be included.</para> - <sect1 id="eresources-mail"> + <sect1 xml:id="eresources-mail"> <title>Mailing Lists</title> <para>The mailing lists are the most direct way of addressing @@ -49,20 +48,18 @@ </note> <para>When in doubt about what list to post a question to, see - <ulink url="&url.articles.freebsd-questions;">How to get best + <link xlink:href="&url.articles.freebsd-questions;">How to get best results from the FreeBSD-questions mailing - list</ulink>.</para> + list</link>.</para> <para>Before posting to any list, please learn about how to best use the mailing lists, such as how to help avoid - frequently-repeated discussions, by reading the <ulink - url="&url.articles.mailing-list-faq;"> Mailing List Frequently - Asked Questions</ulink> (FAQ) document.</para> + frequently-repeated discussions, by reading the <link xlink:href="&url.articles.mailing-list-faq;"> Mailing List Frequently + Asked Questions</link> (FAQ) document.</para> <para>Archives are kept for all of the mailing lists and can be - searched using the <ulink - url="&url.base;/search/index.html">&os; World Wide Web - server</ulink>. The keyword searchable archive offers an + searched using the <link xlink:href="&url.base;/search/index.html">&os; World Wide Web + server</link>. The keyword searchable archive offers an excellent way of finding answers to frequently asked questions and should be consulted before posting a question. Note that this also means that messages sent to &os; mailing lists @@ -70,7 +67,7 @@ concern, consider using a disposable secondary email address and posting only public information.</para> - <sect2 id="eresources-summary"> + <sect2 xml:id="eresources-summary"> <title>List Summary</title> <para><emphasis>General lists:</emphasis> The following are @@ -854,7 +851,7 @@ </informaltable> </sect2> - <sect2 id="eresources-subscribe"> + <sect2 xml:id="eresources-subscribe"> <title>How to Subscribe</title> <para>To subscribe to a list, click the list name at @@ -880,7 +877,7 @@ for infrequent traffic.</para> </sect2> - <sect2 id="eresources-charters"> + <sect2 xml:id="eresources-charters"> <title>List Charters</title> <para><emphasis>All</emphasis> &os; mailing lists have @@ -1059,9 +1056,8 @@ <para>This is the mailing list for reporting bugs in &os;. Whenever possible, bugs should be submitted - using the &man.send-pr.1; command or the <ulink - url="&url.base;/send-pr.html">WEB - interface</ulink> to it.</para> + using the &man.send-pr.1; command or the <link xlink:href="&url.base;/send-pr.html">WEB + interface</link> to it.</para> </listitem> </varlistentry> @@ -1419,7 +1415,7 @@ </listitem> </varlistentry> - <varlistentry id="eresources-charters-jobs"> + <varlistentry xml:id="eresources-charters-jobs"> <term>&a.jobs.name;</term> <listitem> @@ -1432,8 +1428,7 @@ for general employment issues since adequate forums for that already exist elsewhere.</para> - <para>Note that this list, like other <hostid - role="domainname">FreeBSD.org</hostid> mailing lists, + <para>Note that this list, like other <systemitem class="fqdomainname">FreeBSD.org</systemitem> mailing lists, is distributed worldwide. Be clear about the geographic location and the extent to which telecommuting or @@ -1675,8 +1670,7 @@ Collection</quote></emphasis></para> <para>Important news for developers, porters, and users - of the <quote>Ports Collection</quote> (<filename - class="directory">/usr/ports</filename>), including + of the <quote>Ports Collection</quote> (<filename>/usr/ports</filename>), including architecture/infrastructure changes, new capabilities, critical upgrade instructions, and release engineering information. This is a low-volume mailing list, @@ -1977,8 +1971,7 @@ <para>An editorial digest of the messages to this list might be posted to the &os; website every few months as part of the Status Reports - <footnote><para><ulink - url="http://www.freebsd.org/news/status/"></ulink></para></footnote>. + <footnote><para><uri xlink:href="http://www.freebsd.org/news/status/">http://www.freebsd.org/news/status/</uri></para></footnote>. Past reports are archived.</para> </listitem> </varlistentry> @@ -2046,7 +2039,7 @@ </varlistentry> </variablelist> </sect2> - <sect2 id="eresources-mailfiltering"> + <sect2 xml:id="eresources-mailfiltering"> <title>Filtering on the Mailing Lists</title> <para>The &os; mailing lists are filtered in multiple ways to @@ -2123,7 +2116,7 @@ </sect2> </sect1> - <sect1 id="eresources-news"> + <sect1 xml:id="eresources-news"> <title>Usenet Newsgroups</title> <para>In addition to two &os; specific newsgroups, there are @@ -2135,30 +2128,25 @@ <itemizedlist> <listitem> - <para><ulink - url="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</ulink></para> + <para><link xlink:href="news:comp.unix.bsd.freebsd.announce">comp.unix.bsd.freebsd.announce</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</ulink></para> + <para><link xlink:href="news:comp.unix.bsd.freebsd.misc">comp.unix.bsd.freebsd.misc</link></para> </listitem> <listitem> - <para><ulink - url="news:de.comp.os.unix.bsd">de.comp.os.unix.bsd</ulink> + <para><link xlink:href="news:de.comp.os.unix.bsd">de.comp.os.unix.bsd</link> (German)</para> </listitem> <listitem> - <para><ulink - url="news:fr.comp.os.bsd">fr.comp.os.bsd</ulink> + <para><link xlink:href="news:fr.comp.os.bsd">fr.comp.os.bsd</link> (French)</para> </listitem> <listitem> - <para><ulink - url="news:it.comp.os.freebsd">it.comp.os.freebsd</ulink> + <para><link xlink:href="news:it.comp.os.freebsd">it.comp.os.freebsd</link> (Italian)</para> </listitem> </itemizedlist> @@ -2169,57 +2157,47 @@ <itemizedlist> <listitem> - <para><ulink url="news:comp.unix">comp.unix</ulink></para> + <para><link xlink:href="news:comp.unix">comp.unix</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.questions">comp.unix.questions</ulink></para> + <para><link xlink:href="news:comp.unix.questions">comp.unix.questions</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.admin">comp.unix.admin</ulink></para> + <para><link xlink:href="news:comp.unix.admin">comp.unix.admin</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.programmer">comp.unix.programmer</ulink></para> + <para><link xlink:href="news:comp.unix.programmer">comp.unix.programmer</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.shell">comp.unix.shell</ulink></para> + <para><link xlink:href="news:comp.unix.shell">comp.unix.shell</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.user-friendly">comp.unix.user-friendly</ulink></para> + <para><link xlink:href="news:comp.unix.user-friendly">comp.unix.user-friendly</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.security.unix">comp.security.unix</ulink></para> + <para><link xlink:href="news:comp.security.unix">comp.security.unix</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.sources.unix">comp.sources.unix</ulink></para> + <para><link xlink:href="news:comp.sources.unix">comp.sources.unix</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.advocacy">comp.unix.advocacy</ulink></para> + <para><link xlink:href="news:comp.unix.advocacy">comp.unix.advocacy</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.misc">comp.unix.misc</ulink></para> + <para><link xlink:href="news:comp.unix.misc">comp.unix.misc</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.unix.bsd">comp.unix.bsd</ulink></para> + <para><link xlink:href="news:comp.unix.bsd">comp.unix.bsd</link></para> </listitem> </itemizedlist> </sect2> @@ -2229,77 +2207,67 @@ <itemizedlist> <listitem> - <para><ulink - url="news:comp.windows.x.i386unix">comp.windows.x.i386unix</ulink></para> + <para><link xlink:href="news:comp.windows.x.i386unix">comp.windows.x.i386unix</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.windows.x">comp.windows.x</ulink></para> + <para><link xlink:href="news:comp.windows.x">comp.windows.x</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.windows.x.apps">comp.windows.x.apps</ulink></para> + <para><link xlink:href="news:comp.windows.x.apps">comp.windows.x.apps</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.windows.x.announce">comp.windows.x.announce</ulink></para> + <para><link xlink:href="news:comp.windows.x.announce">comp.windows.x.announce</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</ulink></para> + <para><link xlink:href="news:comp.windows.x.intrinsics">comp.windows.x.intrinsics</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.windows.x.motif">comp.windows.x.motif</ulink></para> + <para><link xlink:href="news:comp.windows.x.motif">comp.windows.x.motif</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.windows.x.pex">comp.windows.x.pex</ulink></para> + <para><link xlink:href="news:comp.windows.x.pex">comp.windows.x.pex</link></para> </listitem> <listitem> - <para><ulink - url="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</ulink></para> + <para><link xlink:href="news:comp.emulators.ms-windows.wine">comp.emulators.ms-windows.wine</link></para> </listitem> </itemizedlist> </sect2> </sect1> - <sect1 id="eresources-web"> + <sect1 xml:id="eresources-web"> <title>World Wide Web Servers</title> - <sect2 id="eresources-web-social"> + <sect2 xml:id="eresources-web-social"> <title>Forums, Blogs, and Social Networks</title> <itemizedlist> - <listitem><para><ulink url="http://forums.freebsd.org/">The - &os; Forums</ulink> provide a web based discussion + <listitem><para><link xlink:href="http://forums.freebsd.org/">The + &os; Forums</link> provide a web based discussion forum for &os; questions and technical discussion.</para></listitem> - <listitem><para><ulink - url="http://planet.freebsdish.org/">Planet &os;</ulink> + <listitem><para><link xlink:href="http://planet.freebsdish.org/">Planet &os;</link> offers an aggregation feed of dozens of blogs written by &os; developers. Many developers use this to post quick notes about what they are working on, new patches, and other works in progress.</para></listitem> - <listitem><para>The <ulink - url="http://www.youtube.com/bsdconferences">BSDConferences - YouTube Channel</ulink> provides a collection of high + <listitem><para>The <link xlink:href="http://www.youtube.com/bsdconferences">BSDConferences + YouTube Channel</link> provides a collection of high quality videos from BSD Conferences around the world. This is a great way to watch key developers give presentations about new work in &os;.</para></listitem> </itemizedlist> </sect2> - <sect2 id="eresources-web-mirrors"> + <sect2 xml:id="eresources-web-mirrors"> <title>Official Mirrors</title> &chap.eresources.www.index.inc; @@ -2310,7 +2278,7 @@ </sect2> </sect1> - <sect1 id="eresources-email"> + <sect1 xml:id="eresources-email"> <title>Email Addresses</title> <para>The following user groups provide &os; related email diff --git a/en_US.ISO8859-1/books/handbook/filesystems/chapter.xml b/en_US.ISO8859-1/books/handbook/filesystems/chapter.xml index f47cdeee09..305a66593a 100644 --- a/en_US.ISO8859-1/books/handbook/filesystems/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/filesystems/chapter.xml @@ -3,21 +3,16 @@ The FreeBSD Documentation Project $FreeBSD$ --> - -<chapter id="filesystems"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="filesystems"> + <info><title>File Systems Support</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>File Systems Support</title> + - <sect1 id="filesystems-synopsis"> + <sect1 xml:id="filesystems-synopsis"> <title>Synopsis</title> <indexterm><primary>File Systems</primary></indexterm> @@ -73,13 +68,11 @@ <itemizedlist> <listitem> - <para>Understand &unix; and <link - linkend="basics">&os; basics</link>.</para> + <para>Understand &unix; and <link linkend="basics">&os; basics</link>.</para> </listitem> <listitem> - <para>Be familiar with the basics of <link - linkend="kernelconfig">kernel configuration and + <para>Be familiar with the basics of <link linkend="kernelconfig">kernel configuration and compilation</link>.</para> </listitem> @@ -89,14 +82,13 @@ </listitem> <listitem> - <para>Have some familiarity with <link - linkend="disks">disks</link>, storage, and device names in + <para>Have some familiarity with <link linkend="disks">disks</link>, storage, and device names in &os;.</para> </listitem> </itemizedlist> </sect1> - <sect1 id="filesystems-zfs"> + <sect1 xml:id="filesystems-zfs"> <title>The Z File System (ZFS)</title> <para>The Z file system, originally developed by &sun;, @@ -155,7 +147,7 @@ <sect3> <title>Loader Tunables</title> - <para>The <devicename>kmem</devicename> address space can + <para>The <filename>kmem</filename> address space can be increased on all &os; architectures. On a test system with one gigabyte of physical memory, success was achieved with the following options added to @@ -168,8 +160,7 @@ vfs.zfs.arc_max="40M" vfs.zfs.vdev.cache.size="5M"</programlisting> <para>For a more detailed list of recommendations for - ZFS-related tuning, see <ulink - url="http://wiki.freebsd.org/ZFSTuningGuide"></ulink>.</para> + ZFS-related tuning, see <uri xlink:href="http://wiki.freebsd.org/ZFSTuningGuide">http://wiki.freebsd.org/ZFSTuningGuide</uri>.</para> </sect3> </sect2> @@ -186,11 +177,11 @@ vfs.zfs.vdev.cache.size="5M"</programlisting> <para>The examples in this section assume three <acronym>SCSI</acronym> disks with the device names - <devicename><replaceable>da0</replaceable></devicename>, - <devicename><replaceable>da1</replaceable></devicename>, - and <devicename><replaceable>da2</replaceable></devicename>. + <filename>da0</filename>, + <filename>da1</filename>, + and <filename>da2</filename>. Users of <acronym>IDE</acronym> hardware should instead use - <devicename><replaceable>ad</replaceable></devicename> + <filename>ad</filename> device names.</para> <sect3> @@ -236,8 +227,7 @@ drwxr-xr-x 21 root wheel 512 Aug 29 23:12 .. <para>The <literal>example/compressed</literal> dataset is now a <acronym>ZFS</acronym> compressed file system. Try - copying some large files to <filename - class="directory">/example/compressed</filename>.</para> + copying some large files to <filename>/example/compressed</filename>.</para> <para>Compression can be disabled with:</para> @@ -367,8 +357,7 @@ example/data 17547008 0 17547008 0% /example/data</screen> &prompt.root; <userinput>ln -s /storage/home /usr/home</userinput></screen> <para>Users should now have their data stored on the freshly - created <filename - class="directory">/storage/home</filename>. Test by + created <filename>/storage/home</filename>. Test by adding a new user and logging in as that user.</para> <para>Try creating a snapshot which may be rolled back @@ -386,7 +375,7 @@ example/data 17547008 0 17547008 0% /example/data</screen> <para>To get a list of all available snapshots, run <command>ls</command> in the file system's - <filename class="directory">.zfs/snapshot</filename> + <filename>.zfs/snapshot</filename> directory. For example, to see the previously taken snapshot:</para> @@ -399,9 +388,8 @@ example/data 17547008 0 17547008 0% /example/data</screen> <screen>&prompt.root; <userinput>zfs destroy storage/home@08-30-08</userinput></screen> - <para>After testing, <filename - class="directory">/storage/home</filename> can be made the - real <filename class="directory">/home</filename> using + <para>After testing, <filename>/storage/home</filename> can be made the + real <filename>/home</filename> using this command:</para> <screen>&prompt.root; <userinput>zfs set mountpoint=/home storage/home</userinput></screen> @@ -409,7 +397,7 @@ example/data 17547008 0 17547008 0% /example/data</screen> <para>Run <command>df</command> and <command>mount</command> to confirm that the system now treats the file system as the real - <filename class="directory">/home</filename>:</para> + <filename>/home</filename>:</para> <screen>&prompt.root; <userinput>mount</userinput> /dev/ad0s1a on / (ufs, local) @@ -477,7 +465,7 @@ errors: No known data errors</screen> <screen>&prompt.root; <userinput>zpool offline storage da1</userinput></screen> <para>It is now possible to replace - <devicename>da1</devicename> after the system has been + <filename>da1</filename> after the system has been powered down. When the system is back online, the following command may issued to replace the disk:</para> @@ -575,7 +563,7 @@ errors: No known data errors</screen> </note> <para>The - <literal>refquota=<replaceable>size</replaceable></literal> + <literal>refquota=size</literal> limits the amount of space a dataset can consume by enforcing a hard limit on the space used. However, this hard limit does not include space used by descendants, such @@ -589,22 +577,18 @@ errors: No known data errors</screen> <para>User quotas limit the amount of space that can be used by the specified user. The general format is - <literal>userquota@<replaceable>user</replaceable>=<replaceable>size</replaceable></literal>, + <literal>userquota@user=size</literal>, and the user's name must be in one of the following formats:</para> <itemizedlist> <listitem> - <para><acronym - role="Portable Operating System - Interface">POSIX</acronym> compatible name such as + <para><acronym role="Portable Operating System Interface">POSIX</acronym> compatible name such as <replaceable>joe</replaceable>.</para> </listitem> <listitem> - <para><acronym - role="Portable Operating System - Interface">POSIX</acronym> + <para><acronym role="Portable Operating System Interface">POSIX</acronym> numeric ID such as <replaceable>789</replaceable>.</para> </listitem> @@ -635,14 +619,14 @@ errors: No known data errors</screen> <para>User quota properties are not displayed by <command>zfs get all</command>. - Non-<username>root</username> users can only see their own + Non-<systemitem class="username">root</systemitem> users can only see their own quotas unless they have been granted the <literal>userquota</literal> privilege. Users with this privilege are able to view and set everyone's quota.</para> <para>The group quota limits the amount of space that a specified group can consume. The general format is - <literal>groupquota@<replaceable>group</replaceable>=<replaceable>size</replaceable></literal>.</para> + <literal>groupquota@group=size</literal>.</para> <para>To set the quota for the group <replaceable>firstgroup</replaceable> to 50 GB, @@ -657,9 +641,9 @@ errors: No known data errors</screen> <screen>&prompt.root; <userinput>zfs set groupquota@firstgroup=none</userinput></screen> <para>As with the user quota property, - non-<username>root</username> users can only see the quotas + non-<systemitem class="username">root</systemitem> users can only see the quotas associated with the groups that they belong to. However, - <username>root</username> or a user with the + <systemitem class="username">root</systemitem> or a user with the <literal>groupquota</literal> privilege can view and set all quotas for all groups.</para> @@ -672,7 +656,7 @@ errors: No known data errors</screen> refer to &man.zfs.1;.</para> <para>Users with sufficient privileges and - <username>root</username> can list the quota for + <systemitem class="username">root</systemitem> can list the quota for <filename>storage/home/bob</filename> using:</para> <screen>&prompt.root; <userinput>zfs get quota storage/home/bob</userinput></screen> @@ -710,7 +694,7 @@ errors: No known data errors</screen> <para>The general format of the <literal>reservation</literal> property is - <literal>reservation=<replaceable>size</replaceable></literal>, + <literal>reservation=size</literal>, so to set a reservation of 10 GB on <filename>storage/home/bob</filename>, use:</para> @@ -724,7 +708,7 @@ errors: No known data errors</screen> <para>The same principle can be applied to the <literal>refreservation</literal> property for setting a refreservation, with the general format - <literal>refreservation=<replaceable>size</replaceable></literal>.</para> + <literal>refreservation=size</literal>.</para> <para>To check if any reservations or refreservations exist on <filename>storage/home/bob</filename>, execute one of the @@ -736,7 +720,7 @@ errors: No known data errors</screen> </sect2> </sect1> - <sect1 id="filesystems-linux"> + <sect1 xml:id="filesystems-linux"> <title>&linux; Filesystems</title> <para>This section describes some of the &linux; filesystems @@ -773,7 +757,7 @@ errors: No known data errors</screen> <acronym>SGI</acronym> for the <acronym>IRIX</acronym> operating system and was then ported to &linux; and released under the <acronym>GPL</acronym>. See - <ulink url="http://oss.sgi.com/projects/xfs">this page</ulink> + <link xlink:href="http://oss.sgi.com/projects/xfs">this page</link> for more details. The &os; port was started by Russel Cattelan, &a.kan.email;, and &a.rodrigc.email;.</para> @@ -791,7 +775,7 @@ errors: No known data errors</screen> <screen>&prompt.root; <userinput>mount -t xfs /dev/ad1s1 /mnt</userinput></screen> - <para>The <filename role="package">sysutils/xfsprogs</filename> + <para>The <package>sysutils/xfsprogs</package> port includes the <command>mkfs.xfs</command> which enables the creation of <acronym>XFS</acronym> filesystems, plus utilities for analyzing and repairing them.</para> diff --git a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml index 1105738cec..cfae0f3553 100644 --- a/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/firewalls/chapter.xml @@ -4,26 +4,17 @@ $FreeBSD$ --> - -<chapter id="firewalls"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="firewalls"> + <info><title>Firewalls</title> <authorgroup> - <author> - <firstname>Joseph J.</firstname> - <surname>Barbish</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Joseph J.</firstname><surname>Barbish</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Brad</firstname> - <surname>Davis</surname> - <contrib>Converted to SGML and updated by </contrib> - </author> + <author><personname><firstname>Brad</firstname><surname>Davis</surname></personname><contrib>Converted to SGML and updated by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Firewalls</title> + <indexterm><primary>firewall</primary></indexterm> @@ -33,7 +24,7 @@ <secondary>firewalls</secondary> </indexterm> - <sect1 id="firewalls-intro"> + <sect1 xml:id="firewalls-intro"> <title>Introduction</title> <para>Firewalls make it possible to filter the incoming and @@ -107,7 +98,7 @@ </itemizedlist> </sect1> - <sect1 id="firewalls-concepts"> + <sect1 xml:id="firewalls-concepts"> <title>Firewall Concepts</title> <indexterm> @@ -149,7 +140,7 @@ combination of stateful and non-stateful behavior.</para> </sect1> - <sect1 id="firewalls-apps"> + <sect1 xml:id="firewalls-apps"> <title>Firewall Packages</title> <para>&os; has three firewalls built into the base system: @@ -175,24 +166,18 @@ <acronym>TCP/IP</acronym> works, what the different values in the packet control fields are, and how these values are used in a normal session conversation. For a good introduction, refer - to <ulink - url="http://www.ipprimer.com/overview.cfm">Daryl's TCP/IP - Primer</ulink>.</para> + to <link xlink:href="http://www.ipprimer.com/overview.cfm">Daryl's TCP/IP + Primer</link>.</para> </sect1> - <sect1 id="firewalls-pf"> - <sect1info> + <sect1 xml:id="firewalls-pf"> + <info><title>PF and <acronym>ALTQ</acronym></title> <authorgroup> - <author> - <firstname>John</firstname> - <surname>Ferrell</surname> - <contrib>Revised and updated by </contrib> - <!-- 24 March 2008 --> - </author> + <author><personname><firstname>John</firstname><surname>Ferrell</surname></personname><contrib>Revised and updated by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>PF and <acronym>ALTQ</acronym></title> + <indexterm> <primary>firewall</primary> @@ -208,15 +193,13 @@ Quality of Service (<acronym>QoS</acronym>).</para> <para>Since the OpenBSD Project maintains the definitive - reference for <acronym>PF</acronym> in the<ulink - url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>, this + reference for <acronym>PF</acronym> in the<link xlink:href="http://www.openbsd.org/faq/pf/">PF FAQ</link>, this section of the Handbook focuses on <acronym>PF</acronym> as it pertains to &os;, while providing some general usage information.</para> <para>More information about porting <acronym>PF</acronym> to &os; - can be found at <ulink - url="http://pf4freebsd.love2party.net/"></ulink>.</para> + can be found at <uri xlink:href="http://pf4freebsd.love2party.net/">http://pf4freebsd.love2party.net/</uri>.</para> <sect2> <title>Using the PF Loadable Kernel Modules</title> @@ -241,8 +224,7 @@ <programlisting>pf_rules="<replaceable>/path/to/pf.conf</replaceable>"</programlisting> <para>The sample <filename>pf.conf</filename> - can be found in <filename - class="directory">/usr/share/examples/pf/</filename>.</para> + can be found in <filename>/usr/share/examples/pf/</filename>.</para> <para>The <acronym>PF</acronym> module can also be loaded manually from the command line:</para> @@ -289,8 +271,7 @@ exposes certain changes to the state table used by <acronym>PF</acronym>. It can be paired with &man.carp.4; to create failover firewalls using <acronym>PF</acronym>. More - information on <acronym>CARP</acronym> can be found in <link - linkend="carp">of the Handbook</link>.</para> + information on <acronym>CARP</acronym> can be found in <link linkend="carp">of the Handbook</link>.</para> <para>The following <acronym>PF</acronym> kernel options can be found in <filename>/usr/src/sys/conf/NOTES</filename>:</para> @@ -342,12 +323,11 @@ pflog_flags="" # additional flags for pflogd startup</programli specified in this file. The &os; installation includes several sample files located in <filename>/usr/share/examples/pf/</filename>. Refer to the - <ulink url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink> for + <link xlink:href="http://www.openbsd.org/faq/pf/">PF FAQ</link> for complete coverage of <acronym>PF</acronym> rulesets.</para> <warning> - <para>When reading the <ulink - url="http://www.openbsd.org/faq/pf/">PF FAQ</ulink>, + <para>When reading the <link xlink:href="http://www.openbsd.org/faq/pf/">PF FAQ</link>, keep in mind that different versions of &os; contain different versions of PF. Currently, &os; 8.<replaceable>X</replaceable> is using the @@ -378,33 +358,33 @@ pflog_flags="" # additional flags for pflogd startup</programli <tbody> <row> <entry><command>pfctl - <option>-e</option></command></entry> + -e</command></entry> <entry>Enable PF.</entry> </row> <row> <entry><command>pfctl - <option>-d</option></command></entry> + -d</command></entry> <entry>Disable PF.</entry> </row> <row> - <entry><command>pfctl <option>-F</option> all - <option>-f</option> /etc/pf.conf</command></entry> + <entry><command>pfctl -F all + -f /etc/pf.conf</command></entry> <entry>Flush all NAT, filter, state, and table rules and reload <filename>/etc/pf.conf</filename>.</entry> </row> <row> - <entry><command>pfctl <option>-s</option> [ rules | nat + <entry><command>pfctl -s [ rules | nat state ]</command></entry> <entry>Report on the filter rules, NAT rules, or state table.</entry> </row> <row> - <entry><command>pfctl <option>-vnf</option> + <entry><command>pfctl -vnf /etc/pf.conf</command></entry> <entry>Check <filename>/etc/pf.conf</filename> for errors, but do not load ruleset.</entry> @@ -460,8 +440,7 @@ options ALTQ_NOPCC # Required for SMP build</programlisting> <para><literal>options ALTQ_HFSC</literal> enables the <emphasis>Hierarchical Fair Service Curve Packet Scheduler</emphasis> <acronym>HFSC</acronym>. For more - information, refer to <ulink - url="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html"></ulink>.</para> + information, refer to <uri xlink:href="http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html">http://www-2.cs.cmu.edu/~hzhang/HFSC/main.html</uri>.</para> <para><literal>options ALTQ_PRIQ</literal> enables <emphasis>Priority Queuing</emphasis> @@ -474,34 +453,28 @@ options ALTQ_NOPCC # Required for SMP build</programlisting> systems.</para> </sect2> - <sect2 id="pf-tutorial"> - <sect2info> + <sect2 xml:id="pf-tutorial"> + <info><title><acronym>PF</acronym> Rule Sets and Tools</title> <authorgroup> - <author> - <firstname>Peter</firstname> - <surname>Hansteen</surname> - <othername>N. M.</othername> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Peter</firstname><surname>Hansteen</surname><othername>N. M.</othername></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title><acronym>PF</acronym> Rule Sets and Tools</title> + <para>This section demonstrates some useful <acronym>PF</acronym> features and <acronym>PF</acronym> related tools in a series of examples. A more thorough - tutorial is available at <ulink - url="http://home.nuug.no/~peter/pf/">http://home.nuug.no/~peter/pf/</ulink>.</para> + tutorial is available at <link xlink:href="http://home.nuug.no/~peter/pf/">http://home.nuug.no/~peter/pf/</link>.</para> <tip> - <para><filename role="package">security/sudo</filename> is + <para><package>security/sudo</package> is useful for running commands like <command>pfctl</command> that require elevated privileges. It can be installed from the Ports Collection.</para> </tip> - <sect3 id="pftut-simplest"> + <sect3 xml:id="pftut-simplest"> <title>The Simplest Rule Set Ever</title> <para>The simplest possible setup is for a single machine @@ -533,9 +506,8 @@ pass out all keep state</programlisting> of some thinking. The point of packet filtering is to take control, not to run catch-up with what the bad guys do. Marcus Ranum has written a very entertaining and - informative article about this, <ulink - url="http://www.ranum.com/security/computer_security/editorials/dumb/index.html">The - Six Dumbest Ideas in Computer Security</ulink>, and + informative article about this, <link xlink:href="http://www.ranum.com/security/computer_security/editorials/dumb/index.html">The + Six Dumbest Ideas in Computer Security</link>, and it is well written too.</para></footnote>. This gives us the opportunity to introduce two of the features which make <acronym>PF</acronym> such a wonderful tool: @@ -609,7 +581,7 @@ pass proto udp to any port $udp_services keep state</programlisting> </tip> </sect3> - <sect3 id="pftut-gateway"> + <sect3 xml:id="pftut-gateway"> <title>A Simple Gateway with NAT</title> <para>To most users, a single machine setup will be of limited @@ -618,7 +590,7 @@ pass proto udp to any port $udp_services keep state</programlisting> which is running <acronym>PF</acronym> and also acts as a gateway for at least one other machine.</para> - <sect4 id="pftut-gwpitfalls"> + <sect4 xml:id="pftut-gwpitfalls"> <title>Gateways and the Pitfalls of <literal>in</literal>, <literal>out</literal> and <literal>on</literal></title> @@ -636,8 +608,8 @@ pass proto udp to any port $udp_services keep state</programlisting> <para>It is very reasonable to think that for traffic to pass from the network connected to - <devicename>xl1</devicename> to hosts on the network - connected to <devicename>xl0</devicename>, a rule like + <filename>xl1</filename> to hosts on the network + connected to <filename>xl0</filename>, a rule like this is needed:</para> <programlisting>pass in on xl1 from xl1:network to xl0:network port $ports keep state</programlisting> @@ -680,7 +652,7 @@ pass proto udp to any port $udp_services keep state</programlisting> for readability.</para> </sect4> - <sect4 id="pftut-whatsthelocalnet"> + <sect4 xml:id="pftut-whatsthelocalnet"> <title>What is the Local Network, Anyway?</title> <para>Above, we introduced the @@ -711,7 +683,7 @@ pass proto udp to any port $udp_services keep state</programlisting> stick to that convention from here on.</para> </sect4> - <sect4 id="pftut-gwsimplesetup"> + <sect4 xml:id="pftut-gwsimplesetup"> <title>Setting Up</title> <para>We assume that the machine has acquired another @@ -749,7 +721,7 @@ ipv6_gateway_enable="YES" #for ipv6</programlisting> <para>Use <command>ifconfig -a</command>, or <command>ifconfig - <replaceable>interface_name</replaceable></command> to + interface_name</command> to find out if both of the interfaces to be used are up and running.</para> @@ -862,7 +834,7 @@ pass from { lo0, $localnet } to any keep state</programlisting> </sect4> </sect3> - <sect3 id="pftut-ftp"> + <sect3 xml:id="pftut-ftp"> <title>That Sad Old <acronym>FTP</acronym> Thing</title> <para>The short list of real life <acronym>TCP</acronym> ports @@ -912,7 +884,7 @@ pass from { lo0, $localnet } to any keep state</programlisting> program which is written specifically for this purpose.</para> - <sect4 id="pftut-ftp-proxy"> + <sect4 xml:id="pftut-ftp-proxy"> <title><acronym>FTP</acronym> Via Redirect: <application>ftp-proxy</application></title> @@ -963,7 +935,7 @@ rdr-anchor "ftp-proxy/*"</programlisting> after the <literal>nat</literal> rule in <filename>/etc/pf.conf</filename></para> - <programlisting>rdr pass on $int_if proto tcp from any to any port ftp -> 127.0.0.1 port 8021</programlisting> + <programlisting>rdr pass on $int_if proto tcp from any to any port ftp -> 127.0.0.1 port 8021</programlisting> <para>In addition, the redirected traffic must be allowed to pass. We achieve this with</para> @@ -1005,7 +977,7 @@ rdr-anchor "ftp-proxy/*"</programlisting> </sect4> </sect3> - <sect3 id="pftut-icmp"> + <sect3 xml:id="pftut-icmp"> <title>Easing Troubleshooting</title> <para>Making network troubleshooting friendly is a potentially @@ -1056,7 +1028,7 @@ rdr-anchor "ftp-proxy/*"</programlisting> these rule sets have been around for roughly fifteen years, and the people who put them there are still scared.</para> - <sect4 id="pftut-dowepass"> + <sect4 xml:id="pftut-dowepass"> <title>Then, Do We Let it All Through?</title> <para>The obvious question then becomes, if @@ -1079,7 +1051,7 @@ rdr-anchor "ftp-proxy/*"</programlisting> <literal>keep state</literal> rules.</para> </sect4> - <sect4 id="pftut-icmpstopatgw"> + <sect4 xml:id="pftut-icmpstopatgw"> <title>The Easy Way Out: the Buck Stops Here</title> <para>The easiest solution could very well be to let all @@ -1095,7 +1067,7 @@ pass inet proto icmp from any to $ext_if keep state</programlisting> flexibility.</para> </sect4> - <sect4 id="pftut-letpingthru"> + <sect4 xml:id="pftut-letpingthru"> <title>Letting <command>ping</command> Through</title> <para>The rule set we have developed so far has one clear @@ -1124,7 +1096,7 @@ pass inet proto icmp from any to $ext_if keep state</programlisting> allowed.</para> </sect4> - <sect4 id="pftut-helptraceroute"> + <sect4 xml:id="pftut-helptraceroute"> <title>Helping &man.traceroute.8;</title> <para>&man.traceroute.8; is another command which is quite @@ -1155,13 +1127,12 @@ pass out on $ext_if inet proto udp from any to any port 33433 >< 33626 kee <para>Under any circumstances, this solution was lifted from an openbsd-misc post. I've found that list, and the searchable list archives (accessible among other - places from <ulink - url="http://marc.theaimsgroup.com/">http://marc.theaimsgroup.com/</ulink>), + places from <link xlink:href="http://marc.theaimsgroup.com/">http://marc.theaimsgroup.com/</link>), to be a very valuable resource whenever you need OpenBSD or <acronym>PF</acronym> related information.</para> </sect4> - <sect4 id="pftut-pathmtudisc"> + <sect4 xml:id="pftut-pathmtudisc"> <title>Path <acronym>MTU</acronym> Discovery</title> <para>Internet protocols are designed to be device @@ -1213,14 +1184,14 @@ pass out on $ext_if inet proto udp from any to any port 33433 >< 33626 kee ICMP for IPv6 are found in RFC1885, RFC2463, RFC2466. These documents are available in a number of places on the net, such as the - <ulink url="http://www.ietf.org">ietf.org</ulink> + <link xlink:href="http://www.ietf.org">ietf.org</link> and - <ulink url="http://www.faqs.org">faqs.org</ulink> + <link xlink:href="http://www.faqs.org">faqs.org</link> web sites.</para></footnote>.</para> </sect4> </sect3> - <sect3 id="pftut-tables"> + <sect3 xml:id="pftut-tables"> <title>Tables Make Life Easier</title> <para>By this time it may appear that this gets awfully static @@ -1285,7 +1256,7 @@ pass out on $ext_if inet proto udp from any to any port 33433 >< 33626 kee and creativity.</para> </sect3> - <sect3 id="pftut-overload"> + <sect3 xml:id="pftut-overload"> <title>Overload Tables</title> <para>Those who run a Secure Shell login service which is @@ -1374,9 +1345,8 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from <note> <para>These rules will <emphasis>not</emphasis> block slow - bruteforcers, sometimes referred to as <ulink - url="http://home.nuug.no/~peter/hailmary2013/">the Hail - Mary Cloud</ulink>.</para> + bruteforcers, sometimes referred to as <link xlink:href="http://home.nuug.no/~peter/hailmary2013/">the Hail + Mary Cloud</link>.</para> </note> <para>Once again, please keep in mind that this example rule @@ -1399,8 +1369,8 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from <para>It should be possible to find the set of parameters which is just right for individual situations by reading the relevant man pages and the - <ulink url="http://www.openbsd.org/faq/pf/">PF User - Guide</ulink>, and perhaps a bit of + <link xlink:href="http://www.openbsd.org/faq/pf/">PF User + Guide</link>, and perhaps a bit of experimentation.</para> <note> @@ -1421,7 +1391,7 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from case, to redirect to a specific web page.</para> </note> - <sect4 id="pftut-expire"> + <sect4 xml:id="pftut-expire"> <title>Expiring Table Entries with <application>pfctl</application></title> @@ -1450,7 +1420,7 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from seconds.</para> </sect4> - <sect4 id="pftut-expiretable"> + <sect4 xml:id="pftut-expiretable"> <title>The <application>expiretable</application> Tool</title> @@ -1474,18 +1444,17 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from <programlisting>/usr/local/sbin/expiretable -v -d -t 24h bruteforce</programlisting> <para><application>expiretable</application> is in the - Ports Collection on &os; as <filename - role="package">security/expiretable</filename>.</para> + Ports Collection on &os; as <package>security/expiretable</package>.</para> </sect4> </sect3> - <sect3 id="pftut-tools"> + <sect3 xml:id="pftut-tools"> <title>Other <acronym>PF</acronym> Tools</title> <para>Over time, a number of tools have been developed which interact with <acronym>PF</acronym> in various ways.</para> - <sect4 id="pftut-pftop"> + <sect4 xml:id="pftut-pftop"> <title>The <application>pftop</application> Traffic Viewer</title> @@ -1493,14 +1462,14 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from makes it possible to keep an eye on what passes into and out of the network. <application>pftop</application> is available through the ports system as - <filename role="package">sysutils/pftop</filename>. The + <package>sysutils/pftop</package>. The name is a strong hint at what it does - <application>pftop</application> shows a running snapshot of traffic in a format which is strongly inspired by &man.top.1;.</para> </sect4> - <sect4 id="pftut-spamd"> + <sect4 xml:id="pftut-spamd"> <title>The <application>spamd</application> Spam Deferral Daemon</title> @@ -1537,7 +1506,7 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from implementation with one byte SMTP replies is often referred to as <firstterm>stuttering</firstterm>.</para> - <sect5 id="pftut-spamd-allblack"> + <sect5 xml:id="pftut-spamd-allblack"> <title>A Basic Blacklisting <application>spamd</application></title> @@ -1547,13 +1516,11 @@ Sep 26 03:12:44 skapet sshd[24703]: Failed password for invalid user admin from <procedure> <step> - <para>Install the <filename - role="package">mail/spamd/</filename> port. In + <para>Install the <package>mail/spamd/</package> port. In particular, be sure to read the package message and act upon what it says. Specifically, to use <application>spamd</application>'s greylisting - features, a file descriptor file system (see <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=fdescfs&sektion=5">fdescfs(5)</ulink>) + features, a file descriptor file system (see <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=fdescfs&sektion=5">fdescfs(5)</link>) must be mounted at <filename>/dev/fd/</filename>. Do this by adding the following line to <filename>/etc/fstab</filename>:</para> @@ -1683,7 +1650,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ several minutes.</para> </sect5> - <sect5 id="pftut-spamd-greylist"> + <sect5 xml:id="pftut-spamd-greylist"> <title>Adding Greylisting to the <application>spamd</application> Setup</title> @@ -1703,8 +1670,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ paper by Evan Harris <footnote><para>The original Harris paper and a number of other useful articles - and resources can be found at the <ulink - url="http://www.greylisting.org/">greylisting.org</ulink> + and resources can be found at the <link xlink:href="http://www.greylisting.org/">greylisting.org</link> web site.</para></footnote>, and a number of implementations followed over the next few months. OpenBSD's <application>spamd</application> acquired its @@ -1797,7 +1763,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ </sect5> </sect4> - <sect4 id="pftut-hygiene"> + <sect4 xml:id="pftut-hygiene"> <title>Network Hygiene: Blocking, Scrubbing and so On</title> @@ -1806,7 +1772,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ a bit more sanely towards hosts on the wide net and our local network.</para> - <sect5 id="pftut-blockpolicy"> + <sect5 xml:id="pftut-blockpolicy"> <title><literal>block-policy</literal></title> <para><literal>block-policy</literal> is an option which @@ -1829,7 +1795,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ <programlisting>set block-policy return</programlisting> </sect5> - <sect5 id="pftut-scrub"> + <sect5 xml:id="pftut-scrub"> <title><literal>scrub</literal></title> <para>In <acronym>PF</acronym> versions up to OpenBSD 4.5 @@ -1863,7 +1829,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ experimentation.</para> </sect5> - <sect5 id="pftut-antispoof"> + <sect5 xml:id="pftut-antispoof"> <title><literal>antispoof</literal></title> <para><literal>antispoof</literal> is a common special @@ -1881,7 +1847,7 @@ rdr pass on $ext_if inet proto tcp from !<spamd-white> to \ antispoof for $int_if</programlisting> </sect5> - <sect5 id="pftut-unrouteables"> + <sect5 xml:id="pftut-unrouteables"> <title>Handling Non-Routable Addresses from Elsewhere</title> @@ -1927,8 +1893,7 @@ block drop out quick on $ext_if from any to $martians</programlisting> <para>This completes our simple NATing firewall for a small local network. A more thorough tutorial is - available at <ulink - url="http://home.nuug.no/~peter/pf/">http://home.nuug.no/~peter/pf/</ulink>, + available at <link xlink:href="http://home.nuug.no/~peter/pf/">http://home.nuug.no/~peter/pf/</link>, where you will also find slides from related presentations.</para> </sect5> @@ -1937,7 +1902,7 @@ block drop out quick on $ext_if from any to $martians</programlisting> </sect2> </sect1> - <sect1 id="firewalls-ipf"> + <sect1 xml:id="firewalls-ipf"> <title>The IPFILTER (IPF) Firewall</title> <indexterm> @@ -1975,17 +1940,13 @@ block drop out quick on $ext_if from any to $martians</programlisting> for configuring an inclusive firewall ruleset.</para> <para>For a detailed explanation of the legacy rules processing - method, refer to <ulink - url="http://www.munk.me.uk/ipf/ipf-howto.html"></ulink> - and <ulink - url="http://coombs.anu.edu.au/~avalon/ip-filter.html"></ulink>.</para> + method, refer to <uri xlink:href="http://www.munk.me.uk/ipf/ipf-howto.html">http://www.munk.me.uk/ipf/ipf-howto.html</uri> + and <uri xlink:href="http://coombs.anu.edu.au/~avalon/ip-filter.html">http://coombs.anu.edu.au/~avalon/ip-filter.html</uri>.</para> - <para>The IPF FAQ is at <ulink - url="http://www.phildev.net/ipf/index.html"></ulink>.</para> + <para>The IPF FAQ is at <uri xlink:href="http://www.phildev.net/ipf/index.html">http://www.phildev.net/ipf/index.html</uri>.</para> <para>A searchable archive of the IPFilter mailing list is - available at <ulink - url="http://marc.theaimsgroup.com/?l=ipfilter"></ulink>.</para> + available at <uri xlink:href="http://marc.theaimsgroup.com/?l=ipfilter">http://marc.theaimsgroup.com/?l=ipfilter</uri>.</para> <sect2> <title>Enabling IPF</title> @@ -2047,7 +2008,7 @@ options IPFILTER_DEFAULT_BLOCK</programlisting> the <quote>IPFILTER</quote> firewall.</para> <para><literal>options IPFILTER_LOG</literal> enables IPF - logging using the <devicename>ipl</devicename> packet logging + logging using the <filename>ipl</filename> packet logging pseudo—device for every rule that has the <literal>log</literal> keyword.</para> @@ -2374,7 +2335,7 @@ LOG_ERR - packets which have been logged and which can be considered short</scre unreachable message.</para> </sect2> - <sect2 id="firewalls-ipf-rules-script"> + <sect2 xml:id="firewalls-ipf-rules-script"> <title>Building the Rule Script with Symbolic Substitution</title> @@ -2463,8 +2424,7 @@ EOF adding <literal>ipfilter_enable="NO"</literal>to <filename>/etc/rc.conf</filename>.</para> - <para>Then, add a script like the following to <filename - class="directory">/usr/local/etc/rc.d/</filename>. + <para>Then, add a script like the following to <filename>/usr/local/etc/rc.d/</filename>. The script should have an obvious name like <filename>ipf.loadrules.sh</filename>, where the <filename>.sh</filename> extension is mandatory.</para> @@ -2473,7 +2433,7 @@ EOF sh /etc/ipf.rules.script</programlisting> <para>The permissions on this script file must be read, - write, execute for owner <username>root</username>:</para> + write, execute for owner <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>chmod 700 /usr/local/etc/rc.d/ipf.loadrules.sh</userinput></screen> </listitem> @@ -2698,11 +2658,9 @@ sh /etc/ipf.rules.script</programlisting> <para>There is no way to match ranges of IP addresses which do not express themselves easily using the dotted numeric - form / mask-length notation. The <filename - role="package">net-mgmt/ipcalc</filename> port may be + form / mask-length notation. The <package>net-mgmt/ipcalc</package> port may be used to ease the calculation. Additional information - is available at the utility's web page: <ulink - url="http://jodies.de/ipcalc"></ulink>.</para> + is available at the utility's web page: <uri xlink:href="http://jodies.de/ipcalc">http://jodies.de/ipcalc</uri>.</para> </sect3> <sect3> @@ -2834,8 +2792,8 @@ sh /etc/ipf.rules.script</programlisting> network or a desktop system not protected by firewall on the network.</para> - <para>&os; uses interface <devicename>lo0</devicename> and IP - address <hostid role="ipaddr">127.0.0.1</hostid> for internal + <para>&os; uses interface <filename>lo0</filename> and IP + address <systemitem class="ipaddress">127.0.0.1</systemitem> for internal communication within the operating system. The firewall rules must contain rules to allow free movement of these internally used packets.</para> @@ -2887,7 +2845,7 @@ sh /etc/ipf.rules.script</programlisting> <literal>log first</literal> option, will only log the event the first time they are triggered. This option is included in the sample <literal>nmap OS fingerprint</literal> rule. The - <filename role="package">security/nmap</filename> utility is + <package>security/nmap</package> utility is commonly used by attackers who attempt to identify the operating system of the server.</para> @@ -2900,14 +2858,12 @@ sh /etc/ipf.rules.script</programlisting> <para>To lookup unknown port numbers, refer to <filename>/etc/services</filename>. Alternatively, visit - <ulink - url="http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers"></ulink> + <uri xlink:href="http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers">http://en.wikipedia.org/wiki/List_of_TCP_and_UDP_port_numbers</uri> and do a port number lookup to find the purpose of a particular port number.</para> <para>Check out this link for port numbers used by Trojans - <ulink - url="http://www.sans.org/security-resources/idfaq/oddports.php"></ulink>.</para> + <uri xlink:href="http://www.sans.org/security-resources/idfaq/oddports.php">http://www.sans.org/security-resources/idfaq/oddports.php</uri>.</para> <para>The following ruleset creates an <literal>inclusive</literal> firewall ruleset which can be @@ -2918,7 +2874,7 @@ sh /etc/ipf.rules.script</programlisting> <para>To avoid logging unwanted messages, add a <literal>block</literal> rule in the inbound section.</para> - <para>Change the <devicename>dc0</devicename> interface name in + <para>Change the <filename>dc0</filename> interface name in every rule to the interface name that connects the system to the public Internet.</para> @@ -3210,8 +3166,7 @@ block in log first quick on dc0 all <para>The <replaceable>LAN_IP_RANGE</replaceable> is used by the internal clients use for IP Addressing. Usually, this is - something like <hostid - role="ipaddr">192.168.1.0/24</hostid>.</para> + something like <systemitem class="ipaddress">192.168.1.0/24</systemitem>.</para> <para>The <replaceable>PUBLIC_ADDRESS</replaceable> can either be the static external IP address or the special keyword @@ -3335,9 +3290,8 @@ block in log first quick on dc0 all servers still has to undergo <acronym>NAT</acronym>, but there has to be some way to direct the inbound traffic to the correct server. For example, a web server operating on LAN - address <hostid - role="ipaddr">10.0.10.25</hostid> and using a single public - IP address of <hostid role="ipaddr">20.20.20.5</hostid>, would + address <systemitem class="ipaddress">10.0.10.25</systemitem> and using a single public + IP address of <systemitem class="ipaddress">20.20.20.5</systemitem>, would use this rule:</para> <programlisting>rdr dc0 20.20.20.5/32 port 80 -> 10.0.10.25 port 80</programlisting> @@ -3346,8 +3300,7 @@ block in log first quick on dc0 all <programlisting>rdr dc0 0.0.0.0/0 port 80 -> 10.0.10.25 port 80</programlisting> - <para>For a LAN DNS server on a private address of <hostid - role="ipaddr">10.0.10.33</hostid> that needs to receive + <para>For a LAN DNS server on a private address of <systemitem class="ipaddress">10.0.10.33</systemitem> that needs to receive public DNS requests:</para> <programlisting>rdr dc0 20.20.20.5/32 port 53 -> 10.0.10.33 port 53 udp</programlisting> @@ -3360,8 +3313,7 @@ block in log first quick on dc0 all difference is in how the data channel is acquired. Passive mode is more secure as the data channel is acquired by the ordinal ftp session requester. For a good explanation of FTP - and the different modes, see <ulink - url="http://www.slacksite.com/other/ftp.html"></ulink>.</para> + and the different modes, see <uri xlink:href="http://www.slacksite.com/other/ftp.html">http://www.slacksite.com/other/ftp.html</uri>.</para> <sect3> <title>IP<acronym>NAT</acronym> Rules</title> @@ -3422,7 +3374,7 @@ pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state</pro </sect2> </sect1> - <sect1 id="firewalls-ipfw"> + <sect1 xml:id="firewalls-ipfw"> <title>IPFW</title> <indexterm> @@ -3452,7 +3404,7 @@ pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state</pro facility, and the ipstealth facility. IPFW supports both IPv4 and IPv6.</para> - <sect2 id="firewalls-ipfw-enable"> + <sect2 xml:id="firewalls-ipfw-enable"> <title>Enabling IPFW</title> <indexterm> @@ -3479,7 +3431,7 @@ pass in quick on rl0 proto tcp from any to any port = 20 flags S keep state</pro net.inet.ip.fw.verbose_limit=5</programlisting> </sect2> - <sect2 id="firewalls-ipfw-kernel"> + <sect2 xml:id="firewalls-ipfw-kernel"> <title>Kernel Options</title> <indexterm> @@ -3560,7 +3512,7 @@ net.inet.ip.fw.verbose_limit=5</programlisting> </note> </sect2> - <sect2 id="firewalls-ipfw-rc"> + <sect2 xml:id="firewalls-ipfw-rc"> <title><filename>/etc/rc.conf</filename> Options</title> <para>Enables the firewall:</para> @@ -3597,7 +3549,7 @@ net.inet.ip.fw.verbose_limit=5</programlisting> firewall rules.</para> </listitem> <listitem> - <para><filename><replaceable>filename</replaceable></filename>: + <para><filename>filename</filename>: absolute path of the file containing the firewall rules.</para> </listitem> @@ -3656,7 +3608,7 @@ ipfw add deny out</programlisting> options.</para> </sect2> - <sect2 id="firewalls-ipfw-cmd"> + <sect2 xml:id="firewalls-ipfw-cmd"> <title>The IPFW Command</title> <indexterm><primary><command>ipfw</command></primary></indexterm> @@ -3710,10 +3662,10 @@ ipfw add deny out</programlisting> <para>To zero the counters for just the rule with number <replaceable>NUM</replaceable>:</para> - <screen>&prompt.root; <userinput>ipfw zero <replaceable>NUM</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ipfw zero NUM</userinput></screen> </sect2> - <sect2 id="firewalls-ipfw-rules"> + <sect2 xml:id="firewalls-ipfw-rules"> <title>IPFW Rulesets</title> <indexterm> @@ -3750,7 +3702,7 @@ ipfw add deny out</programlisting> easy to lock out even the administrator.</para> </warning> - <sect3 id="firewalls-ipfw-rules-syntax"> + <sect3 xml:id="firewalls-ipfw-rules-syntax"> <title>Rule Syntax</title> <indexterm> @@ -3877,7 +3829,7 @@ ipfw add deny out</programlisting> are specified in dotted IP address format followed by the mask in CIDR notation, or as a single host in dotted IP address format. This keyword is a mandatory requirement. - The <filename role="package">net-mgmt/ipcalc</filename> + The <package>net-mgmt/ipcalc</package> port may be used to assist the mask calculation.</para> <para><parameter>port number</parameter></para> @@ -4005,7 +3957,7 @@ ipfw add deny out</programlisting> defined in <filename>/etc/syslog.conf</filename>.</para> </sect3> - <sect3 id="firewalls-ipfw-rules-script"> + <sect3 xml:id="firewalls-ipfw-rules-script"> <title>Building a Rule Script</title> <para>Most experienced IPFW users create a file containing @@ -4076,7 +4028,7 @@ ks="keep-state" # just too lazy to key this each time <literal>pass</literal> rules for services that are not required. To avoid logging undesired messages, add a <literal>deny</literal> rule in the inbound section. - Change the <devicename>dc0</devicename> in every rule to the + Change the <filename>dc0</filename> in every rule to the device name of the interface that connects the system to the Internet.</para> diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.xml b/en_US.ISO8859-1/books/handbook/geom/chapter.xml index b25ad6c2c1..66a00571e6 100644 --- a/en_US.ISO8859-1/books/handbook/geom/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/geom/chapter.xml @@ -4,21 +4,16 @@ $FreeBSD$ --> - -<chapter id="geom"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="geom"> + <info><title>GEOM: Modular Disk Transformation Framework</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>GEOM: Modular Disk Transformation Framework</title> + - <sect1 id="geom-synopsis"> + <sect1 xml:id="geom-synopsis"> <title>Synopsis</title> <indexterm> @@ -30,8 +25,7 @@ </indexterm> <para>This chapter covers the use of disks under the GEOM - framework in &os;. This includes the major <acronym - role="Redundant Array of Inexpensive Disks">RAID</acronym> + framework in &os;. This includes the major <acronym role="Redundant Array of Inexpensive Disks">RAID</acronym> control utilities which use the framework for configuration. This chapter will not go into in depth discussion on how GEOM handles or controls I/O, the underlying subsystem, or code. @@ -70,45 +64,35 @@ <itemizedlist> <listitem> - <para>Understand how &os; treats <link - linkend="disks">disk devices</link>.</para> + <para>Understand how &os; treats <link linkend="disks">disk devices</link>.</para> </listitem> <listitem> - <para>Know how to configure and install a new <link - linkend="kernelconfig">&os; kernel</link>.</para> + <para>Know how to configure and install a new <link linkend="kernelconfig">&os; kernel</link>.</para> </listitem> </itemizedlist> </sect1> - <sect1 id="geom-intro"> + <sect1 xml:id="geom-intro"> <title>GEOM Introduction</title> <para>GEOM permits access and control to classes, such as Master Boot Records and <acronym>BSD</acronym> labels, through the use - of providers, or the special files in <filename - class="directory">/dev</filename>. By supporting various + of providers, or the special files in <filename>/dev</filename>. By supporting various software <acronym>RAID</acronym> configurations, GEOM transparently provides access to the operating system and operating system utilities.</para> </sect1> - <sect1 id="geom-striping"> - <sect1info> + <sect1 xml:id="geom-striping"> + <info><title>RAID0 - Striping</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> </authorgroup> - </sect1info> + </info> - <title>RAID0 - Striping</title> + <indexterm> <primary>GEOM</primary> @@ -158,8 +142,7 @@ <step> <para>Ensure that a suitable mount point exists. If this volume will become a root partition, then temporarily use - another mount point such as <filename - class="directory">/mnt</filename>:</para> + another mount point such as <filename>/mnt</filename>:</para> <screen>&prompt.root; <userinput>mkdir /mnt</userinput></screen> </step> @@ -188,11 +171,11 @@ Done.</screen> <step> <para>This process should create two other devices in - <filename class="directory">/dev/stripe</filename> in - addition to <devicename>st0</devicename>. Those include - <devicename>st0a</devicename> and - <devicename>st0c</devicename>. At this point, a file system - may be created on <devicename>st0a</devicename> using + <filename>/dev/stripe</filename> in + addition to <filename>st0</filename>. Those include + <filename>st0a</filename> and + <filename>st0c</filename>. At this point, a file system + may be created on <filename>st0a</filename> using <command>newfs</command>:</para> <screen>&prompt.root; <userinput>newfs -U /dev/stripe/st0a</userinput></screen> @@ -210,8 +193,7 @@ Done.</screen> <para>To mount this striped file system automatically during the boot process, place the volume information in <filename>/etc/fstab</filename>. In this example, a - permanent mount point, named <filename - class="directory">stripe</filename>, is created:</para> + permanent mount point, named <filename>stripe</filename>, is created:</para> <screen>&prompt.root; <userinput>mkdir /stripe</userinput> &prompt.root; <userinput>echo "/dev/stripe/st0a /stripe ufs rw 2 2" \</userinput> @@ -224,7 +206,7 @@ Done.</screen> <screen>&prompt.root; <userinput>echo 'geom_stripe_load="YES"' >> /boot/loader.conf</userinput></screen> </sect1> - <sect1 id="geom-mirror"> + <sect1 xml:id="geom-mirror"> <title>RAID1 - Mirroring</title> <indexterm> @@ -276,7 +258,7 @@ Done.</screen> on detecting and disabling soft updates journaling.</para> </warning> - <sect2 id="geom-mirror-metadata"> + <sect2 xml:id="geom-mirror-metadata"> <title>Metadata Issues</title> <para>Many disk systems store metadata at the end of each disk. @@ -287,14 +269,14 @@ Done.</screen> <para>GPT metadata can be erased with &man.gpart.8;. This example erases both primary and backup GPT partition tables - from disk <devicename>ada8</devicename>:</para> + from disk <filename>ada8</filename>:</para> <screen>&prompt.root; <userinput>gpart destroy -F ada8</userinput></screen> <para>&man.gmirror.8; can remove a disk from an active mirror and erase the metadata in one step. Here, the example disk - <devicename>ada8</devicename> is removed from the active - mirror <devicename>gm4</devicename>:</para> + <filename>ada8</filename> is removed from the active + mirror <filename>gm4</filename>:</para> <screen>&prompt.root; <userinput>gmirror remove gm4 ada8</userinput></screen> @@ -312,13 +294,13 @@ Done.</screen> the disk and does not conflict with &man.gmirror.8;.</para> </sect2> - <sect2 id="geom-mirror-two-new-disks"> + <sect2 xml:id="geom-mirror-two-new-disks"> <title>Creating a Mirror with Two New Disks</title> <para>In this example, &os; has already been installed on a - single disk, <devicename>ada0</devicename>. Two new disks, - <devicename>ada1</devicename> and - <devicename>ada2</devicename>, have been connected to the + single disk, <filename>ada0</filename>. Two new disks, + <filename>ada1</filename> and + <filename>ada2</filename>, have been connected to the system. A new mirror will be created on these two disks and used to replace the old single disk.</para> @@ -333,7 +315,7 @@ Done.</screen> <screen>&prompt.root; <userinput>gmirror label -v gm0 /dev/ada1 /dev/ada2</userinput></screen> - <para><devicename>gm0</devicename> is a user-chosen device name + <para><filename>gm0</filename> is a user-chosen device name assigned to the new mirror. After the mirror has been started, this device name will appear in <filename>/dev/mirror/</filename>.</para> @@ -349,12 +331,12 @@ Done.</screen> <para>Partitions on the mirror do not have to be the same size as those on the existing disk, but they must be large enough to hold all the data already present on - <devicename>ada0</devicename>.</para> + <filename>ada0</filename>.</para> <screen>&prompt.root; <userinput>gpart create -s MBR mirror/gm0</userinput> &prompt.root; <userinput>gpart add -t freebsd -a 4k mirror/gm0</userinput> &prompt.root; <userinput>gpart show mirror/gm0</userinput> -=> 63 156301423 mirror/gm0 MBR (74G) +=> 63 156301423 mirror/gm0 MBR (74G) 63 63 - free - (31k) 126 156301299 1 freebsd (74G) 156301425 61 - free - (30k)</screen> @@ -366,7 +348,7 @@ Done.</screen> &prompt.root; <userinput>gpart add -t freebsd-ufs -a 4k -s 1g mirror/gm0s1</userinput> &prompt.root; <userinput>gpart add -t freebsd-ufs -a 4k mirror/gm0s1</userinput> &prompt.root; <userinput>gpart show mirror/gm0s1</userinput> -=> 0 156301299 mirror/gm0s1 BSD (74G) +=> 0 156301299 mirror/gm0s1 BSD (74G) 0 2 - free - (1.0k) 2 4194304 1 freebsd-ufs (2.0G) 4194306 8388608 2 freebsd-swap (4.0G) @@ -391,7 +373,7 @@ Done.</screen> &prompt.root; <userinput>newfs -U /dev/mirror/gm0s1f</userinput></screen> <para>Filesystems from the original - <devicename>ada0</devicename> disk can now be copied onto the + <filename>ada0</filename> disk can now be copied onto the mirror with &man.dump.8; and &man.restore.8;.</para> <screen>&prompt.root; <userinput>mount /dev/mirror/gm0s1a /mnt</userinput> @@ -425,28 +407,27 @@ Done.</screen> are identical, it does not matter which is selected to boot.</para> - <para>See the <link - linkend="gmirror-troubleshooting">Troubleshooting</link> + <para>See the <link linkend="gmirror-troubleshooting">Troubleshooting</link> section if there are problems booting. Powering down and - disconnecting the original <devicename>ada0</devicename> disk + disconnecting the original <filename>ada0</filename> disk will allow it to be kept as an offline backup.</para> <para>In use, the mirror will behave just like the original single drive.</para> </sect2> - <sect2 id="geom-mirror-existing-drive"> + <sect2 xml:id="geom-mirror-existing-drive"> <title>Creating a Mirror with an Existing Drive</title> <para>In this example, &os; has already been installed on a - single disk, <devicename>ada0</devicename>. A new disk, - <devicename>ada1</devicename>, has been connected to the + single disk, <filename>ada0</filename>. A new disk, + <filename>ada1</filename>, has been connected to the system. A one-disk mirror will be created on the new disk, the existing system copied onto it, and then the old disk will be inserted into the mirror. This slightly complex procedure is required because &man.gmirror.8; needs to put a 512-byte block of metadata at the end of each disk, and the existing - <devicename>ada0</devicename> has usually had all of its space + <filename>ada0</filename> has usually had all of its space already allocated.</para> <para>Load the &man.gmirror.8; kernel module:</para> @@ -467,10 +448,10 @@ Done.</screen> size. This drive does not store any data, but is used only to limit the size of the mirror. When &man.gmirror.8; creates the mirror, it will restrict the capacity to the size of - <devicename>gzero.nop</devicename>, even if the new drive - (<devicename>ada1</devicename>) has more space. Note that the + <filename>gzero.nop</filename>, even if the new drive + (<filename>ada1</filename>) has more space. Note that the <replaceable>1000204821504</replaceable> in the second line - should be equal to <devicename>ada0</devicename>'s media size + should be equal to <filename>ada0</filename>'s media size as shown by &man.diskinfo.8; above.</para> <screen>&prompt.root; <userinput>geom zero load</userinput> @@ -478,19 +459,19 @@ Done.</screen> &prompt.root; <userinput>gmirror label -v gm0 gzero.nop ada1</userinput> &prompt.root; <userinput>gmirror forget gm0</userinput></screen> - <para><devicename>gzero.nop</devicename> does not store any + <para><filename>gzero.nop</filename> does not store any data, so the mirror does not see it as connected. The mirror is told to <quote>forget</quote> unconnected components, - removing references to <devicename>gzero.nop</devicename>. + removing references to <filename>gzero.nop</filename>. The result is a mirror device containing only a single disk, - <devicename>ada1</devicename>.</para> + <filename>ada1</filename>.</para> - <para>After creating <devicename>gm0</devicename>, view the - partition table on <devicename>ada0</devicename>.</para> + <para>After creating <filename>gm0</filename>, view the + partition table on <filename>ada0</filename>.</para> <para>This output is from a 1 TB drive. If there is some unallocated space at the end of the drive, the contents may be - copied directly from <devicename>ada0</devicename> to the new + copied directly from <filename>ada0</filename> to the new mirror.</para> <para>However, if the output shows that all of the space on the @@ -499,12 +480,12 @@ Done.</screen> the end of the disk.</para> <screen>&prompt.root; <userinput>gpart show ada0</userinput> -=> 63 1953525105 ada0 MBR (931G) +=> 63 1953525105 ada0 MBR (931G) 63 1953525105 1 freebsd [active] (931G)</screen> <para>In this case, the partition table must be edited to reduce the capacity by one sector on - <devicename>mirror/gm0</devicename>. The procedure will + <filename>mirror/gm0</filename>. The procedure will be explained later.</para> <para>In either case, partition tables on the primary disk @@ -557,28 +538,28 @@ BSD 8 disk, these two files can be used without modification.</para> <para>Now restore the partition table into - <devicename>mirror/gm0</devicename>:</para> + <filename>mirror/gm0</filename>:</para> <screen>&prompt.root; <userinput>gpart restore mirror/gm0 < table.ada0</userinput> &prompt.root; <userinput>gpart restore mirror/gm0s1 < table.ada0s1</userinput></screen> <para>Check the partition table with <command>gpart show</command>. This example has - <devicename>gm0s1a</devicename> for <filename>/</filename>, - <devicename>gm0s1d</devicename> for <filename>/var</filename>, - <devicename>gm0s1e</devicename> for <filename>/usr</filename>, - <devicename>gm0s1f</devicename> for + <filename>gm0s1a</filename> for <filename>/</filename>, + <filename>gm0s1d</filename> for <filename>/var</filename>, + <filename>gm0s1e</filename> for <filename>/usr</filename>, + <filename>gm0s1f</filename> for <filename>/data1</filename>, and - <devicename>gm0s1g</devicename> for + <filename>gm0s1g</filename> for <filename>/data2</filename>.</para> <screen>&prompt.root; <userinput>gpart show mirror/gm0</userinput> -=> 63 1953525104 mirror/gm0 MBR (931G) +=> 63 1953525104 mirror/gm0 MBR (931G) 63 1953525042 1 freebsd [active] (931G) 1953525105 62 - free - (31k) &prompt.root; <userinput>gpart show mirror/gm0s1</userinput> -=> 0 1953525042 mirror/gm0s1 BSD (931G) +=> 0 1953525042 mirror/gm0s1 BSD (931G) 0 2097152 1 freebsd-ufs (1.0G) 2097152 16777216 2 freebsd-swap (8.0G) 18874368 41943040 4 freebsd-ufs (20G) @@ -592,7 +573,7 @@ BSD 8 <para>Create filesystems on these new partitions. The number of partitions will vary, matching the partitions on the - original disk, <devicename>ada0</devicename>.</para> + original disk, <filename>ada0</filename>.</para> <screen>&prompt.root; <userinput>newfs -U /dev/mirror/gm0s1a</userinput> &prompt.root; <userinput>newfs -U /dev/mirror/gm0s1d</userinput> @@ -614,8 +595,8 @@ BSD 8 <screen>&prompt.root; <userinput>cp /etc/fstab /etc/fstab.orig</userinput></screen> <para>Edit <filename>/etc/fstab</filename>, replacing - <devicename>/dev/ada0</devicename> with - <devicename>mirror/gm0</devicename>.</para> + <filename>/dev/ada0</filename> with + <filename>mirror/gm0</filename>.</para> <programlisting># Device Mountpoint FStype Options Dump Pass# /dev/mirror/gm0s1a / ufs rw 1 1 @@ -648,30 +629,30 @@ BSD 8 &prompt.root; <userinput>dump -C16 -b64 -0aL -f - /data2 | (cd /mnt/data2 && restore -rf -)</userinput></screen> <para>Restart the system, booting from - <devicename>ada1</devicename>. If everything is working, the - system will boot from <devicename>mirror/gm0</devicename>, + <filename>ada1</filename>. If everything is working, the + system will boot from <filename>mirror/gm0</filename>, which now contains the same data as - <devicename>ada0</devicename> had previously. See the + <filename>ada0</filename> had previously. See the <link linkend="gmirror-troubleshooting">Troubleshooting</link> section if there are problems booting.</para> <para>At this point, the mirror still consists of only the - single <devicename>ada1</devicename> disk.</para> + single <filename>ada1</filename> disk.</para> - <para>After booting from <devicename>mirror/gm0</devicename> + <para>After booting from <filename>mirror/gm0</filename> successfully, the final step is inserting - <devicename>ada0</devicename> into the mirror.</para> + <filename>ada0</filename> into the mirror.</para> <important> - <para>When <devicename>ada0</devicename> is inserted into the + <para>When <filename>ada0</filename> is inserted into the mirror, its former contents will be overwritten by data on the mirror. Make certain that - <devicename>mirror/gm0</devicename> has the same contents as - <devicename>ada0</devicename> before adding - <devicename>ada0</devicename> to the mirror. If there is + <filename>mirror/gm0</filename> has the same contents as + <filename>ada0</filename> before adding + <filename>ada0</filename> to the mirror. If there is something wrong with the contents copied by &man.dump.8; and &man.restore.8;, revert <filename>/etc/fstab</filename> to - mount the filesystems on <devicename>ada0</devicename>, + mount the filesystems on <filename>ada0</filename>, reboot, and try the whole procedure again.</para> </important> @@ -695,15 +676,15 @@ mirror/gm0 DEGRADED ada1 (ACTIVE) mirror/gm0 COMPLETE ada1 (ACTIVE) ada0 (ACTIVE)</screen> - <para><devicename>mirror/gm0</devicename> now consists of - the two disks <devicename>ada0</devicename> and - <devicename>ada1</devicename>, and the contents are + <para><filename>mirror/gm0</filename> now consists of + the two disks <filename>ada0</filename> and + <filename>ada1</filename>, and the contents are automatically synchronized with each other. In use, - <devicename>mirror/gm0</devicename> will behave just like the + <filename>mirror/gm0</filename> will behave just like the original single drive.</para> </sect2> - <sect2 id="gmirror-troubleshooting"> + <sect2 xml:id="gmirror-troubleshooting"> <title>Troubleshooting</title> <sect3> @@ -767,12 +748,12 @@ mountroot></screen> require more effort to fix. Enter <literal>ufs:/dev/ada0s1a</literal> at the boot loader prompt. Although the system should boot from - <devicename>ada0</devicename>, another prompt to select a + <filename>ada0</filename>, another prompt to select a shell appears because <filename>/etc/fstab</filename> is incorrect. Press the Enter key at the prompt. Undo the modifications so far by reverting <filename>/etc/fstab</filename>, mounting filesystems from - the original disk (<devicename>ada0</devicename>) instead + the original disk (<filename>ada0</filename>) instead of the mirror. Reboot the system and try the procedure again.</para> @@ -788,9 +769,9 @@ mountroot></screen> <para>The benefit of disk mirroring is that an individual disk can fail without causing the mirror to lose any data. In the - above example, if <devicename>ada0</devicename> fails, the + above example, if <filename>ada0</filename> fails, the mirror will continue to work, providing data from the - remaining working drive, <devicename>ada1</devicename>.</para> + remaining working drive, <filename>ada1</filename>.</para> <para>To replace the failed drive, shut down the system and physically replace the failed drive with a new drive of equal @@ -808,9 +789,8 @@ mountroot></screen> <screen>&prompt.root; <userinput>gmirror forget gm0</userinput></screen> - <para>Any old metadata should be <link - linkend="geom-mirror-metadata">cleared from the replacement - disk</link>. Then the disk, <devicename>ada4</devicename> + <para>Any old metadata should be <link linkend="geom-mirror-metadata">cleared from the replacement + disk</link>. Then the disk, <filename>ada4</filename> for this example, is inserted into the mirror:</para> <screen>&prompt.root; <userinput>gmirror insert gm0 /dev/ada4</userinput></screen> @@ -831,17 +811,13 @@ mountroot></screen> </sect2> </sect1> - <sect1 id="geom-graid"> - <sect1info> + <sect1 xml:id="geom-graid"> + <info><title>Software <acronym>RAID</acronym> Devices</title> <authorgroup> - <author> - <firstname>Warren</firstname> - <surname>Block</surname> - <contrib>Originally contributed by </contrib> - </author> + <author><personname><firstname>Warren</firstname><surname>Block</surname></personname><contrib>Originally contributed by </contrib></author> </authorgroup> - </sect1info> - <title>Software <acronym>RAID</acronym> Devices</title> + </info> + <indexterm> <primary>GEOM</primary> @@ -872,7 +848,7 @@ mountroot></screen> If needed, it can be loaded manually with <command>graid load</command>.</para> - <sect2 id="geom-graid-creating"> + <sect2 xml:id="geom-graid-creating"> <title>Creating an Array</title> <para>Software <acronym>RAID</acronym> devices often have a menu @@ -885,10 +861,10 @@ mountroot></screen> array. The motherboard used for this example has an Intel software <acronym>RAID</acronym> chipset, so the Intel metadata format is specified. The new array is given a label - of <devicename>gm0</devicename>, it is a mirror + of <filename>gm0</filename>, it is a mirror (<acronym>RAID1</acronym>), and uses drives - <devicename>ada0</devicename> and - <devicename>ada1</devicename>.</para> + <filename>ada0</filename> and + <filename>ada1</filename>.</para> <caution> <para>Some space on the drives will be overwritten when they @@ -917,21 +893,21 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) <para>The array device appears in <filename>/dev/raid/</filename>. The first array is called - <devicename>r0</devicename>. Additional arrays, if present, - will be <devicename>r1</devicename>, - <devicename>r2</devicename>, and so on.</para> + <filename>r0</filename>. Additional arrays, if present, + will be <filename>r1</filename>, + <filename>r2</filename>, and so on.</para> <para>The <acronym>BIOS</acronym> menu on some of these devices can create arrays with special characters in their names. To avoid problems with those special characters, arrays are given - simple numbered names like <devicename>r0</devicename>. To - show the actual labels, like <devicename>gm0</devicename> in + simple numbered names like <filename>r0</filename>. To + show the actual labels, like <filename>gm0</filename> in the example above, use &man.sysctl.8;:</para> <screen>&prompt.root; <userinput>sysctl kern.geom.raid.name_format=1</userinput></screen> </sect2> - <sect2 id="geom-graid-volumes"> + <sect2 xml:id="geom-graid-volumes"> <title>Multiple Volumes</title> <para>Some software <acronym>RAID</acronym> devices support @@ -948,16 +924,16 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) &prompt.root; <userinput>graid add -S 20G gm0 RAID0</userinput></screen> <para>Volumes appear as additional - <devicename>r<replaceable>X</replaceable></devicename> entries + <filename>rX</filename> entries in <filename>/dev/raid/</filename>. An array with two volumes - will show <devicename>r0</devicename> and - <devicename>r1</devicename>.</para> + will show <filename>r0</filename> and + <filename>r1</filename>.</para> <para>See &man.graid.8; for the number of volumes supported by different software <acronym>RAID</acronym> devices.</para> </sect2> - <sect2 id="geom-graid-converting"> + <sect2 xml:id="geom-graid-converting"> <title>Converting a Single Drive to a Mirror</title> <para>Under certain specific conditions, it is possible to @@ -1001,7 +977,7 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) degraded status until the copy is complete.</para> </sect2> - <sect2 id="geom-graid-inserting"> + <sect2 xml:id="geom-graid-inserting"> <title>Inserting New Drives into the Array</title> <para>Drives can be inserted into an array as replacements for @@ -1022,7 +998,7 @@ GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 state changed from NEW to REBUILD. GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-ada1 rebuild start at 0.</screen> </sect2> - <sect2 id="geom-graid-removing"> + <sect2 xml:id="geom-graid-removing"> <title>Removing Drives from the Array</title> <para>Individual drives can be permanently removed from a @@ -1034,7 +1010,7 @@ GEOM_RAID: Intel-a29ea104: Subdisk gm0:1-[unknown] state changed from ACTIVE to GEOM_RAID: Intel-a29ea104: Volume gm0 state changed from OPTIMAL to DEGRADED.</screen> </sect2> - <sect2 id="geom-graid-stopping"> + <sect2 xml:id="geom-graid-stopping"> <title>Stopping the Array</title> <para>An array can be stopped without removing metadata from the @@ -1044,7 +1020,7 @@ GEOM_RAID: Intel-a29ea104: Volume gm0 state changed from OPTIMAL to DEGRADED.</s <screen>&prompt.root; <userinput>graid stop raid/r0</userinput></screen> </sect2> - <sect2 id="geom-graid-status"> + <sect2 xml:id="geom-graid-status"> <title>Checking Array Status</title> <para>Array status can be checked at any time. After a drive @@ -1066,7 +1042,7 @@ raid/r0 DEGRADED ada0 (ACTIVE (ACTIVE)) Intel-e2d07d9a BROKEN ada6 (ACTIVE (ACTIVE))</screen> </sect2> - <sect2 id="geom-graid-deleting"> + <sect2 xml:id="geom-graid-deleting"> <title>Deleting Arrays</title> <para>Arrays are destroyed by deleting all of the volumes from @@ -1076,7 +1052,7 @@ Intel-e2d07d9a BROKEN ada6 (ACTIVE (ACTIVE))</screen> <screen>&prompt.root; <userinput>graid delete raid/r0</userinput></screen> </sect2> - <sect2 id="geom-graid-unexpected"> + <sect2 xml:id="geom-graid-unexpected"> <title>Deleting Unexpected Arrays</title> <para>Drives may unexpectedly contain &man.graid.8; metadata, @@ -1139,34 +1115,20 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) </sect2> </sect1> - <sect1 id="geom-raid3"> - <sect1info> + <sect1 xml:id="geom-raid3"> + <info><title><acronym>RAID</acronym>3 - Byte-level Striping with + Dedicated Parity</title> <authorgroup> - <author> - <firstname>Mark</firstname> - <surname>Gladman</surname> - <contrib>Written by </contrib> - </author> - <author> - <firstname>Daniel</firstname> - <surname>Gerzo</surname> - </author> + <author><personname><firstname>Mark</firstname><surname>Gladman</surname></personname><contrib>Written by </contrib></author> + <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname></author> </authorgroup> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Based on documentation by </contrib> - </author> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Based on documentation by </contrib></author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname></author> </authorgroup> - </sect1info> + </info> - <title><acronym>RAID</acronym>3 - Byte-level Striping with - Dedicated Parity</title> + <indexterm> <primary>GEOM</primary> @@ -1230,7 +1192,7 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) <para>Create or ensure that a suitable mount point exists:</para> - <screen>&prompt.root; <userinput>mkdir <replaceable>/multimedia/</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mkdir /multimedia/</userinput></screen> </step> <step> @@ -1240,11 +1202,11 @@ raid/r0 OPTIMAL ada0 (ACTIVE (ACTIVE)) will act as the dedicated parity disk. This example uses three unpartitioned <acronym>ATA</acronym> drives: - <devicename><replaceable>ada1</replaceable></devicename> + <filename>ada1</filename> and - <devicename><replaceable>ada2</replaceable></devicename> + <filename>ada2</filename> for data, and - <devicename><replaceable>ada3</replaceable></devicename> + <filename>ada3</filename> for parity.</para> <screen>&prompt.root; <userinput>graid3 label -v gr0 /dev/ada1 /dev/ada2 /dev/ada3</userinput> @@ -1256,7 +1218,7 @@ Done.</screen> <step> <para>Partition the newly created - <devicename>gr0</devicename> device and put a UFS file + <filename>gr0</filename> device and put a UFS file system on it:</para> <screen>&prompt.root; <userinput>gpart create -s GPT /dev/raid3/gr0</userinput> @@ -1300,7 +1262,7 @@ Done.</screen> </sect2> </sect1> - <sect1 id="geom-ggate"> + <sect1 xml:id="geom-ggate"> <title>GEOM Gate Network Devices</title> <para>GEOM supports the remote use of devices, such as disks, @@ -1317,7 +1279,7 @@ Done.</screen> <programlisting>192.168.1.0/24 RW /dev/da0s4d</programlisting> <para>This allows all hosts inside the specified private network - access to the file system on the <devicename>da0s4d</devicename> + access to the file system on the <filename>da0s4d</filename> partition.</para> <para>To export this device, ensure it is not currently mounted, @@ -1332,8 +1294,7 @@ Done.</screen> ggate0 &prompt.root; <userinput>mount /dev/ggate0 /mnt</userinput></screen> - <para>The device may now be accessed through the <filename - class="directory">/mnt</filename> mount point.</para> + <para>The device may now be accessed through the <filename>/mnt</filename> mount point.</para> <note> <para>However, this will fail if the device is currently mounted @@ -1345,7 +1306,7 @@ ggate0 &man.umount.8;, similar to any other disk device.</para> </sect1> - <sect1 id="geom-glabel"> + <sect1 xml:id="geom-glabel"> <title>Labeling Disk Devices</title> <indexterm> @@ -1360,9 +1321,9 @@ ggate0 devices raises some issues. For instance, what if a new disk device is added via <acronym>USB</acronym>? It is likely that a flash device may be handed the device name of - <devicename>da0</devicename> and the original - <devicename>da0</devicename> shifted to - <devicename>da1</devicename>. This will cause issues mounting + <filename>da0</filename> and the original + <filename>da0</filename> shifted to + <filename>da1</filename>. This will cause issues mounting file systems if they are listed in <filename>/etc/fstab</filename> which may also prevent the system from booting.</para> @@ -1401,19 +1362,16 @@ ggate0 <para>Permanent labels can be a generic or a file system label. Permanent file system labels can be created with &man.tunefs.8; or &man.newfs.8;. These types of labels are - created in a sub-directory of <filename - class="directory">/dev</filename>, and will be named + created in a sub-directory of <filename>/dev</filename>, and will be named according to the file system type. For example, <acronym>UFS</acronym>2 file system labels will be created in - <filename class="directory">/dev/ufs</filename>. Generic + <filename>/dev/ufs</filename>. Generic permanent labels can be created with <command>glabel label</command>. These are not file system specific and - will be created in <filename - class="directory">/dev/label</filename>.</para> + will be created in <filename>/dev/label</filename>.</para> <para>Temporary labels are destroyed at the next reboot. These - labels are created in <filename - class="directory">/dev/label</filename> and are suited to + labels are created in <filename>/dev/label</filename> and are suited to experimentation. A temporary label can be created using <command>glabel create</command>.</para> @@ -1424,15 +1382,14 @@ ggate0 <acronym>UFS</acronym>2 file system without destroying any data, issue the following command:</para> - <screen>&prompt.root; <userinput>tunefs -L <replaceable>home</replaceable> <replaceable>/dev/da3</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>tunefs -L home /dev/da3</userinput></screen> <warning> <para>If the file system is full, this may cause data corruption.</para> </warning> - <para>A label should now exist in <filename - class="directory">/dev/ufs</filename> which may be added + <para>A label should now exist in <filename>/dev/ufs</filename> which may be added to <filename>/etc/fstab</filename>:</para> <programlisting>/dev/ufs/home /home ufs rw 2 2</programlisting> @@ -1475,12 +1432,12 @@ ggate0 a different system. For this example, it is assumed that a single <acronym>ATA</acronym> disk is used, which is currently recognized by the system as - <devicename>ad0</devicename>. It is also assumed that the + <filename>ad0</filename>. It is also assumed that the standard &os; partition scheme is used, with - <filename class="directory">/</filename>, - <filename class="directory">/var</filename>, - <filename class="directory">/usr</filename> and - <filename class="directory">/tmp</filename>, as + <filename>/</filename>, + <filename>/var</filename>, + <filename>/usr</filename> and + <filename>/tmp</filename>, as well as a swap partition.</para> <para>Reboot the system, and at the &man.loader.8; prompt, @@ -1528,7 +1485,7 @@ devfs on /dev (devfs, local) supports a new label type for <acronym>UFS</acronym> file systems, based on the unique file system id, <literal>ufsid</literal>. These labels may be found in - <filename class="directory">/dev/ufsid</filename> and are + <filename>/dev/ufsid</filename> and are created automatically during system startup. It is possible to use <literal>ufsid</literal> labels to mount partitions using <filename>/etc/fstab</filename>. Use <command>glabel @@ -1540,10 +1497,10 @@ devfs on /dev (devfs, local) ufsid/486b6fc38d330916 N/A ad4s1d ufsid/486b6fc16926168e N/A ad4s1f</screen> - <para>In the above example, <devicename>ad4s1d</devicename> - represents <filename class="directory">/var</filename>, - while <devicename>ad4s1f</devicename> represents - <filename class="directory">/usr</filename>. + <para>In the above example, <filename>ad4s1d</filename> + represents <filename>/var</filename>, + while <filename>ad4s1f</filename> represents + <filename>/usr</filename>. Using the <literal>ufsid</literal> values shown, these partitions may now be mounted with the following entries in <filename>/etc/fstab</filename>:</para> @@ -1558,7 +1515,7 @@ ufsid/486b6fc16926168e N/A ad4s1f</screen> </sect2> </sect1> - <sect1 id="geom-gjournal"> + <sect1 xml:id="geom-gjournal"> <title>UFS Journaling Through GEOM</title> <indexterm> @@ -1612,15 +1569,15 @@ ufsid/486b6fc16926168e N/A ad4s1f</screen> <para>Creating a journal on a free file system may now be done using the following steps. In this example, - <devicename>da4</devicename> is a new <acronym>SCSI</acronym> + <filename>da4</filename> is a new <acronym>SCSI</acronym> disk:</para> <screen>&prompt.root; <userinput>gjournal load</userinput> &prompt.root; <userinput>gjournal label /dev/da4</userinput></screen> <para>At this point, there should be a - <devicename>/dev/da4</devicename> device node and a - <devicename>/dev/da4.journal</devicename> device node. + <filename>/dev/da4</filename> device node and a + <filename>/dev/da4.journal</filename> device node. A file system may now be created on this device:</para> <screen>&prompt.root; <userinput>newfs -O 2 -J /dev/da4.journal</userinput></screen> @@ -1631,16 +1588,16 @@ ufsid/486b6fc16926168e N/A ad4s1f</screen> <para><command>mount</command> the device at the desired point with:</para> - <screen>&prompt.root; <userinput>mount /dev/da4.journal <replaceable>/mnt</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mount /dev/da4.journal /mnt</userinput></screen> <note> <para>In the case of several slices, a journal will be created for each individual slice. For instance, if - <devicename>ad4s1</devicename> and - <devicename>ad4s2</devicename> are both slices, then + <filename>ad4s1</filename> and + <filename>ad4s2</filename> are both slices, then <command>gjournal</command> will create - <devicename>ad4s1.journal</devicename> and - <devicename>ad4s2.journal</devicename>.</para> + <filename>ad4s1.journal</filename> and + <filename>ad4s2.journal</filename>.</para> </note> <para>For better performance, the journal may be kept on another @@ -1655,9 +1612,8 @@ ufsid/486b6fc16926168e N/A ad4s1f</screen> <command>tunefs</command>.</para> <para>It is also possible to journal the boot disk of a &os; - system. Refer to the article <ulink - url="&url.articles.gjournal-desktop;">Implementing UFS - Journaling on a Desktop PC</ulink> for detailed + system. Refer to the article <link xlink:href="&url.articles.gjournal-desktop;">Implementing UFS + Journaling on a Desktop PC</link> for detailed instructions.</para> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.xml b/en_US.ISO8859-1/books/handbook/install/chapter.xml index 179ae911c4..e61a51e95b 100644 --- a/en_US.ISO8859-1/books/handbook/install/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/install/chapter.xml @@ -4,32 +4,23 @@ $FreeBSD$ --> - -<chapter id="install"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="install"> + <info><title>Installing &os; 8.<replaceable>X</replaceable></title> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Restructured, reorganized, and parts - rewritten by </contrib> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured, reorganized, and parts + rewritten by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Randy</firstname> - <surname>Pratt</surname> - <contrib>The sysinstall walkthrough, screenshots, and general - copy by </contrib> - </author> + <author><personname><firstname>Randy</firstname><surname>Pratt</surname></personname><contrib>The sysinstall walkthrough, screenshots, and general + copy by </contrib></author> </authorgroup> - <!-- January 2000 --> - </chapterinfo> + + </info> - <title>Installing &os; 8.<replaceable>X</replaceable></title> + - <sect1 id="install-synopsis"> + <sect1 xml:id="install-synopsis"> <title>Synopsis</title> <indexterm><primary>installation</primary></indexterm> @@ -86,10 +77,10 @@ </sect1> - <sect1 id="install-hardware"> + <sect1 xml:id="install-hardware"> <title>Hardware Requirements</title> - <sect2 id="install-hardware-minimal"> + <sect2 xml:id="install-hardware-minimal"> <title>Minimal Configuration</title> <para>The minimal configuration to install &os; varies with the @@ -144,8 +135,7 @@ <title>&os;/&arch.sparc64;</title> <para>To install &os;/&arch.sparc64;, use a supported - platform (see <xref - linkend="install-hardware-supported"/>).</para> + platform (see <xref linkend="install-hardware-supported"/>).</para> <para>A dedicated disk is needed for &os;/&arch.sparc64; as it is not possible to share a disk with another operating @@ -153,7 +143,7 @@ </sect3> </sect2> - <sect2 id="install-hardware-supported"> + <sect2 xml:id="install-hardware-supported"> <title>Supported Hardware</title> <para>A list of supported hardware is provided with each &os; @@ -164,16 +154,15 @@ It lists, for a given architecture, which hardware devices are known to be supported by each release of &os;. Copies of the supported hardware list for various releases and architectures - can also be found on the <ulink - url="http://www.FreeBSD.org/releases/index.html">Release - Information</ulink> page of the &os; website.</para> + can also be found on the <link xlink:href="http://www.FreeBSD.org/releases/index.html">Release + Information</link> page of the &os; website.</para> </sect2> </sect1> - <sect1 id="install-pre"> + <sect1 xml:id="install-pre"> <title>Pre-installation Tasks</title> - <sect2 id="install-inventory"> + <sect2 xml:id="install-inventory"> <title>Inventory the Computer</title> <para>Before installing &os; it is recommended to inventory the @@ -262,7 +251,7 @@ <entry>0x1f0</entry> - <entry></entry> + <entry/> </row> <row> @@ -309,7 +298,7 @@ undone.</para> </sect2> - <sect2 id="install-where"> + <sect2 xml:id="install-where"> <title>Decide Where to Install &os;</title> <para>If &os; is to be installed on the entire hard disk, @@ -320,7 +309,7 @@ systems, a rough understanding of how data is laid out on the disk is useful.</para> - <sect3 id="install-where-i386"> + <sect3 xml:id="install-where-i386"> <title>Disk Layouts for &os;/&arch.i386;</title> <para>A PC disk can be divided into discrete chunks known as @@ -347,7 +336,7 @@ partitions in a particular way. For example, &windows;, assigns each primary and logical partition a <firstterm>drive letter</firstterm>, starting with - <devicename>C:</devicename>.</para> + <filename>C:</filename>.</para> <para>&os; must be installed into a primary partition. If there are multiple disks, a &os; @@ -382,7 +371,7 @@ &os;. <application>GParted</application> is known to work on <acronym>NTFS</acronym> and is available on a number of Live CD Linux distributions, such as - <ulink url="http://www.sysresccd.org/">SystemRescueCD</ulink>.</para> + <link xlink:href="http://www.sysresccd.org/">SystemRescueCD</link>.</para> <warning> <para>Incorrect use of a shrinking tool can delete the data @@ -398,16 +387,16 @@ that already has a version of &windows; installed, where the disk has been split into two drive letters, - <devicename>C:</devicename> and - <devicename>D:</devicename>, each of which is 2 GB in size. - There is 1 GB of data on <devicename>C:</devicename>, + <filename>C:</filename> and + <filename>D:</filename>, each of which is 2 GB in size. + There is 1 GB of data on <filename>C:</filename>, and 0.5 GB of data on - <devicename>D:</devicename>.</para> + <filename>D:</filename>.</para> <para>This disk has two partitions, one per drive letter. Copy all existing data from - <devicename>D:</devicename> to <devicename>C:</devicename>, which + <filename>D:</filename> to <filename>C:</filename>, which will free up the second partition, ready for &os;.</para> </example> @@ -418,7 +407,7 @@ that already has a version of &windows; installed. When &windows; was installed, it created one large partition, a - <devicename>C:</devicename> drive that is 4 GB in size. + <filename>C:</filename> drive that is 4 GB in size. Currently, 1.5 GB of space is used, and &os; should have 2 GB of space.</para> @@ -525,7 +514,7 @@ of &os; is as stable as possible, bugs do occasionally creep into the process. On rare occasions those bugs affect the installation process. As these problems are discovered and fixed, they - are noted in the <ulink url="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">&os; Errata</ulink>, + are noted in the <link xlink:href="http://www.FreeBSD.org/releases/&rel.current;R/errata.html">&os; Errata</link>, which is found on the &os; website. Check the errata before installing to make sure that there are no late-breaking problems to be aware of.</para> @@ -533,11 +522,9 @@ <para>Information about all releases, including the errata for each release, can be found on the - <ulink - url="&url.base;/releases/index.html">release - information</ulink> section of the - <ulink - url="&url.base;/index.html">&os; website</ulink>.</para> + <link xlink:href="&url.base;/releases/index.html">release + information</link> section of the + <link xlink:href="&url.base;/index.html">&os; website</link>.</para> </sect2> <sect2> @@ -594,7 +581,7 @@ <xref linkend="install-boot-media"/>.</para> </sect2> - <sect2 id="install-boot-media"> + <sect2 xml:id="install-boot-media"> <title>Prepare the Boot Media</title> <para>The &os; installation process is started by booting the @@ -624,16 +611,15 @@ <para>Memory stick images for &os; 8.<replaceable>X</replaceable> can be downloaded from - the <filename class="directory">ISO-IMAGES/</filename> + the <filename>ISO-IMAGES/</filename> directory at - <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/<replaceable>arch</replaceable>/ISO-IMAGES/<replaceable>version</replaceable>/&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</literal>. + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/arch/ISO-IMAGES/version/&os;-version-RELEASE-arch-memstick.img</literal>. Replace <replaceable>arch</replaceable> and <replaceable>version</replaceable> with the architecture and the version number to install. For example, the memory stick images for &os;/&arch.i386; &rel2.current;-RELEASE are - available from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img"></ulink>.</para> + available from <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img">ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/&arch.i386;/ISO-IMAGES/&rel2.current;/&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img</uri>.</para> <tip> <para>A different directory path is used for @@ -644,8 +630,7 @@ </tip> <para>The memory stick image has a <filename>.img</filename> - extension. The <filename - class="directory">ISO-IMAGES/</filename> directory + extension. The <filename>ISO-IMAGES/</filename> directory contains a number of different images and the one to use depends on the version of &os; and the type of media supported by the hardware being installed @@ -666,7 +651,7 @@ <warning> <para>The example below - lists <filename class="devicefile">/dev/da0</filename> as the + lists <filename>/dev/da0</filename> as the target device where the image will be written. Be very careful that you have the correct device as the output target, or you may destroy your existing data.</para> @@ -683,7 +668,7 @@ &man.dd.1; must be used to write the image directly to the disk:</para> - <screen>&prompt.root; <userinput>dd if=&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img of=/dev/<replaceable>da0</replaceable> bs=64k</userinput></screen> + <screen>&prompt.root; <userinput>dd if=&os;-&rel2.current;-RELEASE-&arch.i386;-memstick.img of=/dev/da0 bs=64k</userinput></screen> <para>If an <computeroutput>Operation not permitted</computeroutput> @@ -710,7 +695,7 @@ <para><application>Image Writer for Windows</application> is a free application that can correctly write an image file to a memory stick. Download it from - <ulink url="https://launchpad.net/win32-image-writer/"></ulink> + <uri xlink:href="https://launchpad.net/win32-image-writer/">https://launchpad.net/win32-image-writer/</uri> and extract it into a folder.</para> </step> @@ -742,13 +727,12 @@ <para>The &os;/&arch.pc98; boot disks can be downloaded from the floppies directory, - <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/<replaceable>version</replaceable>-RELEASE/floppies/</literal>. + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/version-RELEASE/floppies/</literal>. Replace <replaceable>version</replaceable> with the version number to install.</para> <para>The floppy images have a <filename>.flp</filename> - extension. <filename - class="directory">floppies/</filename> contains a number + extension. <filename>floppies/</filename> contains a number of different images. Download <filename>boot.flp</filename> as well as the number of files associated with the type of installation, such as @@ -804,8 +788,8 @@ <command>rawrite</command> for creating the floppies on a computer running &windows;. This tool can be downloaded from - <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/<replaceable> - version</replaceable>-RELEASE/tools/</literal> + <literal>ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/pc98/ + version-RELEASE/tools/</literal> on the &os; FTP site. Download this tool, insert a floppy, then specify the filename to write to the floppy drive:</para> @@ -838,7 +822,7 @@ </sect2> </sect1> - <sect1 id="install-start"> + <sect1 xml:id="install-start"> <title>Starting the Installation</title> <important> @@ -862,10 +846,10 @@ We can take no responsibility for lost disk contents!</literallayout> done.</para> </important> - <sect2 id="install-starting"> + <sect2 xml:id="install-starting"> <title>Booting</title> - <sect3 id="install-starting-i386"> + <sect3 xml:id="install-starting-i386"> <title>Booting for the &i386;</title> <procedure> @@ -913,8 +897,7 @@ We can take no responsibility for lost disk contents!</literallayout> <note> <para>For &os;/&arch.pc98;, installation boot floppies are - available and can be prepared as described in <xref - linkend="install-boot-media"/>. The first floppy + available and can be prepared as described in <xref linkend="install-boot-media"/>. The first floppy disc will contain <filename>boot.flp</filename>. Put this floppy in the floppy drive to boot into the installer.</para> @@ -1001,7 +984,7 @@ Insert disk labelled "Kernel floppy 1" and press any key...</screen> boot process will then display the &os; boot loader menu:</para> - <figure id="boot-loader-menu"> + <figure xml:id="boot-loader-menu"> <title>&os; Boot Loader Menu</title> <mediaobject> @@ -1041,8 +1024,8 @@ Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> &man.tip.1; or &man.cu.1; to get to the PROM prompt. It looks like this:</para> - <screen><prompt>ok </prompt><co id="prompt-single"/> -<prompt>ok {0} </prompt><co id="prompt-smp"/></screen> + <screen><prompt>ok </prompt><co xml:id="prompt-single"/> +<prompt>ok {0} </prompt><co xml:id="prompt-smp"/></screen> <calloutlist> <callout arearefs="prompt-single"> @@ -1064,7 +1047,7 @@ Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> </sect2> - <sect2 id="view-probe"> + <sect2 xml:id="view-probe"> <title>Reviewing the Device Probe Results</title> <para>The last few hundred lines that have been displayed on screen are @@ -1084,7 +1067,7 @@ Ethernet address 0:3:ba:b:92:d4, Host ID: 830b92d4.</screen> it will differ depending on the devices in the computer.</para> - <figure id="install-dev-probe"> + <figure xml:id="install-dev-probe"> <title>Typical Device Probe Results</title> <screen>avail memory = 253050880 (247120K bytes) @@ -1162,7 +1145,7 @@ Mounting root from ufs:/dev/md0c arrow key to choose a country, region, or group. Then press <keycap>Enter</keycap> to set the country.</para> - <figure id="config-country"> + <figure xml:id="config-country"> <title>Selecting Country Menu</title> <mediaobject> @@ -1179,7 +1162,7 @@ Mounting root from ufs:/dev/md0c displayed. Use the arrow keys to choose the correct keyboard map and press <keycap>Enter</keycap>.</para> - <figure id="config-keymap"> + <figure xml:id="config-keymap"> <title>Selecting Keyboard Menu</title> <mediaobject> @@ -1194,7 +1177,7 @@ Mounting root from ufs:/dev/md0c </sect2> </sect1> - <sect1 id="using-sysinstall"> + <sect1 xml:id="using-sysinstall"> <title>Introducing &man.sysinstall.8;</title> <para>The &os; 8.<replaceable>X</replaceable> installer, @@ -1209,14 +1192,13 @@ Mounting root from ufs:/dev/md0c other keys. To view a detailed description of these keys and what they do, ensure that the <guimenuitem>Usage</guimenuitem> entry is highlighted and that the - <guibutton>[Select]</guibutton> button is selected, as shown in <xref - linkend="sysinstall-main3"/>, then press <keycap>Enter</keycap>.</para> + <guibutton>[Select]</guibutton> button is selected, as shown in <xref linkend="sysinstall-main3"/>, then press <keycap>Enter</keycap>.</para> <para>The instructions for using the menu system will be displayed. After reviewing them, press <keycap>Enter</keycap> to return to the Main Menu.</para> - <figure id="sysinstall-main3"> + <figure xml:id="sysinstall-main3"> <title>Selecting Usage from Sysinstall Main Menu</title> <mediaobject> @@ -1226,14 +1208,14 @@ Mounting root from ufs:/dev/md0c </mediaobject> </figure> - <sect2 id="select-doc"> + <sect2 xml:id="select-doc"> <title>Selecting the Documentation Menu</title> <para>From the Main Menu, select <guimenuitem>Doc</guimenuitem> with the arrow keys and press <keycap>Enter</keycap>.</para> - <figure id="main-doc"> + <figure xml:id="main-doc"> <title>Selecting Documentation Menu</title> <mediaobject> @@ -1245,7 +1227,7 @@ Mounting root from ufs:/dev/md0c <para>This will display the Documentation Menu.</para> - <figure id="docmenu1"> + <figure xml:id="docmenu1"> <title>Sysinstall Documentation Menu</title> <mediaobject> @@ -1266,7 +1248,7 @@ Mounting root from ufs:/dev/md0c arrow keys and press <keycap>Enter</keycap>.</para> </sect2> - <sect2 id="keymap"> + <sect2 xml:id="keymap"> <title>Selecting the Keymap Menu</title> <para>To change the keyboard mapping, use the arrow keys to select @@ -1274,7 +1256,7 @@ Mounting root from ufs:/dev/md0c <keycap>Enter</keycap>. This is only required when using a non-standard or non-US keyboard.</para> - <figure id="sysinstall-keymap"> + <figure xml:id="sysinstall-keymap"> <title>Sysinstall Main Menu</title> <mediaobject> @@ -1295,7 +1277,7 @@ Mounting root from ufs:/dev/md0c Selecting &gui.cancel; by pressing <keycap>Tab</keycap> will use the default keymap and return to the Main Install Menu.</para> - <figure id="sysinstall-keymap-menu"> + <figure xml:id="sysinstall-keymap-menu"> <title>Sysinstall Keymap Menu</title> <mediaobject> @@ -1307,13 +1289,13 @@ Mounting root from ufs:/dev/md0c </sect2> - <sect2 id="viewsetoptions"> + <sect2 xml:id="viewsetoptions"> <title>Installation Options Screen</title> <para>Select <guimenuitem>Options</guimenuitem> and press <keycap>Enter</keycap>.</para> - <figure id="sysinstall-options"> + <figure xml:id="sysinstall-options"> <title>Sysinstall Main Menu</title> <mediaobject> @@ -1323,7 +1305,7 @@ Mounting root from ufs:/dev/md0c </mediaobject> </figure> - <figure id="options"> + <figure xml:id="options"> <title>Sysinstall Options</title> <mediaobject> @@ -1349,7 +1331,7 @@ Mounting root from ufs:/dev/md0c menu.</para> </sect2> - <sect2 id="start-install"> + <sect2 xml:id="start-install"> <title>Begin a Standard Installation</title> <para>The <guimenuitem>Standard</guimenuitem> installation is the @@ -1357,7 +1339,7 @@ Mounting root from ufs:/dev/md0c keys to select <guimenuitem>Standard</guimenuitem> and then press <keycap>Enter</keycap> to start the installation.</para> - <figure id="sysinstall-standard"> + <figure xml:id="sysinstall-standard"> <title>Begin Standard Installation</title> <mediaobject> @@ -1369,7 +1351,7 @@ Mounting root from ufs:/dev/md0c </sect2> </sect1> - <sect1 id="install-steps"> + <sect1 xml:id="install-steps"> <title>Allocating Disk Space</title> <para>The first task is to allocate disk space for &os;, and label @@ -1377,7 +1359,7 @@ Mounting root from ufs:/dev/md0c it. In order to do this you need to know how &os; expects to find information on the disk.</para> - <sect2 id="install-drive-bios-numbering"> + <sect2 xml:id="install-drive-bios-numbering"> <title>BIOS Drive Numbering</title> <para>Before installing and configuring &os; it is important to @@ -1488,7 +1470,7 @@ Mounting root from ufs:/dev/md0c </sidebar> </sect2> - <sect2 id="main-fdisk"> + <sect2 xml:id="main-fdisk"> <title>Creating Slices Using FDisk</title> <para>After choosing to begin a standard installation in @@ -1512,9 +1494,9 @@ Mounting root from ufs:/dev/md0c carried out the device probes will be displayed. <xref linkend="sysinstall-fdisk-drive1"/> shows an example from a system with two IDE disks called - <devicename>ad0</devicename> and <devicename>ad2</devicename>.</para> + <filename>ad0</filename> and <filename>ad2</filename>.</para> - <figure id="sysinstall-fdisk-drive1"> + <figure xml:id="sysinstall-fdisk-drive1"> <title>Select Drive for FDisk</title> <mediaobject> @@ -1524,21 +1506,21 @@ Mounting root from ufs:/dev/md0c </mediaobject> </figure> - <para>Note that <devicename>ad1</devicename> is not + <para>Note that <filename>ad1</filename> is not listed here.</para> <para>Consider two IDE hard disks where one is the master on the first IDE controller and one is the master on the second IDE controller. If &os; numbered these as - <devicename>ad0</devicename> and - <devicename>ad1</devicename>, everything would work.</para> + <filename>ad0</filename> and + <filename>ad1</filename>, everything would work.</para> <para>But if a third disk is later added as the slave device on the - first IDE controller, it would now be <devicename>ad1</devicename>, - and the previous <devicename>ad1</devicename> would become - <devicename>ad2</devicename>. Because device names + first IDE controller, it would now be <filename>ad1</filename>, + and the previous <filename>ad1</filename> would become + <filename>ad2</filename>. Because device names are used to find filesystems, some filesystems may no longer appear correctly, requiring a change to the &os; @@ -1549,14 +1531,14 @@ Mounting root from ufs:/dev/md0c were found. With this scheme, the master disk on the second IDE controller will <emphasis>always</emphasis> be - <devicename>ad2</devicename>, even if there are no - <devicename>ad0</devicename> or <devicename>ad1</devicename> + <filename>ad2</filename>, even if there are no + <filename>ad0</filename> or <filename>ad1</filename> devices.</para> <para>This configuration is the default for the &os; kernel, which is why the display in this example shows - <devicename>ad0</devicename> and - <devicename>ad2</devicename>. The machine on which this screenshot + <filename>ad0</filename> and + <filename>ad2</filename>. The machine on which this screenshot was taken had IDE disks on both master channels of the IDE controllers and no disks on the slave channels.</para> @@ -1578,14 +1560,14 @@ Mounting root from ufs:/dev/md0c small unused slices which are artifacts of disk layout schemes on the PC. It also shows one large <acronym>FAT</acronym> slice, which - appears as <devicename>C:</devicename> in + appears as <filename>C:</filename> in &windows;, and an extended slice, which may contain other drive letters in &windows;.</para> <para>The third section shows the commands that are available in <application>FDisk</application>.</para> - <figure id="sysinstall-fdisk1"> + <figure xml:id="sysinstall-fdisk1"> <title>Typical Default <application>FDisk</application> Partitions</title> @@ -1630,7 +1612,7 @@ Mounting root from ufs:/dev/md0c press <keycap>C</keycap> to create a new slice. Again, you will be prompted for the size of slice you would like to create.</para> - <figure id="sysinstall-fdisk2"> + <figure xml:id="sysinstall-fdisk2"> <title>Fdisk Partition Using Entire Disk</title> <mediaobject> @@ -1646,7 +1628,7 @@ Mounting root from ufs:/dev/md0c written to disk.</para> </sect2> - <sect2 id="bootmgr"> + <sect2 xml:id="bootmgr"> <title>Install a Boot Manager</title> <para>The next menu provides the option to install a boot @@ -1677,7 +1659,7 @@ Mounting root from ufs:/dev/md0c <para>Make a selection and press <keycap>Enter</keycap>.</para> - <figure id="sysinstall-bootmgr"> + <figure xml:id="sysinstall-bootmgr"> <title>Sysinstall Boot Manager Menu</title> <mediaobject> @@ -1707,7 +1689,7 @@ Mounting root from ufs:/dev/md0c both drives.</para> </important> - <figure id="sysinstall-fdisk-drive2"> + <figure xml:id="sysinstall-fdisk-drive2"> <title>Exit Select Drive</title> <mediaobject> @@ -1727,7 +1709,7 @@ Mounting root from ufs:/dev/md0c to continue with the installation.</para> </sect2> - <sect2 id="bsdlabeleditor"> + <sect2 xml:id="bsdlabeleditor"> <title>Creating Partitions Using <application>Disklabel</application></title> @@ -1779,7 +1761,7 @@ Mounting root from ufs:/dev/md0c <row> <entry><literal>a</literal></entry> - <entry><filename class="directory">/</filename></entry> + <entry><filename>/</filename></entry> <entry>1 GB</entry> @@ -1820,12 +1802,11 @@ Mounting root from ufs:/dev/md0c <row> <entry><literal>e</literal></entry> - <entry><filename - class="directory">/var</filename></entry> + <entry><filename>/var</filename></entry> <entry>512 MB to 4096 MB</entry> - <entry><filename class="directory">/var</filename> + <entry><filename>/var</filename> contains files that are constantly varying, such as log files and other administrative files. Many @@ -1840,13 +1821,12 @@ Mounting root from ufs:/dev/md0c <row> <entry><literal>f</literal></entry> - <entry><filename - class="directory">/usr</filename></entry> + <entry><filename>/usr</filename></entry> <entry>Rest of disk (at least 8 GB)</entry> <entry>All other files will typically be stored in - <filename class="directory">/usr</filename> and its + <filename>/usr</filename> and its subdirectories.</entry> </row> </tbody> @@ -1912,15 +1892,14 @@ Mounting root from ufs:/dev/md0c partition, instead of the <literal>e</literal> partition. However, convention says that the <literal>a</literal> partition on a slice is reserved for the filesystem that will - be the root (<filename class="directory">/</filename>) + be the root (<filename>/</filename>) filesystem. Following this convention is not necessary, but &man.sysinstall.8; uses it, so following it makes the installation slightly cleaner. This filesystem can be mounted anywhere; this example mounts it as - <filename - class="directory">/disk<replaceable>n</replaceable></filename>, + <filename>/diskn</filename>, where <replaceable>n</replaceable> is a number that changes for each disk.</entry> @@ -1968,7 +1947,7 @@ Mounting root from ufs:/dev/md0c <para>The bottom third of the screen shows the keystrokes that are valid in <application>Disklabel</application>.</para> - <figure id="sysinstall-label"> + <figure xml:id="sysinstall-label"> <title>Sysinstall Disklabel Editor</title> <mediaobject> @@ -1988,16 +1967,14 @@ Mounting root from ufs:/dev/md0c <note> <para>The default partitioning assigns - <filename class="directory">/tmp</filename> its own + <filename>/tmp</filename> its own partition instead - of being part of the <filename - class="directory">/</filename> partition. This - helps avoid filling the <filename - class="directory">/</filename> partition with + of being part of the <filename>/</filename> partition. This + helps avoid filling the <filename>/</filename> partition with temporary files.</para> </note> - <figure id="sysinstall-label2"> + <figure xml:id="sysinstall-label2"> <title>Sysinstall Disklabel Editor with Auto Defaults</title> <mediaobject> @@ -2015,7 +1992,7 @@ Mounting root from ufs:/dev/md0c <para>To create the first partition, <literal>a</literal>, mounted as - <filename class="directory">/</filename>, make sure the + <filename>/</filename>, make sure the proper disk slice at the top of the screen is selected and press <keycap>C</keycap>. A dialog box @@ -2028,7 +2005,7 @@ Mounting root from ufs:/dev/md0c <literal>G</literal> for gigabytes, or <literal>C</literal> for cylinders.</para> - <figure id="sysinstall-label-add"> + <figure xml:id="sysinstall-label-add"> <title>Free Space for Root Partition</title> <mediaobject> @@ -2046,7 +2023,7 @@ Mounting root from ufs:/dev/md0c <xref linkend="sysinstall-label-add2"/>. Then press &gui.ok;.</para> - <figure id="sysinstall-label-add2"> + <figure xml:id="sysinstall-label-add2"> <title>Edit Root Partition Size</title> <mediaobject> @@ -2064,7 +2041,7 @@ Mounting root from ufs:/dev/md0c <guimenuitem>FS</guimenuitem> is selected and press <keycap>Enter</keycap>.</para> - <figure id="sysinstall-label-type"> + <figure xml:id="sysinstall-label-type"> <title>Choose the Root Partition Type</title> <mediaobject> @@ -2082,7 +2059,7 @@ Mounting root from ufs:/dev/md0c <userinput>/</userinput>, and then press <keycap>Enter</keycap>.</para> - <figure id="sysinstall-label-mount"> + <figure xml:id="sysinstall-label-mount"> <title>Choose the Root Mount Point</title> <mediaobject> @@ -2097,7 +2074,7 @@ Mounting root from ufs:/dev/md0c partitions. When creating the swap partition, it will not prompt for the filesystem mount point. When creating the final partition, - <filename class="directory">/usr</filename>, leave the + <filename>/usr</filename>, leave the suggested size as is to use the rest of the slice.</para> @@ -2107,7 +2084,7 @@ Mounting root from ufs:/dev/md0c chosen may be different. Press <keycap>Q</keycap> to finish.</para> - <figure id="sysinstall-label4"> + <figure xml:id="sysinstall-label4"> <title>Sysinstall Disklabel Editor</title> <mediaobject> @@ -2119,10 +2096,10 @@ Mounting root from ufs:/dev/md0c </sect2> </sect1> - <sect1 id="install-choosing"> + <sect1 xml:id="install-choosing"> <title>Choosing What to Install</title> - <sect2 id="distset"> + <sect2 xml:id="distset"> <title>Select the Distribution Set</title> <para>Deciding which distribution set to install will depend largely @@ -2143,8 +2120,7 @@ Mounting root from ufs:/dev/md0c selection of a default desktop must be done after the installation of &os;. More information regarding the installation and configuration of a - <application>&xorg;</application> can be found in <xref - linkend="x11"/>.</para> + <application>&xorg;</application> can be found in <xref linkend="x11"/>.</para> <para>If compiling a custom kernel is anticipated, select an option which includes the source code. For more information on why a @@ -2163,7 +2139,7 @@ Mounting root from ufs:/dev/md0c Do not fret over the perfect choice, as other distributions can be added after installation.</para> - <figure id="distribution-set1"> + <figure xml:id="distribution-set1"> <title>Choose Distributions</title> <mediaobject> @@ -2174,7 +2150,7 @@ Mounting root from ufs:/dev/md0c </figure> </sect2> - <sect2 id="portscol"> + <sect2 xml:id="portscol"> <title>Installing the Ports Collection</title> <para>After selecting the desired distribution, an opportunity to @@ -2217,7 +2193,7 @@ Mounting root from ufs:/dev/md0c skip this option. Press <keycap>Enter</keycap> to continue. The Choose Distributions menu will redisplay.</para> - <figure id="distribution-set2"> + <figure xml:id="distribution-set2"> <title>Confirm Distributions</title> <mediaobject> @@ -2235,7 +2211,7 @@ Mounting root from ufs:/dev/md0c </sect2> </sect1> - <sect1 id="install-media"> + <sect1 xml:id="install-media"> <title>Choosing the Installation Media</title> <para>If installing from a CD/DVD, use the arrow keys to highlight @@ -2250,7 +2226,7 @@ Mounting root from ufs:/dev/md0c installation media. Press <keycap>Enter</keycap> to return to the media selection menu.</para> - <figure id="choose-media"> + <figure xml:id="choose-media"> <title>Choose Installation Media</title> <mediaobject> @@ -2326,8 +2302,8 @@ Mounting root from ufs:/dev/md0c part of the username, after an <quote>@</quote> sign. The proxy server then <quote>fakes</quote> the real server. For example, to install from - <hostid role="fqdn">ftp.FreeBSD.org</hostid>, using the proxy - FTP server <hostid role="fqdn">foo.example.com</hostid>, + <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem>, using the proxy + FTP server <systemitem class="fqdomainname">foo.example.com</systemitem>, listening on port 1234, go to the options menu, set the FTP username to <literal>ftp@ftp.FreeBSD.org</literal> and the password to an email address. As the installation media, @@ -2335,17 +2311,17 @@ Mounting root from ufs:/dev/md0c the URL <literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para> - <para>Since <filename class="directory">/pub/FreeBSD</filename> + <para>Since <filename>/pub/FreeBSD</filename> from - <hostid role="fqdn">ftp.FreeBSD.org</hostid> is proxied under - <hostid role="fqdn">foo.example.com</hostid>, the proxy + <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> is proxied under + <systemitem class="fqdomainname">foo.example.com</systemitem>, the proxy will fetch the files - from <hostid role="fqdn">ftp.FreeBSD.org</hostid> as the + from <systemitem class="fqdomainname">ftp.FreeBSD.org</systemitem> as the installer requests them.</para> </note> </sect1> - <sect1 id="install-final-warning"> + <sect1 xml:id="install-final-warning"> <title>Committing to the Installation</title> <para>The installation can now proceed if desired. This is also @@ -2408,7 +2384,7 @@ installation menus to retry whichever operations have failed. Main Installation Menu to exit the installation.</para> </sect1> - <sect1 id="install-post"> + <sect1 xml:id="install-post"> <title>Post-installation</title> <para>Configuration of various options can be performed after a @@ -2420,7 +2396,7 @@ installation menus to retry whichever operations have failed. and then selecting the <guimenuitem>Configure</guimenuitem> menu.</para> - <sect2 id="inst-network-dev"> + <sect2 xml:id="inst-network-dev"> <title>Network Device Configuration</title> <para>If PPP was previously configured for an FTP install, this @@ -2442,7 +2418,7 @@ installation menus to retry whichever operations have failed. &gui.yes; and press <keycap>Enter</keycap>. Otherwise, select &gui.no; to continue.</para> - <figure id="ed-config1"> + <figure xml:id="ed-config1"> <title>Selecting an Ethernet Device</title> <mediaobject> @@ -2490,7 +2466,7 @@ installation menus to retry whichever operations have failed. configuration of the Ethernet device for a system that will act as the gateway for a Local Area Network.</para> - <figure id="ed-config2"> + <figure xml:id="ed-config2"> <title>Set Network Configuration for <replaceable>ed0</replaceable></title> <mediaobject> @@ -2509,7 +2485,7 @@ installation menus to retry whichever operations have failed. <listitem> <para>The fully-qualified hostname, such as - <hostid role="fqdn">k6-2.example.com</hostid> in + <systemitem class="fqdomainname">k6-2.example.com</systemitem> in this case.</para> </listitem> </varlistentry> @@ -2519,7 +2495,7 @@ installation menus to retry whichever operations have failed. <listitem> <para>The name of the domain that the machine is - in, such as <hostid role="domainname">example.com</hostid> + in, such as <systemitem class="fqdomainname">example.com</systemitem> for this case.</para> </listitem> </varlistentry> @@ -2546,7 +2522,7 @@ installation menus to retry whichever operations have failed. local DNS server on this private local area network so the IP address of the provider's DNS server - (<hostid role="ipaddr">208.163.10.2</hostid>) was used.</para> + (<systemitem class="ipaddress">208.163.10.2</systemitem>) was used.</para> </listitem> </varlistentry> @@ -2555,7 +2531,7 @@ installation menus to retry whichever operations have failed. <listitem> <para>The IP address to be used for this interface was - <hostid role="ipaddr">192.168.0.1</hostid></para> + <systemitem class="ipaddress">192.168.0.1</systemitem></para> </listitem> </varlistentry> @@ -2565,10 +2541,10 @@ installation menus to retry whichever operations have failed. <listitem> <para>The address block being used for this local area network is - <hostid role="ipaddr">192.168.0.0</hostid> - - <hostid role="ipaddr">192.168.0.255</hostid> + <systemitem class="ipaddress">192.168.0.0</systemitem> - + <systemitem class="ipaddress">192.168.0.255</systemitem> with a netmask of - <hostid role="netmask">255.255.255.0</hostid>.</para> + <systemitem class="netmask">255.255.255.0</systemitem>.</para> </listitem> </varlistentry> @@ -2600,7 +2576,7 @@ installation menus to retry whichever operations have failed. the machine still needs to be rebooted.</para> </sect2> - <sect2 id="gateway"> + <sect2 xml:id="gateway"> <title>Configure Gateway</title> <screen> User Confirmation Requested @@ -2616,7 +2592,7 @@ installation menus to retry whichever operations have failed. <keycap>Enter</keycap> to continue.</para> </sect2> - <sect2 id="inetd-services"> + <sect2 xml:id="inetd-services"> <title>Configure Internet Services</title> <screen> User Confirmation Requested @@ -2663,7 +2639,7 @@ use the current settings. by deleting the <literal>#</literal> at the beginning of the lines representing those services.</para> - <figure id="inetd-edit"> + <figure xml:id="inetd-edit"> <title>Editing <filename>inetd.conf</filename></title> <mediaobject> @@ -2679,7 +2655,7 @@ use the current settings. </sect2> - <sect2 id="ssh-login"> + <sect2 xml:id="ssh-login"> <title>Enabling SSH Login</title> <indexterm> @@ -2698,7 +2674,7 @@ use the current settings. <xref linkend="openssh"/>.</para> </sect2> - <sect2 id="ftpanon"> + <sect2 xml:id="ftpanon"> <title>Anonymous FTP</title> <indexterm> @@ -2711,7 +2687,7 @@ use the current settings. Yes [ No ]</screen> - <sect3 id="deny-anon"> + <sect3 xml:id="deny-anon"> <title>Deny Anonymous FTP</title> <para>Selecting the default &gui.no; and pressing @@ -2719,7 +2695,7 @@ use the current settings. with passwords to use FTP to access the machine.</para> </sect3> - <sect3 id="ftpallow"> + <sect3 xml:id="ftpallow"> <title>Allow Anonymous FTP</title> <para>Anyone can access the machine if @@ -2757,7 +2733,7 @@ use the current settings. <keycap>Enter</keycap> to continue. The following screen will display:</para> - <figure id="anon-ftp2"> + <figure xml:id="anon-ftp2"> <title>Default Anonymous FTP Configuration</title> <mediaobject> @@ -2818,13 +2794,11 @@ use the current settings. </varlistentry> </variablelist> - <para>The FTP root directory will be put in <filename - class="directory">/var</filename> + <para>The FTP root directory will be put in <filename>/var</filename> by default. If there is not enough room there for the - anticipated FTP needs, use <filename - class="directory">/usr</filename> instead + anticipated FTP needs, use <filename>/usr</filename> instead by setting the FTP root directory to - <filename class="directory">/usr/ftp</filename>.</para> + <filename>/usr/ftp</filename>.</para> <para>Once satisfied with the values, press <keycap>Enter</keycap> to continue.</para> @@ -2838,7 +2812,7 @@ use the current settings. <keycap>Enter</keycap> and the &man.cu.1; editor will automatically start.</para> - <figure id="anon-ftp4"> + <figure xml:id="anon-ftp4"> <title>Edit the FTP Welcome Message</title> <mediaobject> @@ -2860,7 +2834,7 @@ use the current settings. </sect3> </sect2> - <sect2 id="nfsconf"> + <sect2 xml:id="nfsconf"> <title>Configure the Network File System</title> <para>The Network File System (<acronym>NFS</acronym>) allows @@ -2869,7 +2843,7 @@ use the current settings. both. Refer to <xref linkend="network-nfs"/> for more information.</para> - <sect3 id="nsf-server-options"> + <sect3 xml:id="nsf-server-options"> <title>NFS Server</title> <screen> User Confirmation Requested @@ -2897,7 +2871,7 @@ Press [Enter] now to invoke an editor on /etc/exports start, allowing <filename>/etc/exports</filename> to be edited.</para> - <figure id="nfs-server-edit"> + <figure xml:id="nfs-server-edit"> <title>Editing <filename>exports</filename></title> <mediaobject> @@ -2917,7 +2891,7 @@ Press [Enter] now to invoke an editor on /etc/exports <keycap>Enter</keycap> to exit and continue.</para> </sect3> - <sect3 id="nfs-client-options"> + <sect3 xml:id="nfs-client-options"> <title><acronym>NFS</acronym> Client</title> <para>The <acronym>NFS</acronym> client allows the machine to @@ -2934,7 +2908,7 @@ Press [Enter] now to invoke an editor on /etc/exports </sect3> </sect2> - <sect2 id="console"> + <sect2 xml:id="console"> <title>System Console Settings</title> <para>There are several options available to customize the system @@ -2949,7 +2923,7 @@ Press [Enter] now to invoke an editor on /etc/exports &gui.yes; and press <keycap>Enter</keycap>.</para> - <figure id="saver-options"> + <figure xml:id="saver-options"> <title>System Console Configuration Options</title> <mediaobject> @@ -2963,7 +2937,7 @@ Press [Enter] now to invoke an editor on /etc/exports to select <guimenuitem>Saver</guimenuitem> and then press <keycap>Enter</keycap>.</para> - <figure id="saver-select"> + <figure xml:id="saver-select"> <title>Screen Saver Options</title> <mediaobject> @@ -2983,7 +2957,7 @@ Press [Enter] now to invoke an editor on /etc/exports using the arrow keys and press <keycap>Enter</keycap>. A pop-up menu will appear:</para> - <figure id="saver-timeout"> + <figure xml:id="saver-timeout"> <title>Screen Saver Timeout</title> <mediaobject> @@ -2997,7 +2971,7 @@ Press [Enter] now to invoke an editor on /etc/exports and press <keycap>Enter</keycap> to return to the System Console Configuration menu.</para> - <figure id="saver-exit"> + <figure xml:id="saver-exit"> <title>System Console Configuration Exit</title> <mediaobject> @@ -3012,7 +2986,7 @@ Press [Enter] now to invoke an editor on /etc/exports configuration.</para> </sect2> - <sect2 id="timezone"> + <sect2 xml:id="timezone"> <title>Setting the Time Zone</title> <para>Setting the time zone allows the system to @@ -3042,7 +3016,7 @@ Press [Enter] now to invoke an editor on /etc/exports or &gui.no; according to how the machine's clock is configured, then press <keycap>Enter</keycap>.</para> - <figure id="set-timezone-region"> + <figure xml:id="set-timezone-region"> <title>Select the Region</title> <mediaobject> @@ -3055,7 +3029,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>The appropriate region is selected using the arrow keys and then pressing <keycap>Enter</keycap>.</para> - <figure id="set-timezone-country"> + <figure xml:id="set-timezone-country"> <title>Select the Country</title> <mediaobject> @@ -3068,7 +3042,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>Select the appropriate country using the arrow keys and press <keycap>Enter</keycap>.</para> - <figure id="set-timezone-locality"> + <figure xml:id="set-timezone-locality"> <title>Select the Time Zone</title> <mediaobject> @@ -3092,7 +3066,7 @@ Press [Enter] now to invoke an editor on /etc/exports the post-installation configuration.</para> </sect2> - <sect2 id="mouse"> + <sect2 xml:id="mouse"> <title>Mouse Settings</title> <para>This option allows cut and paste in the @@ -3111,7 +3085,7 @@ Press [Enter] now to invoke an editor on /etc/exports &gui.no; for a USB mouse, then press <keycap>Enter</keycap>.</para> - <figure id="mouse-protocol"> + <figure xml:id="mouse-protocol"> <title>Select Mouse Protocol Type</title> <mediaobject> @@ -3124,7 +3098,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>Use the arrow keys to select <guimenuitem>Type</guimenuitem> and press <keycap>Enter</keycap>.</para> - <figure id="set-mouse-protocol"> + <figure xml:id="set-mouse-protocol"> <title>Set Mouse Protocol</title> <mediaobject> @@ -3140,7 +3114,7 @@ Press [Enter] now to invoke an editor on /etc/exports use the arrow keys to select another option. Ensure that &gui.ok; is highlighted and press <keycap>Enter</keycap> to exit this menu.</para> - <figure id="config-mouse-port"> + <figure xml:id="config-mouse-port"> <title>Configure Mouse Port</title> <mediaobject> @@ -3153,7 +3127,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>Use the arrow keys to select <guimenuitem>Port</guimenuitem> and press <keycap>Enter</keycap>.</para> - <figure id="set-mouse-port"> + <figure xml:id="set-mouse-port"> <title>Setting the Mouse Port</title> <mediaobject> @@ -3168,7 +3142,7 @@ Press [Enter] now to invoke an editor on /etc/exports port, use the arrow keys and then press <keycap>Enter</keycap>.</para> - <figure id="test-daemon"> + <figure xml:id="test-daemon"> <title>Enable the Mouse Daemon</title> <mediaobject> @@ -3184,7 +3158,7 @@ Press [Enter] now to invoke an editor on /etc/exports daemon.</para> - <figure id="test-mouse-daemon"> + <figure xml:id="test-mouse-daemon"> <title>Test the Mouse Daemon</title> <mediaobject> @@ -3206,7 +3180,7 @@ Press [Enter] now to invoke an editor on /etc/exports post-installation configuration.</para> </sect2> - <sect2 id="packages"> + <sect2 xml:id="packages"> <title>Install Packages</title> <para>Packages are pre-compiled binaries and are a convenient @@ -3229,7 +3203,7 @@ Press [Enter] now to invoke an editor on /etc/exports <keycap>Enter</keycap> to be presented with the Package Selection screens:</para> - <figure id="package-category"> + <figure xml:id="package-category"> <title>Select Package Category</title> <mediaobject> @@ -3251,7 +3225,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>A menu will display showing all the packages available for the selection made:</para> - <figure id="package-select"> + <figure xml:id="package-select"> <title>Select Packages</title> <mediaobject> @@ -3282,7 +3256,7 @@ Press [Enter] now to invoke an editor on /etc/exports press <keycap>Enter</keycap> to return to the Package Selection menu.</para> - <figure id="package-install"> + <figure xml:id="package-install"> <title>Install Packages</title> <mediaobject> @@ -3296,7 +3270,7 @@ Press [Enter] now to invoke an editor on /etc/exports and press <keycap>Enter</keycap> to see the installation confirmation message:</para> - <figure id="package-install-confirm"> + <figure xml:id="package-install-confirm"> <title>Confirm Package Installation</title> <mediaobject> @@ -3317,13 +3291,13 @@ Press [Enter] now to invoke an editor on /etc/exports configuration.</para> </sect2> - <sect2 id="addusers"> + <sect2 xml:id="addusers"> <title>Add Users/Groups</title> <para>Add at least one user during the installation so that the system can be used without logging in as - <username>root</username>. The root partition is generally small - and running applications as <username>root</username> can quickly + <systemitem class="username">root</systemitem>. The root partition is generally small + and running applications as <systemitem class="username">root</systemitem> can quickly fill it. A bigger danger is noted below:</para> <screen> User Confirmation Requested @@ -3337,7 +3311,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>Select &gui.yes; and press <keycap>Enter</keycap> to continue with adding a user.</para> - <figure id="add-user2"> + <figure xml:id="add-user2"> <title>Select User</title> <mediaobject> @@ -3350,7 +3324,7 @@ Press [Enter] now to invoke an editor on /etc/exports <para>Select <guimenuitem>User</guimenuitem> with the arrow keys and press <keycap>Enter</keycap>.</para> - <figure id="add-user3"> + <figure xml:id="add-user3"> <title>Add User Information</title> <mediaobject> @@ -3444,14 +3418,14 @@ Press [Enter] now to invoke an editor on /etc/exports is the C shell, <filename>/bin/tcsh</filename>.</para> - <para>The user was also added to the <groupname>wheel</groupname> group - to be able to become a superuser with <username>root</username> + <para>The user was also added to the <systemitem class="groupname">wheel</systemitem> group + to be able to become a superuser with <systemitem class="username">root</systemitem> privileges.</para> <para>Once satisfied, press &gui.ok; and the User and Group Management menu will redisplay:</para> - <figure id="add-user4"> + <figure xml:id="add-user4"> <title>Exit User and Group Management</title> <mediaobject> @@ -3471,8 +3445,8 @@ Press [Enter] now to invoke an editor on /etc/exports <keycap>Enter</keycap> to continue the installation.</para> </sect2> - <sect2 id="rootpass"> - <title>Set the <username>root</username> Password</title> + <sect2 xml:id="rootpass"> + <title>Set the <systemitem class="username">root</systemitem> Password</title> <screen> Message Now you must set the system manager's password. @@ -3482,7 +3456,7 @@ Press [Enter] now to invoke an editor on /etc/exports [ Press enter or space ]</screen> - <para>Press <keycap>Enter</keycap> to set the <username>root</username> + <para>Press <keycap>Enter</keycap> to set the <systemitem class="username">root</systemitem> password.</para> <para>The password will need to be typed in twice correctly. @@ -3497,7 +3471,7 @@ Retype new password :</screen> successfully entered.</para> </sect2> - <sect2 id="exit-inst"> + <sect2 xml:id="exit-inst"> <title>Exiting Install</title> <para>A message will ask if @@ -3513,7 +3487,7 @@ Retype new password :</screen> and press <keycap>Enter</keycap> to return to the Main Installation Menu.</para> - <figure id="final-main"> + <figure xml:id="final-main"> <title>Exit Install</title> <mediaobject> @@ -3552,17 +3526,13 @@ Retype new password :</screen> details.</para> </sect2> - <sect2 id="network-services"> - <sect2info> + <sect2 xml:id="network-services"> + <info><title>Configure Additional Network Services</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> - <title>Configure Additional Network Services</title> + </info> + <para>Configuring network services can be a daunting task for users that lack previous @@ -3585,7 +3555,7 @@ Retype new password :</screen> <para>Selecting the <guimenu>Networking</guimenu> option will display a menu similar to the one below:</para> - <figure id="network-configuration"> + <figure xml:id="network-configuration"> <title>Network Configuration Upper-level</title> <mediaobject> @@ -3617,9 +3587,9 @@ Retype new password :</screen> specifies the default <filename>log</filename>; however, when &man.syslogd.8; is used, all log activity will be sent to the system log daemon. - <filename class="directory">/host</filename> is used + <filename>/host</filename> is used to mount an exported file system from a remote - host, while <filename class="directory">/net</filename> + host, while <filename>/net</filename> is used to mount an exported filesystem from an <acronym>IP</acronym> address. The default options for <acronym>AMD</acronym> exports are defined in @@ -3650,7 +3620,7 @@ Retype new password :</screen> system's default Mail Transfer Agent (<acronym>MTA</acronym>). Selecting this option will bring up the following menu:</para> - <figure id="mta-selection"> + <figure xml:id="mta-selection"> <title>Select a Default MTA</title> <mediaobject> @@ -3701,7 +3671,7 @@ Retype new password :</screen> which deals with time synchronization. When selected, a menu like the one below shows up:</para> - <figure id="Ntpdate-config"> + <figure xml:id="Ntpdate-config"> <title>Ntpdate Configuration</title> <mediaobject> @@ -3719,7 +3689,7 @@ Retype new password :</screen> <para>The next option is the <acronym>PCNFSD</acronym> selection. This option will install the - <filename role="package">net/pcnfsd</filename> package from + <package>net/pcnfsd</package> package from the Ports Collection. This is a useful utility which provides <acronym>NFS</acronym> authentication services for systems which are unable to provide their own, such as Microsoft's @@ -3728,7 +3698,7 @@ Retype new password :</screen> <para>Now, scroll down a bit to see the other options:</para> - <figure id="Network-configuration-cont"> + <figure xml:id="Network-configuration-cont"> <title>Network Configuration Lower-level</title> <mediaobject> @@ -3806,10 +3776,10 @@ Retype new password :</screen> </sect2> - <sect2 id="freebsdboot"> + <sect2 xml:id="freebsdboot"> <title>&os; Bootup</title> - <sect3 id="freebsdboot-i386"> + <sect3 xml:id="freebsdboot-i386"> <title>&os;/&arch.i386; Bootup</title> <para>If everything went well, messages will scroll along @@ -3827,7 +3797,7 @@ Retype new password :</screen> <para>Login using the username and password which were set during installation. Avoid logging in as - <username>root</username> except when necessary.</para> + <systemitem class="username">root</systemitem> except when necessary.</para> <para>Typical boot messages (version information omitted):</para> @@ -3919,7 +3889,7 @@ Automatic boot in progress... /dev/ad0s1e: filesystem CLEAN; SKIPPING CHECKS /dev/ad0s1e: clean, 128193 free (17 frags, 16022 blocks, 0.0% fragmentation) Doing initial network setup: hostname. -ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 +ed0: flags=8843<UP,BROADCAST,RUNNING,SIMPLEX,MULTICAST> mtu 1500 inet 192.168.0.1 netmask 0xffffff00 broadcast 192.168.0.255 inet6 fe80::5054::5ff::fede:731b%ed0 prefixlen 64 tentative scopeid 0x1 ether 52:54:05:de:73:1b @@ -3970,16 +3940,16 @@ Password:</screen> </sect3> </sect2> - <sect2 id="shutdown"> + <sect2 xml:id="shutdown"> <title>&os; Shutdown</title> <para>It is important to properly shutdown the operating system. Do not just turn off the power. First, become the superuser using &man.su.1; and entering the - <username>root</username> password. This will work only if the user - is a member of <groupname>wheel</groupname>. - Otherwise, login as <username>root</username>. To shutdown + <systemitem class="username">root</systemitem> password. This will work only if the user + is a member of <systemitem class="groupname">wheel</systemitem>. + Otherwise, login as <systemitem class="username">root</systemitem>. To shutdown the system, type <command>shutdown -h now</command>.</para> @@ -4004,7 +3974,7 @@ Please press any key to reboot.</screen> </sect2> </sect1> - <sect1 id="install-trouble"> + <sect1 xml:id="install-trouble"> <title>Troubleshooting</title> <indexterm> @@ -4024,14 +3994,12 @@ Please press any key to reboot.</screen> there are a few things to try if it fails.</para> - <para>Check the <ulink - url="http://www.FreeBSD.org/releases/index.html">Hardware Notes - </ulink> document for the version of &os; to make sure the + <para>Check the <link xlink:href="http://www.FreeBSD.org/releases/index.html">Hardware Notes + </link> document for the version of &os; to make sure the hardware is supported.</para> <para>If the hardware is supported but still experiences - lock-ups or other problems, build a <link - linkend="kernelconfig">custom kernel</link> + lock-ups or other problems, build a <link linkend="kernelconfig">custom kernel</link> to add in support for devices which are not present in the <filename>GENERIC</filename> kernel. The default kernel assumes that most hardware devices are in their @@ -4091,7 +4059,7 @@ Please press any key to reboot.</screen> <programlisting>/dev/ad0sN /dos msdosfs rw 0 0</programlisting> - <note><para><filename class="directory">/dos</filename> must + <note><para><filename>/dos</filename> must already exist for this to work. For details about the format of <filename>/etc/fstab</filename>, see &man.fstab.5;.</para></note> @@ -4177,8 +4145,8 @@ Please press any key to reboot.</screen> bus, where &os; should be booted from the second disk. The BIOS sees these as disk 0 and disk 1, while &os; sees - them as <devicename>ad0</devicename> and - <devicename>ad2</devicename>.</para> + them as <filename>ad0</filename> and + <filename>ad2</filename>.</para> <para>If &os; is on BIOS disk 1, of type <literal>ad</literal> and the &os; disk number is 2, @@ -4278,9 +4246,7 @@ Please press any key to reboot.</screen> <answer> <para>If the default colors chosen by &man.sysinstall.8; - make text illegible while using <filename - role="package">x11/xterm</filename> or <filename - role="package">x11/rxvt</filename>, + make text illegible while using <package>x11/xterm</package> or <package>x11/rxvt</package>, add the following to <filename>~/.Xdefaults</filename> to get a darker background gray: <literal>XTerm*color7: @@ -4291,33 +4257,25 @@ Please press any key to reboot.</screen> </sect2> </sect1> - <sect1 id="install-advanced"> - <sect1info> + <sect1 xml:id="install-advanced"> + <info><title>Advanced Installation Guide</title> <authorgroup> - <author> - <firstname>Valentino</firstname> - <surname>Vaschetto</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Valentino</firstname><surname>Vaschetto</surname></personname><contrib>Contributed by </contrib></author> <!-- May 2001 --> </authorgroup> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Fonvieille</surname> - <contrib>Updated by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Fonvieille</surname></personname><contrib>Updated by </contrib></author> </authorgroup> - <!-- August 2010 --> - </sect1info> + + </info> - <title>Advanced Installation Guide</title> + <para>This section describes how to install &os; in exceptional cases.</para> - <sect2 id="headless-install"> + <sect2 xml:id="headless-install"> <title>Installing &os; on a System Without a Monitor or Keyboard</title> @@ -4333,10 +4291,8 @@ Please press any key to reboot.</screen> serial console, another machine which acts as the main display and keyboard. To do this, follow the steps to create - an installation USB stick, explained in <xref - linkend="install-boot-media"/>, or download the correct - installation ISO image as described in <xref - linkend="install-cdrom"/>.</para> + an installation USB stick, explained in <xref linkend="install-boot-media"/>, or download the correct + installation ISO image as described in <xref linkend="install-cdrom"/>.</para> <para>To modify the installation media to boot into a serial console, follow @@ -4357,7 +4313,7 @@ Please press any key to reboot.</screen> USB disk onto a &os; system using &man.mount.8;:</para> - <screen>&prompt.root; <userinput>mount /dev/<replaceable>da0a</replaceable> <replaceable>/mnt</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mount /dev/da0a /mnt</userinput></screen> <note> <para>Adapt the device node and the mount point to the @@ -4369,12 +4325,12 @@ Please press any key to reboot.</screen> Add this line to <filename>/boot/loader.conf</filename> on the USB stick:</para> - <screen>&prompt.root; <userinput>echo 'console="comconsole"' >> <replaceable>/mnt</replaceable>/boot/loader.conf</userinput></screen> + <screen>&prompt.root; <userinput>echo 'console="comconsole"' >> /mnt/boot/loader.conf</userinput></screen> <para>Now that the USB is stick configured correctly, unmount the disk using &man.umount.8;:</para> - <screen>&prompt.root; <userinput>umount <replaceable>/mnt</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>umount /mnt</userinput></screen> <para>Now, unplug the USB stick and jump directly to the third step of this procedure.</para> @@ -4398,23 +4354,23 @@ Please press any key to reboot.</screen> ISO image, use &man.tar.1; to extract all the files:</para> - <screen>&prompt.root; <userinput>mkdir <replaceable>/path/to/headless-iso</replaceable></userinput> -&prompt.root; <userinput>tar -C <replaceable>/path/to/headless-iso</replaceable> -pxvf &os;-<replaceable>&rel.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso</userinput></screen> + <screen>&prompt.root; <userinput>mkdir /path/to/headless-iso</userinput> +&prompt.root; <userinput>tar -C /path/to/headless-iso -pxvf &os;-&rel.current;-RELEASE-i386-disc1.iso</userinput></screen> <para>Next, set the installation media to boot into a serial console. Add this line to the <filename>/boot/loader.conf</filename> of the extracted ISO image:</para> - <screen>&prompt.root; <userinput>echo 'console="comconsole"' >> <replaceable>/path/to/headless-iso</replaceable>/boot/loader.conf</userinput></screen> + <screen>&prompt.root; <userinput>echo 'console="comconsole"' >> /path/to/headless-iso/boot/loader.conf</userinput></screen> <para>Then, create a new ISO image from the modified tree. This example uses &man.mkisofs.8; from the - <filename role="package">sysutils/cdrtools</filename> + <package>sysutils/cdrtools</package> package or port:</para> - <screen>&prompt.root; <userinput>mkisofs -v -b boot/cdboot -no-emul-boot -r -J -V "<replaceable>Headless_install</replaceable>" \ - -o <replaceable>Headless-</replaceable>&os;-<replaceable>&rel2.current;</replaceable>-RELEASE-<replaceable>i386</replaceable>-disc1.iso<replaceable>/path/to/headless-iso</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mkisofs -v -b boot/cdboot -no-emul-boot -r -J -V "Headless_install" \ + -o Headless-&os;-&rel2.current;-RELEASE-i386-disc1.iso/path/to/headless-iso</userinput></screen> <para>Now that the ISO image is configured correctly, burn it to a CD/DVD media using a burning @@ -4466,7 +4422,7 @@ Please press any key to reboot.</screen> </sect2> </sect1> - <sect1 id="install-diff-media"> + <sect1 xml:id="install-diff-media"> <title>Preparing Custom Installation Media</title> <para>Some situations may require a customized @@ -4504,7 +4460,7 @@ Please press any key to reboot.</screen> </listitem> </itemizedlist> - <sect2 id="install-cdrom"> + <sect2 xml:id="install-cdrom"> <title>Creating an Installation ISO</title> <para>As part of each release, the &os; Project provides ISO @@ -4519,7 +4475,7 @@ Please press any key to reboot.</screen> <step> <title>Download the Correct ISO Images</title> - <para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-<replaceable>arch</replaceable>/<replaceable>version</replaceable></filename> or the closest mirror. + <para>The ISO images for each release can be downloaded from <filename>ftp://ftp.FreeBSD.org/pub/FreeBSD/ISO-IMAGES-arch/version</filename> or the closest mirror. or the closest mirror. Substitute <replaceable>arch</replaceable> and <replaceable>version</replaceable> as appropriate.</para> @@ -4542,7 +4498,7 @@ Please press any key to reboot.</screen> <tbody> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-bootonly.iso</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-bootonly.iso</filename></entry> <entry>This CD image starts the installation process by booting from a CD-ROM drive but it does not @@ -4553,7 +4509,7 @@ Please press any key to reboot.</screen> </row> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-dvd1.iso.gz</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-dvd1.iso.gz</filename></entry> <entry>This DVD image contains everything necessary to install the base &os; operating system, a @@ -4563,7 +4519,7 @@ Please press any key to reboot.</screen> </row> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-memstick.img</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-memstick.img</filename></entry> <entry>This image can be written to an USB memory stick in order to install machines capable of booting @@ -4574,7 +4530,7 @@ Please press any key to reboot.</screen> </row> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc1.iso</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-disc1.iso</filename></entry> <entry>This CD image contains the base &os; operating system and the documentation package but no other @@ -4582,7 +4538,7 @@ Please press any key to reboot.</screen> </row> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc2.iso</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-disc2.iso</filename></entry> <entry>A CD image with as many third-party packages as would fit on the disc. This image is not @@ -4590,7 +4546,7 @@ Please press any key to reboot.</screen> </row> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-disc3.iso</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-disc3.iso</filename></entry> <entry>Another CD image with as many third-party packages as would fit on the disc. This image is @@ -4598,7 +4554,7 @@ Please press any key to reboot.</screen> </row> <row> - <entry><filename>&os;-<replaceable>version</replaceable>-RELEASE-<replaceable>arch</replaceable>-livefs.iso</filename></entry> + <entry><filename>&os;-version-RELEASE-arch-livefs.iso</filename></entry> <entry>This CD image contains support for booting into a <quote>livefs</quote> based rescue mode but does not @@ -4643,13 +4599,12 @@ Please press any key to reboot.</screen> </procedure> <note><para>To build a customized - release of &os;, refer to the <ulink - url="&url.articles.releng;">Release Engineering - Article</ulink>.</para></note> + release of &os;, refer to the <link xlink:href="&url.articles.releng;">Release Engineering + Article</link>.</para></note> </sect2> - <sect2 id="install-ftp"> + <sect2 xml:id="install-ftp"> <title>Creating a Local FTP Site with a &os; Disc</title> <indexterm> @@ -4686,7 +4641,7 @@ Please press any key to reboot.</screen> <para>Anyone with network connectivity to the machine can now chose a media type of FTP and type in - <userinput>ftp://<replaceable>your machine</replaceable></userinput> + <userinput>ftp://your machine</userinput> after picking <quote>Other</quote> in the FTP sites menu during the install.</para> @@ -4714,7 +4669,7 @@ Please press any key to reboot.</screen> </warning> </sect2> - <sect2 id="install-msdos"> + <sect2 xml:id="install-msdos"> <title>Installing from an &windows; Partition</title> <indexterm> @@ -4725,8 +4680,7 @@ Please press any key to reboot.</screen> partition, copy the files from the distribution into a directory in the root directory of the - partition, such as <filename - class="directory">c:\freebsd</filename>. Since the + partition, such as <filename>c:\freebsd</filename>. Since the directory structure must be reproduced, it is recommended to use <command>robocopy</command> when copying from a CD/DVD. @@ -4737,23 +4691,20 @@ Please press any key to reboot.</screen> <prompt>C:\></prompt> <userinput>robocopy e:\bin c:\freebsd\bin\ /s</userinput> <prompt>C:\></prompt> <userinput>robocopy e:\manpages c:\freebsd\manpages\ /s</userinput></screen> - <para>This example assumes that <devicename>C:</devicename> + <para>This example assumes that <filename>C:</filename> has enough - free space and <devicename>E:</devicename> is where the + free space and <filename>E:</filename> is where the CD/DVD is mounted.</para> <para>Alternatively, download the - distribution from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">ftp.FreeBSD.org</ulink>. + distribution from <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/">ftp.FreeBSD.org</link>. Each distribution is in its own directory; for example, the - <emphasis>base</emphasis> distribution can be found in the <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/base/">&rel2.current;/base/</ulink> + <emphasis>base</emphasis> distribution can be found in the <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/releases/i386/&rel2.current;-RELEASE/base/">&rel2.current;/base/</link> directory.</para> <para>Copy the distributions to install from a &windows; - partition to <filename - class="directory">c:\freebsd</filename>. Both the + partition to <filename>c:\freebsd</filename>. Both the <literal>base</literal> and <literal>kernel</literal> distributions are needed for the most minimal installation.</para> @@ -4814,9 +4765,7 @@ Please press any key to reboot.</screen> know how to dial the <acronym>ISP</acronym> using the <quote>AT commands</quote> specific to the modem, as the PPP dialer provides only a - simple terminal emulator. Refer to <xref - linkend="userppp"/> and <ulink - url="&url.books.faq;/ppp.html"></ulink> + simple terminal emulator. Refer to <xref linkend="userppp"/> and <uri xlink:href="&url.books.faq;/ppp.html">&url.books.faq;/ppp.html</uri> for further information. Logging can be directed to the screen using <command>set log local ...</command>.</para> @@ -4856,15 +4805,12 @@ Please press any key to reboot.</screen> work, the server must support subdir mounts. For example, if the &os; &rel.current; distribution lives on: - <filename - class="directory">ziggy:/usr/archive/stuff/FreeBSD</filename>, - <hostid>ziggy</hostid> will have to allow the direct mounting - of <filename - class="directory">/usr/archive/stuff/FreeBSD</filename>, + <filename>ziggy:/usr/archive/stuff/FreeBSD</filename>, + <systemitem>ziggy</systemitem> will have to allow the direct mounting + of <filename>/usr/archive/stuff/FreeBSD</filename>, not just - <filename class="directory">/usr</filename> or - <filename - class="directory">/usr/archive/stuff</filename>.</para> + <filename>/usr</filename> or + <filename>/usr/archive/stuff</filename>.</para> <para>In &os;, this is controlled by using <option>-alldirs</option> in diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml index afbe796fcf..74de18266c 100644 --- a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml @@ -4,22 +4,17 @@ $FreeBSD$ --> - -<chapter id="introduction"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="introduction"> + <info><title>Introduction</title> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Restructured, reorganized, and parts - rewritten by </contrib> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured, reorganized, and parts + rewritten by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Introduction</title> + - <sect1 id="introduction-synopsis"> + <sect1 xml:id="introduction-synopsis"> <title>Synopsis</title> <para>Thank you for your interest in &os;! The following chapter @@ -54,7 +49,7 @@ </itemizedlist> </sect1> - <sect1 id="nutshell"> + <sect1 xml:id="nutshell"> <title>Welcome to &os;!</title> <indexterm><primary>4.4BSD-Lite</primary></indexterm> @@ -66,11 +61,10 @@ read about <link linkend="history">the history of &os;</link>, or the <link linkend="relnotes">current release</link>. If you are interested in contributing something to the Project (code, - hardware, funding), see the <ulink - url="&url.articles.contributing;/index.html">Contributing to - &os;</ulink> article.</para> + hardware, funding), see the <link xlink:href="&url.articles.contributing;/index.html">Contributing to + &os;</link> article.</para> - <sect2 id="os-overview"> + <sect2 xml:id="os-overview"> <title>What Can &os; Do?</title> <para>&os; has many noteworthy features. Some of these @@ -357,8 +351,7 @@ </indexterm> With support for the &arm;, &mips; and &powerpc; platforms, coupled with a robust network stack, - cutting edge features and the permissive <ulink - url="&url.books.faq;/introduction.html#bsd-license-restrictions">BSD license</ulink> + cutting edge features and the permissive <link xlink:href="&url.books.faq;/introduction.html#bsd-license-restrictions">BSD license</link> &os; makes an excellent foundation for building embedded routers, firewalls, and other devices.</para> </listitem> @@ -400,12 +393,11 @@ </itemizedlist> <para>&os; is available to download free of charge, or can be - obtained on either CD-ROM or DVD. Please see <xref - linkend="mirrors"/> for more information about obtaining + obtained on either CD-ROM or DVD. Please see <xref linkend="mirrors"/> for more information about obtaining &os;.</para> </sect2> - <sect2 id="introduction-nutshell-users"> + <sect2 xml:id="introduction-nutshell-users"> <title>Who Uses &os;?</title> <indexterm> @@ -421,8 +413,7 @@ <itemizedlist> <listitem> - <para><ulink - url="http://www.apache.org/">Apache</ulink><indexterm> + <para><link xlink:href="http://www.apache.org/">Apache</link><indexterm> <primary>Apache</primary></indexterm> - The Apache Software Foundation runs most of its public facing infrastructure, including possibly one of the largest SVN @@ -431,8 +422,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.apple.com/">Apple</ulink><indexterm> + <para><link xlink:href="http://www.apple.com/">Apple</link><indexterm> <primary>Apple</primary></indexterm> - OS X borrows heavily from &os; for the network stack, virtual file system, and many userland components. Apple iOS also @@ -440,16 +430,14 @@ </listitem> <listitem> - <para><ulink - url="http://www.cisco.com/">Cisco</ulink><indexterm> + <para><link xlink:href="http://www.cisco.com/">Cisco</link><indexterm> <primary>Cisco</primary></indexterm> - IronPort network security and anti-spam appliances run a modified &os; kernel.</para> </listitem> <listitem> - <para><ulink - url="http://www.citrix.com/">Citrix</ulink><indexterm> + <para><link xlink:href="http://www.citrix.com/">Citrix</link><indexterm> <primary>Citrix</primary></indexterm> - The NetScaler line of security appliances provide layer 4-7 load balancing, content caching, application firewall, secure @@ -458,9 +446,8 @@ </listitem> <listitem> - <para><ulink - url="http://www.dell.com/KACE">Dell - KACE</ulink><indexterm><primary>Dell + <para><link xlink:href="http://www.dell.com/KACE">Dell + KACE</link><indexterm><primary>Dell KACE</primary></indexterm> - The KACE system management appliances run &os; because of its reliability, scalability, and the community that supports @@ -468,8 +455,8 @@ </listitem> <listitem> - <para><ulink url="http://www.experts-exchange.com/">Experts - Exchange</ulink><indexterm> + <para><link xlink:href="http://www.experts-exchange.com/">Experts + Exchange</link><indexterm> <primary>Experts Exchange</primary> </indexterm> - All public facing web servers are powered by &os; and they make extensive use of jails to isolate @@ -478,8 +465,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.isilon.com/">Isilon</ulink><indexterm> + <para><link xlink:href="http://www.isilon.com/">Isilon</link><indexterm> <primary>Isilon</primary></indexterm> - Isilon's enterprise storage appliances are based on &os;. The extremely liberal &os; license allowed Isilon to integrate @@ -489,8 +475,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.ixsystems.com/">iXsystems</ulink><indexterm> + <para><link xlink:href="http://www.ixsystems.com/">iXsystems</link><indexterm> <primary>iXsystems</primary></indexterm> - The TrueNAS line of unified storage appliances is based on &os;. In addition to their commercial products, iXsystems also @@ -499,8 +484,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.juniper.net/">Juniper</ulink><indexterm> + <para><link xlink:href="http://www.juniper.net/">Juniper</link><indexterm> <primary>Juniper</primary></indexterm> - The JunOS operating system that powers all Juniper networking gear (including routers, switches, security, and networking @@ -513,16 +497,14 @@ </listitem> <listitem> - <para><ulink - url="http://www.mcafee.com/">McAfee</ulink><indexterm> + <para><link xlink:href="http://www.mcafee.com/">McAfee</link><indexterm> <primary>McAfee</primary></indexterm> - SecurOS, the basis of McAfee enterprise firewall products including Sidewinder is based on &os;.</para> </listitem> <listitem> - <para><ulink - url="http://www.netapp.com/">NetApp</ulink><indexterm> + <para><link xlink:href="http://www.netapp.com/">NetApp</link><indexterm> <primary>NetApp</primary></indexterm> - The Data ONTAP GX line of storage appliances are based on &os;. In addition, NetApp has contributed back many features, @@ -530,8 +512,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.netflix.com/">Netflix</ulink><indexterm> + <para><link xlink:href="http://www.netflix.com/">Netflix</link><indexterm> <primary>Netflix</primary></indexterm> - The OpenConnect appliance that Netflix uses to stream movies to its customers is based on &os;. Netflix has make extensive @@ -542,8 +523,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.sandvine.com/">Sandvine</ulink> + <para><link xlink:href="http://www.sandvine.com/">Sandvine</link> <indexterm><primary>Sandvine</primary></indexterm> - Sandvine uses &os; as the basis of their high performance realtime network processing platforms that @@ -552,16 +532,14 @@ </listitem> <listitem> - <para><ulink - url="http://www.sony.com/">Sony</ulink> + <para><link xlink:href="http://www.sony.com/">Sony</link> <indexterm><primary>Sony</primary></indexterm> - Both the PlayStation 3 and PlayStation 4 gaming consoles run modified versions of &os;.</para> </listitem> <listitem> - <para><ulink - url="http://www.sophos.com/">Sophos</ulink> + <para><link xlink:href="http://www.sophos.com/">Sophos</link> <indexterm><primary>Sophos</primary></indexterm> - The Sophos Email Appliance product is based on a hardened &os; and scans inbound mail for spam and viruses, @@ -570,17 +548,15 @@ </listitem> <listitem> - <para><ulink - url="http://www.spectralogic.com/">Spectra Logic</ulink> + <para><link xlink:href="http://www.spectralogic.com/">Spectra Logic</link> <indexterm><primary>Spectra Logic</primary></indexterm> - The nTier line of archive grade storage appliances run &os; and OpenZFS.</para> </listitem> <listitem> - <para><ulink - url="http://www.weather.com/">The Weather - Channel</ulink><indexterm><primary>The Weather + <para><link xlink:href="http://www.weather.com/">The Weather + Channel</link><indexterm><primary>The Weather Channel</primary></indexterm> - The IntelliStar appliance that is installed at each local cable providers headend and is responsible for injecting local @@ -589,8 +565,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.verisign.com/">Verisign</ulink> + <para><link xlink:href="http://www.verisign.com/">Verisign</link> <indexterm><primary>Verisign</primary></indexterm> - Verisign is responsible for operating the .com and .net root domain registries as well as the accompanying DNS @@ -601,8 +576,7 @@ </listitem> <listitem> - <para><ulink - url="http://www.whatsapp.com/">WhatsApp</ulink> + <para><link xlink:href="http://www.whatsapp.com/">WhatsApp</link> <indexterm><primary>WhatsApp</primary></indexterm> - When WhatsApp needed a platform that would be able to handle more than 1 million concurrent TCP connections per server, @@ -611,8 +585,7 @@ </listitem> <listitem> - <para><ulink - url="http://wheelsystems.com/en/">Wheel Systems</ulink> + <para><link xlink:href="http://wheelsystems.com/en/">Wheel Systems</link> <indexterm><primary>Wheel Systems</primary></indexterm> - The FUDO security appliance allows enterprises to monitor, control, record, and audit contractors and @@ -627,16 +600,14 @@ <itemizedlist> <listitem> - <para><ulink - url="http://bsdrp.net/">BSD Router</ulink><indexterm> + <para><link xlink:href="http://bsdrp.net/">BSD Router</link><indexterm> <primary>BSD Router</primary></indexterm> - A &os; based replacement for large enterprise routers designed to run on standard PC hardware.</para> </listitem> <listitem> - <para><ulink - url="http://www.freenas.org/">FreeNAS</ulink><indexterm> + <para><link xlink:href="http://www.freenas.org/">FreeNAS</link><indexterm> <primary>FreeNAS</primary></indexterm> - A customized &os; designed to be used as a network file server appliance. Provides a python based web interface to @@ -647,32 +618,28 @@ </listitem> <listitem> - <para><ulink - url="http://www.ghostbsd.org/">GhostBSD</ulink><indexterm> + <para><link xlink:href="http://www.ghostbsd.org/">GhostBSD</link><indexterm> <primary>GhostBSD</primary></indexterm> - A desktop oriented distribution of &os; bundled with the Gnome desktop environment.</para> </listitem> <listitem> - <para><ulink - url="http://mfsbsd.vx.sk/">mfsBSD</ulink><indexterm> + <para><link xlink:href="http://mfsbsd.vx.sk/">mfsBSD</link><indexterm> <primary>mfsBSD</primary></indexterm> - A toolkit for building a &os; system image that runs entirely from memory.</para> </listitem> <listitem> - <para><ulink - url="http://www.nas4free.org/">NAS4Free</ulink><indexterm> + <para><link xlink:href="http://www.nas4free.org/">NAS4Free</link><indexterm> <primary>NAS4Free</primary></indexterm> - A file server distribution based on &os; with a PHP powered web interface.</para> </listitem> <listitem> - <para><ulink - url="http://www.pcbsd.org/">PC-BSD</ulink><indexterm> + <para><link xlink:href="http://www.pcbsd.org/">PC-BSD</link><indexterm> <primary>PC-BSD</primary></indexterm> - A customized version of &os; geared towards desktop users with graphical utilities to exposing the power of &os; to @@ -681,16 +648,14 @@ </listitem> <listitem> - <para><ulink - url="http://www.pfsense.org/">pfSense</ulink><indexterm> + <para><link xlink:href="http://www.pfsense.org/">pfSense</link><indexterm> <primary>pfSense</primary></indexterm> - A firewall distribution based on &os; with a huge array of features and extensive IPv6 support.</para> </listitem> <listitem> - <para><ulink - url="http://m0n0.ch/wall/">m0n0wall</ulink><indexterm> + <para><link xlink:href="http://m0n0.ch/wall/">m0n0wall</link><indexterm> <primary>m0n0wall</primary></indexterm> - A stripped down version of &os; bundled with a web server and PHP. Designed as an embedded firewall appliance with a @@ -698,8 +663,7 @@ </listitem> <listitem> - <para><ulink - url="http://zrouter.org/">ZRouter</ulink><indexterm> + <para><link xlink:href="http://zrouter.org/">ZRouter</link><indexterm> <primary>ZRouter</primary></indexterm> - An open source alternative firmware for embedded devices based on &os;. Designed to replace the proprietary firmware on @@ -712,89 +676,80 @@ <itemizedlist> <listitem> - <para><ulink - url="http://www.yahoo.com/">Yahoo!</ulink><indexterm> + <para><link xlink:href="http://www.yahoo.com/">Yahoo!</link><indexterm> <primary>Yahoo!</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="http://www.yandex.ru/">Yandex</ulink><indexterm> + <para><link xlink:href="http://www.yandex.ru/">Yandex</link><indexterm> <primary>Yandex</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="http://www.rambler.ru/">Rambler</ulink><indexterm> + <para><link xlink:href="http://www.rambler.ru/">Rambler</link><indexterm> <primary>Rambler</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="http://www.sina.com/">Sina</ulink><indexterm> + <para><link xlink:href="http://www.sina.com/">Sina</link><indexterm> <primary>Sina</primary> </indexterm></para> </listitem> <listitem> - <para><ulink url="http://www.pair.com/">Pair - Networks</ulink><indexterm> + <para><link xlink:href="http://www.pair.com/">Pair + Networks</link><indexterm> <primary>Pair Networks</primary></indexterm></para> </listitem> <listitem> - <para><ulink url="http://www.sony.co.jp/">Sony - Japan</ulink><indexterm> + <para><link xlink:href="http://www.sony.co.jp/">Sony + Japan</link><indexterm> <primary>Sony Japan</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="http://www.netcraft.com/">Netcraft</ulink><indexterm> + <para><link xlink:href="http://www.netcraft.com/">Netcraft</link><indexterm> <primary>Netcraft</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="https://signup.netflix.com/openconnect">Netflix</ulink> + <para><link xlink:href="https://signup.netflix.com/openconnect">Netflix</link> <indexterm><primary>Netflix</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="http://www.163.com/">NetEase</ulink><indexterm> + <para><link xlink:href="http://www.163.com/">NetEase</link><indexterm> <primary>NetEase</primary></indexterm></para> </listitem> <listitem> - <para><ulink - url="http://www.weathernews.com/">Weathernews</ulink> + <para><link xlink:href="http://www.weathernews.com/">Weathernews</link> <indexterm><primary>Weathernews</primary></indexterm></para> </listitem> <listitem> - <para><ulink url="http://www.telehouse.com/">TELEHOUSE - America</ulink><indexterm> + <para><link xlink:href="http://www.telehouse.com/">TELEHOUSE + America</link><indexterm> <primary>TELEHOUSE America</primary> </indexterm></para> </listitem> </itemizedlist> - <para>and many more. Wikipedia also maintains a <ulink - url="http://en.wikipedia.org/wiki/List_of_products_based_on_FreeBSD"> - list of products based on &os;</ulink></para> + <para>and many more. Wikipedia also maintains a <link xlink:href="http://en.wikipedia.org/wiki/List_of_products_based_on_FreeBSD"> + list of products based on &os;</link></para> </sect2> </sect1> - <sect1 id="history"> + <sect1 xml:id="history"> <title>About the &os; Project</title> <para>The following section provides some background information on the project, including a brief history, project goals, and the development model of the project.</para> - <sect2 id="intro-history"> + <sect2 xml:id="intro-history"> <title>A Brief History of &os;</title> <indexterm><primary>386BSD Patchkit</primary></indexterm> @@ -904,23 +859,18 @@ <para>For now, long-term development projects continue to take place in the 10.X-CURRENT (trunk) branch, and snapshot - releases of 10.X are continually made available from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/">the - snapshot server</ulink> as work progresses.</para> + releases of 10.X are continually made available from <link xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/snapshots/">the + snapshot server</link> as work progresses.</para> </sect2> - <sect2 id="goals"> - <sect2info> + <sect2 xml:id="goals"> + <info><title>&os; Project Goals</title> <authorgroup> - <author> - <firstname>Jordan</firstname> - <surname>Hubbard</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Jordan</firstname><surname>Hubbard</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>&os; Project Goals</title> + <indexterm> <primary>FreeBSD Project</primary> @@ -955,18 +905,14 @@ it is a reasonable option to do so.</para> </sect2> - <sect2 id="development"> - <sect2info> + <sect2 xml:id="development"> + <info><title>The &os; Development Model</title> <authorgroup> - <author> - <firstname>Satoshi</firstname> - <surname>Asami</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Satoshi</firstname><surname>Asami</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>The &os; Development Model</title> + <indexterm> <primary>FreeBSD Project</primary> @@ -975,9 +921,8 @@ <para>The development of &os; is a very open and flexible process, being literally built from the contributions of thousands of people around the world, as can be seen from - our <ulink - url="&url.articles.contributors;/article.html">list of - contributors</ulink>. &os;'s development infrastructure + our <link xlink:href="&url.articles.contributors;/article.html">list of + contributors</link>. &os;'s development infrastructure allow these thousands of contributors to collaborate over the Internet. We are constantly on the lookout for new developers and ideas, and those interested in becoming more closely @@ -992,8 +937,7 @@ <variablelist> <varlistentry> - <term>The SVN repositories<anchor - id="development-cvs-repository"/></term> + <term>The SVN repositories<anchor xml:id="development-cvs-repository"/></term> <listitem> <para> <indexterm> @@ -1023,11 +967,10 @@ </indexterm> For several years, the central source tree for &os; was maintained by - <ulink url="http://www.nongnu.org/cvs/">CVS</ulink> + <link xlink:href="http://www.nongnu.org/cvs/">CVS</link> (Concurrent Versions System), a freely available source code control tool. In June - 2008, the Project switched to using <ulink - url="http://subversion.tigris.org">SVN</ulink> + 2008, the Project switched to using <link xlink:href="http://subversion.tigris.org">SVN</link> (Subversion). The switch was deemed necessary, as the technical limitations imposed by <application>CVS</application> were becoming obvious @@ -1047,8 +990,7 @@ </varlistentry> <varlistentry> - <term>The committers list<anchor - id="development-committers"/></term> + <term>The committers list<anchor xml:id="development-committers"/></term> <listitem> <para>The <firstterm>committers</firstterm><indexterm> @@ -1067,8 +1009,7 @@ </varlistentry> <varlistentry> - <term>The FreeBSD core team<anchor - id="development-core"/></term> + <term>The FreeBSD core team<anchor xml:id="development-core"/></term> <listitem> <para>The <firstterm>&os; core team</firstterm><indexterm> @@ -1109,22 +1050,19 @@ and bug fixes to us on an almost constant basis. The primary way of keeping in touch with &os;'s more non-centralized development is to subscribe to the - &a.hackers; where such things are discussed. See <xref - linkend="eresources"/> for more information about the + &a.hackers; where such things are discussed. See <xref linkend="eresources"/> for more information about the various &os; mailing lists.</para> - <para><citetitle><ulink - url="&url.articles.contributors;/article.html">The - &os; Contributors List</ulink></citetitle><indexterm> + <para><citetitle><link xlink:href="&url.articles.contributors;/article.html">The + &os; Contributors List</link></citetitle><indexterm> <primary>contributors</primary></indexterm> is a long and growing one, so why not join it by contributing something back to &os; today?</para> <para>Providing code is not the only way of contributing to the project; for a more complete list of things that - need doing, please refer to the <ulink - url="&url.base;/index.html">&os; Project web - site</ulink>.</para> + need doing, please refer to the <link xlink:href="&url.base;/index.html">&os; Project web + site</link>.</para> </listitem> </varlistentry> </variablelist> @@ -1144,7 +1082,7 @@ continued success!</para> </sect2> - <sect2 id="relnotes"> + <sect2 xml:id="relnotes"> <title>Third Party Programs</title> <para>In addition to the base distributions, &os; offers a @@ -1172,8 +1110,7 @@ <para>All recent &os; versions provide an option in the installer (either &man.sysinstall.8; or &man.bsdinstall.8;) to - install additional documentation under <filename - class="directory">/usr/local/share/doc/freebsd</filename> + install additional documentation under <filename>/usr/local/share/doc/freebsd</filename> during the initial system setup. Documentation may also be installed at any later time using packages as described in <xref linkend="doc-ports-install-package"/>. You may view the @@ -1185,8 +1122,7 @@ <term>The FreeBSD Handbook</term> <listitem> - <para><ulink type="html" - url="file://localhost/usr/local/share/doc/freebsd/handbook/index.html"><filename>/usr/local/share/doc/freebsd/handbook/index.html</filename></ulink></para> + <para><link xlink:href="file://localhost/usr/local/share/doc/freebsd/handbook/index.html"><filename>/usr/local/share/doc/freebsd/handbook/index.html</filename></link></para> </listitem> </varlistentry> @@ -1194,15 +1130,13 @@ <term>The FreeBSD FAQ</term> <listitem> - <para><ulink type="html" - url="file://localhost/usr/local/share/doc/freebsd/faq/index.html"><filename>/usr/local/share/doc/freebsd/faq/index.html</filename></ulink></para> + <para><link xlink:href="file://localhost/usr/local/share/doc/freebsd/faq/index.html"><filename>/usr/local/share/doc/freebsd/faq/index.html</filename></link></para> </listitem> </varlistentry> </variablelist> <para>You can also view the master (and most frequently updated) - copies at <ulink - url="http://www.FreeBSD.org/"></ulink>.</para> + copies at <uri xlink:href="http://www.FreeBSD.org/">http://www.FreeBSD.org/</uri>.</para> </sect2> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/handbook/jails/chapter.xml b/en_US.ISO8859-1/books/handbook/jails/chapter.xml index 06e09b74c9..39f803f448 100644 --- a/en_US.ISO8859-1/books/handbook/jails/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/jails/chapter.xml @@ -4,22 +4,18 @@ $FreeBSD$ --> -<chapter id="jails"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="jails"> + <info><title>Jails</title> <authorgroup> - <author> - <firstname>Matteo</firstname> - <surname>Riondato</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Matteo</firstname><surname>Riondato</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Jails</title> + <indexterm><primary>jails</primary></indexterm> - <sect1 id="jails-synopsis"> + <sect1 xml:id="jails-synopsis"> <title>Synopsis</title> <para>This chapter will provide an explanation of what &os; jails @@ -84,7 +80,7 @@ </itemizedlist> </sect1> - <sect1 id="jails-terms"> + <sect1 xml:id="jails-terms"> <title>Terms Related to Jails</title> <para>To facilitate better understanding of parts of the &os; @@ -145,7 +141,7 @@ </variablelist> </sect1> - <sect1 id="jails-intro"> + <sect1 xml:id="jails-intro"> <title>Introduction</title> <para>Since system administration is a difficult and perplexing @@ -164,7 +160,7 @@ subsystem. Their development still goes on, enhancing their usefulness, performance, reliability, and security.</para> - <sect2 id="jails-what"> + <sect2 xml:id="jails-what"> <title>What is a Jail</title> <para>BSD-like operating systems have had &man.chroot.2; since @@ -236,21 +232,21 @@ </itemizedlist> <para>Apart from these, jails can have their own set of users - and their own <username>root</username> user. Naturally, the - powers of the <username>root</username> user are limited + and their own <systemitem class="username">root</systemitem> user. Naturally, the + powers of the <systemitem class="username">root</systemitem> user are limited within the jail environment and, from the point of view of the - host system, the jail <username>root</username> user is not an - omnipotent user. In addition, the <username>root</username> + host system, the jail <systemitem class="username">root</systemitem> user is not an + omnipotent user. In addition, the <systemitem class="username">root</systemitem> user of a jail is not allowed to perform critical operations to the system outside of the associated &man.jail.8; environment. More information about capabilities and - restrictions of the <username>root</username> user will be + restrictions of the <systemitem class="username">root</systemitem> user will be discussed in <xref linkend="jails-tuning"/> below.</para> </sect2> </sect1> - <sect1 id="jails-build"> + <sect1 xml:id="jails-build"> <title>Creating and Controlling Jails</title> <para>Some administrators divide jails into the following two @@ -261,24 +257,23 @@ is not affected by it. The &man.jail.8; manual page is quite clear about the procedure for building a jail:</para> - <screen>&prompt.root; <userinput>setenv D <replaceable>/here/is/the/jail</replaceable></userinput> -&prompt.root; <userinput>mkdir -p $D</userinput> <co id="jailpath"/> + <screen>&prompt.root; <userinput>setenv D /here/is/the/jail</userinput> +&prompt.root; <userinput>mkdir -p $D</userinput> <co xml:id="jailpath"/> &prompt.root; <userinput>cd /usr/src</userinput> -&prompt.root; <userinput>make buildworld</userinput> <co id="jailbuildworld"/> -&prompt.root; <userinput>make installworld DESTDIR=$D</userinput> <co id="jailinstallworld"/> -&prompt.root; <userinput>make distribution DESTDIR=$D</userinput> <co id="jaildistrib"/> -&prompt.root; <userinput>mount -t devfs devfs $D/dev</userinput> <co id="jaildevfs"/></screen> +&prompt.root; <userinput>make buildworld</userinput> <co xml:id="jailbuildworld"/> +&prompt.root; <userinput>make installworld DESTDIR=$D</userinput> <co xml:id="jailinstallworld"/> +&prompt.root; <userinput>make distribution DESTDIR=$D</userinput> <co xml:id="jaildistrib"/> +&prompt.root; <userinput>mount -t devfs devfs $D/dev</userinput> <co xml:id="jaildevfs"/></screen> <calloutlist> <callout arearefs="jailpath"> <para>Selecting a location for a jail is the best starting point. This is where the jail will physically reside within the file system of the jail's host. A good choice can be - <filename - class="directory">/usr/jail/<replaceable>jailname</replaceable></filename>, + <filename>/usr/jail/jailname</filename>, where <replaceable>jailname</replaceable> is the hostname identifying the jail. The - <filename class="directory">/usr/</filename> file system + <filename>/usr/</filename> file system usually has enough space for the jail file system, which for <quote>complete</quote> jails is, essentially, a replication of every file present in a default installation of the &os; @@ -300,14 +295,14 @@ </callout> <callout arearefs="jaildistrib"> - <para>The <maketarget>distribution</maketarget> target for + <para>The <buildtarget>distribution</buildtarget> target for <application>make</application> installs every needed configuration file. In simple words, it installs every installable file of - <filename class="directory">/usr/src/etc/</filename> to the - <filename class="directory">/etc</filename> directory of the + <filename>/usr/src/etc/</filename> to the + <filename>/etc</filename> directory of the jail environment: - <filename class="directory">$D/etc/</filename>.</para> + <filename>$D/etc/</filename>.</para> </callout> <callout arearefs="jaildevfs"> @@ -385,8 +380,8 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep start or stop a jail by hand, if an entry for it exists in <filename>rc.conf</filename>:</para> - <screen>&prompt.root; <userinput>service jail start <replaceable>www</replaceable></userinput> -&prompt.root; <userinput>service jail stop <replaceable>www</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>service jail start www</userinput> +&prompt.root; <userinput>service jail stop www</userinput></screen> <para>A clean way to shut down a &man.jail.8; is not available at the moment. This is because commands normally used to @@ -401,7 +396,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep manual page.</para> </sect1> - <sect1 id="jails-tuning"> + <sect1 xml:id="jails-tuning"> <title>Fine Tuning and Administration</title> <para>There are several options which can be set for any jail, and @@ -424,7 +419,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep </listitem> </itemizedlist> - <sect2 id="jails-tuning-utilities"> + <sect2 xml:id="jails-tuning-utilities"> <title>System Tools for Jail Tuning in &os;</title> <para>Fine tuning of a jail's configuration is mostly done by @@ -476,11 +471,11 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep <para>These variables can be used by the system administrator of the <emphasis>host system</emphasis> to add or remove some of the limitations imposed by default on the - <username>root</username> user. Note that there are some + <systemitem class="username">root</systemitem> user. Note that there are some limitations which cannot be removed. The - <username>root</username> user is not allowed to mount or + <systemitem class="username">root</systemitem> user is not allowed to mount or unmount file systems from within a &man.jail.8;. The - <username>root</username> inside a jail may not load or unload + <systemitem class="username">root</systemitem> inside a jail may not load or unload &man.devfs.8; rulesets, set firewall rules, or do many other administrative tasks which require modifications of in-kernel data, such as setting the <varname>securelevel</varname> of @@ -503,49 +498,43 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep <para>Attach to a running jail, from its host system, and run a command inside the jail or perform administrative tasks inside the jail itself. This is especially useful - when the <username>root</username> user wants to cleanly + when the <systemitem class="username">root</systemitem> user wants to cleanly shut down a jail. The &man.jexec.8; utility can also be used to start a shell in a jail to do administration in it; for example:</para> - <screen>&prompt.root; <userinput>jexec <replaceable>1</replaceable> tcsh</userinput></screen> + <screen>&prompt.root; <userinput>jexec 1 tcsh</userinput></screen> </listitem> </itemizedlist> </sect2> - <sect2 id="jails-tuning-admintools"> + <sect2 xml:id="jails-tuning-admintools"> <title>High-Level Administrative Tools in the &os; Ports Collection</title> <para>Among the many third-party utilities for jail administration, one of the most complete and useful is - <filename role="package">sysutils/jailutils</filename>. It is + <package>sysutils/jailutils</package>. It is a set of small applications that contribute to &man.jail.8; management. Please refer to its web page for more information.</para> </sect2> </sect1> - <sect1 id="jails-application"> + <sect1 xml:id="jails-application"> <title>Application of Jails</title> - <sect2 id="jails-service-jails"> - <sect2info> + <sect2 xml:id="jails-service-jails"> + <info><title>Service Jails</title> <authorgroup> - <author> - <firstname>Daniel</firstname> - <surname>Gerzo</surname> - <contrib>Contributed by </contrib> - <!-- 15. May 2007 --> - </author> + <author><personname><firstname>Daniel</firstname><surname>Gerzo</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>Service Jails</title> + <para>This section is based upon an idea originally presented by - &a.simon.email; at <ulink - url="http://simon.nitro.dk/service-jails.html"></ulink>, and + &a.simon.email; at <uri xlink:href="http://simon.nitro.dk/service-jails.html">http://simon.nitro.dk/service-jails.html</uri>, and an updated article written by Ken Tom <email>locals@gmail.com</email>. This section illustrates how to set up a &os; system that adds an additional layer of @@ -554,7 +543,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep information provided earlier in this chapter has been well understood.</para> - <sect3 id="jails-service-jails-design"> + <sect3 xml:id="jails-service-jails-design"> <title>Design</title> <para>One of the major problems with jails is the management @@ -570,7 +559,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep usage of its features. If the presented steps below look too complicated, it is advised to take a look at a simpler system such as - <filename role="package">sysutils/ezjail</filename>, which + <package>sysutils/ezjail</package>, which provides an easier method of administering &os; jails and is not as sophisticated as this setup.</para> </warning> @@ -641,45 +630,43 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep <itemizedlist> <listitem> <para>Each jail will be mounted under the - <filename class="directory">/home/j</filename> + <filename>/home/j</filename> directory.</para> </listitem> <listitem> - <para><filename class="directory">/home/j/mroot</filename> + <para><filename>/home/j/mroot</filename> is the template for each jail and the read-only partition for all of the jails.</para> </listitem> <listitem> <para>A blank directory will be created for each jail - under the <filename class="directory">/home/j</filename> + under the <filename>/home/j</filename> directory.</para> </listitem> <listitem> <para>Each jail will have a - <filename class="directory">/s</filename> directory, + <filename>/s</filename> directory, that will be linked to the read-write portion of the system.</para> </listitem> <listitem> <para>Each jail shall have its own read-write system that - is based upon <filename - class="directory">/home/j/skel</filename>.</para> + is based upon <filename>/home/j/skel</filename>.</para> </listitem> <listitem> <para>Each jailspace (read-write portion of each jail) - shall be created in <filename - class="directory">/home/js</filename>.</para> + shall be created in <filename>/home/js</filename>.</para> </listitem> </itemizedlist> <note> <para>This assumes that the jails are based under the - <filename class="directory">/home</filename> partition. + <filename>/home</filename> partition. This can, of course, be changed to anything else, but this change will have to be reflected in each of the examples below.</para> @@ -687,7 +674,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep <!-- Insert an image or drawing here to illustrate the example. --> </sect3> - <sect3 id="jails-service-jails-template"> + <sect3 xml:id="jails-service-jails-template"> <title>Creating the Template</title> <para>This section will describe the steps needed to create @@ -696,16 +683,15 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep <para>It is always a good idea to update the &os; system to the latest -RELEASE branch. Check the corresponding - Handbook <ulink - url="&url.books.handbook;/makeworld.html">Chapter</ulink> + Handbook <link xlink:href="&url.books.handbook;/makeworld.html">Chapter</link> to accomplish this task. In the case the update is not feasible, the buildworld will be required in order to be able to proceed. Additionally, the - <filename role="package">sysutils/cpdup</filename> package + <package>sysutils/cpdup</package> package will be required. We will use the &man.portsnap.8; utility to download the &os; Ports Collection. The Handbook - <ulink url="&url.books.handbook;/portsnap.html">Portsnap - Chapter</ulink> is always good reading for + <link xlink:href="&url.books.handbook;/portsnap.html">Portsnap + Chapter</link> is always good reading for newcomers.</para> <procedure> @@ -759,7 +745,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep <para>Now, symlink the read-write file system to the read-only file system. Please make sure that the symlinks are created in the correct - <filename class="directory">s/</filename> locations. + <filename>s/</filename> locations. Real directories or the creation of directories in the wrong locations will cause the installation to fail.</para> @@ -793,7 +779,7 @@ jail_<replaceable>www</replaceable>_devfs_ruleset="<replaceable>www_ruleset</rep </procedure> </sect3> - <sect3 id="jails-service-jails-creating"> + <sect3 xml:id="jails-service-jails-creating"> <title>Creating Jails</title> <para>Now that we have a complete &os; jail template, we can @@ -855,13 +841,13 @@ jail_www_devfs_enable="YES"</programlisting> <para>The reason why the <varname>jail_<replaceable>name</replaceable>_rootdir</varname> variable is set to - <filename class="directory">/usr/home</filename> + <filename>/usr/home</filename> instead of - <filename class="directory">/home</filename> is that + <filename>/home</filename> is that the physical path of the - <filename class="directory">/home</filename> directory + <filename>/home</filename> directory on a default &os; installation is - <filename class="directory">/usr/home</filename>. The + <filename>/usr/home</filename>. The <varname>jail_<replaceable>name</replaceable>_rootdir</varname> variable must <emphasis>not</emphasis> be set to a path which includes a symbolic link, otherwise the @@ -882,7 +868,7 @@ jail_www_devfs_enable="YES"</programlisting> <step> <para>Install the read-write template into each jail. Note the use of - <filename role="package">sysutils/cpdup</filename>, + <package>sysutils/cpdup</package>, which helps to ensure that a correct copy is done of each directory:</para> <!-- keramida: Why is cpdup required here? Doesn't cpio(1) @@ -927,7 +913,7 @@ jail_www_devfs_enable="YES"</programlisting> <screen>&prompt.root; <userinput>jexec 3 tcsh</userinput></screen> </sect3> - <sect3 id="jails-service-jails-upgrading"> + <sect3 xml:id="jails-service-jails-upgrading"> <title>Upgrading</title> <para>In time, there will be a need to upgrade the system to a @@ -944,8 +930,7 @@ jail_www_devfs_enable="YES"</programlisting> <step> <para>The first step is to upgrade the host system in the usual manner. Then create a new temporary read-only - template in <filename - class="directory">/home/j/mroot2</filename>.</para> + template in <filename>/home/j/mroot2</filename>.</para> <screen>&prompt.root; <userinput>mkdir /home/j/mroot2</userinput> &prompt.root; <userinput>cd /usr/src</userinput> @@ -954,7 +939,7 @@ jail_www_devfs_enable="YES"</programlisting> &prompt.root; <userinput>cpdup /usr/src usr/src</userinput> &prompt.root; <userinput>mkdir s</userinput></screen> - <para>The <maketarget>installworld</maketarget> run + <para>The <buildtarget>installworld</buildtarget> run creates a few unnecessary directories, which should be removed:</para> @@ -997,7 +982,7 @@ jail_www_devfs_enable="YES"</programlisting> <note> <para>The read-write systems are attached to the read-only system - (<filename class="directory">/s</filename>) and must + (<filename>/s</filename>) and must be unmounted first.</para> </note> </step> diff --git a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml index 911c0e0a7e..0796a550b0 100644 --- a/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/kernelconfig/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="kernelconfig"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="kernelconfig"> <!--<chapterinfo> <authorgroup> <author> @@ -26,7 +25,7 @@ <title>Configuring the FreeBSD Kernel</title> - <sect1 id="kernelconfig-synopsis"> + <sect1 xml:id="kernelconfig-synopsis"> <title>Synopsis</title> <indexterm> @@ -70,10 +69,10 @@ </itemizedlist> <para>All of the commands listed in the examples in this chapter - should be executed as <username>root</username>.</para> + should be executed as <systemitem class="username">root</systemitem>.</para> </sect1> - <sect1 id="kernelconfig-custom-kernel"> + <sect1 xml:id="kernelconfig-custom-kernel"> <title>Why Build a Custom Kernel?</title> <para>Traditionally, &os; used a monolithic kernel. @@ -133,8 +132,7 @@ doing so. If there is a need for specific hardware support, it may already exist as a module.</para> - <para>Kernel modules exist in <filename - class="directory">/boot/kernel</filename> and may be + <para>Kernel modules exist in <filename>/boot/kernel</filename> and may be dynamically loaded into the running kernel using &man.kldload.8;. Most kernel drivers have a loadable module and manual page. For example, the &man.ath.4; @@ -150,12 +148,11 @@ following line in &man.loader.conf.5;: <filename>/boot/loader.conf</filename> will load this module dynamically at boot time.</para> - <para>In some cases, there is no associated module in <filename - class="directory">/boot/kernel</filename>. This is + <para>In some cases, there is no associated module in <filename>/boot/kernel</filename>. This is mostly true for certain subsystems.</para> </sect1> - <sect1 id="kernelconfig-devices"> + <sect1 xml:id="kernelconfig-devices"> <!-- <sect1info> <authorgroup> @@ -207,7 +204,7 @@ psm0: model Generic PS/2 mouse, device ID 0</programlisting> &man.pciconf.8;, which provides more verbose output. For example:</para> - <programlisting><command>pciconf <option>-lv</option></command> + <programlisting><command>pciconf -lv</command> ath0@pci0:3:0:0: class=0x020000 card=0x058a1014 chip=0x1014168c rev=0x01 hdr=0x00 vendor = 'Atheros Communications Inc.' device = 'AR5212 Atheros AR5212 802.11abg wireless' @@ -215,7 +212,7 @@ psm0: model Generic PS/2 mouse, device ID 0</programlisting> subclass = ethernet</programlisting> <para>This output shows that the - <devicename>ath</devicename> driver located a wireless Ethernet + <filename>ath</filename> driver located a wireless Ethernet device.</para> <para>The <option>-k</option> flag of &man.man.1; @@ -233,7 +230,7 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting> kernel configuration file.</para> </sect1> - <sect1 id="kernelconfig-config"> + <sect1 xml:id="kernelconfig-config"> <!-- <sect1info> <authorgroup> @@ -250,30 +247,21 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting> <para>In order to create a custom kernel configuration file and build a custom kernel, the full &os; source tree must first be installed.</para> - <para>If <filename class="directory">/usr/src/</filename> does + <para>If <filename>/usr/src/</filename> does not exist or it is empty, source has not been installed. Source can be installed using - <application>svn</application>, which is described in <xref - linkend="svn"/>, or by installing the + <application>svn</application>, which is described in <xref linkend="svn"/>, or by installing the <literal>src</literal> distribution using &man.sysinstall.8;. This distribution can be selected by navigating to the <literal>Configuration</literal> and then to the <literal>Distributions</literal> menu within &man.sysinstall.8;.</para> - <para>Once source is installed, review the contents of <filename - class="directory">/usr/src/sys</filename>. This directory contains a + <para>Once source is installed, review the contents of <filename>/usr/src/sys</filename>. This directory contains a number of subdirectories, including those which represent the following - supported architectures: <filename - class="directory">amd64</filename>, <filename - class="directory">i386</filename>, <filename - class="directory">ia64</filename>, <filename - class="directory">pc98</filename>, <filename - class="directory">powerpc</filename>, and <filename - class="directory">sparc64</filename>. Everything inside a + supported architectures: <filename>amd64</filename>, <filename>i386</filename>, <filename>ia64</filename>, <filename>pc98</filename>, <filename>powerpc</filename>, and <filename>sparc64</filename>. Everything inside a particular architecture's directory deals with that architecture only and the rest of the code is machine independent code common - to all platforms. Each supported architecture has a <filename - class="directory">conf</filename> subdirectory + to all platforms. Each supported architecture has a <filename>conf</filename> subdirectory which contains the <filename>GENERIC</filename> kernel configuration file for that architecture.</para> @@ -285,25 +273,24 @@ ath_hal(4) - Atheros Hardware Access Layer (HAL)</programlisting> example creates a custom configuration file for the <literal>amd64</literal> architecture:</para> - <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput> -&prompt.root; <userinput>cp GENERIC <replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput> +&prompt.root; <userinput>cp GENERIC MYKERNEL</userinput></screen> <tip> <para>When finished customizing the kernel configuration file, - save a backup copy to a location outside of <filename - class="directory">/usr/src</filename>.</para> + save a backup copy to a location outside of <filename>/usr/src</filename>.</para> <para>Alternately, keep the kernel configuration file elsewhere and create a symbolic link to the file:</para> - <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>amd64</replaceable>/conf</userinput> + <screen>&prompt.root; <userinput>cd /usr/src/sys/amd64/conf</userinput> &prompt.root; <userinput>mkdir /root/kernels</userinput> -&prompt.root; <userinput>cp GENERIC /root/kernels/<replaceable>MYKERNEL</replaceable></userinput> -&prompt.root; <userinput>ln -s /root/kernels/<replaceable>MYKERNEL</replaceable></userinput></screen> +&prompt.root; <userinput>cp GENERIC /root/kernels/MYKERNEL</userinput> +&prompt.root; <userinput>ln -s /root/kernels/MYKERNEL</userinput></screen> </tip> <para>The configuration file - <filename><replaceable>MYKERNEL</replaceable></filename> can now be customized + <filename>MYKERNEL</filename> can now be customized with any ASCII text editor. The default editor is <application>vi</application>, though an easier editor for beginners, called <application>ee</application>, is also @@ -362,8 +349,8 @@ options IPDIVERT</programlisting> <note> <para>To build a file which contains all available options, - run the following command as <username>root</username>:</para> - <screen>&prompt.root; <userinput>cd /usr/src/sys/<replaceable>i386</replaceable>/conf && make LINT</userinput></screen> + run the following command as <systemitem class="username">root</systemitem>:</para> + <screen>&prompt.root; <userinput>cd /usr/src/sys/i386/conf && make LINT</userinput></screen> </note> @@ -376,7 +363,7 @@ options IPDIVERT</programlisting> <para>This is the identification of the kernel. Change this to the new kernel name, such as - <literal><replaceable>MYKERNEL</replaceable></literal>. + <literal>MYKERNEL</literal>. The value in the <literal>ident</literal> string will print when the kernel boots.</para> @@ -465,8 +452,7 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENT</progra <para>The &ms-dos; file system. Unless the system needs to mount a DOS formatted hard drive partition at boot time, comment this out. It will be automatically loaded the first time a DOS - partition is mounted. The <filename - role="package">emulators/mtools</filename> package allows + partition is mounted. The <package>emulators/mtools</package> package allows access to DOS floppies without having to mount and unmount them and does not require <literal>MSDOSFS</literal>.</para> @@ -481,8 +467,7 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENT</progra <programlisting>options PROCFS # Process filesystem (requires PSEUDOFS)</programlisting> <para>The process file system. This is a <quote>pretend</quote> - file system mounted on <filename - class="directory">/proc</filename> which allows some programs + file system mounted on <filename>/proc</filename> which allows some programs to provide more information on what processes are running. Use of <literal>PROCFS</literal> is not required under most circumstances, as most debugging and monitoring tools have been @@ -496,9 +481,8 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENT</progra <programlisting>options GEOM_PART_GPT # GUID Partition Tables.</programlisting> - <para>Adds support for <ulink - url="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID - Partition Tables</ulink> (<acronym>GPT</acronym>). GPT + <para>Adds support for <link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table">GUID + Partition Tables</link> (<acronym>GPT</acronym>). GPT provides the ability to have a large number of partitions per disk, 128 in the standard configuration.</para> @@ -578,8 +562,7 @@ options NFS_ROOT # NFS usable as /, requires NFSCLIENT</progra <programlisting>options KBD_INSTALL_CDEV # install a CDEV entry in /dev</programlisting> <para>This option is required to allow the creation of keyboard - device nodes in <filename - class="directory">/dev</filename>.</para> + device nodes in <filename>/dev</filename>.</para> <indexterm> <primary>kernel options</primary> @@ -633,7 +616,7 @@ device ata</programlisting> <para>This is needed along with <literal>device ata</literal> for ATA RAID drives.</para> - <programlisting><anchor id="kernelconfig-atapi"/> + <programlisting><anchor xml:id="kernelconfig-atapi"/> device atapicd # ATAPI CDROM drives</programlisting> <para>This is needed along with <literal>device ata</literal> @@ -819,12 +802,12 @@ device cardbus # CardBus (32-bit) bus</programlisting> device sio # 8250, 16[45]50 based serial ports</programlisting> <para>These are the serial ports referred to as - <devicename>COM</devicename> ports in &windows;.</para> + <filename>COM</filename> ports in &windows;.</para> <note> <para>If the system has an internal modem on - <devicename>COM4</devicename> and a serial port at - <devicename>COM2</devicename>, change the IRQ of the modem to + <filename>COM4</filename> and a serial port at + <filename>COM2</filename>, change the IRQ of the modem to 2. For a multiport serial card, refer to &man.sio.4; for more information on the proper values to add to <filename>/boot/device.hints</filename>. Some video cards, @@ -832,12 +815,12 @@ device sio # 8250, 16[45]50 based serial ports</programli form of <literal>0x*2e8</literal>. Since many cheap serial cards do not fully decode the 16-bit I/O address space, they clash with these cards, making the - <devicename>COM4</devicename> port practically + <filename>COM4</filename> port practically unavailable.</para> <para>Each serial port is required to have a unique IRQ and the - default IRQs for <devicename>COM3</devicename> and - <devicename>COM4</devicename> cannot be used. The exception + default IRQs for <filename>COM3</filename> and + <filename>COM4</filename> cannot be used. The exception is multiport cards where shared interrupts are supported.</para> </note> @@ -943,7 +926,7 @@ device xe # Xircom pccard Ethernet #device le</programlisting> <para>ISA Ethernet drivers. See - <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename> + <filename>/usr/src/sys/i386/conf/NOTES</filename> for details of which cards are supported by which driver.</para> <programlisting># Wireless NIC cards @@ -1003,11 +986,10 @@ device loop # Network loopback</programlisting> <programlisting>device tun # Packet tunnel.</programlisting> - <para>This is used by the userland PPP software. See the <link - linkend="userppp">PPP</link> section of the Handbook for more + <para>This is used by the userland PPP software. See the <link linkend="userppp">PPP</link> section of the Handbook for more information.</para> - <programlisting><anchor id="kernelconfig-ptys"/> + <programlisting><anchor xml:id="kernelconfig-ptys"/> device pty # Pseudo-ttys (telnet etc)</programlisting> <para>This is a <quote>pseudo-terminal</quote> or simulated @@ -1083,7 +1065,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl <para>For more information and additional devices supported by &os;, see - <filename>/usr/src/sys/<replaceable>i386</replaceable>/conf/NOTES</filename>.</para> + <filename>/usr/src/sys/i386/conf/NOTES</filename>.</para> <sect2> <title>Large Memory Configurations @@ -1173,7 +1155,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl </sect2> </sect1> - <sect1 id="kernelconfig-building"> + <sect1 xml:id="kernelconfig-building"> <title>Building and Installing a Custom Kernel</title> <para>After saving the edits, compile the source code for the @@ -1182,7 +1164,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl <note> <para>After <link linkend="svn">syncing the source tree</link> with the latest sources, <emphasis>always</emphasis> read - <filename class="directory">/usr/src/UPDATING</filename> + <filename>/usr/src/UPDATING</filename> before performing any update steps. This file describes any important issues or areas requiring special attention within the updated source code. @@ -1212,8 +1194,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl </note> <step> - <para><command>cd</command> to <filename - class="directory">/usr/src</filename>:</para> + <para><command>cd</command> to <filename>/usr/src</filename>:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput></screen> </step> @@ -1222,13 +1203,13 @@ device fwe # Ethernet over FireWire (non-standard!)</programl <para>Compile the new kernel by specifying the name of the custom kernel configuration file:</para> - <screen>&prompt.root; <userinput>make buildkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make buildkernel KERNCONF=MYKERNEL</userinput></screen> </step> <step> <para>Install the new kernel:</para> - <screen>&prompt.root; <userinput>make installkernel KERNCONF=<replaceable>MYKERNEL</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>make installkernel KERNCONF=MYKERNEL</userinput></screen> </step> </procedure> @@ -1252,34 +1233,28 @@ device fwe # Ethernet over FireWire (non-standard!)</programl </tip> <indexterm> - <primary><filename - class="directory">/boot/kernel.old</filename></primary> + <primary><filename>/boot/kernel.old</filename></primary> </indexterm> - <para>The new kernel will be copied to <filename - class="directory">/boot/kernel</filename> as + <para>The new kernel will be copied to <filename>/boot/kernel</filename> as <filename>/boot/kernel/kernel</filename> and the old kernel will be moved to <filename>/boot/kernel.old/kernel</filename>. Now, shutdown the system and reboot into the new kernel. - If something goes wrong, refer to the <link - linkend="kernelconfig-trouble">troubleshooting</link> + If something goes wrong, refer to the <link linkend="kernelconfig-trouble">troubleshooting</link> instructions and the section which explains how to - recover when the new kernel <link - linkend="kernelconfig-noboot">does not boot</link>.</para> + recover when the new kernel <link linkend="kernelconfig-noboot">does not boot</link>.</para> <note> <para>Other files relating to the boot process, such as the boot - &man.loader.8; and configuration, are stored in <filename - class="directory">/boot</filename>. Third party or - custom modules can be placed in <filename - class="directory">/boot/kernel</filename>, although users + &man.loader.8; and configuration, are stored in <filename>/boot</filename>. Third party or + custom modules can be placed in <filename>/boot/kernel</filename>, although users should be aware that keeping modules in sync with the compiled kernel is very important. Modules not intended to run with the compiled kernel may result in instability.</para> </note> </sect1> - <sect1 id="kernelconfig-trouble"> + <sect1 xml:id="kernelconfig-trouble"> <title>If Something Goes Wrong</title> <para>There are four categories of trouble that can occur when @@ -1318,8 +1293,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl </varlistentry> <varlistentry> - <term>The kernel does not boot:<anchor - id="kernelconfig-noboot"/></term> + <term>The kernel does not boot:<anchor xml:id="kernelconfig-noboot"/></term> <listitem> <para>If the new kernel does not boot, or fails to recognize @@ -1330,7 +1304,7 @@ device fwe # Ethernet over FireWire (non-standard!)</programl appears by selecting the <quote>Escape to a loader prompt</quote> option. At the prompt, type <command>boot - <replaceable>kernel.old</replaceable></command>, or + kernel.old</command>, or the name of any other kernel that will boot properly. When reconfiguring a kernel, it is always a good idea to keep a kernel that is known to work on hand.</para> @@ -1351,14 +1325,13 @@ device fwe # Ethernet over FireWire (non-standard!)</programl a new kernel, <filename>kernel.old</filename> is overwritten with the last installed kernel which may be non-functional. As soon as possible, move the - working kernel to the proper <filename - class="directory">/boot/kernel</filename> + working kernel to the proper <filename>/boot/kernel</filename> location or commands such as &man.ps.1; may not work properly. To do this, simply rename the directory containing the good kernel:</para> - <screen>&prompt.root; <userinput>mv /boot/kernel <replaceable>/boot/kernel.bad</replaceable></userinput> -&prompt.root; <userinput>mv /boot/<replaceable>kernel.good</replaceable> /boot/kernel</userinput></screen> + <screen>&prompt.root; <userinput>mv /boot/kernel /boot/kernel.bad</userinput> +&prompt.root; <userinput>mv /boot/kernel.good /boot/kernel</userinput></screen> </note> </listitem> diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml index 51c669150b..5c7b6ba78e 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml @@ -4,31 +4,22 @@ $FreeBSD$ --> - -<chapter id="l10n"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="l10n"> + <info><title>Localization - + <acronym>i18n</acronym>/<acronym>L10n</acronym> Usage and + Setup</title> <authorgroup> - <author> - <firstname>Andrey</firstname> - <surname>Chernov</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Andrey</firstname><surname>Chernov</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Michael C.</firstname> - <surname>Wu</surname> - <contrib>Rewritten by </contrib> - </author> + <author><personname><firstname>Michael C.</firstname><surname>Wu</surname></personname><contrib>Rewritten by </contrib></author> <!-- 30 Nv 2000 --> </authorgroup> - </chapterinfo> + </info> - <title>Localization - - <acronym>i18n</acronym>/<acronym>L10n</acronym> Usage and - Setup</title> + - <sect1 id="l10n-synopsis"> + <sect1 xml:id="l10n-synopsis"> <title>Synopsis</title> <para>&os; is a distributed project with users and contributors @@ -77,7 +68,7 @@ </itemizedlist> </sect1> - <sect1 id="l10n-basics"> + <sect1 xml:id="l10n-basics"> <title>The Basics</title> <sect2> @@ -126,7 +117,7 @@ </sect2> </sect1> - <sect1 id="using-localization"> + <sect1 xml:id="using-localization"> <title>Using Localization</title> <indexterm><primary>locale</primary></indexterm> @@ -198,8 +189,8 @@ required to compile an application with wide or multibyte character support, or configure it correctly. To provide application support for wide or multibyte characters, the - <ulink url="&url.base;/ports/index.html">&os; Ports - Collection</ulink> contains programs for several languages. + <link xlink:href="&url.base;/ports/index.html">&os; Ports + Collection</link> contains programs for several languages. Refer to the <acronym>i18n</acronym> documentation in the respective &os; port.</para> @@ -224,9 +215,8 @@ </itemizedlist> <para>The active list of character sets can be found at the - <ulink - url="http://www.iana.org/assignments/character-sets">IANA - Registry</ulink>.</para> + <link xlink:href="http://www.iana.org/assignments/character-sets">IANA + Registry</link>.</para> <note> <para>&os; uses Xorg-compatible locale encodings @@ -239,7 +229,7 @@ the language needed.</para> </sect2> - <sect2 id="setting-locale"> + <sect2 xml:id="setting-locale"> <title>Setting Locale</title> <para>Usually it is sufficient to export the value of the @@ -290,7 +280,7 @@ system's shell <link linkend="startup-file">startup file</link>.</para> - <sect4 id="login-class"> + <sect4 xml:id="login-class"> <title>Login Classes Method</title> <para>This method allows environment variables needed for @@ -302,7 +292,7 @@ <link linkend="adm-setup">Administrator Level Setup</link> requires superuser privileges.</para> - <sect5 id="usr-setup"> + <sect5 xml:id="usr-setup"> <title>User Level Setup</title> <para>This provides a minimal example of a @@ -342,7 +332,7 @@ me:\ details.</para> </sect5> - <sect5 id="adm-setup"> + <sect5 xml:id="adm-setup"> <title>Administrator Level Setup</title> <para>Verify that the user's login class in @@ -393,7 +383,7 @@ me:\ <listitem> <para>If all new users use the same language, set <literal>defaultclass = - <replaceable>language</replaceable></literal> in + language</literal> in <filename>/etc/adduser.conf</filename>.</para> </listitem> @@ -413,7 +403,7 @@ me:\ than the one set in <filename>/etc/adduser.conf</filename>:</para> - <screen>&prompt.root; <userinput>adduser -class <replaceable>language</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>adduser -class language</userinput></screen> </listitem> </itemizedlist> @@ -425,17 +415,16 @@ me:\ <para>If &man.pw.8; is used to add new users, call it in this form:</para> - <screen>&prompt.root; <userinput>pw useradd <replaceable>user_name</replaceable> -L <replaceable>language</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw useradd user_name -L language</userinput></screen> </sect5> </sect4> - <sect4 id="startup-file"> + <sect4 xml:id="startup-file"> <title>Shell Startup File Method</title> <note> <para>This method is not recommended because it requires - a different setup for each shell. Use the <link - linkend="login-class">Login Class Method</link> + a different setup for each shell. Use the <link linkend="login-class">Login Class Method</link> instead.</para> </note> @@ -473,7 +462,7 @@ me:\ </sect3> </sect2> - <sect2 id="setting-console"> + <sect2 xml:id="setting-console"> <title>Console Setup</title> <para>For all single C chars character sets, set the correct @@ -485,8 +474,7 @@ font8x14=<replaceable>font_name</replaceable> font8x8=<replaceable>font_name</replaceable></programlisting> <para>The <replaceable>font_name</replaceable> is taken from - <filename - class="directory">/usr/share/syscons/fonts</filename>, + <filename>/usr/share/syscons/fonts</filename>, without the <filename>.fnt</filename> suffix.</para> <indexterm> @@ -506,8 +494,7 @@ keymap=<replaceable>keymap_name</replaceable> keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> <para>The <replaceable>screenmap_name</replaceable> is taken - from <filename - class="directory">/usr/share/syscons/scrnmaps</filename>, + from <filename>/usr/share/syscons/scrnmaps</filename>, without the <filename>.scm</filename> suffix. A screenmap with a corresponding mapped font is usually needed as a workaround for expanding bit 8 to bit 9 on a VGA adapter's @@ -531,8 +518,7 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> <programlisting>mousechar_start=3</programlisting> <para>The <replaceable>keymap_name</replaceable> in the above - example is taken from <filename - class="directory">/usr/share/syscons/keymaps</filename>, + example is taken from <filename>/usr/share/syscons/keymaps</filename>, without the <filename>.kbd</filename> suffix. When uncertain as to which keymap to use, &man.kbdmap.1; can be used to test keymaps without rebooting.</para> @@ -595,8 +581,7 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> </informaltable> <para>For languages with wide or multibyte characters, use the - correct &os; port in <filename - class="directory">/usr/ports/<replaceable>language</replaceable></filename>. + correct &os; port in <filename>/usr/ports/language</filename>. Some applications appear as serial terminals to the system. Reserve enough terminals in <filename>/etc/ttys</filename> for both <application>Xorg</application> and the pseudo-serial @@ -615,22 +600,18 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> <tbody> <row> <entry>Traditional Chinese (BIG-5)</entry> - <entry><filename - role="package">chinese/big5con</filename></entry> + <entry><package>chinese/big5con</package></entry> </row> <row> <entry>Japanese</entry> - <entry><filename - role="package">japanese/kon2-16dot</filename> or - <filename - role="package">japanese/mule-freewnn</filename></entry> + <entry><package>japanese/kon2-16dot</package> or + <package>japanese/mule-freewnn</package></entry> </row> <row> <entry>Korean</entry> - <entry><filename - role="package">korean/han</filename></entry> + <entry><package>korean/han</package></entry> </row> </tbody> </tgroup> @@ -656,7 +637,7 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> <indexterm><primary>Xorg True Type font server</primary></indexterm> <para>After installing - <filename role="package">x11-servers/xorg-server</filename>, + <package>x11-servers/xorg-server</package>, install the language's &truetype; fonts. Setting the correct locale should allow users to view their selected language in graphical application menus.</para> @@ -711,7 +692,7 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> </sect2> </sect1> - <sect1 id="l10n-compiling"> + <sect1 xml:id="l10n-compiling"> <title>Compiling <acronym>i18n</acronym> Programs</title> <para>Many applications in the &os; Ports Collection have been @@ -732,20 +713,16 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> <application>configure</application> in the source.</para> </sect1> - <sect1 id="lang-setup"> + <sect1 xml:id="lang-setup"> <title>Localizing &os; to Specific Languages</title> - <sect2 id="ru-localize"> - <sect2info> + <sect2 xml:id="ru-localize"> + <info><title>Russian Language (KOI8-R Encoding)</title> <authorgroup> - <author> - <firstname>Andrey</firstname> - <surname>Chernov</surname> - <contrib>Originally contributed by </contrib> - </author> + <author><personname><firstname>Andrey</firstname><surname>Chernov</surname></personname><contrib>Originally contributed by </contrib></author> </authorgroup> - </sect2info> - <title>Russian Language (KOI8-R Encoding)</title> + </info> + <indexterm> <primary>localization</primary> @@ -753,8 +730,8 @@ keychange="<replaceable>fkey_number sequence</replaceable>"</programlisting> </indexterm> <para>For more information about KOI8-R encoding, refer to - <ulink url="http://koi8.pp.ru/">KOI8-R References - (Russian Net Character Set)</ulink>.</para> + <link xlink:href="http://koi8.pp.ru/">KOI8-R References + (Russian Net Character Set)</link>.</para> <sect3> <title>Locale Setup</title> @@ -835,8 +812,7 @@ mousechar_start=3</programlisting> <listitem> <para>When using <application>&xorg;</application>, - install the <filename - role="package">x11-fonts/xorg-fonts-cyrillic</filename> + install the <package>x11-fonts/xorg-fonts-cyrillic</package> package.</para> <para>Check the <literal>"Files"</literal> section in @@ -865,13 +841,11 @@ Option "XkbOptions" "grp:toggle"</programlisting> <para>For <literal>grp:toggle</literal> use <keycap>Right Alt</keycap>, for - <literal>grp:ctrl_shift_toggle</literal> use <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>. + <literal>grp:ctrl_shift_toggle</literal> use <keycombo action="simul"><keycap>Ctrl</keycap><keycap>Shift</keycap></keycombo>. For <literal>grp:caps_toggle</literal> use <keycap>CapsLock</keycap>. The old <keycap>CapsLock</keycap> function is still available - in LAT mode only using <keycombo - action="simul"><keycap>Shift</keycap><keycap>CapsLock</keycap></keycombo>. + in LAT mode only using <keycombo action="simul"><keycap>Shift</keycap><keycap>CapsLock</keycap></keycombo>. <literal>grp:caps_toggle</literal> does not work in <application>&xorg;</application> for some unknown reason.</para> @@ -895,8 +869,8 @@ Option "XkbOptions" "grp:toggle"</programlisting> <function>XtSetLanguageProc (NULL, NULL, NULL);</function> function early in the program.</para> - <para>See <ulink url="http://koi8.pp.ru/xwin.html"> - KOI8-R for X Window</ulink> for more instructions on + <para>See <link xlink:href="http://koi8.pp.ru/xwin.html"> + KOI8-R for X Window</link> for more instructions on localizing <application>Xorg</application> applications.</para> </note> @@ -911,8 +885,7 @@ Option "XkbOptions" "grp:toggle"</programlisting> <secondary>Traditional Chinese</secondary> </indexterm> <para>The &os;-Taiwan Project has a Chinese HOWTO for - &os; at <ulink - url="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/"></ulink> + &os; at <uri xlink:href="http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/">http://netlab.cse.yzu.edu.tw/~statue/freebsd/zh-tut/</uri> using many Chinese ports. The current editor for the <literal>&os; Chinese HOWTO</literal> is Shen Chuan-Hsing <email>statue@freebsd.sinica.edu.tw</email>.</para> @@ -929,8 +902,7 @@ Option "XkbOptions" "grp:toggle"</programlisting> <para>Slaven Rezic <email>eserte@cs.tu-berlin.de</email> wrote a tutorial on using umlauts on &os;. The tutorial - is written in German and is available at <ulink - url="http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html"></ulink>.</para> + is written in German and is available at <uri xlink:href="http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html">http://user.cs.tu-berlin.de/~eserte/FreeBSD/doc/umlaute/umlaute.html</uri>.</para> </sect2> <sect2> @@ -942,8 +914,7 @@ Option "XkbOptions" "grp:toggle"</programlisting> </indexterm> <para>Nikos Kokkalis <email>nickkokkalis@gmail.com</email> has written a complete article on Greek support in &os;. It is - available <ulink - url="&url.doc.base;/el_GR.ISO8859-7/articles/greek-language-support/index.html">here</ulink>, + available <link xlink:href="&url.doc.base;/el_GR.ISO8859-7/articles/greek-language-support/index.html">here</link>, in Greek only, as part of the official &os; Greek documentation.</para> </sect2> @@ -960,9 +931,9 @@ Option "XkbOptions" "grp:toggle"</programlisting> <secondary>Korean</secondary> </indexterm> <para>For Japanese, refer to - <ulink url="http://www.jp.FreeBSD.org/"></ulink>, + <uri xlink:href="http://www.jp.FreeBSD.org/">http://www.jp.FreeBSD.org/</uri>, and for Korean, refer to - <ulink url="http://www.kr.FreeBSD.org/"></ulink>.</para> + <uri xlink:href="http://www.kr.FreeBSD.org/">http://www.kr.FreeBSD.org/</uri>.</para> </sect2> <sect2> @@ -971,8 +942,8 @@ Option "XkbOptions" "grp:toggle"</programlisting> <para>Some &os; contributors have translated parts of the &os; documentation to other languages. They are available through links on the - <ulink url="&url.base;/index.html">main site</ulink> or in - <filename class="directory">/usr/share/doc</filename>.</para> + <link xlink:href="&url.base;/index.html">main site</link> or in + <filename>/usr/share/doc</filename>.</para> </sect2> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml index e339f273d9..67df6a9211 100644 --- a/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/linuxemu/chapter.xml @@ -4,33 +4,21 @@ $FreeBSD$ --> - -<chapter id="linuxemu"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="linuxemu"> + <info><title>&linux; Binary Compatibility</title> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Restructured and parts updated by </contrib> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured and parts updated by </contrib></author> <!-- 22 Mar 2000 --> </authorgroup> <authorgroup> - <author> - <firstname>Brian N.</firstname> - <surname>Handy</surname> - <contrib>Originally contributed by </contrib> - </author> - <author> - <firstname>Rich</firstname> - <surname>Murphey</surname> - </author> + <author><personname><firstname>Brian N.</firstname><surname>Handy</surname></personname><contrib>Originally contributed by </contrib></author> + <author><personname><firstname>Rich</firstname><surname>Murphey</surname></personname></author> </authorgroup> - </chapterinfo> + </info> - <title>&linux; Binary Compatibility</title> + - <sect1 id="linuxemu-synopsis"> + <sect1 xml:id="linuxemu-synopsis"> <title>Synopsis</title> <indexterm><primary>Linux binary @@ -88,7 +76,7 @@ </sect1> - <sect1 id="linuxemu-lbc-install"> + <sect1 xml:id="linuxemu-lbc-install"> <title>Installation</title> <indexterm><primary>Ports Collection</primary></indexterm> @@ -108,7 +96,7 @@ <para>Once the port is installed, enable &linux; binary compatibility by loading the <literal>linux</literal> module. Type the following as - <username>root</username>:</para> + <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>kldload linux</userinput></screen> @@ -134,17 +122,15 @@ Id Refs Address Size Name <para>Users who prefer to statically link &linux; binary compatibility into the kernel should add <literal>options COMPAT_LINUX</literal> to the custom kernel configuration - file. Compile and install the new kernel as described in <xref - linkend="kernelconfig"/>.</para> + file. Compile and install the new kernel as described in <xref linkend="kernelconfig"/>.</para> - <sect2 id="linuxemu-libs-manually"> + <sect2 xml:id="linuxemu-libs-manually"> <title>Installing Libraries Manually</title> <para>While using the Ports Collection is recommended, &linux; libraries can be installed manually. The &linux; shared libraries required by a program and the runtime linker - should be copied to <filename - class="directory">/compat/linux</filename>. Any shared + should be copied to <filename>/compat/linux</filename>. Any shared libraries opened by &linux; programs run under &os; will look in this directory first. For example, if a &linux; program loads <filename>/lib/libc.so</filename>, &os; will @@ -152,8 +138,7 @@ Id Refs Address Size Name <filename>/compat/linux/lib/libc.so</filename>, and if that does not exist, it will then try <filename>/lib/libc.so</filename>. Shared libraries should - be installed to <filename - class="directory">/compat/linux/lib</filename> rather than + be installed to <filename>/compat/linux/lib</filename> rather than to the paths that the &linux; <command>ld.so</command> reports.</para> @@ -171,7 +156,7 @@ Id Refs Address Size Name <para>If the <literal>linux_base</literal> port is installed and an application still complains about missing shared - libraries, there are two methods <username>root</username> + libraries, there are two methods <systemitem class="username">root</systemitem> can use to determine which shared libraries the &linux; binaries need.</para> @@ -192,7 +177,7 @@ libc.so.4 (DLL Jump 4.5pl26) => /lib/libc.so.4.6.29</screen> <indexterm><primary>symbolic links</primary></indexterm> <para>Copy all the files in the last column into - <filename class="directory">/compat/linux</filename> on + <filename>/compat/linux</filename> on the &os; system, with the names in the first column as symbolic links pointing to them. This example will result in the following files on the &os; system:</para> @@ -285,9 +270,8 @@ Abort</screen> database is not supported.</para> <para>In order to install a &linux; RPM-based application, first - install the <filename - role="package">archivers/rpm2cpio</filename> package or - port. Once installed, <username>root</username> can use this + install the <package>archivers/rpm2cpio</package> package or + port. Once installed, <systemitem class="username">root</systemitem> can use this command to install a <filename>.rpm</filename> as follows:</para> @@ -326,8 +310,7 @@ multi on</programlisting> </sect2> </sect1> -<?ignore - While the installer works, the binaries do not. As of Oct 2013, Linux +<?ignore While the installer works, the binaries do not. As of Oct 2013, Linux emulation is 32-bit but the trial version of Mathematica is only available as 64-bit. This section should be revisited if Linux emulation gets 64-bit binary support. @@ -1139,7 +1122,7 @@ export PATH</programlisting> </sect1> ?> - <sect1 id="linuxemu-advanced"> + <sect1 xml:id="linuxemu-advanced"> <title>Advanced Topics</title> <para>This section describes how &linux; binary compatibility @@ -1213,18 +1196,16 @@ export PATH</programlisting> <para>&linux; mode dynamically <emphasis>reroots</emphasis> lookups. This is, in effect, equivalent to the <option>union</option> option to file system mounts. First, - an attempt is made to lookup the file in <filename - class="directory">/compat/linux/<replaceable>original-path</replaceable></filename>. + an attempt is made to lookup the file in <filename>/compat/linux/original-path</filename>. If that fails, the lookup is done in - <filename - class="directory">/<replaceable>original-path</replaceable></filename>. + <filename>/original-path</filename>. This makes sure that binaries that require other binaries can run. For example, the &linux; toolchain can all run under &linux; <acronym>ABI</acronym> support. It also means that the &linux; binaries can load and execute &os; binaries, if there are no corresponding &linux; binaries present, and that a &man.uname.1; command can be placed in the - <filename class="directory">/compat/linux</filename> directory + <filename>/compat/linux</filename> directory tree to ensure that the &linux; binaries can not tell they are not running on &linux;.</para> diff --git a/en_US.ISO8859-1/books/handbook/mac/chapter.xml b/en_US.ISO8859-1/books/handbook/mac/chapter.xml index 835959f2ab..52289f3590 100644 --- a/en_US.ISO8859-1/books/handbook/mac/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mac/chapter.xml @@ -3,21 +3,16 @@ The FreeBSD Documentation Project $FreeBSD$ --> - -<chapter id="mac"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="mac"> + <info><title>Mandatory Access Control</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Mandatory Access Control</title> + - <sect1 id="mac-synopsis"> + <sect1 xml:id="mac-synopsis"> <title>Synopsis</title> <indexterm><primary>MAC</primary></indexterm> @@ -27,8 +22,8 @@ </indexterm> <para>&os; 5.X introduced new security extensions from the - <ulink url="http://www.trustedbsd.org">TrustedBSD - Project</ulink> based on the &posix;.1e draft. Two of the + <link xlink:href="http://www.trustedbsd.org">TrustedBSD + Project</link> based on the &posix;.1e draft. Two of the most significant new security mechanisms are file system Access Control Lists (<acronym>ACL</acronym>s) and Mandatory Access Control (<acronym>MAC</acronym>) facilities. MAC allows new @@ -131,7 +126,7 @@ </sect2> </sect1> - <sect1 id="mac-inline-glossary"> + <sect1 xml:id="mac-inline-glossary"> <title>Key Terms in This Chapter</title> <para>Before reading this chapter, a few key terms must be @@ -251,7 +246,7 @@ </itemizedlist> </sect1> - <sect1 id="mac-initial"> + <sect1 xml:id="mac-initial"> <title>Explanation of MAC</title> <para>With all of these new terms in mind, consider how the @@ -326,7 +321,7 @@ </caution> </sect1> - <sect1 id="mac-understandlabel"> + <sect1 xml:id="mac-understandlabel"> <title>Understanding MAC Labels</title> <para>A <acronym>MAC</acronym> label is a security attribute @@ -375,12 +370,12 @@ <para>In most cases, the administrator will set up a single label to use throughout the file system. This is similar to <acronym>DAC</acronym> to some extent as - <username>root</username> is the one in control and who + <systemitem class="username">root</systemitem> is the one in control and who configures the policies so that users are placed in the appropriate categories/access levels. Alas, many policy modules - can restrict the <username>root</username> user as well. Basic + can restrict the <systemitem class="username">root</systemitem> user as well. Basic control over objects will then be released to the group, but - <username>root</username> may revoke or modify the settings + <systemitem class="username">root</systemitem> may revoke or modify the settings at any time. This is the hierarchical/clearance model covered by policies such as Biba and <acronym>MLS</acronym>.</para> @@ -693,7 +688,7 @@ test: biba/high</screen> </sect2> </sect1> - <sect1 id="mac-planning"> + <sect1 xml:id="mac-planning"> <title>Planning the Security Configuration</title> <para>Whenever a new technology is implemented, a planning phase @@ -742,7 +737,7 @@ test: biba/high</screen> choice.</para> </sect1> - <sect1 id="mac-modules"> + <sect1 xml:id="mac-modules"> <title>Module Configuration</title> <para>Beginning with &os; 8.0, the default &os; kernel @@ -768,7 +763,7 @@ test: biba/high</screen> option is called <option>multilabel</option>.</para> </sect1> - <sect1 id="mac-seeotheruids"> + <sect1 xml:id="mac-seeotheruids"> <title>The MAC See Other UIDs Policy</title> <indexterm> @@ -823,7 +818,7 @@ test: biba/high</screen> </itemizedlist> </sect1> - <sect1 id="mac-bsdextended"> + <sect1 xml:id="mac-bsdextended"> <title>The MAC BSD Extended Policy</title> <indexterm> @@ -872,7 +867,7 @@ test: biba/high</screen> <para>By default, no rules are defined and everything is completely accessible. To create a rule which will block all - access by users but leave <username>root</username> + access by users but leave <systemitem class="username">root</systemitem> unaffected, run the following command:</para> <screen>&prompt.root; <userinput>ugidfw add subject not uid root new object not uid root mode n</userinput></screen> @@ -880,21 +875,21 @@ test: biba/high</screen> <para>This is a very bad idea as it will block all users from issuing even the most simple commands, such as <command>ls</command>. The next example will block - <username>user1</username> any and all access, including + <systemitem class="username">user1</systemitem> any and all access, including directory listings, to - <username><replaceable>user2</replaceable></username>'s home + <systemitem class="username"><replaceable>user2</replaceable></systemitem>'s home directory:</para> - <screen>&prompt.root; <userinput>ugidfw set 2 subject uid <replaceable>user1</replaceable> object uid <replaceable>user2</replaceable> mode n</userinput> -&prompt.root; <userinput>ugidfw set 3 subject uid <replaceable>user1</replaceable> object gid <replaceable>user2</replaceable> mode n</userinput></screen> + <screen>&prompt.root; <userinput>ugidfw set 2 subject uid user1 object uid user2 mode n</userinput> +&prompt.root; <userinput>ugidfw set 3 subject uid user1 object gid user2 mode n</userinput></screen> - <para>Instead of <username>user1</username>, + <para>Instead of <systemitem class="username">user1</systemitem>, <option>not uid <replaceable>user2</replaceable></option> could be used. This enforces the same access restrictions for all users instead of just one user.</para> <note> - <para>The <username>root</username> user is unaffected by + <para>The <systemitem class="username">root</systemitem> user is unaffected by these changes.</para> </note> @@ -903,7 +898,7 @@ test: biba/high</screen> </sect2> </sect1> - <sect1 id="mac-ifoff"> + <sect1 xml:id="mac-ifoff"> <title>The MAC Interface Silencing Policy</title> <indexterm> @@ -949,12 +944,12 @@ test: biba/high</screen> monitoring in an environment where network traffic should not be permitted during the boot sequence. Another suggested use would be to write a script which uses - <filename role="package">security/aide</filename> to + <package>security/aide</package> to automatically block network traffic if it finds new or altered files in protected directories.</para> </sect1> - <sect1 id="mac-portacl"> + <sect1 xml:id="mac-portacl"> <title>The MAC Port Access Control List Policy</title> <indexterm> @@ -972,7 +967,7 @@ test: biba/high</screen> local <acronym>TCP</acronym> and <acronym>UDP</acronym> ports using a variety of <command>sysctl</command> variables. &man.mac.portacl.4; makes it possible to allow - non-<username>root</username> users to bind to specified + non-<systemitem class="username">root</systemitem> users to bind to specified privileged ports below 1024.</para> <para>Once loaded, this module enables the @@ -994,7 +989,7 @@ test: biba/high</screen> <listitem> <para><varname>security.mac.portacl.suser_exempt</varname>, when set to a non-zero value, exempts the - <username>root</username> user from this policy.</para> + <systemitem class="username">root</systemitem> user from this policy.</para> </listitem> <listitem> @@ -1025,7 +1020,7 @@ test: biba/high</screen> <para>By default, ports below 1024 can only be used by or bound to privileged processes, which run as - <username>root</username>. For &man.mac.portacl.4; to allow + <systemitem class="username">root</systemitem>. For &man.mac.portacl.4; to allow non-privileged processes to bind to ports below 1024, this restriction has to be disabled by setting the &man.sysctl.8; variables @@ -1043,7 +1038,7 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> <sect2> <title>Examples</title> - <para>Since the <username>root</username> user should not be + <para>Since the <systemitem class="username">root</systemitem> user should not be crippled by this policy, this example starts by setting the <varname>security.mac.portacl.suser_exempt</varname> to a non-zero value.</para> @@ -1051,9 +1046,9 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> <screen>&prompt.root; <userinput>sysctl security.mac.portacl.suser_exempt=1</userinput></screen> <para>Next, allow the user with <acronym>UID</acronym> 80 - to bind to port 80. This allows the <username>www</username> + to bind to port 80. This allows the <systemitem class="username">www</systemitem> user to run a web server without ever having - <username>root</username> privilege.</para> + <systemitem class="username">root</systemitem> privilege.</para> <screen>&prompt.root; <userinput>sysctl security.mac.portacl.rules=uid:80:tcp:80</userinput></screen> @@ -1068,7 +1063,7 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> </sect2> </sect1> - <sect1 id="mac-partition"> + <sect1 xml:id="mac-partition"> <title>The MAC Partition Policy</title> <indexterm> @@ -1132,7 +1127,7 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> <screen>&prompt.root; <userinput>ps -ZU trhodes</userinput></screen> <note> - <para>Users can see processes in <username>root</username>'s + <para>Users can see processes in <systemitem class="username">root</systemitem>'s label unless the &man.mac.seeotheruids.4; policy is loaded.</para> </note> @@ -1151,7 +1146,7 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> </sect2> </sect1> - <sect1 id="mac-mls"> + <sect1 xml:id="mac-mls"> <title>The MAC Multi-Level Security Module</title> <indexterm> @@ -1277,7 +1272,7 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> <screen>&prompt.root; <userinput>getfmac test</userinput></screen> <para>Another approach is to create a master policy file in - <filename class="directory">/etc/</filename> which specifies the + <filename>/etc/</filename> which specifies the <acronym>MLS</acronym> policy information and to feed that file to <command>setfmac</command>. This method will be explained after all policies are covered.</para> @@ -1310,7 +1305,7 @@ net.inet.ip.portrange.reservedhigh=0</userinput></screen> </sect2> </sect1> - <sect1 id="mac-biba"> + <sect1 xml:id="mac-biba"> <title>The MAC Biba Module</title> <indexterm> @@ -1465,7 +1460,7 @@ test: biba/low</screen> </sect2> </sect1> - <sect1 id="mac-lomac"> + <sect1 xml:id="mac-lomac"> <title>The MAC LOMAC Module</title> <indexterm> @@ -1516,7 +1511,7 @@ test: biba/low</screen> </sect2> </sect1> - <sect1 id="mac-implementing"> + <sect1 xml:id="mac-implementing"> <title>Nagios in a MAC Jail</title> <indexterm> @@ -1531,10 +1526,9 @@ test: biba/low</screen> <para>Before beginning this process, <option>multilabel</option> must be set on each file system as not doing so will result in - errors. This example assumes that <filename - role="package">net-mngt/nagios-plugins</filename>, - <filename role="package">net-mngt/nagios</filename>, and - <filename role="package">www/apache22</filename> are all + errors. This example assumes that <package>net-mngt/nagios-plugins</package>, + <package>net-mngt/nagios</package>, and + <package>www/apache22</package> are all installed, configured, and working correctly.</para> <sect2> @@ -1590,12 +1584,12 @@ mac_seeotheruids_load="YES"</programlisting> <sect2> <title>Configure Users</title> - <para>Set the <username>root</username> user to the default + <para>Set the <systemitem class="username">root</systemitem> user to the default class using:</para> <screen>&prompt.root; <userinput>pw usermod root -L default</userinput></screen> - <para>All user accounts that are not <username>root</username> + <para>All user accounts that are not <systemitem class="username">root</systemitem> or system users will now require a login class. The login class is required otherwise users will be refused access to common commands such as &man.vi.1;. The following @@ -1604,8 +1598,8 @@ mac_seeotheruids_load="YES"</programlisting> <screen>&prompt.root; <userinput>for x in `awk -F: '($3 >= 1001) && ($3 != 65534) { print $1 }' \</userinput> <userinput>/etc/passwd`; do pw usermod $x -L default; done;</userinput></screen> - <para>Drop the <username>nagios</username> and - <username>www</username> users into the insecure class:</para> + <para>Drop the <systemitem class="username">nagios</systemitem> and + <systemitem class="username">www</systemitem> users into the insecure class:</para> <screen>&prompt.root; <userinput>pw usermod nagios -L insecure</userinput></screen> @@ -1656,7 +1650,7 @@ mac_seeotheruids_load="YES"</programlisting> <para>This policy enforces security by setting restrictions on the flow of information. In this specific configuration, - users, including <username>root</username>, should never be + users, including <systemitem class="username">root</systemitem>, should never be allowed to access <application>Nagios</application>. Configuration files and processes that are a part of <application>Nagios</application> will be completely self @@ -1709,9 +1703,9 @@ default_labels socket ?biba</programlisting> <para>Ensure that the web server and <application>Nagios</application> will not be started on system initialization and reboot. Ensure the - <username>root</username> user cannot access any of the files + <systemitem class="username">root</systemitem> user cannot access any of the files in the <application>Nagios</application> configuration - directory. If <username>root</username> can issue an + directory. If <systemitem class="username">root</systemitem> can issue an &man.ls.1; command on <filename>/var/spool/nagios</filename>, something is wrong. Otherwise a <quote>permission denied</quote> error should be returned.</para> @@ -1731,7 +1725,7 @@ setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></s usual.</para> <note> - <para>The <username>root</username> user can still change the + <para>The <systemitem class="username">root</systemitem> user can still change the security enforcement and edit its configuration files. The following command will permit the degradation of the security policy to a lower grade for a newly spawned @@ -1749,7 +1743,7 @@ setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></s </sect2> </sect1> - <sect1 id="mac-userlocked"> + <sect1 xml:id="mac-userlocked"> <title>User Lock Down</title> <para>This example considers a relatively small storage system @@ -1786,7 +1780,7 @@ setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></s of other users are visible. Verify that running &man.ls.1; on another user's home directory fails.</para> - <para>Do not try to test with the <username>root</username> user + <para>Do not try to test with the <systemitem class="username">root</systemitem> user unless the specific <command>sysctl</command>s have been modified to block super user access.</para> @@ -1798,7 +1792,7 @@ setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></s </note> </sect1> - <sect1 id="mac-troubleshoot"> + <sect1 xml:id="mac-troubleshoot"> <title>Troubleshooting the MAC Framework</title> <indexterm> @@ -1876,8 +1870,7 @@ setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></s <step> <para>Double-check the label policies. Ensure that the policies are set correctly for the user, the Xorg - application, and the <filename - class="directory">/dev</filename> entries.</para> + application, and the <filename>/dev</filename> entries.</para> </step> <step> @@ -1893,30 +1886,30 @@ setpmac biba/10\(10-10\) /usr/local/etc/rc.d/nagios.sh forcestart</userinput></s .login_conf</errorname> shows up.</para> <para>When a user attempts to switch from the - <username>root</username> user to another user in the system, + <systemitem class="username">root</systemitem> user to another user in the system, the error message <errorname>_secure_path: unable to stat .login_conf</errorname> appears.</para> <para>This message is usually shown when the user has a higher label setting than that of the user they are attempting to - become. For instance, <username>joe</username> has a default + become. For instance, <systemitem class="username">joe</systemitem> has a default label of <option>biba/low</option>. The - <username>root</username> user, who has a label of + <systemitem class="username">root</systemitem> user, who has a label of <option>biba/high</option>, cannot view - <username>joe</username>'s home directory. This will happen - whether or not <username>root</username> has used - <command>su</command> to become <username>joe</username> as + <systemitem class="username">joe</systemitem>'s home directory. This will happen + whether or not <systemitem class="username">root</systemitem> has used + <command>su</command> to become <systemitem class="username">joe</systemitem> as the Biba integrity model will not permit - <username>root</username> to view objects set at a lower + <systemitem class="username">root</systemitem> to view objects set at a lower integrity level.</para> </listitem> <listitem> <para>The system no longer recognizes the - <username>root</username> user.</para> + <systemitem class="username">root</systemitem> user.</para> <para>In normal or even single user mode, the - <username>root</username> is not recognized, + <systemitem class="username">root</systemitem> is not recognized, <command>whoami</command> returns 0 (zero), and <command>su</command> returns <errorname>who are you?</errorname>.</para> diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.xml b/en_US.ISO8859-1/books/handbook/mail/chapter.xml index 6a5a690e83..c9447d185e 100644 --- a/en_US.ISO8859-1/books/handbook/mail/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mail/chapter.xml @@ -4,29 +4,19 @@ $FreeBSD$ --> - -<chapter id="mail"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="mail"> + <info><title>Electronic Mail</title> <authorgroup> - <author> - <firstname>Bill</firstname> - <surname>Lloyd</surname> - <contrib>Original work by </contrib> - </author> + <author><personname><firstname>Bill</firstname><surname>Lloyd</surname></personname><contrib>Original work by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Rewritten by </contrib> - <!-- 2 Dec 1999 --> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Rewritten by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Electronic Mail</title> + - <sect1 id="mail-synopsis"> + <sect1 xml:id="mail-synopsis"> <title>Synopsis</title> <indexterm><primary>email</primary></indexterm> @@ -108,8 +98,7 @@ <itemizedlist> <listitem> - <para>Properly set up a network connection (<xref - linkend="advanced-networking"/>).</para> + <para>Properly set up a network connection (<xref linkend="advanced-networking"/>).</para> </listitem> <listitem> @@ -124,7 +113,7 @@ </itemizedlist> </sect1> - <sect1 id="mail-using"> + <sect1 xml:id="mail-using"> <title>Using Electronic Mail</title> <indexterm><primary>POP</primary></indexterm> @@ -133,13 +122,11 @@ <para>There are five major parts involved in an email exchange: <link linkend="mail-mua">the Mail User Agent - <acronym>MUA></acronym></link>, <link linkend="mail-mta">the - Mail Transfer Agent<acronym>MTA</acronym></link>, <link - linkend="mail-dns"><acronym>DNS</acronym></link>, <link - linkend="mail-receive">a remote or local mailbox</link>, and + <acronym>MUA></acronym></link>, <link linkend="mail-mta">the + Mail Transfer Agent<acronym>MTA</acronym></link>, <link linkend="mail-dns"><acronym>DNS</acronym></link>, <link linkend="mail-receive">a remote or local mailbox</link>, and <link linkend="mail-host">the mail host</link>.</para> - <sect2 id="mail-mua"> + <sect2 xml:id="mail-mua"> <title>The Mail User Agent</title> <para>This includes command line programs such as @@ -150,14 +137,12 @@ as <application>balsa</application> or <application>xfmail</application>, and web mail programs which can be accessed from a web browser. User programs pass - the email transactions to the local <link - linkend="mail-host"><quote>mail host</quote></link>, either - by a <link - linkend="mail-mta"><acronym>MTA</acronym></link>, or by + the email transactions to the local <link linkend="mail-host"><quote>mail host</quote></link>, either + by a <link linkend="mail-mta"><acronym>MTA</acronym></link>, or by delivering it over <acronym>TCP</acronym>.</para> </sect2> - <sect2 id="mail-mta"> + <sect2 xml:id="mail-mta"> <title>The Mail Transfer Agent</title> <indexterm> @@ -201,8 +186,7 @@ responsible for the collection of mail using protocols such as <acronym>POP</acronym> or <acronym>IMAP</acronym>, nor does it allow connecting to local <filename>mbox</filename> or Maildir - mailboxes. An additional <link - linkend="mail-receive">daemon</link> may be required for + mailboxes. An additional <link linkend="mail-receive">daemon</link> may be required for these functions.</para> <warning> @@ -216,7 +200,7 @@ </warning> </sect2> - <sect2 id="mail-dns"> + <sect2 xml:id="mail-dns"> <title>Email and DNS</title> <para>The Domain Name System (<acronym>DNS</acronym>) and its @@ -251,7 +235,7 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen> </sect2> - <sect2 id="mail-receive"> + <sect2 xml:id="mail-receive"> <title>Receiving Mail</title> <indexterm> @@ -270,7 +254,7 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen> a <acronym>POP</acronym> or <acronym>IMAP</acronym> server does not need to be installed.</para> - <sect3 id="pop-and-imap"> + <sect3 xml:id="pop-and-imap"> <title>Accessing Remote Mailboxes Using <acronym>POP</acronym> and <acronym>IMAP</acronym></title> @@ -319,28 +303,23 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen> <itemizedlist> <listitem> - <para><filename - role="package">mail/qpopper</filename></para> + <para><package>mail/qpopper</package></para> </listitem> <listitem> - <para><filename - role="package">mail/teapop</filename></para> + <para><package>mail/teapop</package></para> </listitem> <listitem> - <para><filename - role="package">mail/imap-uw</filename></para> + <para><package>mail/imap-uw</package></para> </listitem> <listitem> - <para><filename - role="package">mail/courier-imap</filename></para> + <para><package>mail/courier-imap</package></para> </listitem> <listitem> - <para><filename - role="package">mail/dovecot2</filename></para> + <para><package>mail/dovecot2</package></para> </listitem> </itemizedlist> @@ -368,7 +347,7 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen> </warning> </sect3> - <sect3 id="local"> + <sect3 xml:id="local"> <title>Accessing Local Mailboxes</title> <para>Mailboxes may be accessed locally by directly using an @@ -379,7 +358,7 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen> </sect3> </sect2> - <sect2 id="mail-host"> + <sect2 xml:id="mail-host"> <title>The Mail Host</title> <indexterm><primary>mail host</primary></indexterm> @@ -389,17 +368,13 @@ FreeBSD.org mail is handled by 10 mx1.FreeBSD.org</screen> </sect2> </sect1> - <sect1 id="sendmail"> - <sect1info> + <sect1 xml:id="sendmail"> + <info><title><application>Sendmail</application> Configuration</title> <authorgroup> - <author> - <firstname>Christopher</firstname> - <surname>Shumway</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Christopher</firstname><surname>Shumway</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> - <title><application>Sendmail</application> Configuration</title> + </info> + <indexterm> <primary><application>Sendmail</application></primary> @@ -531,20 +506,17 @@ okay.cyberspammer.com OK routine. The message is sent to the remote host when a mail matches the left side of the table. The third entry rejects mail from a specific host on the Internet, - <hostid>another.source.of.spam</hostid>. The fourth entry - accepts mail connections from <hostid - role="fqdn">okay.cyberspammer.com</hostid>, which is - more specific than the <hostid - role="domainname">cyberspammer.com</hostid> line above. + <systemitem>another.source.of.spam</systemitem>. The fourth entry + accepts mail connections from <systemitem class="fqdomainname">okay.cyberspammer.com</systemitem>, which is + more specific than the <systemitem class="fqdomainname">cyberspammer.com</systemitem> line above. More specific matches override less exact matches. The last entry allows relaying of email from hosts with an IP address - that begins with <hostid>128.32</hostid>. These hosts can + that begins with <systemitem>128.32</systemitem>. These hosts can send mail through this mail server that is destined for other mail servers.</para> <para>Whenever this file is updated, run - <command>make</command> in <filename - class="directory">/etc/mail/</filename> to update the + <command>make</command> in <filename>/etc/mail/</filename> to update the database.</para> </sect2> @@ -567,15 +539,15 @@ procmail: "|/usr/local/bin/procmail"</programlisting> <para>The mailbox name on the left side of the colon is expanded to the target(s) on the right. The first entry expands the - mailbox <username>root</username> to the mailbox - <username>localuser</username>, which is then looked up again + mailbox <systemitem class="username">root</systemitem> to the mailbox + <systemitem class="username">localuser</systemitem>, which is then looked up again in the <filename>aliases</filename> database. If no match is found, the message is delivered to - <username>localuser</username>. The second entry shows a - mail list. Mail to the mailbox <username>ftp-bugs</username> + <systemitem class="username">localuser</systemitem>. The second entry shows a + mail list. Mail to the mailbox <systemitem class="username">ftp-bugs</systemitem> is expanded to the three local mailboxes - <username>joe</username>, <username>eric</username>, and - <username>paul</username>. A remote mailbox could be + <systemitem class="username">joe</systemitem>, <systemitem class="username">eric</systemitem>, and + <systemitem class="username">paul</systemitem>. A remote mailbox could be specified as <email>user@example.com</email>. The third entry shows how to write mail to a file, in this case <filename>/dev/null</filename>. The last entry demonstrates @@ -584,8 +556,7 @@ procmail: "|/usr/local/bin/procmail"</programlisting> pipe.</para> <para>Whenever this file is updated, run - <command>make</command> in <filename - class="directory">/etc/mail/</filename> to update the + <command>make</command> in <filename>/etc/mail/</filename> to update the database.</para> </sect2> <sect2> @@ -595,8 +566,8 @@ procmail: "|/usr/local/bin/procmail"</programlisting> as the local host name. Place any domains or hosts that <application>Sendmail</application> will receive mail for. For example, to configure a mail server to accept mail - for the domain <hostid role="domainname">example.com</hostid> - and the host <hostid role="fqdn">mail.example.com</hostid>, + for the domain <systemitem class="fqdomainname">example.com</systemitem> + and the host <systemitem class="fqdomainname">mail.example.com</systemitem>, add these entries to <filename>local-host-names</filename>:</para> @@ -648,41 +619,32 @@ postmaster@example.com postmaster@noc.example.net </example> <para>The above example contains a mapping for the domain - <hostid role="domainname">example.com</hostid>. This file + <systemitem class="fqdomainname">example.com</systemitem>. This file is processed in a first match order. The first item maps <email>root@example.com</email> to the local mailbox - <username>root</username>. The second entry maps + <systemitem class="username">root</systemitem>. The second entry maps <email>postmaster@example.com</email> to the mailbox - <username>postmaster</username> on the host <hostid - role="fqdn">noc.example.net</hostid>. Finally, if - nothing from <hostid role="domainname">example.com</hostid> + <systemitem class="username">postmaster</systemitem> on the host <systemitem class="fqdomainname">noc.example.net</systemitem>. Finally, if + nothing from <systemitem class="fqdomainname">example.com</systemitem> has matched so far, it will match the last mapping, which matches every other mail message addressed to someone at - <hostid role="domainname">example.com</hostid> to the local - mailbox <username>joe</username>.</para> + <systemitem class="fqdomainname">example.com</systemitem> to the local + mailbox <systemitem class="username">joe</systemitem>.</para> </sect2> </sect1> - <sect1 id="mail-changingmta"> - <sect1info> + <sect1 xml:id="mail-changingmta"> + <info><title>Changing the Mail Transfer Agent</title> <authorgroup> - <author> - <firstname>Andrew</firstname> - <surname>Boothman</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Andrew</firstname><surname>Boothman</surname></personname><contrib>Written by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Gregory</firstname> - <surname>Neil Shapiro</surname> - <contrib>Information taken from emails written - by</contrib> - </author> + <author><personname><firstname>Gregory</firstname><surname>Neil Shapiro</surname></personname><contrib>Information taken from emails written + by</contrib></author> </authorgroup> - </sect1info> - <title>Changing the Mail Transfer Agent</title> + </info> + <indexterm> <primary>email</primary> @@ -704,8 +666,7 @@ postmaster@example.com postmaster@noc.example.net <title>Install a New <acronym>MTA</acronym></title> <para>A wide choice of <acronym>MTA</acronym>s is available - from the <literal>mail</literal> category of the <link - linkend="ports">&os; Ports Collection</link>.</para> + from the <literal>mail</literal> category of the <link linkend="ports">&os; Ports Collection</link>.</para> <para>Once a new <acronym>MTA</acronym> is installed, configure the new software and decide if it really fulfills your needs @@ -716,7 +677,7 @@ postmaster@example.com postmaster@noc.example.net software.</para> </sect2> - <sect2 id="mail-disable-sendmail"> + <sect2 xml:id="mail-disable-sendmail"> <title>Disable <application>Sendmail</application></title> <warning> @@ -834,7 +795,7 @@ purgestat /usr/local/supermailer/bin/purgestat-compat</programlisting> </sect2> </sect1> - <sect1 id="mail-trouble"> + <sect1 xml:id="mail-trouble"> <title>Troubleshooting</title> <indexterm> @@ -851,14 +812,11 @@ purgestat /usr/local/supermailer/bin/purgestat-compat</programlisting> <answer> <para>The host may actually be in a different domain. - For example, in order for a host in <hostid - role="fqdn">foo.bar.edu</hostid> to reach a host - called <hostid>mumble</hostid> in the <hostid - role="domainname">bar.edu</hostid> domain, refer to + For example, in order for a host in <systemitem class="fqdomainname">foo.bar.edu</systemitem> to reach a host + called <systemitem>mumble</systemitem> in the <systemitem class="fqdomainname">bar.edu</systemitem> domain, refer to it by the Fully-Qualified Domain Name - <acronym>FQDN</acronym>, <hostid - role="fqdn">mumble.bar.edu</hostid>, instead of just - <hostid>mumble</hostid>.</para> + <acronym>FQDN</acronym>, <systemitem class="fqdomainname">mumble.bar.edu</systemitem>, instead of just + <systemitem>mumble</systemitem>.</para> <para>This is because the version of <application>BIND</application><indexterm> @@ -866,15 +824,14 @@ purgestat /usr/local/supermailer/bin/purgestat-compat</programlisting> &os; no longer provides default abbreviations for non-FQDNs other than the local domain. An unqualified host such as - <hostid>mumble</hostid> must either be found as - <hostid role="fqdn">mumble.foo.bar.edu</hostid>, + <systemitem>mumble</systemitem> must either be found as + <systemitem class="fqdomainname">mumble.foo.bar.edu</systemitem>, or it will be searched for in the root domain.</para> <para>In older versions of <application>BIND</application>, - the search continued across <hostid - role="domainname">mumble.bar.edu</hostid>, and - <hostid role="domainname">mumble.edu</hostid>. RFC + the search continued across <systemitem class="fqdomainname">mumble.bar.edu</systemitem>, and + <systemitem class="fqdomainname">mumble.edu</systemitem>. RFC 1535 details why this is considered bad practice or even a security hole.</para> @@ -900,9 +857,8 @@ purgestat /usr/local/supermailer/bin/purgestat-compat</programlisting> </question> <answer> - <para>This is answered in the <ulink - url="http://www.sendmail.org/faq/">Sendmail - FAQ</ulink> as follows. This FAQ is recommended reading + <para>This is answered in the <link xlink:href="http://www.sendmail.org/faq/">Sendmail + FAQ</link> as follows. This FAQ is recommended reading when <quote>tweaking</quote> the mail setup.</para> <programlisting>I'm getting these error messages: @@ -936,10 +892,8 @@ to /etc/mail/sendmail.cf.</programlisting> <para>One way to do this is to get a full-time Internet server to provide secondary <acronym>MX</acronym><indexterm> <primary>MX record</primary></indexterm> services for the - domain. In this example, the domain is <hostid - role="domainname">example.com</hostid> and the ISP has - configured <hostid - role="domainname">example.net</hostid> to provide + domain. In this example, the domain is <systemitem class="fqdomainname">example.com</systemitem> and the ISP has + configured <systemitem class="fqdomainname">example.net</systemitem> to provide secondary <acronym>MX</acronym> services to the domain:</para> @@ -950,19 +904,17 @@ to /etc/mail/sendmail.cf.</programlisting> recipient. For <application>Sendmail</application>, add <literal>Cw example.com</literal> in <filename>/etc/mail/sendmail.cf</filename> on - <hostid role="domainname">example.com</hostid>.</para> + <systemitem class="fqdomainname">example.com</systemitem>.</para> <para>When the sending <acronym>MTA</acronym> attempts to deliver mail, it will try to connect to the system, - <hostid role="domainname">example.com</hostid>, over the PPP + <systemitem class="fqdomainname">example.com</systemitem>, over the PPP link. This will time out if the destination is offline. The <acronym>MTA</acronym> will automatically deliver it to the secondary <acronym>MX</acronym> site at the Internet - Service Provider (<acronym>ISP</acronym>), <hostid - role="domainname">example.net</hostid>. The secondary + Service Provider (<acronym>ISP</acronym>), <systemitem class="fqdomainname">example.net</systemitem>. The secondary <acronym>MX</acronym> site will periodically try to connect - to the primary <acronym>MX</acronym> host, <hostid - role="domainname">example.com</hostid>.</para> + to the primary <acronym>MX</acronym> host, <systemitem class="fqdomainname">example.com</systemitem>.</para> <para>Use something like this as a login script:</para> @@ -974,8 +926,7 @@ to /etc/mail/sendmail.cf.</programlisting> <para>When creating a separate login script for users, instead use <command>sendmail -qRexample.com</command> in the script - above. This will force all mail in the queue for <hostid - role="domainname">example.com</hostid> to be processed + above. This will force all mail in the queue for <systemitem class="fqdomainname">example.com</systemitem> to be processed immediately.</para> <para>A further refinement of the situation can be seen from @@ -1061,13 +1012,13 @@ www.example.org</programlisting> </qandaset> </sect1> - <sect1 id="mail-advanced"> + <sect1 xml:id="mail-advanced"> <title>Advanced Topics</title> <para>This section covers more involved topics such as mail configuration and setting up mail for an entire domain.</para> - <sect2 id="mail-config"> + <sect2 xml:id="mail-config"> <title>Basic Configuration</title> <indexterm> @@ -1125,11 +1076,10 @@ example.FreeBSD.org &prompt.root; <userinput>host example.FreeBSD.org</userinput> example.FreeBSD.org has address 204.216.27.XX</screen> - <para>In this example, mail sent directly to <email - role="nolink">yourlogin@example.FreeBSD.org</email> + <para>In this example, mail sent directly to <email role="nolink">yourlogin@example.FreeBSD.org</email> should work without problems, assuming <application>Sendmail</application> is running correctly on - <hostid role="fqdn">example.FreeBSD.org</hostid>.</para> + <systemitem class="fqdomainname">example.FreeBSD.org</systemitem>.</para> <para>For this example:</para> @@ -1137,9 +1087,8 @@ example.FreeBSD.org has address 204.216.27.XX</screen> example.FreeBSD.org has address 204.216.27.XX example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org</screen> - <para>All mail sent to <hostid - role="fqdn">example.FreeBSD.org</hostid> will be - collected on <hostid>hub</hostid> under the same username + <para>All mail sent to <systemitem class="fqdomainname">example.FreeBSD.org</systemitem> will be + collected on <systemitem>hub</systemitem> under the same username instead of being sent directly to your host.</para> <para>The above information is handled by the @@ -1149,8 +1098,7 @@ example.FreeBSD.org mail is handled (pri=10) by hub.FreeBSD.org</screen> record exists, mail will be delivered directly to the host by way of its IP address.</para> - <para>The <acronym>MX</acronym> entry for <hostid - role="fqdn">freefall.FreeBSD.org</hostid> at one time looked + <para>The <acronym>MX</acronym> entry for <systemitem class="fqdomainname">freefall.FreeBSD.org</systemitem> at one time looked like this:</para> <programlisting>freefall MX 30 mail.crl.net @@ -1158,7 +1106,7 @@ freefall MX 40 agora.rdrop.com freefall MX 10 freefall.FreeBSD.org freefall MX 20 who.cdrom.com</programlisting> - <para><hostid>freefall</hostid> had many <acronym>MX</acronym> + <para><systemitem>freefall</systemitem> had many <acronym>MX</acronym> entries. The lowest <acronym>MX</acronym> number is the host that receives mail directly, if available. If it is not accessible for some reason, the next lower-numbered host will @@ -1170,7 +1118,7 @@ freefall MX 20 who.cdrom.com</programlisting> <acronym>ISP</acronym> can provide this service.</para> </sect2> - <sect2 id="mail-domain"> + <sect2 xml:id="mail-domain"> <title>Mail for a Domain</title> <para>When configuring a <acronym>MTA</acronym> for a network, @@ -1204,20 +1152,17 @@ freefall MX 20 who.cdrom.com</programlisting> provider.</para> <para>The following is an example of virtual email hosting. - Consider a customer with the domain <hostid - role="domainname">customer1.org</hostid>, where all the mail - for <hostid role="domainname">customer1.org</hostid> should be - sent to <hostid role="fqdn">mail.myhost.com</hostid>. The + Consider a customer with the domain <systemitem class="fqdomainname">customer1.org</systemitem>, where all the mail + for <systemitem class="fqdomainname">customer1.org</systemitem> should be + sent to <systemitem class="fqdomainname">mail.myhost.com</systemitem>. The <acronym>DNS</acronym> entry should look like this:</para> <programlisting>customer1.org MX 10 mail.myhost.com</programlisting> - <para>An <literal>A</literal>> record is - <emphasis>not</emphasis> needed for <hostid - role="domainname">customer1.org</hostid> in order to only + <para>An <literal>A</literal>> record is + <emphasis>not</emphasis> needed for <systemitem class="fqdomainname">customer1.org</systemitem> in order to only handle email for that domain. However, running - <command>ping</command> against <hostid - role="domainname">customer1.org</hostid> will not work + <command>ping</command> against <systemitem class="fqdomainname">customer1.org</systemitem> will not work unless an <literal>A</literal> record exists for it.</para> <para>Tell the <acronym>MTA</acronym> which domains and/or @@ -1245,18 +1190,14 @@ freefall MX 20 who.cdrom.com</programlisting> </sect2> </sect1> - <sect1 id="outgoing-only"> - <sect1info> + <sect1 xml:id="outgoing-only"> + <info><title>Setting Up to Send Only</title> <authorgroup> - <author> - <firstname>Bill</firstname> - <surname>Moran</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Bill</firstname><surname>Moran</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Setting Up to Send Only</title> + <para>There are many instances where one may only want to send mail through a relay. Some examples are:</para> @@ -1286,13 +1227,12 @@ freefall MX 20 who.cdrom.com</programlisting> may forbid one from running a <quote>mail server</quote>.</para> <para>The easiest way to fulfill those needs is to install the - <filename role="package">mail/ssmtp</filename> port:</para> + <package>mail/ssmtp</package> port:</para> <screen>&prompt.root; <userinput>cd /usr/ports/mail/ssmtp</userinput> &prompt.root; <userinput>make install replace clean</userinput></screen> - <para>Once installed, <filename - role="package">mail/ssmtp</filename> can be configured with + <para>Once installed, <package>mail/ssmtp</package> can be configured with <filename>/usr/local/etc/ssmtp/ssmtp.conf</filename>:</para> <programlisting>root=yourrealemail@example.com @@ -1300,9 +1240,9 @@ mailhub=mail.example.com rewriteDomain=example.com hostname=_HOSTNAME_</programlisting> - <para>Use the real email address for <username>root</username>. + <para>Use the real email address for <systemitem class="username">root</systemitem>. Enter the <acronym>ISP</acronym>'s outgoing mail relay in place - of <hostid role="fqdn">mail.example.com</hostid>. Some + of <systemitem class="fqdomainname">mail.example.com</systemitem>. Some <acronym>ISP</acronym>s call this the <quote>outgoing mail server</quote> or <quote>SMTP server</quote>).</para> @@ -1311,7 +1251,7 @@ hostname=_HOSTNAME_</programlisting> service. See <xref linkend="mail-disable-sendmail"/> for details.</para> - <para><filename role="package">mail/ssmtp</filename> has some + <para><package>mail/ssmtp</package> has some other options available. Refer to the examples in <filename>/usr/local/etc/ssmtp</filename> or the manual page of <application>ssmtp</application> for more information.</para> @@ -1323,7 +1263,7 @@ hostname=_HOSTNAME_</programlisting> to be hijacked for spamming.</para> </sect1> - <sect1 id="SMTP-dialup"> + <sect1 xml:id="SMTP-dialup"> <title>Using Mail with a Dialup Connection</title> <para>When using a static IP address, one should not need to @@ -1334,16 +1274,13 @@ hostname=_HOSTNAME_</programlisting> <para>When using a dynamically assigned IP address and a dialup PPP connection to the Internet, one usually has a mailbox on the <acronym>ISP</acronym>'s mail server. In this example, the - <acronym>ISP</acronym>'s domain is <hostid - role="domainname">example.net</hostid>, the user name is - <username>user</username>, the hostname is <hostid - role="fqdn">bsd.home</hostid>, and the <acronym>ISP</acronym> - has allowed <hostid - role="fqdn">relay.example.net</hostid> as a mail relay.</para> + <acronym>ISP</acronym>'s domain is <systemitem class="fqdomainname">example.net</systemitem>, the user name is + <systemitem class="username">user</systemitem>, the hostname is <systemitem class="fqdomainname">bsd.home</systemitem>, and the <acronym>ISP</acronym> + has allowed <systemitem class="fqdomainname">relay.example.net</systemitem> as a mail relay.</para> <para>In order to retrieve mail from the <acronym>ISP</acronym>'s mailbox, install a retrieval agent from the Ports Collection. - <filename role="package">mail/fetchmail</filename> is a good + <package>mail/fetchmail</package> is a good choice as it supports many different protocols. Usually, the <acronym>ISP</acronym> will provide <acronym>POP</acronym>. When using user <acronym>PPP</acronym>, email can be @@ -1364,25 +1301,22 @@ hostname=_HOSTNAME_</programlisting> <programlisting> !bg su user -c "sendmail -q"</programlisting> <para>In this example, there is an account for - <username>user</username> on <hostid - role="fqdn">bsd.home</hostid>. In the home directory of - <username>user</username> on <hostid - role="fqdn">bsd.home</hostid>, create a + <systemitem class="username">user</systemitem> on <systemitem class="fqdomainname">bsd.home</systemitem>. In the home directory of + <systemitem class="username">user</systemitem> on <systemitem class="fqdomainname">bsd.home</systemitem>, create a <filename>.fetchmailrc</filename> which contains this line:</para> <programlisting>poll example.net protocol pop3 fetchall pass MySecret</programlisting> <para>This file should not be readable by anyone except - <username>user</username> as it contains the password + <systemitem class="username">user</systemitem> as it contains the password <literal>MySecret</literal>.</para> <para>In order to send mail with the correct <literal>from:</literal> header, configure <application>Sendmail</application> to use - <email>user@example.net</email> rather than <email - role="nolink">user@bsd.home</email> and to send all mail - via <hostid role="fqdn">relay.example.net</hostid>, allowing + <email>user@example.net</email> rather than <email role="nolink">user@bsd.home</email> and to send all mail + via <systemitem class="fqdomainname">relay.example.net</systemitem>, allowing quicker mail transmission.</para> <para>The following <filename>.mc</filename> file should @@ -1412,18 +1346,14 @@ define(`confDELIVERY_MODE',`deferred')dnl</programlisting> <filename>sendmail.cf</filename>.</para> </sect1> - <sect1 id="SMTP-Auth"> - <sect1info> + <sect1 xml:id="SMTP-Auth"> + <info><title>SMTP Authentication</title> <authorgroup> - <author> - <firstname>James</firstname> - <surname>Gorham</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>James</firstname><surname>Gorham</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>SMTP Authentication</title> + <para>Configuring <acronym>SMTP</acronym> authentication on the <acronym>MTA</acronym> provides a number of benefits. @@ -1435,8 +1365,7 @@ define(`confDELIVERY_MODE',`deferred')dnl</programlisting> <procedure> <step> - <para>Install <filename - role="package">security/cyrus-sasl2</filename> + <para>Install <package>security/cyrus-sasl2</package> from the Ports Collection. This port supports a number of compile-time options. For the SMTP authentication method demonstrated in this example, make sure that @@ -1445,8 +1374,7 @@ define(`confDELIVERY_MODE',`deferred')dnl</programlisting> <step> - <para>After installing <filename - role="package">security/cyrus-sasl2</filename>, + <para>After installing <package>security/cyrus-sasl2</package>, edit <filename>/usr/local/lib/sasl2/Sendmail.conf</filename>, or create it if it does not exist, and add the following @@ -1456,8 +1384,7 @@ define(`confDELIVERY_MODE',`deferred')dnl</programlisting> </step> <step> - <para>Next, install <filename - role="package">security/cyrus-sasl2-saslauthd</filename> + <para>Next, install <package>security/cyrus-sasl2-saslauthd</package> and add the following line to <filename>/etc/rc.conf</filename>:</para> @@ -1486,10 +1413,8 @@ SENDMAIL_LDADD=-lsasl2</programlisting> <para>These lines provide <application>Sendmail</application> the proper configuration - options for linking to <filename - role="package">cyrus-sasl2</filename> at compile time. - Make sure that <filename - role="package">cyrus-sasl2</filename> has been installed + options for linking to <package>cyrus-sasl2</package> at compile time. + Make sure that <package>cyrus-sasl2</package> has been installed before recompiling <application>Sendmail</application>.</para> </step> @@ -1506,7 +1431,7 @@ SENDMAIL_LDADD=-lsasl2</programlisting> &prompt.root; <userinput>make cleandir && make obj && make && make install</userinput></screen> <para>This compile should not have any problems if - <filename class="directory">/usr/src</filename> has not + <filename>/usr/src</filename> has not changed extensively and the shared libraries it needs are available.</para> </step> @@ -1532,8 +1457,7 @@ define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlis </step> <step> - <para>Finally, run &man.make.1; while in <filename - class="directory">/etc/mail</filename>. That will run the + <para>Finally, run &man.make.1; while in <filename>/etc/mail</filename>. That will run the new <filename>.mc</filename> and create a <filename>.cf</filename> named either <filename>freebsd.cf</filename> or the name used for the @@ -1552,22 +1476,17 @@ define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlis to <literal>13</literal> and watch <filename>/var/log/maillog</filename> for any errors.</para> - <para>For more information, refer to <ulink - url="http://www.sendmail.org/~ca/email/auth.html"> - <acronym>SMTP</acronym> authentication</ulink>.</para> + <para>For more information, refer to <link xlink:href="http://www.sendmail.org/~ca/email/auth.html"> + <acronym>SMTP</acronym> authentication</link>.</para> </sect1> - <sect1 id="mail-agents"> - <sect1info> + <sect1 xml:id="mail-agents"> + <info><title>Mail User Agents</title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Silver</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Silver</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> - <title>Mail User Agents</title> + </info> + <indexterm> <primary>Mail User Agents</primary> @@ -1585,7 +1504,7 @@ define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlis as <application>mutt</application> or <application>alpine</application>.</para> - <sect2 id="mail-command"> + <sect2 xml:id="mail-command"> <title><command>mail</command></title> <para>&man.mail.1; is the default @@ -1607,8 +1526,7 @@ define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlis <screen>&prompt.user; <userinput>mail</userinput></screen> - <para>The contents of the user's mailbox in <filename - class="directory">/var/mail</filename> are automatically + <para>The contents of the user's mailbox in <filename>/var/mail</filename> are automatically read by <command>mail</command>. Should the mailbox be empty, the utility exits with a message indicating that no mail could be found. If mail exists, the application interface starts, @@ -1618,7 +1536,7 @@ define(`confAUTH_MECHANISMS', `GSSAPI DIGEST-MD5 CRAM-MD5 LOGIN')dnl</programlis <screen>Mail version 8.1 6/6/93. Type ? for help. "/var/mail/marcs": 3 messages 3 new ->N 1 root@localhost Mon Mar 8 14:05 14/510 "test" +>N 1 root@localhost Mon Mar 8 14:05 14/510 "test" N 2 root@localhost Mon Mar 8 14:05 14/509 "user account" N 3 root@localhost Mon Mar 8 14:05 14/509 "sample"</screen> @@ -1685,13 +1603,12 @@ EOT</screen> <para>&man.mail.1; was not designed to handle attachments and thus deals with them poorly. Newer <acronym>MUA</acronym>s handle attachments in a more intelligent way. Users who - prefer to use <command>mail</command> may find the <filename - role="package">converters/mpack</filename> port to be of + prefer to use <command>mail</command> may find the <package>converters/mpack</package> port to be of considerable use.</para> </note> </sect2> - <sect2 id="mutt-command"> + <sect2 xml:id="mutt-command"> <title><application>mutt</application></title> <para><application>mutt</application> is a powerful @@ -1720,21 +1637,18 @@ EOT</screen> </listitem> </itemizedlist> - <para>Refer to <ulink - url="http://www.mutt.org"></ulink> for more + <para>Refer to <uri xlink:href="http://www.mutt.org">http://www.mutt.org</uri> for more information on <application>mutt</application>.</para> <para><application>mutt</application> - may be installed using the <filename - role="package">mail/mutt</filename> port. After the + may be installed using the <package>mail/mutt</package> port. After the port has been installed, <application>mutt</application> can be started by issuing the following command:</para> <screen>&prompt.user; <userinput>mutt</userinput></screen> <para><application>mutt</application> will automatically read - and display the contents of the user mailbox in <filename - class="directory">/var/mail</filename>. If no mails are + and display the contents of the user mailbox in <filename>/var/mail</filename>. If no mails are found, <application>mutt</application> will wait for commands from the user. The example below shows <application>mutt</application> displaying a list of @@ -1771,7 +1685,7 @@ EOT</screen> <filename>.muttrc</filename> in their home directory and setting the <literal>editor</literal> variable or by setting the <envar>EDITOR</envar> environment variable. Refer to - <ulink url="http://www.mutt.org/"></ulink> for more + <uri xlink:href="http://www.mutt.org/">http://www.mutt.org/</uri> for more information about configuring <application>mutt</application>.</para> </note> @@ -1799,7 +1713,7 @@ EOT</screen> </sect2> - <sect2 id="alpine-command"> + <sect2 xml:id="alpine-command"> <title><application>alpine</application></title> <para><application>alpine</application> is aimed at a beginner @@ -1819,8 +1733,7 @@ EOT</screen> </warning> <para>The current version of <application>alpine</application> - may be installed using the <filename - role="package">mail/alpine</filename> port. Once the port + may be installed using the <package>mail/alpine</package> port. Once the port has installed, <application>alpine</application> can be started by issuing the following command:</para> @@ -1851,8 +1764,7 @@ EOT</screen> the task at hand are shown.</para> <para>The default directory opened by - <application>alpine</application> is <filename - class="directory">inbox</filename>. To view the message + <application>alpine</application> is <filename>inbox</filename>. To view the message index, press <keycap>I</keycap>, or select the <guimenuitem>MESSAGE INDEX</guimenuitem> option shown below:</para> @@ -1894,8 +1806,7 @@ EOT</screen> <application>pico</application> makes it easy to navigate the message and is easier for novice users to use than &man.vi.1; or &man.mail.1;. Once the reply is complete, the message can - be sent by pressing <keycombo - action="simul"><keycap>Ctrl</keycap><keycap>X</keycap> + be sent by pressing <keycombo action="simul"><keycap>Ctrl</keycap><keycap>X</keycap> </keycombo>. <application>alpine</application> will ask for confirmation before sending the message.</para> @@ -1907,24 +1818,19 @@ EOT</screen> <para><application>alpine</application> can be customized using the <guimenuitem>SETUP</guimenuitem> option from the main - menu. Consult <ulink - url="http://www.washington.edu/alpine/"></ulink> + menu. Consult <uri xlink:href="http://www.washington.edu/alpine/">http://www.washington.edu/alpine/</uri> for more information.</para> </sect2> </sect1> - <sect1 id="mail-fetchmail"> - <sect1info> + <sect1 xml:id="mail-fetchmail"> + <info><title>Using <application>fetchmail</application></title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Silver</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Silver</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> - <title>Using <application>fetchmail</application></title> + </info> + <indexterm> <primary>fetchmail</primary> @@ -1936,7 +1842,7 @@ EOT</screen> <acronym>IMAP</acronym> and <acronym>POP</acronym> servers and save it into local mailboxes where it can be accessed more easily. <application>fetchmail</application> can be installed - using the <filename role="package">mail/fetchmail</filename> + using the <package>mail/fetchmail</package> port, and offers various features, including:</para> <itemizedlist> @@ -1978,11 +1884,10 @@ EOT</screen> <para>The following <filename>.fetchmailrc</filename> serves as an example for downloading a single user mailbox using <acronym>POP</acronym>. It tells - <application>fetchmail</application> to connect to <hostid - role="fqdn">example.com</hostid> using a username of - <username>joesoap</username> and a password of + <application>fetchmail</application> to connect to <systemitem class="fqdomainname">example.com</systemitem> using a username of + <systemitem class="username">joesoap</systemitem> and a password of <literal>XXX</literal>. This example assumes that the user - <username>joesoap</username> exists on the local system.</para> + <systemitem class="username">joesoap</systemitem> exists on the local system.</para> <programlisting>poll example.com protocol pop3 username "joesoap" password "XXX"</programlisting> @@ -2007,21 +1912,16 @@ user "john", with password "XXXXX", is "myth" here;</programlisting> <screen>&prompt.user; <userinput>fetchmail -d 600</userinput></screen> <para>More information on <application>fetchmail</application> can - be found at <ulink - url="http://fetchmail.berlios.de/"></ulink>.</para> + be found at <uri xlink:href="http://fetchmail.berlios.de/">http://fetchmail.berlios.de/</uri>.</para> </sect1> - <sect1 id="mail-procmail"> - <sect1info> + <sect1 xml:id="mail-procmail"> + <info><title>Using <application>procmail</application></title> <authorgroup> - <author> - <firstname>Marc</firstname> - <surname>Silver</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Marc</firstname><surname>Silver</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> - <title>Using <application>procmail</application></title> + </info> + <indexterm> <primary>procmail</primary> @@ -2033,7 +1933,7 @@ user "john", with password "XXXXX", is "myth" here;</programlisting> mails to perform specific functions or to reroute mail to alternative mailboxes or email addresses. <application>procmail</application> can be installed using the - <filename role="package">mail/procmail</filename> port. Once + <package>mail/procmail</package> port. Once installed, it can be directly integrated into most <acronym>MTA</acronym>s. Consult the <acronym>MTA</acronym> documentation for more information. Alternatively, @@ -2053,16 +1953,14 @@ user "john", with password "XXXXX", is "myth" here;</programlisting> &man.procmailex.5;.</para> <para>To forward all mail from <email>user@example.com</email> to - an external address of <email - role="nolink">goodmail@example2.com</email>:</para> + an external address of <email role="nolink">goodmail@example2.com</email>:</para> <programlisting>:0 * ^From.*user@example.com ! goodmail@example2.com</programlisting> <para>To forward all mails shorter than 1000 bytes to an external - address of <email - role="nolink">goodmail@example2.com</email>:</para> + address of <email role="nolink">goodmail@example2.com</email>:</para> <programlisting>:0 * < 1000 @@ -2077,14 +1975,13 @@ user "john", with password "XXXXX", is "myth" here;</programlisting> alternate</programlisting> <para>To send all mail with a subject of <quote>Spam</quote> to - <devicename>/dev/null</devicename>:</para> + <filename>/dev/null</filename>:</para> <programlisting>:0 ^Subject:.*Spam /dev/null</programlisting> - <para>A useful recipe that parses incoming <hostid - role="domainname">&os;.org</hostid> mailing lists and places + <para>A useful recipe that parses incoming <systemitem class="fqdomainname">&os;.org</systemitem> mailing lists and places each list in its own mailbox:</para> <programlisting>:0 diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml index ba2dde8e6b..4a8bf7c0c3 100644 --- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - -<appendix id="mirrors"> +<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="mirrors"> <title>Obtaining &os;</title> - <sect1 id="mirrors-cdrom"> + <sect1 xml:id="mirrors-cdrom"> <title>CDROM and DVD Publishers</title> <sect2> @@ -20,7 +19,7 @@ <itemizedlist> <listitem> <address> - <otheraddr>&os; Mall, Inc.</otheraddr> + &os; Mall, Inc. <street>2420 Sand Creek Rd C-1 #347</street> <city>Brentwood</city>, <state>CA</state> @@ -29,72 +28,67 @@ Phone: <phone>+1 925 240-6652</phone> Fax: <fax>+1 925 674-0821</fax> Email: <email>info@freebsdmall.com</email> - WWW: <otheraddr><ulink - url="http://www.freebsdmall.com/"></ulink></otheraddr> + WWW: <otheraddr xlink:href="http://www.freebsdmall.com/">http://www.freebsdmall.com/</otheraddr> </address> </listitem> <listitem> <address> - <otheraddr>Dr. Hinner EDV</otheraddr> + Dr. Hinner EDV <street>Kochelseestr. 11</street> <postcode>D-81371</postcode> <city>München</city> <country>Germany</country> Phone: <phone>(0177) 428 419 0</phone> - WWW: <otheraddr><ulink - url="http://www.hinner.de/linux/freebsd.html"></ulink></otheraddr> + WWW: <otheraddr xlink:href="http://www.hinner.de/linux/freebsd.html">http://www.hinner.de/linux/freebsd.html</otheraddr> </address> </listitem> <listitem> <address> - <otheraddr>Linux Distro UK</otheraddr> + Linux Distro UK <street>42 Wharfedale Road</street> <city>Margate</city> <postcode>CT9 2TB</postcode> <country>United Kingdom</country> - WWW: <otheraddr><ulink - url="https://linux-distro.co.uk/"></ulink></otheraddr> + WWW: <otheraddr xlink:href="https://linux-distro.co.uk/">https://linux-distro.co.uk/</otheraddr> </address> </listitem> <listitem> <address> - <otheraddr>The Linux Emporium</otheraddr> + The Linux Emporium <street>The Techno Centre, Puma Way</street> <city>Parkside</city> <postcode>CV1 2TT</postcode> <country>United Kingdom</country> Phone: <phone>+44 (0)247 615 8121</phone> Fax: <fax>+44 1491 837016</fax> - WWW: <otheraddr><ulink - url="http://www.linuxemporium.co.uk/products/bsd/"></ulink></otheraddr> + WWW: <otheraddr xlink:href="http://www.linuxemporium.co.uk/products/bsd/">http://www.linuxemporium.co.uk/products/bsd/</otheraddr> </address> </listitem> <listitem> <address> - <otheraddr>LinuxCenter.Ru</otheraddr> + LinuxCenter.Ru <street>Galernaya Street, 55</street> <city>Saint-Petersburg</city> <postcode>190000</postcode> <country>Russia</country> Phone: <phone>+7-812-3125208</phone> Email: <email>info@linuxcenter.ru</email> - WWW: <otheraddr><ulink - url="http://linuxcenter.ru/shop/freebsd"></ulink></otheraddr> + WWW: <otheraddr xlink:href="http://linuxcenter.ru/shop/freebsd">http://linuxcenter.ru/shop/freebsd</otheraddr> </address> </listitem> </itemizedlist> </sect2> </sect1> - <sect1 id="mirrors-ftp"> + <sect1 xml:id="mirrors-ftp"> <title>FTP Sites</title> <para>The official sources for &os; are available via anonymous FTP from a worldwide set of mirror sites. The site - <ulink url="ftp://ftp.FreeBSD.org/pub/FreeBSD/"></ulink> is well + <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/">ftp://ftp.FreeBSD.org/pub/FreeBSD/</uri> is well connected and allows a large number of connections to it, but you are probably better off finding a <quote>closer</quote> mirror site (especially if you decide to set up some sort of @@ -121,7 +115,7 @@ &chap.mirrors.ftp.inc; </sect1> - <sect1 id="anoncvs"> + <sect1 xml:id="anoncvs"> <title>Anonymous CVS (Deprecated)</title> <sect2> @@ -130,13 +124,13 @@ <warning> <para>CVS has been deprecated by the project, and its use is not recommended. - <ulink url="&url.books.handbook;/svn.html">Subversion</ulink> + <link xlink:href="&url.books.handbook;/svn.html">Subversion</link> should be used instead.</para> </warning> </sect2> </sect1> - <sect1 id="ctm"> + <sect1 xml:id="ctm"> <title>Using CTM</title> <indexterm> @@ -176,8 +170,7 @@ caveats related to working directly from the development sources rather than a pre-packaged release. This is particularly true if you choose the <quote>current</quote> - sources. It is recommended that you read <link - linkend="current">Staying current with &os;</link>.</para> + sources. It is recommended that you read <link linkend="current">Staying current with &os;</link>.</para> </sect2> <sect2> @@ -200,11 +193,9 @@ the following FTP sites support access to <application>CTM</application>:</para> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para> + <para><uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/CTM/</uri></para> - <para>or see section <link - linkend="mirrors-ctm">mirrors</link>.</para> + <para>or see section <link linkend="mirrors-ctm">mirrors</link>.</para> <para>FTP the relevant directory and fetch the <filename>README</filename> file, starting from there.</para> @@ -428,7 +419,7 @@ been all that high yet.</para> </sect2> - <sect2 id="mirrors-ctm"> + <sect2 xml:id="mirrors-ctm"> <title>CTM Mirrors</title> <para><link linkend="ctm">CTM</link>/&os; is available via @@ -446,8 +437,7 @@ <listitem> <itemizedlist> <listitem> - <para><ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + <para><uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ftp.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para> </listitem> </itemizedlist> </listitem> @@ -459,8 +449,7 @@ <listitem> <itemizedlist> <listitem> - <para><ulink - url="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/"></ulink></para> + <para><uri xlink:href="ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/">ftp://ftp.za.FreeBSD.org/pub/FreeBSD/CTM/</uri></para> </listitem> </itemizedlist> </listitem> @@ -472,18 +461,15 @@ <listitem> <itemizedlist> <listitem> - <para><ulink - url="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + <para><uri xlink:href="ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para> </listitem> <listitem> - <para><ulink - url="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + <para><uri xlink:href="ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm2.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para> </listitem> <listitem> - <para><ulink - url="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/"></ulink></para> + <para><uri xlink:href="ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/">ftp://ctm3.tw.FreeBSD.org/pub/FreeBSD/development/CTM/</uri></para> </listitem> </itemizedlist> </listitem> @@ -491,33 +477,29 @@ </variablelist> <para>If you did not find a mirror near to you or the mirror is - incomplete, try to use a search engine such as <ulink - url="http://www.alltheweb.com/">alltheweb</ulink>.</para> + incomplete, try to use a search engine such as <link xlink:href="http://www.alltheweb.com/">alltheweb</link>.</para> </sect2> </sect1> - <sect1 id="svn"> + <sect1 xml:id="svn"> <title>Using <application>Subversion</application></title> <indexterm> <primary>Subversion</primary> </indexterm> - <sect2 id="svn-intro"> + <sect2 xml:id="svn-intro"> <title>Introduction</title> - <para>As of July 2012, &os; uses <ulink - url="http://subversion.apache.org/">Subversion</ulink> + <para>As of July 2012, &os; uses <link xlink:href="http://subversion.apache.org/">Subversion</link> (<emphasis>svn</emphasis>) as the primary version control system for storing all of &os;'s source code, documentation, and the Ports Collection.</para> <note> <para>Subversion is generally a developer tool. Most users - should use <link - linkend="updating-upgrading-freebsdupdate">FreeBSD - Update</link> to update the &os; base system, and <link - linkend="updating-upgrading-portsnap">Portsnap</link> to + should use <link linkend="updating-upgrading-freebsdupdate">FreeBSD + Update</link> to update the &os; base system, and <link linkend="updating-upgrading-portsnap">Portsnap</link> to update the &os; Ports Collection.</para> </note> @@ -532,11 +514,11 @@ documentation. For example, the URL <literal>svn://svn0.us-east.FreeBSD.org/ports/head/</literal> specifies the main branch of the ports repository on the - <hostid role="fqdn">svn0.us-east.FreeBSD.org</hostid> mirror, + <systemitem class="fqdomainname">svn0.us-east.FreeBSD.org</systemitem> mirror, using the <literal>svn</literal> protocol.</para> </sect2> - <sect2 id="svn-install"> + <sect2 xml:id="svn-install"> <title>Installation</title> <para><application>Subversion</application> must be installed @@ -561,7 +543,7 @@ <screen>&prompt.root; <userinput>pkg install devel/subversion</userinput></screen> </sect2> - <sect2 id="svn-usage"> + <sect2 xml:id="svn-usage"> <title>Running <application>Subversion</application></title> <para>The <command>svn</command> command is used to fetch a @@ -581,7 +563,7 @@ <para>A checkout from a given repository is performed with a command like this:</para> - <screen>&prompt.root; <userinput>svn checkout <replaceable>svn-mirror</replaceable>/<replaceable>repository</replaceable>/<replaceable>branch</replaceable> <replaceable>lwcdir</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>svn checkout svn-mirror/repository/branch lwcdir</userinput></screen> <para>where:</para> @@ -619,11 +601,11 @@ <para><replaceable>lwcdir</replaceable> is the target directory where the contents of the specified branch should be placed. This is usually - <filename class="directory">/usr/ports</filename> for + <filename>/usr/ports</filename> for <literal>ports</literal>, - <filename class="directory">/usr/src</filename> for + <filename>/usr/src</filename> for <literal>base</literal>, and - <filename class="directory">/usr/doc</filename> for + <filename>/usr/doc</filename> for <literal>doc</literal>.</para> </listitem> </itemizedlist> @@ -631,12 +613,12 @@ <para>This example checks out the Ports Collection from the western US repository using the <acronym>HTTPS</acronym> protocol, placing the local working copy in - <filename class="directory">/usr/ports</filename>. If - <filename class="directory">/usr/ports</filename> is already + <filename>/usr/ports</filename>. If + <filename>/usr/ports</filename> is already present but was not created by <command>svn</command>, remember to rename or delete it before the checkout.</para> - <screen>&prompt.root; <userinput>svn checkout <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen> + <screen>&prompt.root; <userinput>svn checkout https://svn0.us-west.FreeBSD.org/ports/head /usr/ports</userinput></screen> <para>Because the initial checkout has to download the full branch of the remote repository, it can take a while. Please @@ -645,10 +627,10 @@ <para>After the initial checkout, the local working copy can be updated by running:</para> - <screen>&prompt.root; <userinput>svn update <replaceable>lwcdir</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>svn update lwcdir</userinput></screen> <para>To update - <filename class="directory">/usr/ports</filename> created in + <filename>/usr/ports</filename> created in the example above, use:</para> <screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen> @@ -658,12 +640,12 @@ <para>An alternate way of updating the local working copy after checkout is provided by the <filename>Makefile</filename> in - the <filename class="directory">/usr/ports</filename>, - <filename class="directory">/usr/src</filename>, and - <filename class="directory">/usr/doc</filename> directories. - Set <makevar>SVN_UPDATE</makevar> and use the - <maketarget>update</maketarget> target. For example, to - update <filename class="directory">/usr/src</filename>:</para> + the <filename>/usr/ports</filename>, + <filename>/usr/src</filename>, and + <filename>/usr/doc</filename> directories. + Set <varname>SVN_UPDATE</varname> and use the + <buildtarget>update</buildtarget> target. For example, to + update <filename>/usr/src</filename>:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make update SVN_UPDATE=yes</userinput></screen> @@ -675,14 +657,14 @@ <para>For other information about using <application>Subversion</application>, please see the <quote>Subversion Book</quote>, titled - <ulink url="http://svnbook.red-bean.com/">Version Control with - Subversion</ulink>, or the - <ulink url="http://subversion.apache.org/docs/">Subversion - Documentation</ulink>.</para> + <link xlink:href="http://svnbook.red-bean.com/">Version Control with + Subversion</link>, or the + <link xlink:href="http://subversion.apache.org/docs/">Subversion + Documentation</link>.</para> </sect2> </sect1> - <sect1 id="svn-mirrors"> + <sect1 xml:id="svn-mirrors"> <title><application>Subversion</application> Mirror Sites</title> <indexterm> @@ -693,12 +675,11 @@ <para>All mirrors carry all repositories.</para> <para>The master &os; <application>Subversion</application> - server, <hostid role="fqdn">svn.FreeBSD.org</hostid>, is + server, <systemitem class="fqdomainname">svn.FreeBSD.org</systemitem>, is publicly accessible, read-only. That may change in the future, so users are encouraged to use one of the official mirrors. To view the &os; <application>Subversion</application> repositories - through a browser, use <ulink - url="http://svnweb.FreeBSD.org/">http://svnweb.FreeBSD.org/</ulink>.</para> + through a browser, use <link xlink:href="http://svnweb.FreeBSD.org/">http://svnweb.FreeBSD.org/</link>.</para> <note> <para>The &os; svn mirror network is still in its early days, @@ -727,13 +708,10 @@ <tbody> <row> - <entry><hostid - role="fqdn">svn0.us-west.FreeBSD.org</hostid></entry> + <entry><systemitem class="fqdomainname">svn0.us-west.FreeBSD.org</systemitem></entry> - <entry>svn, <ulink - url="http://svn0.us-west.FreeBSD.org/">http</ulink>, - <ulink - url="https://svn0.us-west.FreeBSD.org/">https</ulink></entry> + <entry>svn, <link xlink:href="http://svn0.us-west.FreeBSD.org/">http</link>, + <link xlink:href="https://svn0.us-west.FreeBSD.org/">https</link></entry> <entry>USA, California</entry> @@ -742,13 +720,10 @@ </row> <row> - <entry><hostid - role="fqdn">svn0.us-east.FreeBSD.org</hostid></entry> + <entry><systemitem class="fqdomainname">svn0.us-east.FreeBSD.org</systemitem></entry> - <entry>svn, <ulink - url="http://svn0.us-east.FreeBSD.org/">http</ulink>, - <ulink - url="https://svn0.us-east.FreeBSD.org/">https</ulink>, rsync</entry> + <entry>svn, <link xlink:href="http://svn0.us-east.FreeBSD.org/">http</link>, + <link xlink:href="https://svn0.us-east.FreeBSD.org/">https</link>, rsync</entry> <entry>USA, New Jersey</entry> @@ -757,13 +732,10 @@ </row> <row> - <entry><hostid - role="fqdn">svn0.eu.FreeBSD.org</hostid></entry> + <entry><systemitem class="fqdomainname">svn0.eu.FreeBSD.org</systemitem></entry> - <entry>svn, <ulink - url="http://svn0.eu.FreeBSD.org/">http</ulink>, - <ulink - url="https://svn0.eu.FreeBSD.org/">https</ulink>, rsync</entry> + <entry>svn, <link xlink:href="http://svn0.eu.FreeBSD.org/">http</link>, + <link xlink:href="https://svn0.eu.FreeBSD.org/">https</link>, rsync</entry> <entry>Europe, UK</entry> @@ -802,7 +774,7 @@ Certificate information: the server, and the verification step will be repeated on the next connection. Accepting the certificate permanently will store the authentication credentials in - <filename class="directory">~/.subversion/auth/</filename> and + <filename>~/.subversion/auth/</filename> and the user will not be asked to verify the fingerprint again until the certificate expires.</para> @@ -812,10 +784,10 @@ Certificate information: <acronym>HTTP</acronym>.</para> </sect1> - <sect1 id="cvsup"> + <sect1 xml:id="cvsup"> <title>Using CVSup (Deprecated)</title> - <sect2 id="cvsup-intro"> + <sect2 xml:id="cvsup-intro"> <title>Introduction</title> <warning> @@ -867,17 +839,16 @@ Certificate information: </note> </sect2> - <sect2 id="cvsup-install"> + <sect2 xml:id="cvsup-install"> <title>Installation</title> <para>The easiest way to install <application>CVSup</application> is to use the precompiled - <filename role="package">net/cvsup</filename> package from the + <package>net/cvsup</package> package from the &os; <link linkend="ports">packages collection</link>. If you prefer to build <application>CVSup</application> from source, - you can use the <filename role="package">net/cvsup</filename> - port instead. But be forewarned: the <filename - role="package">net/cvsup</filename> port depends on the + you can use the <package>net/cvsup</package> + port instead. But be forewarned: the <package>net/cvsup</package> port depends on the Modula-3 system, which takes a substantial amount of time and disk space to download and build.</para> @@ -887,20 +858,17 @@ Certificate information: have <application>&xorg;</application> installed, such as a server, be sure to use the port which does not include the <application>CVSup</application> <acronym>GUI</acronym>, - <filename - role="package">net/cvsup-without-gui</filename>.</para> + <package>net/cvsup-without-gui</package>.</para> </note> </sect2> - <sect2 id="cvsup-config"> + <sect2 xml:id="cvsup-config"> <title>CVSup Configuration</title> <para><application>CVSup</application>'s operation is controlled by a configuration file called the <filename>supfile</filename>. There are some sample - <filename>supfiles</filename> in the directory <ulink - type="html" - url="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></ulink>.</para> + <filename>supfiles</filename> in the directory <link xlink:href="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></link>.</para> <para>The information in a <filename>supfile</filename> answers the following questions for @@ -982,7 +950,7 @@ Certificate information: <itemizedlist> <listitem> - <para><anchor id="cvsup-config-files"/>Which files do you + <para><anchor xml:id="cvsup-config-files"/>Which files do you want to receive?</para> <para>The files available via @@ -1002,7 +970,7 @@ Certificate information: </listitem> <listitem> - <para><anchor id="cvsup-config-vers"/>Which version(s) of + <para><anchor xml:id="cvsup-config-vers"/>Which version(s) of them do you want?</para> <para>With <application>CVSup</application>, you can receive @@ -1081,7 +1049,7 @@ Certificate information: </listitem> <listitem> - <para><anchor id="cvsup-config-where"/>Where do you want to + <para><anchor xml:id="cvsup-config-where"/>Where do you want to get them from?</para> <para>We use the <literal>host=</literal> field to tell @@ -1091,7 +1059,7 @@ Certificate information: will do, though you should try to select one that is close to you in cyberspace. In this example we will use a fictional &os; distribution site, - <hostid role="fqdn">cvsup99.FreeBSD.org</hostid>:</para> + <systemitem class="fqdomainname">cvsup99.FreeBSD.org</systemitem>:</para> <programlisting>*default host=cvsup99.FreeBSD.org</programlisting> @@ -1104,7 +1072,7 @@ Certificate information: </listitem> <listitem> - <para><anchor id="cvsup-config-dest"/>Where do you want to + <para><anchor xml:id="cvsup-config-dest"/>Where do you want to put them on your own machine?</para> <para>The <literal>prefix=</literal> field tells @@ -1120,7 +1088,7 @@ Certificate information: </listitem> <listitem> - <para><anchor id="cvsup-config-status"/>Where should + <para><anchor xml:id="cvsup-config-status"/>Where should <command>cvsup</command> maintain its status files?</para> <para>The <application>CVSup</application> client maintains @@ -1192,7 +1160,7 @@ src-all</programlisting> </listitem> </itemizedlist> - <sect3 id="cvsup-refuse-file"> + <sect3 xml:id="cvsup-refuse-file"> <title>The <filename>refuse</filename> File</title> <para>As mentioned above, <application>CVSup</application> @@ -1215,7 +1183,7 @@ src-all</programlisting> files from the server. The <filename>refuse</filename> file can be found (or, if you do not yet have one, should be placed) in - <filename><replaceable>base</replaceable>/sup/</filename>. + <filename>base/sup/</filename>. <replaceable>base</replaceable> is defined in your <filename>supfile</filename>; our defined <replaceable>base</replaceable> is @@ -1246,10 +1214,10 @@ usr.bin/</programlisting> <para>You are now ready to try an update. The command line for doing this is quite simple:</para> - <screen>&prompt.root; <userinput>cvsup <replaceable>supfile</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cvsup supfile</userinput></screen> <para>where - <filename><replaceable>supfile</replaceable></filename> is of + <filename>supfile</filename> is of course the name of the <filename>supfile</filename> you have just created. Assuming you are running under X11, <command>cvsup</command> will display a GUI window with some @@ -1258,7 +1226,7 @@ usr.bin/</programlisting> <para>Since you are updating your actual <filename>/usr/src</filename> tree in this example, you will - need to run the program as <username>root</username> so that + need to run the program as <systemitem class="username">root</systemitem> so that <command>cvsup</command> has the permissions it needs to update your files. Having just created your configuration file, and having never used this program before, that might @@ -1281,14 +1249,14 @@ usr.bin/</programlisting> versions of those files will be written into the specified directory. As long as you have read access to <filename>/usr/src</filename>, you do not even need to be - <username>root</username> to perform this kind of trial + <systemitem class="username">root</systemitem> to perform this kind of trial run.</para> <para>If you are not running X11 or if you just do not like GUIs, you should add a couple of options to the command line when you run <command>cvsup</command>:</para> - <screen>&prompt.root; <userinput>cvsup -g -L 2 <replaceable>supfile</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cvsup -g -L 2 supfile</userinput></screen> <para>The <option>-g</option> tells <application>CVSup</application> not to use its GUI. This is @@ -1313,7 +1281,7 @@ usr.bin/</programlisting> use its GUI when running it from &man.cron.8;.</para> </sect2> - <sect2 id="cvsup-collec"> + <sect2 xml:id="cvsup-collec"> <title><application>CVSup</application> File Collections</title> <para>The file collections available via @@ -1659,8 +1627,8 @@ usr.bin/</programlisting> <para>For the <application>CVSup</application> FAQ and other information about <application>CVSup</application>, see - <ulink url="http://www.cvsup.org">The - CVSup Home Page</ulink>.</para> + <link xlink:href="http://www.cvsup.org">The + CVSup Home Page</link>.</para> <para>Most &os;-related discussion of <application>CVSup</application> takes place on the @@ -1669,11 +1637,11 @@ usr.bin/</programlisting> <para>For questions or bug reports about <application>CVSup</application> take a look at the - <ulink url="http://www.cvsup.org/faq.html#bugreports"> - CVSup FAQ</ulink>.</para> + <link xlink:href="http://www.cvsup.org/faq.html#bugreports"> + CVSup FAQ</link>.</para> </sect2> - <sect2 id="cvsup-mirrors"> + <sect2 xml:id="cvsup-mirrors"> <title>CVSup Sites</title> <para><link linkend="cvsup">CVSup</link> servers for &os; are @@ -1688,7 +1656,7 @@ usr.bin/</programlisting> </sect2> </sect1> - <sect1 id="cvs-tags"> + <sect1 xml:id="cvs-tags"> <title>CVS Tags</title> <warning> @@ -2097,16 +2065,16 @@ usr.bin/</programlisting> <para>These tags refer to a specific point in time when a particular version of &os; was released. The release engineering process is documented in more detail by the - <ulink url="&url.base;/releng/">Release Engineering - Information</ulink> and - <ulink url="&url.articles.releng;/release-proc.html">Release - Process</ulink> documents. The - <filename class="directory">src</filename> tree uses tag names + <link xlink:href="&url.base;/releng/">Release Engineering + Information</link> and + <link xlink:href="&url.articles.releng;/release-proc.html">Release + Process</link> documents. The + <filename>src</filename> tree uses tag names that start with <literal>RELENG_</literal> tags. The - <filename class="directory">ports</filename> and - <filename class="directory">doc</filename> trees use tags + <filename>ports</filename> and + <filename>doc</filename> trees use tags whose names begin with <literal>RELEASE</literal> tags. - Finally, the <filename class="directory">www</filename> tree + Finally, the <filename>www</filename> tree is not tagged with any special name for releases.</para> <variablelist> @@ -2529,7 +2497,7 @@ usr.bin/</programlisting> </sect2> </sect1> - <sect1 id="mirrors-rsync"> + <sect1 xml:id="mirrors-rsync"> <title><application>rsync</application> Sites</title> <para>The following sites make &os; available through the rsync @@ -2542,7 +2510,7 @@ usr.bin/</programlisting> &os; FTP server, or the CVS repository. The <application>rsync</application> suite is available for many operating systems, on &os;, see the - <filename role="package">net/rsync</filename> + <package>net/rsync</package> port or use the package.</para> <variablelist> diff --git a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml index bdcac98391..fc1b285374 100644 --- a/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/multimedia/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="multimedia"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="multimedia"> <!-- <chapterinfo> <authorgroup> @@ -20,7 +19,7 @@ <title>Multimedia</title> - <sect1 id="multimedia-synopsis"> + <sect1 xml:id="multimedia-synopsis"> <title>Synopsis</title> <para>&os; supports a wide variety of sound cards, allowing users @@ -92,7 +91,7 @@ </itemizedlist> </sect1> - <sect1 id="sound-setup"> + <sect1 xml:id="sound-setup"> <!-- <sect1info> <authorgroup> @@ -119,8 +118,8 @@ <para>Before beginning the configuration, determine the model of the sound card and the chip it uses. &os; supports a wide variety of sound cards. Check the supported audio devices - list of the <ulink url="&rel.current.hardware;">Hardware - Notes</ulink> to see if the card is supported and which &os; + list of the <link xlink:href="&rel.current.hardware;">Hardware + Notes</link> to see if the card is supported and which &os; driver it uses.</para> <indexterm> @@ -164,8 +163,7 @@ <para>This section is for users who prefer to statically compile in support for the sound card in a custom kernel. For more - information about recompiling a kernel, refer to <xref - linkend="kernelconfig"/>.</para> + information about recompiling a kernel, refer to <xref linkend="kernelconfig"/>.</para> <para>When using a custom kernel to provide sound support, make sure that the audio framework driver exists in the custom @@ -220,7 +218,7 @@ hint.sbc.0.flags="0x15"</programlisting> about this card.</para> </sect2> - <sect2 id="sound-testing"> + <sect2 xml:id="sound-testing"> <title>Testing Sound</title> <para>After loading the required module or rebooting into the @@ -243,7 +241,7 @@ pcm1: <NVIDIA (0x001c) (HDMI/DP 8ch)> (play) pcm2: <Conexant CX20590 (Analog 2.0+HP/2.0)> (play/rec) default</screen> <para>The output will vary depending upon the sound card. If no - <devicename>pcm</devicename> devices are listed, double-check + <filename>pcm</filename> devices are listed, double-check that the correct device driver was loaded or compiled into the kernel. The next section lists some common problems and their solutions.</para> @@ -261,31 +259,29 @@ pcm2: <Conexant CX20590 (Analog 2.0+HP/2.0)> (play/rec) default</screen> they should not be mounted using &man.mount.8;.</para> </warning> - <para>Various applications, such as <filename - role="package">audio/workman</filename>, provide a - friendlier interface. The <filename - role="package">audio/mpg123</filename> port can be installed + <para>Various applications, such as <package>audio/workman</package>, provide a + friendlier interface. The <package>audio/mpg123</package> port can be installed to listen to MP3 audio files.</para> <para>Another quick way to test the card is to send data to - <devicename>/dev/dsp</devicename>:</para> + <filename>/dev/dsp</filename>:</para> - <screen>&prompt.user; <userinput>cat <replaceable>filename</replaceable> > /dev/dsp</userinput></screen> + <screen>&prompt.user; <userinput>cat filename > /dev/dsp</userinput></screen> <para>where - <filename><replaceable>filename</replaceable></filename> can + <filename>filename</filename> can be any type of file. This command should produce some noise, confirming that the sound card is working.</para> <note> - <para>The <devicename>/dev/dsp*</devicename> device nodes will + <para>The <filename>/dev/dsp*</filename> device nodes will be created automatically as needed. When not in use, they do not exist and will not appear in the output of &man.ls.1;.</para> </note> </sect2> - <sect2 id="troubleshooting"> + <sect2 xml:id="troubleshooting"> <title>Troubleshooting Sound</title> <indexterm><primary>device nodes</primary></indexterm> @@ -377,7 +373,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 <varname>hw.snd.default_unit</varname> to the unit that should be used for playback:</para> - <screen>&prompt.root; <userinput>sysctl hw.snd.default_unit=<replaceable>n</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>sysctl hw.snd.default_unit=n</userinput></screen> <para>where <literal>n</literal> is the number of the sound device to use. In this example, it should be @@ -388,7 +384,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 <programlisting>hw.snd.default_unit=<replaceable>4</replaceable></programlisting> </sect2> - <sect2 id="sound-multiple-sources"> + <sect2 xml:id="sound-multiple-sources"> <!-- <sect2info> <authorgroup> @@ -419,8 +415,8 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 <varname>dev.pcm.0.play.vchans=4</varname> and <varname>dev.pcm.0.rec.vchans=4</varname> are configurable after a device has been attached and represent the number of virtual - channels <devicename>pcm0</devicename> has for playback and - recording. Since the <devicename>pcm</devicename> module can be + channels <filename>pcm0</filename> has for playback and + recording. Since the <filename>pcm</filename> module can be loaded independently of the hardware drivers, <varname>hw.snd.maxautovchans</varname> indicates how many virtual channels will be given to an audio device when it is @@ -433,7 +429,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 </note> <para> - The correct <devicename>pcm</devicename> device will + The correct <filename>pcm</filename> device will automatically be allocated transparently to a program that requests <filename>/dev/dsp0</filename>.</para> </sect2> @@ -470,7 +466,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 </sect2> </sect1> -<sect1 id="sound-mp3"> +<sect1 xml:id="sound-mp3"> <!-- <sect1info> <authorgroup> @@ -489,7 +485,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 players available for &os;, how to rip audio CD tracks, and how to encode and decode <acronym>MP3</acronym>s.</para> - <sect2 id="mp3-players"> + <sect2 xml:id="mp3-players"> <title>MP3 Players</title> <para>A popular graphical <acronym>MP3</acronym> player is @@ -502,7 +498,7 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 support.</para> <para><application>XMMS</application> can be installed from - the <filename role="package">multimedia/xmms</filename> port + the <package>multimedia/xmms</package> port or package.</para> <para><application>XMMS</application>'s interface is intuitive, @@ -510,19 +506,19 @@ pcm7: <HDA Realtek ALC889 PCM #3 Digital> at cad 2 nid 1 on hdac1 with <application>Winamp</application> will find <application>XMMS</application> simple to use.</para> - <para>The <filename role="package">audio/mpg123</filename> port + <para>The <package>audio/mpg123</package> port provides an alternative, command-line <acronym>MP3</acronym> player.</para> <para><application>mpg123</application> can be run by specifying the sound device and the <acronym>MP3</acronym> file on the command line. Assuming the audio device is - <devicename>/dev/dsp1.0</devicename> and the + <filename>/dev/dsp1.0</filename> and the <acronym>MP3</acronym> file is <replaceable>Foobar-GreatestHits.mp3</replaceable>, enter the following to play the file:</para> - <screen>&prompt.root; <userinput>mpg123 -a <devicename>/dev/dsp1.0</devicename> <replaceable>Foobar-GreatestHits.mp3</replaceable></userinput> + <screen>&prompt.root; <userinput>mpg123 -a /dev/dsp1.0 Foobar-GreatestHits.mp3</userinput> High Performance MPEG 1.0/2.0/2.5 Audio Player for Layer 1, 2 and 3. Version 0.59r (1999/Jun/15). Written and copyrights by Michael Hipp. Uses code from various people. See 'README' for more! @@ -536,7 +532,7 @@ Playing MPEG stream from Foobar-GreatestHits.mp3 ... MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> </sect2> - <sect2 id="rip-cd"> + <sect2 xml:id="rip-cd"> <title>Ripping CD Audio Tracks</title> <para>Before encoding a CD or CD track to @@ -546,19 +542,19 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> <acronym>WAV</acronym> files.</para> <para>The <command>cdda2wav</command> tool, which is installed - with the <filename role="package">sysutils/cdrtools</filename> + with the <package>sysutils/cdrtools</package> suite, is used for ripping audio information from CDs and the information associated with them.</para> <para>With the audio CD in the drive, the following command can - be issued as <username>root</username> to rip an entire CD + be issued as <systemitem class="username">root</systemitem> to rip an entire CD into individual (per track) <acronym>WAV</acronym> files:</para> - <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -B</userinput></screen> + <screen>&prompt.root; <userinput>cdda2wav -D 0,1,0 -B</userinput></screen> <para>The <option>-D <replaceable>0,1,0</replaceable></option> - indicates the SCSI device <devicename>0,1,0</devicename>, + indicates the SCSI device <filename>0,1,0</filename>, which corresponds to the output of <command>cdrecord -scanbus</command>.</para> @@ -567,48 +563,47 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> device name in place of the SCSI unit numbers. For example, to rip track 7 from an IDE drive:</para> - <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>/dev/acd0</replaceable> -t 7</userinput></screen> + <screen>&prompt.root; <userinput>cdda2wav -D /dev/acd0 -t 7</userinput></screen> <para>To rip individual tracks, make use of the <option>-t</option> as shown:</para> - <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 7</userinput></screen> + <screen>&prompt.root; <userinput>cdda2wav -D 0,1,0 -t 7</userinput></screen> <para>This example rips track seven of the audio CDROM. To rip a range of tracks, such as track one to seven, specify a range:</para> - <screen>&prompt.root; <userinput>cdda2wav -D <replaceable>0,1,0</replaceable> -t 1+7</userinput></screen> + <screen>&prompt.root; <userinput>cdda2wav -D 0,1,0 -t 1+7</userinput></screen> <para>&man.dd.1; can also be used to extract audio tracks on - ATAPI drives, as described in <xref - linkend="duplicating-audiocds"/>.</para> + ATAPI drives, as described in <xref linkend="duplicating-audiocds"/>.</para> </sect2> - <sect2 id="mp3-encoding"> + <sect2 xml:id="mp3-encoding"> <title>Encoding MP3s</title> <para> <application>Lame</application> is a popular <acronym>MP3</acronym> encoder which can be installed from the - <filename role="package">audio/lame</filename> port. Due to + <package>audio/lame</package> port. Due to licensing restrictions, a package is not available.</para> <para>The following command will convert the ripped <acronym>WAV</acronym> files - <filename><replaceable>audio01.wav</replaceable></filename> + <filename>audio01.wav</filename> to - <filename><replaceable>audio01.mp3</replaceable></filename>:</para> + <filename>audio01.mp3</filename>:</para> - <screen>&prompt.root; <userinput>lame -h -b <replaceable>128</replaceable> \ ---tt "<replaceable>Foo Song Title</replaceable>" \ ---ta "<replaceable>FooBar Artist</replaceable>" \ ---tl "<replaceable>FooBar Album</replaceable>" \ ---ty "<replaceable>2001</replaceable>" \ ---tc "<replaceable>Ripped and encoded by Foo</replaceable>" \ ---tg "<replaceable>Genre</replaceable>" \ -<replaceable>audio01.wav audio01.mp3</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>lame -h -b 128 \ +--tt "Foo Song Title" \ +--ta "FooBar Artist" \ +--tl "FooBar Album" \ +--ty "2001" \ +--tc "Ripped and encoded by Foo" \ +--tg "Genre" \ +audio01.wav audio01.mp3</userinput></screen> <para>128 kbits is a standard <acronym>MP3</acronym> bitrate. The 160 and 192 bitrates provide higher quality. @@ -622,7 +617,7 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> page.</para> </sect2> - <sect2 id="mp3-decoding"> + <sect2 xml:id="mp3-decoding"> <title>Decoding MP3s</title> <para>In order to burn an audio CD from <acronym>MP3</acronym>s, @@ -690,8 +685,8 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> <procedure> <step> <para>Run <command>mpg123 -s - <replaceable>audio01.mp3</replaceable> > - <replaceable>audio01.pcm</replaceable></command></para> + audio01.mp3 > + audio01.pcm</command></para> </step> </procedure> @@ -706,17 +701,16 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> sound at the beginning of each track. This sound is the header of the <acronym>WAV</acronym> file. One can remove the header with <application>SoX</application>, which can be - installed from the <filename - role="package">audio/sox</filename> port or package:</para> + installed from the <package>audio/sox</package> port or package:</para> - <screen>&prompt.user; <userinput>sox -t wav -r 44100 -s -w -c 2 <replaceable>track.wav track.raw</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>sox -t wav -r 44100 -s -w -c 2 track.wav track.raw</userinput></screen> <para>Refer to <xref linkend="creating-cds"/> for more information on using a CD burner in &os;.</para> </sect2> </sect1> - <sect1 id="video-playback"> + <sect1 xml:id="video-playback"> <!-- <sect1info> <authorgroup> @@ -743,8 +737,7 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> <para>It is a good idea to have a short MPEG test file for evaluating various players and options. Since some <acronym>DVD</acronym> applications look for - <acronym>DVD</acronym> media in <filename - class="directory">/dev/dvd</filename> by default, or have this + <acronym>DVD</acronym> media in <filename>/dev/dvd</filename> by default, or have this device name hardcoded in them, it might be useful to make a symbolic links to the proper device:</para> @@ -769,7 +762,7 @@ MPEG 1.0 layer III, 128 kbit/s, 44100 Hz joint-stereo</screen> <programlisting>kern.ipc.shmmax=67108864 kern.ipc.shmall=32768</programlisting> - <sect2 id="video-interface"> + <sect2 xml:id="video-interface"> <title>Determining Video Capabilities</title> <indexterm><primary>XVideo</primary></indexterm> @@ -807,8 +800,7 @@ kern.ipc.shmall=32768</programlisting> provides a low-level abstraction to the hardware which can sometimes be more efficient than the <application>&xorg;</application> interface. On &os;, - <acronym>SDL</acronym> can be installed using the <filename - role="package">devel/sdl20</filename> package or + <acronym>SDL</acronym> can be installed using the <package>devel/sdl20</package> package or port.</para> </listitem> @@ -818,7 +810,7 @@ kern.ipc.shmall=32768</programlisting> program to bypass the <application>&xorg;</application> server and directly alter the framebuffer. Because it relies on a low level memory mapping, programs using it must - be run as <username>root</username>. The + be run as <systemitem class="username">root</systemitem>. The <acronym>DGA</acronym> extension can be tested and benchmarked using &man.dga.1;. When <command>dga</command> is running, it changes the colors of the display whenever a @@ -830,7 +822,7 @@ kern.ipc.shmall=32768</programlisting> </listitem> </orderedlist> - <sect3 id="video-interface-xvideo"> + <sect3 xml:id="video-interface-xvideo"> <title>XVideo</title> <para>To check whether this extension is running, use @@ -927,7 +919,7 @@ no adaptors present</screen> </sect3> </sect2> - <sect2 id="video-ports"> + <sect2 xml:id="video-ports"> <title>Ports and Packages Dealing with Video</title> <indexterm><primary>video ports</primary></indexterm> @@ -937,7 +929,7 @@ no adaptors present</screen> the &os; Ports Collection which can be used for video playback.</para> - <sect3 id="video-mplayer"> + <sect3 xml:id="video-mplayer"> <title><application>MPlayer</application> and <application>MEncoder</application></title> @@ -950,7 +942,7 @@ no adaptors present</screen> <indexterm><primary>MPlayer</primary></indexterm> <para><application>MPlayer</application> can be installed using - the <filename role="package">multimedia/mplayer</filename> + the <package>multimedia/mplayer</package> package or port. Several compile options are available and a variety of hardware checks occur during the build process. For these reasons, some users prefer to build the port rather @@ -968,14 +960,12 @@ no adaptors present</screen> <para>By default, the package or port will build the <command>mplayer</command> command line utility and the <command>gmplayer</command> graphical utility. To encode - videos, compile the <filename - role="package">multimedia/mencoder</filename> port. Due to + videos, compile the <package>multimedia/mencoder</package> port. Due to licensing restrictions, a package is not available for <application>MEncoder</application>.</para> <para>The first time <application>MPlayer</application> is run, - it will create <filename - class="directory">~/.mplayer</filename> in the user's home + it will create <filename>~/.mplayer</filename> in the user's home directory. This subdirectory contains default versions of the user-specific configuration files.</para> @@ -984,32 +974,32 @@ no adaptors present</screen> options.</para> <para>To play the file - <filename><replaceable>testfile.avi</replaceable></filename>, + <filename>testfile.avi</filename>, specify the video interfaces with <option>-vo</option>, as seen in the following examples:</para> - <screen>&prompt.user; <userinput>mplayer -vo xv <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mplayer -vo xv testfile.avi</userinput></screen> - <screen>&prompt.user; <userinput>mplayer -vo sdl <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mplayer -vo sdl testfile.avi</userinput></screen> - <screen>&prompt.user; <userinput>mplayer -vo x11 <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mplayer -vo x11 testfile.avi</userinput></screen> - <screen>&prompt.root; <userinput>mplayer -vo dga <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mplayer -vo dga testfile.avi</userinput></screen> - <screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' <replaceable>testfile.avi</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mplayer -vo 'sdl:dga' testfile.avi</userinput></screen> <para>It is worth trying all of these options, as their relative performance depends on many factors and will vary significantly with hardware.</para> <para>To play a <acronym>DVD</acronym>, replace - <filename><replaceable>testfile.avi</replaceable></filename> + <filename>testfile.avi</filename> with <option>dvd://<replaceable>N</replaceable> -dvd-device <replaceable>DEVICE</replaceable></option>, where <replaceable>N</replaceable> is the title number to play and <replaceable>DEVICE</replaceable> is the device node for the <acronym>DVD</acronym>. For example, to play title 3 from - <devicename>/dev/dvd</devicename>:</para> + <filename>/dev/dvd</filename>:</para> <screen>&prompt.root; <userinput>mplayer -vo xv dvd://3 -dvd-device /dev/dvd</userinput></screen> @@ -1017,7 +1007,7 @@ no adaptors present</screen> <para>The default <acronym>DVD</acronym> device can be defined during the build of the <application>MPlayer</application> port by including the - <makevar>WITH_DVD_DEVICE=/path/to/desired/device</makevar> + <varname>WITH_DVD_DEVICE=/path/to/desired/device</varname> option. By default, the device is <filename>/dev/cd0</filename>. More details can be found in the port's <filename>Makefile.options</filename>.</para> @@ -1048,8 +1038,7 @@ zoom=yes</programlisting> <acronym>MPEG</acronym> format.</para> <para>Anyone wishing to obtain a high level of expertise with - &unix; video should consult <ulink - url="http://www.mplayerhq.hu/DOCS/">mplayerhq.hu/DOCS</ulink> + &unix; video should consult <link xlink:href="http://www.mplayerhq.hu/DOCS/">mplayerhq.hu/DOCS</link> as it is technically informative. This documentation should be considered as required reading before submitting any bug reports.</para> @@ -1060,8 +1049,7 @@ zoom=yes</programlisting> <para>Before using <command>mencoder</command>, it is a good idea to become familiar with the options described at - <ulink - url="http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html">mplayerhq.hu/DOCS/HTML/en/mencoder.html</ulink>. + <link xlink:href="http://www.mplayerhq.hu/DOCS/HTML/en/mencoder.html">mplayerhq.hu/DOCS/HTML/en/mencoder.html</link>. There are innumerable ways to improve quality, lower bitrate, and change formats, and some of these options may make the difference between good or bad performance. Improper @@ -1070,40 +1058,40 @@ zoom=yes</programlisting> <para>Here is an example of a simple copy:</para> - <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac copy -ovc copy -o <replaceable>output.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mencoder input.avi -oac copy -ovc copy -o output.avi</userinput></screen> <para>To rip to a file, use <option>-dumpfile</option> with <command>mplayer</command>.</para> <para>To convert - <filename><replaceable>input.avi</replaceable></filename> to + <filename>input.avi</filename> to the MPEG4 codec with MPEG3 audio encoding, first install the - <filename role="package">audio/lame</filename> port. Due to + <package>audio/lame</package> port. Due to licensing restrictions, a package is not available. Once installed, type:</para> - <screen>&prompt.user; <userinput>mencoder <replaceable>input.avi</replaceable> -oac mp3lame -lameopts br=192 \ - -ovc lavc -lavcopts vcodec=mpeg4:vhq -o <replaceable>output.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>mencoder input.avi -oac mp3lame -lameopts br=192 \ + -ovc lavc -lavcopts vcodec=mpeg4:vhq -o output.avi</userinput></screen> <para>This will produce output playable by applications such as <command>mplayer</command> and <command>xine</command>.</para> - <para><filename><replaceable>input.avi</replaceable></filename> + <para><filename>input.avi</filename> can be replaced with <option>dvd://1 -dvd-device - /dev/dvd</option> and run as <username>root</username> to + /dev/dvd</option> and run as <systemitem class="username">root</systemitem> to re-encode a <acronym>DVD</acronym> title directly. Since it may take a few tries to get the desired result, it is recommended to instead dump the title to a file and to work on the file.</para> </sect3> - <sect3 id="video-xine"> + <sect3 xml:id="video-xine"> <title>The <application>xine</application> Video Player</title> <para><application>xine</application> is a video player with a reusable base library and a modular executable which can be extended with plugins. It can be installed using the - <filename role="package">multimedia/xine</filename> package or + <package>multimedia/xine</package> package or port.</para> <para>In practice, <application>xine</application> requires @@ -1119,15 +1107,14 @@ zoom=yes</programlisting> invoked from the command line by specifying the name of the file to play:</para> - <screen>&prompt.user; <userinput>xine -g -p <replaceable>mymovie.avi</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>xine -g -p mymovie.avi</userinput></screen> - <para>Refer to <ulink - url="http://www.xine-project.org/faq"> - xine-project.org/faq</ulink> for more information and + <para>Refer to <link xlink:href="http://www.xine-project.org/faq"> + xine-project.org/faq</link> for more information and troubleshooting tips.</para> </sect3> - <sect3 id="video-ports-transcode"> + <sect3 xml:id="video-ports-transcode"> <title>The <application>Transcode</application> Utilities</title> @@ -1139,8 +1126,7 @@ zoom=yes</programlisting> interfaces.</para> <para>In &os;, <application>Transcode</application> can be - installed using the <filename - role="package">multimedia/transcode</filename> package or + installed using the <package>multimedia/transcode</package> package or port. Many users prefer to compile the port as it provides a menu of compile options for specifying the support and codecs to compile in. If an option is not selected, @@ -1154,27 +1140,24 @@ zoom=yes</programlisting> a PAL MPEG-1 file (PAL VCD):</para> <screen>&prompt.user; <userinput>transcode -i -<replaceable>input.avi</replaceable> -V --export_prof vcd-pal -o output_vcd</userinput> -&prompt.user; <userinput>mplex -f 1 -o <replaceable>output_vcd.mpg output_vcd.m1v output_vcd.mpa</replaceable></userinput></screen> +input.avi -V --export_prof vcd-pal -o output_vcd</userinput> +&prompt.user; <userinput>mplex -f 1 -o output_vcd.mpg output_vcd.m1v output_vcd.mpa</userinput></screen> <para>The resulting <acronym>MPEG</acronym> file, - <filename><replaceable>output_vcd.mpg</replaceable></filename>, + <filename>output_vcd.mpg</filename>, is ready to be played with <application>MPlayer</application>. The file can be burned on a <acronym>CD</acronym> media to create a video <acronym>CD</acronym> using a utility such as - <filename - role="package">multimedia/vcdimager</filename> or <filename - role="package">sysutils/cdrdao</filename>.</para> + <package>multimedia/vcdimager</package> or <package>sysutils/cdrdao</package>.</para> <para>In addition to the manual page for - <command>transcode</command>, refer to <ulink - url="http://www.transcoding.org/cgi-bin/transcode">transcoding.org/cgi-bin/transcode</ulink> + <command>transcode</command>, refer to <link xlink:href="http://www.transcoding.org/cgi-bin/transcode">transcoding.org/cgi-bin/transcode</link> for further information and examples.</para> </sect3> </sect2> </sect1> -<sect1 id="tvcard"> +<sect1 xml:id="tvcard"> <!-- <sect1info> <authorgroup> @@ -1270,16 +1253,16 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <itemizedlist> <listitem> - <para><filename role="package">multimedia/fxtv</filename> + <para><package>multimedia/fxtv</package> provides TV-in-a-window and image/audio/video capture capabilities.</para> </listitem> <listitem> - <para><filename role="package">multimedia/xawtv</filename> + <para><package>multimedia/xawtv</package> is another TV application with similar features.</para> </listitem> <listitem> - <para><filename role="package">audio/xmradio</filename> + <para><package>audio/xmradio</package> provides an application for using the FM radio tuner of a TV card.</para> </listitem> @@ -1301,31 +1284,28 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> </sect2> </sect1> - <sect1 id="mythtv"> + <sect1 xml:id="mythtv"> <title>MythTV</title> <para>MythTV is a popular, open source Personal Video Recorder (<acronym>PVR</acronym>) application. This section demonstrates - how to install and setup MythTV on &os;. Refer to <ulink - url="http://www.mythtv.org/wiki/">mythtv.org/wiki</ulink> for + how to install and setup MythTV on &os;. Refer to <link xlink:href="http://www.mythtv.org/wiki/">mythtv.org/wiki</link> for more information on how to use MythTV.</para> <para>MythTV requires a frontend and a backend. These components can either be installed on the same system or on different machines.</para> - <para>The frontend can be installed on &os; using the <filename - role="package">multimedia/mythtv-frontend</filename> package + <para>The frontend can be installed on &os; using the <package>multimedia/mythtv-frontend</package> package or port. <application>&xorg;</application> must also be - installed and configured as described in <xref - linkend="x11"/>. Ideally, this system has a video card that + installed and configured as described in <xref linkend="x11"/>. Ideally, this system has a video card that supports X-Video Motion Compensation (<acronym>XvMC</acronym>) and, optionally, a Linux Infrared Remote Control (<acronym>LIRC</acronym>)-compatible remote.</para> <para>To install both the backend and the frontend on &os;, use - the <filename role="package">multimedia/mythtv</filename> + the <package>multimedia/mythtv</package> package or port. A &mysql; database server is also required and should automatically be installed as a dependency. Optionally, this system should have a tuner card and @@ -1337,25 +1317,20 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <para>MythTV uses Video for Linux (<acronym>V4L</acronym>) to access video input devices such as encoders and tuners. In &os;, MythTV works best with <acronym>USB</acronym> DVB-S/C/T - cards as they are well supported by the <filename - role="package">multimedia/webcamd</filename> package or port + cards as they are well supported by the <package>multimedia/webcamd</package> package or port which provides a <acronym>V4L</acronym> userland application. Any Digital Video Broadcasting (<acronym>DVB</acronym>) card supported by <application>webcamd</application> should work with MythTV. A list of known working cards can be found at - <ulink - url="http://wiki.freebsd.org/WebcamCompat">wiki.freebsd.org/WebcamCompat</ulink>. + <link xlink:href="http://wiki.freebsd.org/WebcamCompat">wiki.freebsd.org/WebcamCompat</link>. Drivers are also available for Hauppauge cards in the - <filename - role="package">multimedia/pvr250</filename> and <filename - role="package">multimedia/pvrxxx</filename> ports, but they + <package>multimedia/pvr250</package> and <package>multimedia/pvrxxx</package> ports, but they provide a non-standard driver interface that does not work with versions of MythTV greater than 0.23. Due to licensing restrictions, no packages are available and these two ports must be compiled.</para> - <para>The <ulink - url="http://wiki.freebsd.org/HTPC">wiki.freebsd.org/HTPC</ulink> + <para>The <link xlink:href="http://wiki.freebsd.org/HTPC">wiki.freebsd.org/HTPC</link> page contains a list of all available <acronym>DVB</acronym> drivers.</para> </sect2> @@ -1383,7 +1358,7 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> </sect2> </sect1> - <sect1 id="scanners"> + <sect1 xml:id="scanners"> <!-- <sect1info> <authorgroup> @@ -1404,17 +1379,15 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> <para>In &os;, access to image scanners is provided by the <application>SANE</application> (Scanner Access Now Easy) - <acronym role="Application Programming - Interface">API</acronym> available through the &os; Ports + <acronym role="Application Programming Interface">API</acronym> available through the &os; Ports Collection. <application>SANE</application> will also use some &os; device drivers to provide access to the scanner hardware.</para> <para>&os; supports both SCSI and USB scanners. Be sure the scanner is supported by <application>SANE</application> prior - to performing any configuration. Refer to the <ulink - url="http://www.sane-project.org/sane-supported-devices.html"> - supported devices list</ulink> for more information about + to performing any configuration. Refer to the <link xlink:href="http://www.sane-project.org/sane-supported-devices.html"> + supported devices list</link> for more information about supported scanners.</para> <sect2> @@ -1424,7 +1397,7 @@ bktr0: Pinnacle/Miro TV, Philips SECAM tuner.</programlisting> upon the scanner interface, different device drivers are required.</para> - <sect3 id="scanners-kernel-usb"> + <sect3 xml:id="scanners-kernel-usb"> <title>USB Interface</title> <para>The <filename>GENERIC</filename> kernel by default @@ -1503,20 +1476,16 @@ Re-scan of bus 3 was successful</screen> <title>SANE Configuration</title> <para>The <application>SANE</application> system is split in two - parts: the backends (<filename - role="package">graphics/sane-backends</filename>) and the - frontends (<filename - role="package">graphics/sane-frontends</filename>). The + parts: the backends (<package>graphics/sane-backends</package>) and the + frontends (<package>graphics/sane-frontends</package>). The backends provide access to the scanner. The - <application>SANE</application>'s <ulink - url="http://www.sane-project.org/sane-supported-devices.html">supported - devices</ulink> list specifies which backend will support the + <application>SANE</application>'s <link xlink:href="http://www.sane-project.org/sane-supported-devices.html">supported + devices</link> list specifies which backend will support the image scanner. The correct backend is needed in order to use the scanner. The frontends provide the graphical scanning interface, <application>xscanimage</application>.</para> - <para>After installing the <filename - role="package">graphics/sane-backends</filename> port or + <para>After installing the <package>graphics/sane-backends</package> port or package, use <command>sane-find-scanner</command> to check the scanner detection by the <application>SANE</application> system:</para> @@ -1544,8 +1513,7 @@ found SCSI scanner "AGFA SNAPSCAN 600 1.10" at /dev/pass3</screen> <screen>&prompt.root; <userinput>scanimage -L</userinput> device `snapscan:/dev/pass3' is a AGFA SNAPSCAN 600 flatbed scanner</screen> - <para>Here is the output for the USB scanner used in <xref - linkend="scanners-kernel-usb"/>:</para> + <para>Here is the output for the USB scanner used in <xref linkend="scanners-kernel-usb"/>:</para> <screen>&prompt.root; <userinput>scanimage -L</userinput> device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner</screen> @@ -1560,8 +1528,7 @@ device 'epson2:libusb:/dev/usb:/dev/ugen0.2' is a Epson GT-8200 flatbed scanner< <para>No output or a message saying that no scanners were identified indicates that &man.scanimage.1; is unable to identify the scanner. If this happens, edit the backend - configuration file in <filename - class="directory">/usr/local/etc/sane.d/</filename> + configuration file in <filename>/usr/local/etc/sane.d/</filename> and define the scanner device used.</para> <para>In the above example, the USB scanner is perfectly @@ -1610,12 +1577,12 @@ device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen> <para>While &man.scanimage.1; can be used to perform an image acquisition from the command line, it is often preferable to use a graphical interface to perform image scanning. The - <filename role="package">graphics/sane-frontends</filename> + <package>graphics/sane-frontends</package> package or port installs a simple but efficient graphical interface, <application>xscanimage</application>.</para> <para><application>Xsane</application>, which is installed with - the <filename role="package">graphics/xsane</filename> package + the <package>graphics/xsane</package> package or port, is another popular graphical scanning frontend. It offers advanced features such as various scanning modes, color correction, and batch scans. Both of these applications are @@ -1632,23 +1599,23 @@ device `epson:/dev/uscanner0' is a Epson GT-8200 flatbed scanner</screen> symlink to the real device node <filename>/dev/usb/0.2.0</filename>. The symlink and the device node are owned, respectively, by the - <groupname>wheel</groupname> and - <groupname>operator</groupname> groups. Adding the user to + <systemitem class="groupname">wheel</systemitem> and + <systemitem class="groupname">operator</systemitem> groups. Adding the user to these groups will allow access to the scanner. However, for security reasons, always think twice before adding a user - to any group, especially <groupname>wheel</groupname>. A better + to any group, especially <systemitem class="groupname">wheel</systemitem>. A better solution is to create a group to make the scanner device accessible to members of this group.</para> <para>This example creates a group called - <groupname><replaceable>usb</replaceable></groupname> using + <systemitem class="groupname"><replaceable>usb</replaceable></systemitem> using &man.pw.8;:</para> <screen>&prompt.root; <userinput>pw groupadd usb</userinput></screen> <para>Then, make the <filename>/dev/ugen0.2</filename> symlink and the <filename>/dev/usb/0.2.0</filename> device node - accessible to the <groupname>usb</groupname> group with write + accessible to the <systemitem class="groupname">usb</systemitem> group with write permissions of (<literal>0660</literal> or <literal>0664</literal>. All of this is done by adding the following lines to @@ -1659,10 +1626,10 @@ add path ugen0.2 mode 0660 group usb add path usb/0.2.0 mode 0666 group usb</programlisting> <para>Finally, add the users to - <groupname><replaceable>usb</replaceable></groupname> in order + <systemitem class="groupname"><replaceable>usb</replaceable></systemitem> in order to allow access to the scanner:</para> - <screen>&prompt.root; <userinput>pw groupmod usb -m <replaceable>joe</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw groupmod usb -m joe</userinput></screen> <para>For more details refer to &man.pw.8;.</para> </sect2> diff --git a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml index 8a270095e9..0b41db2778 100644 --- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="network-servers"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="network-servers"> <!-- <chapterinfo> <authorgroup> @@ -20,7 +19,7 @@ <title>Network Servers</title> - <sect1 id="network-servers-synopsis"> + <sect1 xml:id="network-servers-synopsis"> <title>Synopsis</title> <para>This chapter covers some of the more frequently used network @@ -113,7 +112,7 @@ </itemizedlist> </sect1> - <sect1 id="network-inetd"> + <sect1 xml:id="network-inetd"> <!-- <sect1info> <authorgroup> @@ -135,7 +134,7 @@ <title>The <application>inetd</application> <quote>Super-Server</quote></title> - <sect2 id="network-inetd-overview"> + <sect2 xml:id="network-inetd-overview"> <title>Overview</title> <para>The &man.inetd.8; daemon is sometimes referred to as the @@ -162,7 +161,7 @@ <filename>/etc/inetd.conf</filename>.</para> </sect2> - <sect2 id="network-inetd-settings"> + <sect2 xml:id="network-inetd-settings"> <title>Settings</title> <para><application>inetd</application> is initialized through @@ -186,7 +185,7 @@ <literal>inetd_flags</literal> option.</para> </sect2> - <sect2 id="network-inetd-cmdline"> + <sect2 xml:id="network-inetd-cmdline"> <title>Command-Line Options</title> <para>Like most server daemons, <application>inetd</application> @@ -260,7 +259,7 @@ </variablelist> </sect2> - <sect2 id="network-inetd-conf"> + <sect2 xml:id="network-inetd-conf"> <!-- XXX This section is not very clear and could do with some tlc --> <title><filename>inetd.conf</filename></title> @@ -272,7 +271,7 @@ <application>inetd</application> can be forced to re-read its configuration file by running the command:</para> - <example id="network-inetd-reread"> + <example xml:id="network-inetd-reread"> <title>Reloading the <application>inetd</application> Configuration File</title> @@ -455,10 +454,10 @@ server-program-arguments</programlisting> <listitem> <para>This is the username that the particular daemon should run as. Most commonly, daemons run as the - <username>root</username> user. For security purposes, + <systemitem class="username">root</systemitem> user. For security purposes, it is common to find some servers running as the - <username>daemon</username> user, or the least - privileged <username>nobody</username> user.</para> + <systemitem class="username">daemon</systemitem> user, or the least + privileged <systemitem class="username">nobody</systemitem> user.</para> </listitem> </varlistentry> @@ -492,7 +491,7 @@ server-program-arguments</programlisting> </variablelist> </sect2> - <sect2 id="network-inetd-security"> + <sect2 xml:id="network-inetd-security"> <title>Security</title> <para>Depending on the choices made at install time, many @@ -523,7 +522,7 @@ server-program-arguments</programlisting> <application>inetd</application> invoked daemons.</para> </sect2> - <sect2 id="network-inetd-misc"> + <sect2 xml:id="network-inetd-misc"> <title>Miscellaneous</title> <para><application>daytime</application>, @@ -543,7 +542,7 @@ server-program-arguments</programlisting> </sect2> </sect1> - <sect1 id="network-nfs"> + <sect1 xml:id="network-nfs"> <!-- <sect1info> <authorgroup> @@ -667,7 +666,7 @@ server-program-arguments</programlisting> <para>Running &man.nfsiod.8; can improve performance on the client, but is not required.</para> - <sect2 id="network-configuring-nfs"> + <sect2 xml:id="network-configuring-nfs"> <title>Configuring <acronym>NFS</acronym></title> <indexterm> @@ -712,7 +711,7 @@ mountd_flags="-r"</programlisting> on the reader's network.</para> <para>This example shows how to export the - <filename class="directory">/cdrom</filename> directory to + <filename>/cdrom</filename> directory to three clients called <replaceable>alpha</replaceable>, <replaceable>bravo</replaceable>, and <replaceable>charlie</replaceable>:</para> @@ -724,7 +723,7 @@ mountd_flags="-r"</programlisting> those exported file systems.</para> <para>The next example exports - <filename class="directory">/home</filename> to three clients + <filename>/home</filename> to three clients by <acronym>IP</acronym> address. This can be useful for networks without <acronym>DNS</acronym>. Optionally, <filename>/etc/hosts</filename> could be configured for @@ -737,16 +736,16 @@ mountd_flags="-r"</programlisting> <programlisting>/home -alldirs 10.0.0.2 10.0.0.3 10.0.0.4</programlisting> <para>This next line exports - <filename class="directory">/a</filename> so that two clients + <filename>/a</filename> so that two clients from different domains may access the file system. The <option>-maproot=root</option> flag allows the - <username>root</username> user on the remote system to write - data on the exported file system as <username>root</username>. + <systemitem class="username">root</systemitem> user on the remote system to write + data on the exported file system as <systemitem class="username">root</systemitem>. If the <literal>-maproot=root</literal> flag is not specified, - the client's <username>root</username> user will be mapped to - the server's <username>nobody</username> account and will be + the client's <systemitem class="username">root</systemitem> user will be mapped to + the server's <systemitem class="username">nobody</systemitem> account and will be subject to the access limitations defined for user, - <username>nobody</username>.</para> + <systemitem class="username">nobody</systemitem>.</para> <programlisting>/a -maproot=root host.example.com box.example.org</programlisting> @@ -758,7 +757,7 @@ mountd_flags="-r"</programlisting> the export information for one file system to one or more clients. A remote host can only be specified once per file system. For example, assume that - <filename class="directory">/usr</filename> is a single file + <filename>/usr</filename> is a single file system. This entry, in <filename>/etc/exports</filename>, would be invalid:</para> @@ -766,9 +765,9 @@ mountd_flags="-r"</programlisting> /usr/src client /usr/ports client</programlisting> - <para>The <filename class="directory">/usr</filename> file + <para>The <filename>/usr</filename> file system has two lines specifying exports to the same host, - <hostid>client</hostid>. The correct format for this + <systemitem>client</systemitem>. The correct format for this situation is:</para> <programlisting>/usr/src /usr/ports client</programlisting> @@ -779,8 +778,8 @@ mountd_flags="-r"</programlisting> system.</para> <para>The following is an example of a valid export list, where - <filename class="directory">/usr</filename> and - <filename class="directory">/exports</filename> are local + <filename>/usr</filename> and + <filename>/exports</filename> are local file systems:</para> <programlisting># Export src and ports to client01 and client02, but only @@ -805,7 +804,7 @@ mountd_flags="-r"</programlisting> <para>On a new server being configured with <acronym>NFS</acronym> services, the server can be started by - running this command as <username>root</username>:</para> + running this command as <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>service nfsd start</userinput></screen> @@ -815,11 +814,11 @@ mountd_flags="-r"</programlisting> <para>The client now has everything it needs to mount a remote file system. In these examples, the server's name is - <hostid>server</hostid> and the client's name is - <hostid>client</hostid>. For testing or to temporarily mount + <systemitem>server</systemitem> and the client's name is + <systemitem>client</systemitem>. For testing or to temporarily mount a remote file system, execute <application>mount</application> - as <username>root</username> on - <hostid>client</hostid>:</para> + as <systemitem class="username">root</systemitem> on + <systemitem>client</systemitem>:</para> <indexterm> <primary>NFS</primary> @@ -827,14 +826,14 @@ mountd_flags="-r"</programlisting> </indexterm> <screen>&prompt.root; <userinput>mount server:/home /mnt</userinput></screen> - <para>This mounts the <hostid>server</hostid>: - <filename class="directory">/home</filename> file system to - the <hostid>client</hostid>: - <filename class="directory">/mnt</filename> mount point. The - files and directories in the <hostid>server</hostid> - <filename class="directory">/home</filename> file system will - now be available on <hostid>client</hostid>, in the - <filename class="directory">/mnt</filename> directory.</para> + <para>This mounts the <systemitem>server</systemitem>: + <filename>/home</filename> file system to + the <systemitem>client</systemitem>: + <filename>/mnt</filename> mount point. The + files and directories in the <systemitem>server</systemitem> + <filename>/home</filename> file system will + now be available on <systemitem>client</systemitem>, in the + <filename>/mnt</filename> directory.</para> <para>To mount a remote file system each time the client boots, add it to <filename>/etc/fstab</filename>:</para> @@ -862,7 +861,7 @@ rpc_statd_enable="YES"</programlisting> <acronym>NFS</acronym> client and server are already configured.</para> - <para>Start the application, as <username>root</username>, + <para>Start the application, as <systemitem class="username">root</systemitem>, with:</para> <screen>&prompt.root; <userinput>service lockd start</userinput> @@ -902,8 +901,7 @@ rpc_statd_enable="YES"</programlisting> </listitem> <listitem> - <para>Several clients may need access to the <filename - class="directory">/usr/ports/distfiles</filename> + <para>Several clients may need access to the <filename>/usr/ports/distfiles</filename> directory. Sharing that directory allows for quick access to the source files without having to download them to each client.</para> @@ -911,7 +909,7 @@ rpc_statd_enable="YES"</programlisting> </itemizedlist> </sect2> - <sect2 id="network-amd"> + <sect2 xml:id="network-amd"> <!-- <sect2info> <authorgroup> @@ -949,21 +947,20 @@ rpc_statd_enable="YES"</programlisting> <para><application>amd</application> operates by attaching itself as an NFS server to the - <filename class="directory">/host</filename> and - <filename class="directory">/net</filename> directories. When + <filename>/host</filename> and + <filename>/net</filename> directories. When a file is accessed within one of these directories, <application>amd</application> looks up the corresponding - remote mount and automatically mounts it. <filename - class="directory">/net</filename> is used to mount an + remote mount and automatically mounts it. <filename>/net</filename> is used to mount an exported file system from an <acronym>IP</acronym> address, - while <filename class="directory">/host</filename> is used to + while <filename>/host</filename> is used to mount an export from a remote hostname.</para> <para>For instance, an attempt to access a file within - <filename class="directory">/host/foobar/usr</filename> would + <filename>/host/foobar/usr</filename> would tell <application>amd</application> to mount the - <filename class="directory">/usr</filename> export on the host - <hostid>foobar</hostid>.</para> + <filename>/usr</filename> export on the host + <systemitem>foobar</systemitem>.</para> <example> <title>Mounting an Export with @@ -972,7 +969,7 @@ rpc_statd_enable="YES"</programlisting> <para><command>showmount -e</command> shows the exported file systems that can be mounted from the <acronym>NFS</acronym> server, - <hostid>foobar</hostid>:</para> + <systemitem>foobar</systemitem>:</para> <screen>&prompt.user; <userinput>showmount -e foobar</userinput> Exports list on foobar: @@ -982,11 +979,11 @@ Exports list on foobar: </example> <para>The output from <command>showmount</command> shows - <filename class="directory">/usr</filename> as an export. + <filename>/usr</filename> as an export. When changing directories to - <filename class="directory">/host/foobar/usr</filename>, + <filename>/host/foobar/usr</filename>, <application>amd</application> intercepts the request and - attempts to resolve the hostname <hostid>foobar</hostid>. If + attempts to resolve the hostname <systemitem>foobar</systemitem>. If successful, <application>amd</application> automatically mounts the desired export.</para> @@ -1015,7 +1012,7 @@ Exports list on foobar: </sect2> </sect1> - <sect1 id="network-nis"> + <sect1 xml:id="network-nis"> <!-- <sect1info> <authorgroup> @@ -1260,33 +1257,33 @@ Exports list on foobar: <tbody> <row> - <entry><hostid>ellington</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.2</hostid></entry> + <entry><systemitem>ellington</systemitem></entry> + <entry><systemitem class="ipaddress">10.0.0.2</systemitem></entry> <entry><acronym>NIS</acronym> master</entry> </row> <row> - <entry><hostid>coltrane</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.3</hostid></entry> + <entry><systemitem>coltrane</systemitem></entry> + <entry><systemitem class="ipaddress">10.0.0.3</systemitem></entry> <entry><acronym>NIS</acronym> slave</entry> </row> <row> - <entry><hostid>basie</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.4</hostid></entry> + <entry><systemitem>basie</systemitem></entry> + <entry><systemitem class="ipaddress">10.0.0.4</systemitem></entry> <entry>Faculty workstation</entry> </row> <row> - <entry><hostid>bird</hostid></entry> - <entry><hostid role="ipaddr">10.0.0.5</hostid></entry> + <entry><systemitem>bird</systemitem></entry> + <entry><systemitem class="ipaddress">10.0.0.5</systemitem></entry> <entry>Client machine</entry> </row> <row> - <entry><hostid>cli[1-11]</hostid></entry> + <entry><systemitem>cli[1-11]</systemitem></entry> <entry> - <hostid role="ipaddr">10.0.0.[6-17]</hostid></entry> + <systemitem class="ipaddress">10.0.0.[6-17]</systemitem></entry> <entry>Other client machines</entry> </row> </tbody> @@ -1445,8 +1442,7 @@ nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</ <secondary>maps</secondary> </indexterm> <para><acronym>NIS</acronym> maps - are generated from the configuration files in <filename - class="directory">/etc</filename> on the + are generated from the configuration files in <filename>/etc</filename> on the <acronym>NIS</acronym> master, with one exception: <filename>/etc/master.passwd</filename>. This is to prevent the propagation of passwords to all the servers in @@ -1461,7 +1457,7 @@ nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</ <para>It is advisable to remove all entries for system accounts as well as any user accounts that do not need to be propagated to the <acronym>NIS</acronym> clients, such - as the <username>root</username> and any other + as the <systemitem class="username">root</systemitem> and any other administrative accounts.</para> <note><para>Ensure that the @@ -1523,7 +1519,7 @@ ellington has been setup as an YP master server without any errors.</screen> Until this occurs, the new user will not be able to login anywhere except on the <acronym>NIS</acronym> master. For example, to add the new user - <username>jsmith</username> to the + <systemitem class="username">jsmith</systemitem> to the <literal>test-domain</literal> domain, run these commands on the master server:</para> @@ -1615,8 +1611,7 @@ coltrane has been setup as an YP slave server without any errors. Remember to update map ypservers on ellington.</screen> <para>This will generate a directory on the slave server - called <filename - class="directory">/var/yp/test-domain</filename> which + called <filename>/var/yp/test-domain</filename> which contains copies of the <acronym>NIS</acronym> master server's maps. Adding these <filename>/etc/crontab</filename> entries on each slave @@ -1688,7 +1683,7 @@ nis_client_enable="YES"</programlisting> <filename>/etc/master.passwd</filename>. When removing the accounts, keep in mind that at least one local account should remain and this account should be - a member of <groupname>wheel</groupname>. If there is + a member of <systemitem class="groupname">wheel</systemitem>. If there is a problem with <acronym>NIS</acronym>, this local account can be used to log in remotely, become the superuser, and fix the problem. Before saving the @@ -1798,7 +1793,7 @@ nis_client_enable="YES"</programlisting> <sect3> <title>Barring Some Users</title> - <para>In this example, the <hostid>basie</hostid> system + <para>In this example, the <systemitem>basie</systemitem> system is a faculty workstation within the <acronym>NIS</acronym> domain. The <filename>passwd</filename> map on the master <acronym>NIS</acronym> server contains accounts for both @@ -1810,15 +1805,15 @@ nis_client_enable="YES"</programlisting> system, even if they are present in the <acronym>NIS</acronym> database, use <command>vipw</command> to add - <literal>-<replaceable>username</replaceable></literal> with + <literal>-username</literal> with the correct number of colons towards the end of <filename>/etc/master.passwd</filename> on the client, where <replaceable>username</replaceable> is the username of a user to bar from logging in. The line with the blocked user must be before the <literal>+</literal> line that allows <acronym>NIS</acronym> users. In this example, - <username>bill</username> is barred from logging on to - <hostid>basie</hostid>:</para> + <systemitem class="username">bill</systemitem> is barred from logging on to + <systemitem>basie</systemitem>:</para> <screen>basie&prompt.root; <userinput>cat /etc/master.passwd</userinput> root:[password]:0:0::0:0:The super-user:/root:/bin/csh @@ -1843,7 +1838,7 @@ basie&prompt.root;</screen> </sect3> </sect2> - <sect2 id="network-netgroups"> + <sect2 xml:id="network-netgroups"> <!-- <sect2info> <authorgroup> @@ -1888,27 +1883,27 @@ basie&prompt.root;</screen> <tbody> <row> - <entry><username>alpha</username>, - <username>beta</username></entry> + <entry><systemitem class="username">alpha</systemitem>, + <systemitem class="username">beta</systemitem></entry> <entry>IT department employees</entry> </row> <row> - <entry><username>charlie</username>, - <username>delta</username></entry> + <entry><systemitem class="username">charlie</systemitem>, + <systemitem class="username">delta</systemitem></entry> <entry>IT department apprentices</entry> </row> <row> - <entry><username>echo</username>, - <username>foxtrott</username>, - <username>golf</username>, ...</entry> + <entry><systemitem class="username">echo</systemitem>, + <systemitem class="username">foxtrott</systemitem>, + <systemitem class="username">golf</systemitem>, ...</entry> <entry>employees</entry> </row> <row> - <entry><username>able</username>, - <username>baker</username>, ...</entry> + <entry><systemitem class="username">able</systemitem>, + <systemitem class="username">baker</systemitem>, ...</entry> <entry>interns</entry> </row> </tbody> @@ -1930,32 +1925,32 @@ basie&prompt.root;</screen> <row> <!-- Names taken from "Good Omens" by Neil Gaiman and Terry Pratchett. Many thanks for a brilliant book. --> - <entry><hostid>war</hostid>, - <hostid>death</hostid>, <hostid>famine</hostid>, - <hostid>pollution</hostid></entry> + <entry><systemitem>war</systemitem>, + <systemitem>death</systemitem>, <systemitem>famine</systemitem>, + <systemitem>pollution</systemitem></entry> <entry>Only IT employees are allowed to log onto these servers.</entry> </row> <row> <!-- gluttony was omitted because it was too fat --> - <entry><hostid>pride</hostid>, <hostid>greed</hostid>, - <hostid>envy</hostid>, <hostid>wrath</hostid>, - <hostid>lust</hostid>, <hostid>sloth</hostid></entry> + <entry><systemitem>pride</systemitem>, <systemitem>greed</systemitem>, + <systemitem>envy</systemitem>, <systemitem>wrath</systemitem>, + <systemitem>lust</systemitem>, <systemitem>sloth</systemitem></entry> <entry>All members of the IT department are allowed to login onto these servers.</entry> </row> <row> - <entry><hostid>one</hostid>, <hostid>two</hostid>, - <hostid>three</hostid>, <hostid>four</hostid>, + <entry><systemitem>one</systemitem>, <systemitem>two</systemitem>, + <systemitem>three</systemitem>, <systemitem>four</systemitem>, ...</entry> <entry>Ordinary workstations used by employees.</entry> </row> <row> - <entry><hostid>trashcan</hostid></entry> + <entry><systemitem>trashcan</systemitem></entry> <entry>A very old machine without any critical data. Even interns are allowed to use this system.</entry> </row> @@ -2062,7 +2057,7 @@ ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen> <para>To configure a client, use &man.vipw.8; to specify the name of the netgroup. For example, on the server named - <hostid>war</hostid>, replace this line:</para> + <systemitem>war</systemitem>, replace this line:</para> <programlisting>+:::::::::</programlisting> @@ -2079,7 +2074,7 @@ ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen> <literal>~</literal> function of the shell and all routines which convert between user names and numerical user IDs. In other words, - <command>cd ~<replaceable>user</replaceable></command> will + <command>cd ~user</command> will not work, <command>ls -l</command> will show the numerical ID instead of the username, and <command>find . -user joe -print</command> will fail with the message @@ -2249,7 +2244,7 @@ TWO (,hotel,test-domain) </sect2> </sect1> - <sect1 id="network-ldap"> + <sect1 xml:id="network-ldap"> <!-- <sect1info> <authorgroup> @@ -2349,7 +2344,7 @@ result: 0 Success server, the OpenLDAP port needs installed. This may be accomplished using the <command>pkg_add</command> command or by installing the - <filename role="port">net/openldap24-server</filename> + <package role="port">net/openldap24-server</package> port. Building the port is recommended as the administrator may select a great deal of options at this time and disable some options. In most cases, the defaults will be fine; @@ -2378,8 +2373,7 @@ result: 0 Success during the certificate creation process below.</para> <para>The following commands must be executed in the - <filename - class="directory">/usr/local/etc/openldap/private</filename> + <filename>/usr/local/etc/openldap/private</filename> directory. This is important as the file permissions will need to be restrictive and users should not have access to these files directly. To create the certificates, issues the @@ -2557,7 +2551,7 @@ cn: Manager</programlisting> <para>To import this datafile, issue the following command, assuming the file is <filename>import.ldif</filename>:</para> - <screen>&prompt.root; <userinput>ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f <replaceable>import.ldif</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f import.ldif</userinput></screen> <para>There will be a request for the password specified earlier, and the output should look like this:</para> @@ -2607,7 +2601,7 @@ result: 0 Success </sect2> </sect1> - <sect1 id="network-dhcp"> + <sect1 xml:id="network-dhcp"> <!-- <sect1info> <authorgroup> @@ -2638,10 +2632,8 @@ result: 0 Success by the client to obtain the addressing information. &os; does not install a <acronym>DHCP</acronym> server, but several servers are available in the &os; Ports Collection. The - <acronym>DHCP</acronym> protocol is fully described in <ulink - url="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</ulink>. - Informational resources are also available at <ulink - url="http://www.isc.org/downloads/dhcp/">isc.org/downloads/dhcp/</ulink>.</para> + <acronym>DHCP</acronym> protocol is fully described in <link xlink:href="http://www.freesoft.org/CIE/RFC/2131/">RFC 2131</link>. + Informational resources are also available at <link xlink:href="http://www.isc.org/downloads/dhcp/">isc.org/downloads/dhcp/</link>.</para> <para>This section describes how to use the built-in <acronym>DHCP</acronym> client. It then describes how to @@ -2655,7 +2647,7 @@ result: 0 Success &os;. Users who prefer to create a custom kernel need to keep this device if <acronym>DHCP</acronym> is used.</para> - <para>It should be noted that <devicename>bpf</devicename> also + <para>It should be noted that <filename>bpf</filename> also allows privileged users to run network packet sniffers on that system.</para> </note> @@ -2762,7 +2754,7 @@ result: 0 Success </listitem> <listitem> - <para><filename>/var/db/dhclient.leases.<replaceable>interface</replaceable></filename></para> + <para><filename>/var/db/dhclient.leases.interface</filename></para> <para>The <acronym>DHCP</acronym> client keeps a database of valid leases in this file, which is written as a log and @@ -2771,7 +2763,7 @@ result: 0 Success </itemizedlist> </sect2> - <sect2 id="network-dhcp-server"> + <sect2 xml:id="network-dhcp-server"> <title>Installing and Configuring a <acronym>DHCP</acronym> Server</title> @@ -2779,8 +2771,7 @@ result: 0 Success to act as a <acronym>DHCP</acronym> server using the Internet Systems Consortium (<acronym>ISC</acronym>) implementation of the <acronym>DHCP</acronym> server. This implementation and - its documentation can be installed using the <filename - role="package">net/isc-dhcp42-server</filename> package or + its documentation can be installed using the <package>net/isc-dhcp42-server</package> package or port.</para> <indexterm> @@ -2793,8 +2784,7 @@ result: 0 Success <secondary>installation</secondary> </indexterm> - <para>The installation of <filename - role="package">net/isc-dhcp42-server</filename> installs a + <para>The installation of <package>net/isc-dhcp42-server</package> installs a sample configuration file. Copy <filename>/usr/local/etc/dhcpd.conf.example</filename> to <filename>/usr/local/etc/dhcpd.conf</filename> and make any @@ -2809,22 +2799,22 @@ result: 0 Success provided to <acronym>DHCP</acronym> clients. For example, these lines configure the following:</para> - <programlisting>option domain-name "example.org";<co id="domain-name"/> -option domain-name-servers ns1.example.org;<co id="domain-name-servers"/> -option subnet-mask 255.255.255.0;<co id="subnet-mask"/> + <programlisting>option domain-name "example.org";<co xml:id="domain-name"/> +option domain-name-servers ns1.example.org;<co xml:id="domain-name-servers"/> +option subnet-mask 255.255.255.0;<co xml:id="subnet-mask"/> -default-lease-time 600;<co id="default-lease-time"/> -max-lease-time 72400;<co id="max-lease-time"/> -ddns-update-style none;<co id="ddns-update-style"/> +default-lease-time 600;<co xml:id="default-lease-time"/> +max-lease-time 72400;<co xml:id="max-lease-time"/> +ddns-update-style none;<co xml:id="ddns-update-style"/> subnet 10.254.239.0 netmask 255.255.255.224 { - range 10.254.239.10 10.254.239.20;<co id="range"/> - option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;<co id="routers"/> + range 10.254.239.10 10.254.239.20;<co xml:id="range"/> + option routers rtr-239-0-1.example.org, rtr-239-0-2.example.org;<co xml:id="routers"/> } host fantasia { - hardware ethernet 08:00:07:26:c0:a5;<co id="hardware"/> - fixed-address fantasia.fugue.com;<co id="fixed-address"/> + hardware ethernet 08:00:07:26:c0:a5;<co xml:id="hardware"/> + fixed-address fantasia.fugue.com;<co xml:id="fixed-address"/> }</programlisting> <calloutlist> @@ -2973,8 +2963,7 @@ dhcpd_ifaces="dc0"</programlisting> one <acronym>DHCP</acronym> server forwards a request from a client to another <acronym>DHCP</acronym> server on a separate network. If this functionality is - required, install the <filename - role="package">net/isc-dhcp42-relay</filename> + required, install the <package>net/isc-dhcp42-relay</package> package or port. The installation includes dhcrelay(8) which provides more detail.</para> </listitem> @@ -2982,7 +2971,7 @@ dhcpd_ifaces="dc0"</programlisting> </sect2> </sect1> - <sect1 id="network-dns"> + <sect1 xml:id="network-dns"> <!-- <sect1info> <authorgroup> @@ -3015,8 +3004,7 @@ dhcpd_ifaces="dc0"</programlisting> is the most common implementation of the <acronym>DNS</acronym> protocol. The &os; version provides enhanced security features, a new file system layout, and automated &man.chroot.8; - configuration. BIND is maintained by the <ulink - url="https://www.isc.org/">isc.org</ulink>. It is not + configuration. BIND is maintained by the <link xlink:href="https://www.isc.org/">isc.org</link>. It is not necessary to run a name server to perform <acronym>DNS</acronym> lookups on a system.</para> @@ -3105,36 +3093,34 @@ dhcpd_ifaces="dc0"</programlisting> <itemizedlist> <listitem> - <para><hostid>.</hostid> is how the root zone is usually + <para><systemitem>.</systemitem> is how the root zone is usually referred to in documentation.</para> </listitem> <listitem> - <para><hostid>org.</hostid> is a Top Level Domain + <para><systemitem>org.</systemitem> is a Top Level Domain (<acronym>TLD</acronym>) under the root zone.</para> </listitem> <listitem> - <para><hostid role="domainname">example.org.</hostid> is a - zone under the <hostid>org.</hostid> + <para><systemitem class="fqdomainname">example.org.</systemitem> is a + zone under the <systemitem>org.</systemitem> <acronym>TLD</acronym>.</para> </listitem> <listitem> - <para><hostid>1.168.192.in-addr.arpa</hostid> is a zone + <para><systemitem>1.168.192.in-addr.arpa</systemitem> is a zone referencing all <acronym>IP</acronym> addresses which fall - under the <hostid role="ipaddr">192.168.1.*</hostid> + under the <systemitem class="ipaddress">192.168.1.*</systemitem> <acronym>IP</acronym> address space.</para> </listitem> </itemizedlist> <para>As one can see, the more specific part of a hostname - appears to its left. For example, <hostid - role="domainname">example.org.</hostid> is more specific than - <hostid>org.</hostid>, as <hostid>org.</hostid> is more specific + appears to its left. For example, <systemitem class="fqdomainname">example.org.</systemitem> is more specific than + <systemitem>org.</systemitem>, as <systemitem>org.</systemitem> is more specific than the root zone. The layout of each part of a hostname is - much like a file system: the <filename - class="directory">/dev</filename> directory falls within the + much like a file system: the <filename>/dev</filename> directory falls within the root, and so on.</para> <sect2> @@ -3154,7 +3140,7 @@ dhcpd_ifaces="dc0"</programlisting> <listitem> <para>A domain, such as - <hostid role="domainname">example.org</hostid>, is + <systemitem class="fqdomainname">example.org</systemitem>, is registered and <acronym>IP</acronym> addresses need to be assigned to hostnames under it.</para> </listitem> @@ -3182,7 +3168,7 @@ dhcpd_ifaces="dc0"</programlisting> </itemizedlist> <para>When one queries for - <hostid role="fqdn">www.FreeBSD.org</hostid>, the resolver + <systemitem class="fqdomainname">www.FreeBSD.org</systemitem>, the resolver usually queries the uplink <acronym>ISP</acronym>'s name server, and retrieves the reply. With a local, caching <acronym>DNS</acronym> server, the query only has to be made @@ -3219,8 +3205,7 @@ dhcpd_ifaces="dc0"</programlisting> </row> <row> - <entry><filename - class="directory">/etc/namedb</filename></entry> + <entry><filename>/etc/namedb</filename></entry> <entry>Directory where BIND zone information resides.</entry> </row> @@ -3235,10 +3220,10 @@ dhcpd_ifaces="dc0"</programlisting> <para>Depending on how a given zone is configured on the server, the files related to that zone can be found in the - <filename class="directory">master</filename>, - <filename class="directory">slave</filename>, or - <filename class="directory">dynamic</filename> subdirectories - of the <filename class="directory">/etc/namedb</filename> + <filename>master</filename>, + <filename>slave</filename>, or + <filename>dynamic</filename> subdirectories + of the <filename>/etc/namedb</filename> directory. These files contain the <acronym>DNS</acronym> information that will be given out by the name server in response to queries.</para> @@ -3274,7 +3259,7 @@ dhcpd_ifaces="dc0"</programlisting> <filename>/etc/namedb/named.conf</filename> that are beyond the scope of this document. Other startup options for <application>named</application> on &os; can be found in - the <literal>named_<replaceable>*</replaceable></literal> + the <literal>named_*</literal> flags in <filename>/etc/defaults/rc.conf</filename> and in &man.rc.conf.5;. The <xref linkend="configtuning-rcd"/> section is also a good @@ -3291,7 +3276,7 @@ dhcpd_ifaces="dc0"</programlisting> <para>Configuration files for <application>named</application> currently reside in - <filename class="directory">/etc/namedb</filename> directory + <filename>/etc/namedb</filename> directory and will need modification before use unless all that is needed is a simple resolver. This is where most of the configuration will be performed.</para> @@ -3366,7 +3351,7 @@ options { name server, enabling this may be worthwhile.</para> <warning> - <para><hostid role="ipaddr">127.0.0.1</hostid> will + <para><systemitem class="ipaddress">127.0.0.1</systemitem> will <emphasis>not</emphasis> work here. Change this <acronym>IP</acronym> address to a name server at the uplink.</para> @@ -3618,7 +3603,7 @@ zone "1.168.192.in-addr.arpa" { to <filename>named.conf</filename>.</para> <para>For example, the simplest zone entry for - <hostid role="domainname">example.org</hostid> can look + <systemitem class="fqdomainname">example.org</systemitem> can look like:</para> <programlisting>zone "example.org" { @@ -3654,7 +3639,7 @@ zone "1.168.192.in-addr.arpa" { </indexterm> <para>An example master zone file for - <hostid role="domainname">example.org</hostid> (existing + <systemitem class="fqdomainname">example.org</systemitem> (existing within <filename>/etc/namedb/master/example.org</filename>) is as follows:</para> @@ -3691,7 +3676,7 @@ www IN CNAME example.org.</programlisting> an exact hostname, whereas everything without a trailing <quote>.</quote> is relative to the origin. For example, <literal>ns1</literal> is translated into - <literal>ns1.<replaceable>example.org.</replaceable></literal></para> + <literal>ns1.example.org.</literal></para> <para>The format of a zone file follows:</para> @@ -3757,8 +3742,7 @@ www IN CNAME example.org.</programlisting> <variablelist> <varlistentry> - <term><hostid - role="domainname">example.org.</hostid></term> + <term><systemitem class="fqdomainname">example.org.</systemitem></term> <listitem> <para>the domain name, also the origin for this @@ -3767,7 +3751,7 @@ www IN CNAME example.org.</programlisting> </varlistentry> <varlistentry> - <term><hostid role="fqdn">ns1.example.org.</hostid></term> + <term><systemitem class="fqdomainname">ns1.example.org.</systemitem></term> <listitem> <para>the primary/authoritative name server for this @@ -3817,24 +3801,24 @@ mx IN A 192.168.1.4 mail IN A 192.168.1.5</programlisting> <para>The A record indicates machine names. As seen above, - <hostid role="fqdn">ns1.example.org</hostid> would resolve - to <hostid role="ipaddr">192.168.1.2</hostid>.</para> + <systemitem class="fqdomainname">ns1.example.org</systemitem> would resolve + to <systemitem class="ipaddress">192.168.1.2</systemitem>.</para> <programlisting> IN A 192.168.1.1</programlisting> <para>This line assigns <acronym>IP</acronym> address - <hostid role="ipaddr">192.168.1.1</hostid> to the current + <systemitem class="ipaddress">192.168.1.1</systemitem> to the current origin, in this case - <hostid role="domainname">example.org</hostid>.</para> + <systemitem class="fqdomainname">example.org</systemitem>.</para> <programlisting>www IN CNAME @</programlisting> <para>The canonical name record is usually used for giving - aliases to a machine. In the example, <hostid>www</hostid> + aliases to a machine. In the example, <systemitem>www</systemitem> is aliased to the <quote>master</quote> machine whose name happens to be the same as the domain name - <hostid role="domainname">example.org</hostid> - (<hostid role="ipaddr">192.168.1.1</hostid>). CNAMEs can + <systemitem class="fqdomainname">example.org</systemitem> + (<systemitem class="ipaddress">192.168.1.1</systemitem>). CNAMEs can never be used together with another kind of record for the same hostname.</para> @@ -3846,13 +3830,13 @@ mail IN A 192.168.1.5</programlisting> <para>The MX record indicates which mail servers are responsible for handling incoming mail for the zone. - <hostid role="fqdn">mail.example.org</hostid> is the + <systemitem class="fqdomainname">mail.example.org</systemitem> is the hostname of a mail server, and 10 is the priority of that mail server.</para> <para>One can have several mail servers, with priorities of 10, 20 and so on. A mail server attempting to deliver to - <hostid role="domainname">example.org</hostid> would first + <systemitem class="fqdomainname">example.org</systemitem> would first try the highest priority MX (the record with the lowest priority number), then the second highest, etc, until the mail can be properly delivered.</para> @@ -3902,9 +3886,7 @@ mail IN A 192.168.1.5</programlisting> </sect2> <sect2> - <title><acronym - role="Domain Name Security - Extensions">DNSSEC</acronym></title> + <title><acronym role="Domain Name Security Extensions">DNSSEC</acronym></title> <indexterm> <primary>BIND</primary> @@ -3912,20 +3894,17 @@ mail IN A 192.168.1.5</programlisting> extensions</secondary> </indexterm> - <para>Domain Name System Security Extensions, or <acronym - role="Domain Name Security Extensions">DNSSEC</acronym> for + <para>Domain Name System Security Extensions, or <acronym role="Domain Name Security Extensions">DNSSEC</acronym> for short, is a suite of specifications to protect resolving name servers from forged <acronym>DNS</acronym> data, such as spoofed <acronym>DNS</acronym> records. By using digital signatures, a resolver can verify the integrity of the record. - Note that <acronym role="Domain Name Security - Extensions">DNSSEC</acronym> only provides integrity via - digitally signing the Resource Records (<acronym - role="Resource Record">RR</acronym>s). It provides neither + Note that <acronym role="Domain Name Security Extensions">DNSSEC</acronym> only provides integrity via + digitally signing the Resource Records (<acronym role="Resource Record">RR</acronym>s). It provides neither confidentiality nor protection against false end-user assumptions. This means that it cannot protect against people - going to <hostid role="domainname">example.net</hostid> - instead of <hostid role="domainname">example.com</hostid>. + going to <systemitem class="fqdomainname">example.net</systemitem> + instead of <systemitem class="fqdomainname">example.com</systemitem>. The only thing <acronym>DNSSEC</acronym> does is authenticate that the data has not been compromised in transit. The security of <acronym>DNS</acronym> is an important step in @@ -4021,13 +4000,11 @@ mail IN A 192.168.1.5</programlisting> . IN DS 19036 8 2 49AAC11D7B6F6446702E54A1607371607A1A41855200FD2CE1CDDE32F24E8FB5</programlisting> <para>The SHA-256 <acronym>RR</acronym> can now be compared to - the digest in <ulink - url="https://data.iana.org/root-anchors/root-anchors.xml">https://data.iana.org/root-anchors/root-anchors.xml</ulink>. + the digest in <link xlink:href="https://data.iana.org/root-anchors/root-anchors.xml">https://data.iana.org/root-anchors/root-anchors.xml</link>. To be absolutely sure that the key has not been tampered with the data in the <acronym>XML</acronym> file can be verified using the <acronym>PGP</acronym> signature in - <ulink - url="https://data.iana.org/root-anchors/root-anchors.asc">https://data.iana.org/root-anchors/root-anchors.asc</ulink>.</para> + <link xlink:href="https://data.iana.org/root-anchors/root-anchors.asc">https://data.iana.org/root-anchors/root-anchors.asc</link>.</para> <para>Next, the key must be formatted properly. This differs a little between <acronym>BIND</acronym> versions 9.6.2 and @@ -4081,7 +4058,7 @@ dnssec-validation yes;</programlisting> will contain the <literal>AD</literal> flag to indicate the data was authenticated. Running a query such as</para> - <screen>&prompt.user; <userinput>dig @<replaceable>resolver</replaceable> +dnssec se ds </userinput></screen> + <screen>&prompt.user; <userinput>dig @resolver +dnssec se ds </userinput></screen> <para>should return the <acronym>DS</acronym> <acronym>RR</acronym> for the <literal>.se</literal> zone. @@ -4097,7 +4074,7 @@ dnssec-validation yes;</programlisting> <acronym>DNS</acronym> queries.</para> </sect3> - <sect3 id="dns-dnssec-auth"> + <sect3 xml:id="dns-dnssec-auth"> <title>Authoritative <acronym>DNS</acronym> Server Configuration</title> @@ -4111,17 +4088,14 @@ dnssec-validation yes;</programlisting> not rotated very often and a Zone Signing Key (<acronym role="Zone Signing Key">ZSK</acronym>) that is rotated more frequently. Information on recommended - operational practices can be found in <ulink - url="http://tools.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym> + operational practices can be found in <link xlink:href="http://tools.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym> 4641: <acronym>DNSSEC</acronym> Operational - Practices</ulink>. Practices regarding the root zone can - be found in <ulink - url="http://www.root-dnssec.org/wp-content/uploads/2010/06/icann-dps-00.txt"><acronym>DNSSEC</acronym> + Practices</link>. Practices regarding the root zone can + be found in <link xlink:href="http://www.root-dnssec.org/wp-content/uploads/2010/06/icann-dps-00.txt"><acronym>DNSSEC</acronym> Practice Statement for the Root Zone - <acronym>KSK</acronym> operator</ulink> and <ulink - url="http://www.root-dnssec.org/wp-content/uploads/2010/06/vrsn-dps-00.txt"><acronym>DNSSEC</acronym> + <acronym>KSK</acronym> operator</link> and <link xlink:href="http://www.root-dnssec.org/wp-content/uploads/2010/06/vrsn-dps-00.txt"><acronym>DNSSEC</acronym> Practice Statement for the Root Zone - <acronym>ZSK</acronym> operator</ulink>. The + <acronym>ZSK</acronym> operator</link>. The <acronym role="Key Signing Key">KSK</acronym> is used to build a chain of authority to the data in need of validation and as such is also called a Secure Entry Point @@ -4135,7 +4109,7 @@ dnssec-validation yes;</programlisting> there.</para> <para>To enable <acronym>DNSSEC</acronym> for the - <hostid role="domainname">example.com</hostid> zone depicted + <systemitem class="fqdomainname">example.com</systemitem> zone depicted in previous examples, the first step is to use <application>dnssec-keygen</application> to generate the <acronym>KSK</acronym> and <acronym>ZSK</acronym> key pair. @@ -4143,7 +4117,7 @@ dnssec-validation yes;</programlisting> algorithms. It is recommended to use RSA/SHA256 for the keys and 2048 bits key length should be enough. To generate the <acronym>KSK</acronym> for - <hostid role="domainname">example.com</hostid>, run</para> + <systemitem class="fqdomainname">example.com</systemitem>, run</para> <screen>&prompt.user; <userinput>dnssec-keygen -f KSK -a RSASHA256 -b 2048 -n ZONE example.com</userinput></screen> @@ -4179,7 +4153,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> to use the signed zone file. To sign a zone <application>dnssec-signzone</application> is used. The command to sign the zone - <hostid role="domainname">example.com</hostid>, located in + <systemitem class="fqdomainname">example.com</systemitem>, located in <filename>example.com.db</filename> would look similar to</para> @@ -4222,10 +4196,9 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> the new key has propagated through the <acronym>DNS</acronym> hierarchy. For more information on key rollovers and other <acronym>DNSSEC</acronym> - operational issues, see <ulink - url="http://www.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym> + operational issues, see <link xlink:href="http://www.ietf.org/rfc/rfc4641.txt"><acronym>RFC</acronym> 4641: <acronym>DNSSEC</acronym> Operational - practices</ulink>.</para> + practices</link>.</para> </sect3> <sect3> @@ -4247,7 +4220,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> option <option>sign</option>. To tell <acronym>BIND</acronym> to use this automatic signing and zone updating for - <hostid role="domainname">example.com</hostid>, add the + <systemitem class="fqdomainname">example.com</systemitem>, add the following to <filename>named.conf</filename>:</para> <programlisting>zone example.com { @@ -4286,7 +4259,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <acronym>DNS</acronym> service attacks.</para> <para>It is always good idea to read - <ulink url="http://www.cert.org/">CERT</ulink>'s security + <link xlink:href="http://www.cert.org/">CERT</link>'s security advisories and to subscribe to the &a.security-notifications; to stay up to date with the current Internet and &os; security issues.</para> @@ -4298,7 +4271,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> </tip> </sect2> - <sect2 id="dns-read"> + <sect2 xml:id="dns-read"> <title>Further Reading</title> <para>BIND/<application>named</application> manual pages: @@ -4307,89 +4280,77 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <itemizedlist> <listitem> - <para><ulink - url="https://www.isc.org/software/bind">Official ISC - BIND Page</ulink></para> + <para><link xlink:href="https://www.isc.org/software/bind">Official ISC + BIND Page</link></para> </listitem> <listitem> - <para><ulink - url="https://www.isc.org/software/guild">Official ISC - BIND Forum</ulink></para> + <para><link xlink:href="https://www.isc.org/software/guild">Official ISC + BIND Forum</link></para> </listitem> <listitem> - <para><ulink - url="http://www.oreilly.com/catalog/dns5/">O'Reilly + <para><link xlink:href="http://www.oreilly.com/catalog/dns5/">O'Reilly <acronym>DNS</acronym> and BIND 5th - Edition</ulink></para> + Edition</link></para> </listitem> <listitem> - <para><ulink - url="http://www.root-dnssec.org/documentation/">Root - <acronym>DNSSEC</acronym></ulink></para> + <para><link xlink:href="http://www.root-dnssec.org/documentation/">Root + <acronym>DNSSEC</acronym></link></para> </listitem> <listitem> - <para><ulink - url="http://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html"><acronym>DNSSEC</acronym> + <para><link xlink:href="http://data.iana.org/root-anchors/draft-icann-dnssec-trust-anchor.html"><acronym>DNSSEC</acronym> Trust Anchor Publication for the Root - Zone</ulink></para> + Zone</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc1034">RFC1034 - - Domain Names - Concepts and Facilities</ulink></para> + <para><link xlink:href="http://tools.ietf.org/html/rfc1034">RFC1034 + - Domain Names - Concepts and Facilities</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc1035">RFC1035 + <para><link xlink:href="http://tools.ietf.org/html/rfc1035">RFC1035 - Domain Names - Implementation and - Specification</ulink></para> + Specification</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc4033">RFC4033 + <para><link xlink:href="http://tools.ietf.org/html/rfc4033">RFC4033 - <acronym>DNS</acronym> Security Introduction and - Requirements</ulink></para> + Requirements</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc4034">RFC4034 + <para><link xlink:href="http://tools.ietf.org/html/rfc4034">RFC4034 - Resource Records for the <acronym>DNS</acronym> - Security Extensions</ulink></para> + Security Extensions</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc4035">RFC4035 + <para><link xlink:href="http://tools.ietf.org/html/rfc4035">RFC4035 - Protocol Modifications for the <acronym>DNS</acronym> - Security Extensions</ulink></para> + Security Extensions</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc4641">RFC4641 - - DNSSEC Operational Practices</ulink></para> + <para><link xlink:href="http://tools.ietf.org/html/rfc4641">RFC4641 + - DNSSEC Operational Practices</link></para> </listitem> <listitem> - <para><ulink - url="http://tools.ietf.org/html/rfc5011">RFC 5011 + <para><link xlink:href="http://tools.ietf.org/html/rfc5011">RFC 5011 - Automated Updates of <acronym>DNS</acronym> Security (<acronym>DNSSEC</acronym> - Trust Anchors</ulink></para> + Trust Anchors</link></para> </listitem> </itemizedlist> </sect2> </sect1> - <sect1 id="network-apache"> + <sect1 xml:id="network-apache"> <!-- <sect1info> <authorgroup> @@ -4410,16 +4371,14 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <para>The open source <application>Apache HTTP Server </application> is the most widely used web server. &os; does not install this web server by default, but it can be installed - from the <filename - role="package">www/apache24</filename> package or port.</para> + from the <package>www/apache24</package> package or port.</para> <para>This section summarizes how to configure and start version 2.<replaceable>x</replaceable> of the <application>Apache HTTP Server</application>, the most widely used version, on &os;. For more detailed information about <application>Apache</application> 2.X and its configuration - directives, refer to <ulink - url="http://httpd.apache.org/">httpd.apache.org</ulink>.</para> + directives, refer to <link xlink:href="http://httpd.apache.org/">httpd.apache.org</link>.</para> <sect2> <title>Configuring and Starting Apache</title> @@ -4429,7 +4388,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <para>In &os;, the main <application>Apache HTTP Server</application> configuration file is installed as - <filename>/usr/local/etc/apache2<replaceable>x</replaceable>/httpd.conf</filename>. + <filename>/usr/local/etc/apache2x/httpd.conf</filename>. This ASCII text file begins comment lines with the <literal>#</literal>. The most frequently modified directives are:</para> @@ -4442,11 +4401,10 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <para>Specifies the default directory hierarchy for the <application>Apache</application> installation. Binaries are stored in the - <filename class="directory">bin</filename> and - <filename class="directory">sbin</filename> + <filename>bin</filename> and + <filename>sbin</filename> subdirectories of the server root, and configuration - files are stored in <filename - class="directory">etc/apache2<replaceable>x</replaceable></filename>.</para> + files are stored in <filename>etc/apache2x</filename>.</para> </listitem> </varlistentry> @@ -4467,14 +4425,14 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <para>Allows an administrator to set a host name which is sent back to clients for the server. For example, - <hostid>www</hostid> can be used instead of the actual + <systemitem>www</systemitem> can be used instead of the actual host name.</para> </listitem> </varlistentry> <varlistentry> <term><literal>DocumentRoot - "/usr/local/www/apache2<replaceable>x</replaceable>/data"</literal></term> + "/usr/local/www/apache2x/data"</literal></term> <listitem> <para>The directory @@ -4497,11 +4455,10 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <indexterm><primary>Apache</primary> <secondary>starting or stopping</secondary></indexterm> - <para>The <filename role="package">www/apache24</filename> port + <para>The <package>www/apache24</package> port installs an &man.rc.8; script to aid in starting, stopping, and restarting <application>Apache</application>, which can be - found in <filename - class="directory">/usr/local/etc/rc.d/</filename>.</para> + found in <filename>/usr/local/etc/rc.d/</filename>.</para> <para>To launch <application>Apache</application> at system startup, add the following line to @@ -4539,8 +4496,7 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <screen>&prompt.root; <userinput>service apache24 start</userinput></screen> <para>The <command>httpd</command> service can be tested by - entering <literal>http://<hostid - role="fqdn"><replaceable>localhost</replaceable></hostid></literal> + entering <literal>http://localhost</literal> in a web browser, replacing <replaceable>localhost</replaceable> with the fully-qualified domain name of the machine running <command>httpd</command>, @@ -4566,9 +4522,9 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <programlisting>NameVirtualHost *</programlisting> <para>If the webserver was named - <hostid role="fqdn">www.domain.tld</hostid> and + <systemitem class="fqdomainname">www.domain.tld</systemitem> and a virtual domain for - <hostid role="fqdn">www.someotherdomain.tld</hostid> then + <systemitem class="fqdomainname">www.someotherdomain.tld</systemitem> then add the following entries to <filename>httpd.conf</filename>:</para> @@ -4587,8 +4543,7 @@ DocumentRoot /www/someotherdomain.tld <para>For more information about setting up virtual hosts, please consult the official <application>Apache</application> - documentation at: <ulink - url="http://httpd.apache.org/docs/vhosts/"></ulink>.</para> + documentation at: <uri xlink:href="http://httpd.apache.org/docs/vhosts/">http://httpd.apache.org/docs/vhosts/</uri>.</para> </sect2> <sect2> @@ -4680,7 +4635,7 @@ DocumentRoot /www/someotherdomain.tld these pre-requisites with the appropriate flags.</para> - <example id="network-www-django-install"> + <example xml:id="network-www-django-install"> <title>Installing Django with <application>Apache2</application>, <application>mod_python3</application>, and @@ -4695,7 +4650,7 @@ DocumentRoot /www/someotherdomain.tld interpreter. This will be the interpreter to call the application for specific URLs on the site.</para> - <example id="network-www-django-apache-config"> + <example xml:id="network-www-django-apache-config"> <title>Apache Configuration for Django/mod_python</title> <para>A line must be added to the apache @@ -4747,7 +4702,7 @@ DocumentRoot /www/someotherdomain.tld interpreter and the penalty of Perl start-up time.</para> <para><application>mod_perl2</application> is available in the - <filename role="package">www/mod_perl2</filename> + <package>www/mod_perl2</package> port.</para> </sect3> @@ -4780,14 +4735,13 @@ DocumentRoot /www/someotherdomain.tld <para>To gain support for <acronym>PHP</acronym>5 for the <application>Apache</application> web server, begin by - installing the <filename role="package">lang/php5</filename> + installing the <package>lang/php5</package> port.</para> - <para>If the <filename role="package">lang/php5</filename> + <para>If the <package>lang/php5</package> port is being installed for the first time, available <literal>OPTIONS</literal> will be displayed automatically. - If a menu is not displayed, i.e., because the <filename - role="package">lang/php5</filename> port has been installed + If a menu is not displayed, i.e., because the <package>lang/php5</package> port has been installed some time in the past, it is always possible to bring the options dialog up again by running:</para> @@ -4806,10 +4760,10 @@ DocumentRoot /www/someotherdomain.tld deployed web applications). If the <application>mod_php4</application> is needed instead of <application>mod_php5</application>, then please use the - <filename role="package">lang/php4</filename> port. The - <filename role="package">lang/php4</filename> port + <package>lang/php4</package> port. The + <package>lang/php4</package> port supports many of the configuration and build-time options - of the <filename role="package">lang/php5</filename> + of the <package>lang/php5</package> port.</para> </note> @@ -4844,7 +4798,7 @@ DocumentRoot /www/someotherdomain.tld <para>The <acronym>PHP</acronym> support in &os; is extremely modular so the base install is very limited. It is very easy to add support using the - <filename role="package">lang/php5-extensions</filename> + <package>lang/php5-extensions</package> port. This port provides a menu driven interface to <acronym>PHP</acronym> extension installation. Alternatively, individual extensions can be installed using @@ -4864,7 +4818,7 @@ DocumentRoot /www/someotherdomain.tld </sect2> </sect1> - <sect1 id="network-ftp"> + <sect1 xml:id="network-ftp"> <!-- <sect1info> <authorgroup> @@ -4917,16 +4871,16 @@ DocumentRoot /www/someotherdomain.tld </indexterm> <para>To enable anonymous <acronym>FTP</acronym> access to the - server, create a user named <username>ftp</username> on the + server, create a user named <systemitem class="username">ftp</systemitem> on the &os; system. Users will then be able to log on to the <acronym>FTP</acronym> server with a username of - <username>ftp</username> or <username>anonymous</username>. + <systemitem class="username">ftp</systemitem> or <systemitem class="username">anonymous</systemitem>. When prompted for the password, any input will be accepted, but by convention, an email address should be used as the password. The <acronym>FTP</acronym> server will call &man.chroot.2; when an anonymous user logs in, to restrict access to only the home directory of the - <username>ftp</username> user.</para> + <systemitem class="username">ftp</systemitem> user.</para> <para>There are two text files that can be created to specify welcome messages to be displayed to <acronym>FTP</acronym> @@ -4989,7 +4943,7 @@ DocumentRoot /www/someotherdomain.tld </sect2> </sect1> - <sect1 id="network-samba"> + <sect1 xml:id="network-samba"> <!-- <sect1info> <authorgroup> @@ -5024,8 +4978,7 @@ DocumentRoot /www/someotherdomain.tld <para><application>Samba</application> software packages should be included on the &os; installation media. If they were not installed when first installing &os;, then they may be - installed from the <filename - role="package">net/samba34</filename> port or + installed from the <package>net/samba34</package> port or package.</para> <!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. --> @@ -5069,8 +5022,8 @@ DocumentRoot /www/someotherdomain.tld <para>Once <application>swat</application> has been enabled in <filename>inetd.conf</filename>, a web browser may be used - to connect to <ulink url="http://localhost:901"></ulink>. - At first login, the system <username>root</username> account + to connect to <uri xlink:href="http://localhost:901">http://localhost:901</uri>. + At first login, the system <systemitem class="username">root</systemitem> account must be used.</para> <!-- XXX screenshots go here, loader is creating them @@ -5192,12 +5145,11 @@ DocumentRoot /www/someotherdomain.tld <literal>tdbsam</literal>, and the following command should be used to add user accounts:</para> - <screen>&prompt.root; <userinput><command>pdbedit <option>-a</option> <option>-u</option> <replaceable>username</replaceable></command></userinput></screen> + <screen>&prompt.root; <userinput>pdbedit -a -u username</userinput></screen> </note> - <para>Please see the <ulink - url="http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/">Official - Samba HOWTO</ulink> for additional information about + <para>Please see the <link xlink:href="http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/">Official + Samba HOWTO</link> for additional information about configuration options. With the basics outlined here, the minimal required start running <application>Samba</application> will be explained. Other @@ -5209,7 +5161,7 @@ DocumentRoot /www/someotherdomain.tld <sect2> <title>Starting <application>Samba</application></title> - <para>The <filename role="package">net/samba34</filename> port + <para>The <package>net/samba34</package> port adds a new startup script, which can be used to control <application>Samba</application>. To enable this script, so that it can be used for example to start, stop or restart @@ -5260,11 +5212,11 @@ Starting smbd.</screen> suite with functionality that allows broad integration with µsoft.windows; networks. For more information about functionality beyond the basic installation described here, - please see <ulink url="http://www.samba.org"></ulink>.</para> + please see <uri xlink:href="http://www.samba.org">http://www.samba.org</uri>.</para> </sect2> </sect1> - <sect1 id="network-ntp"> + <sect1 xml:id="network-ntp"> <!-- <sect1info> <authorgroup> @@ -5317,9 +5269,8 @@ Starting smbd.</screen> <acronym role="Network Time Protocol">NTP</acronym> servers must be defined. The network administrator or ISP may have set up an NTP server for this purpose—check their - documentation to see if this is the case. There is an <ulink - url="http://support.ntp.org/bin/view/Servers/WebHome">online - list of publicly accessible NTP servers</ulink> which may be + documentation to see if this is the case. There is an <link xlink:href="http://support.ntp.org/bin/view/Servers/WebHome">online + list of publicly accessible NTP servers</link> which may be referenced to find an NTP server nearest to the system. Take care to review the policy for any chosen servers, and ask for permission if required.</para> @@ -5386,7 +5337,7 @@ driftfile /var/db/ntp.drift</programlisting> servers are to be used, with one server listed on each line. If a server is specified with the <literal>prefer</literal> argument, as with - <hostid role="fqdn">ntplocal.example.com</hostid>, that + <systemitem class="fqdomainname">ntplocal.example.com</systemitem>, that server is preferred over other servers. A response from a preferred server will be discarded if it differs significantly from other servers' responses, otherwise it @@ -5439,9 +5390,9 @@ driftfile /var/db/ntp.drift</programlisting> <programlisting>restrict 192.168.1.0 mask 255.255.255.0 nomodify notrap</programlisting> <para>instead, where - <hostid role="ipaddr">192.168.1.0</hostid> is an + <systemitem class="ipaddress">192.168.1.0</systemitem> is an <acronym>IP</acronym> address on the network and - <hostid role="netmask">255.255.255.0</hostid> is the + <systemitem class="netmask">255.255.255.0</systemitem> is the network's netmask.</para> <para>The <filename>/etc/ntp.conf</filename> file can contain @@ -5512,7 +5463,7 @@ driftfile /var/db/ntp.drift</programlisting> </sect2> </sect1> - <sect1 id="network-syslogd"> + <sect1 xml:id="network-syslogd"> <!-- <sect1info> <authorgroup> @@ -5540,11 +5491,11 @@ driftfile /var/db/ntp.drift</programlisting> Log file aggregation, merging and rotation may be configured in one location, using the native tools of &os;, such as &man.syslogd.8; and &man.newsyslog.8;. In the following example - configuration, host <hostid>A</hostid>, named - <hostid role="fqdn">logserv.example.com</hostid>, will collect + configuration, host <systemitem>A</systemitem>, named + <systemitem class="fqdomainname">logserv.example.com</systemitem>, will collect logging information for the local network. Host - <hostid>B</hostid>, named - <hostid role="fqdn">logclient.example.com</hostid> will pass + <systemitem>B</systemitem>, named + <systemitem class="fqdomainname">logclient.example.com</systemitem> will pass logging information to the server system. In live configurations, both hosts require proper forward and reverse <acronym>DNS</acronym> or entries in @@ -5625,14 +5576,14 @@ syslogd_flags="-a logclient.example.com -v -v"</programlisting> does not matter, but &man.touch.1; works great for situations such as this:</para> - <screen>&prompt.root; <userinput><command>touch</command> - <filename>/var/log/logclient.log</filename></userinput></screen> + <screen>&prompt.root; <userinput>touch + /var/log/logclient.log</userinput></screen> <para>At this point, the <command>syslogd</command> daemon should be restarted and verified:</para> - <screen>&prompt.root; <userinput>service <command>syslogd</command> restart</userinput> -&prompt.root; <userinput><command>pgrep</command> syslog</userinput></screen> + <screen>&prompt.root; <userinput>service syslogd restart</userinput> +&prompt.root; <userinput>pgrep syslog</userinput></screen> <para>If a <acronym>PID</acronym> is returned, the server has been restarted successfully, and client configuration may @@ -5707,14 +5658,14 @@ syslogd_flags="-s -v -v"</programlisting> <para>Once added, <command>syslogd</command> must be restarted for the changes to take effect:</para> - <screen>&prompt.root; <userinput>service <command>syslogd</command> restart</userinput></screen> + <screen>&prompt.root; <userinput>service syslogd restart</userinput></screen> <para>To test that log messages are being sent across the network, use &man.logger.1; on the client to send a message to <command>syslogd</command>:</para> - <screen>&prompt.root; <userinput><command>logger</command> - "<replaceable>Test message from logclient</replaceable>"</userinput></screen> + <screen>&prompt.root; <userinput>logger + "Test message from logclient"</userinput></screen> <para>This message should now exist both in <filename>/var/log/messages</filename> on the client, and @@ -5745,7 +5696,7 @@ syslogd_flags="-s -v -v"</programlisting> <programlisting>syslogd_flags="-d -a logclien.example.com -v -v"</programlisting> - <screen>&prompt.root; <userinput>service <command>syslogd</command> restart</userinput></screen> + <screen>&prompt.root; <userinput>service syslogd restart</userinput></screen> <para>Debugging data similar to the following will flash on the screen immediately after the restart:</para> @@ -5770,7 +5721,7 @@ rejected in rule 0 due to name mismatch.</screen> <literal>logclien</literal>. After the proper alterations are made, a restart is issued with expected results:</para> - <screen>&prompt.root; <userinput>service <command>syslogd</command> restart</userinput> + <screen>&prompt.root; <userinput>service syslogd restart</userinput> logmsg: pri 56, flags 4, from logserv.example.com, msg syslogd: restart syslogd: restarted logmsg: pri 6, flags 4, from logserv.example.com, msg syslogd: kernel boot file is /boot/kernel/kernel @@ -5798,7 +5749,7 @@ Logging to FILE /var/log/messages</screen> data. Network data sent from the client to the server will not be encrypted nor password protected. If a need for encryption exists, it might be possible to use - <filename role="package">security/stunnel</filename>, which + <package>security/stunnel</package>, which will transmit data over an encrypted tunnel.</para> <para>Local security is also an issue. Log files are not @@ -5813,7 +5764,7 @@ Logging to FILE /var/log/messages</screen> </sect2> </sect1> - <sect1 id="network-iscsi"> + <sect1 xml:id="network-iscsi"> <!-- <sect1info> <authorgroup> @@ -5837,13 +5788,13 @@ Logging to FILE /var/log/messages</screen> nodes appear in <filename>/dev/</filename>, and must be separately mounted.</para> - <sect2 id="network-iscsi-target"> + <sect2 xml:id="network-iscsi-target"> <title><acronym>iSCSI</acronym> Target</title> <para>Note: the native <acronym>iSCSI</acronym> target is supported starting with &os; 10.0-RELEASE. To use <acronym>iSCSI</acronym> in older versions of &os;, install a userspace target from the Ports Collection, such as - <filename role="package">net/istgt</filename>. + <package>net/istgt</package>. This chapter only describes the native target.</para> <sect3> @@ -5852,13 +5803,11 @@ Logging to FILE /var/log/messages</screen> <para>Configuring an <acronym>iSCSI</acronym> target is straightforward: create the <filename>/etc/ctl.conf</filename> configuration file, add an appropriate line to - <filename>/etc/rc.conf</filename> to make sure the <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + <filename>/etc/rc.conf</filename> to make sure the <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> daemon is automatically started at boot, and then start the daemon.</para> - <para>A simple <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</ulink> + <para>A simple <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</link> configuration file looks like this:</para> <programlisting>portal-group pg0 { @@ -5879,13 +5828,11 @@ target iqn.2012-06.com.example:target0 { <para>The first entry defines the <literal>pg0</literal> portal group. Portal groups define network addresses the - <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> daemon will listen on. <literal>discovery-auth-group no-authentication</literal> means that every initiator is allowed to perform <acronym>iSCSI</acronym> SendTargets discovery without any - authentication. The following two lines make <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + authentication. The following two lines make <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> listen on all <acronym>IPv4</acronym> (<literal>listen 0.0.0.0</literal>) and <acronym>IPv6</acronym> (<literal>listen [::]</literal>) addresses on the default port (3560). It is not necessary to define @@ -5925,31 +5872,25 @@ target iqn.2012-06.com.example:target0 { line of <acronym>LUN</acronym> configuration (<literal>path /data/target0-0</literal>) defines the full path to a file or ZVOL backing the <acronym>LUN</acronym>. The file must - exist before starting <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink>. + exist before starting <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link>. The second line is optional and specifies the size.</para> - <para>To make sure <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + <para>To make sure <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> daemon is started at boot, add this line to <filename>/etc/rc.conf</filename>:</para> <programlisting>ctld_enable="YES"</programlisting> <para>On a new server being configured as <acronym>iSCSI</acronym> target, - <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> - can be started by running this command as <username>root</username>:</para> + <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> + can be started by running this command as <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>service ctld start</userinput></screen> - <para>The <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> - daemon reads <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</ulink> + <para>The <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> + daemon reads <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctl.conf&sektion=5&manpath=FreeBSD+10-current">ctl.conf(5)</link> file when started. To make configuration changes take - effect immediately, force <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</ulink> + effect immediately, force <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=ctld&sektion=8&manpath=FreeBSD+10-current">ctld(8)</link> to reread it:</para> <screen>&prompt.root; <userinput>service ctld reload</userinput></screen> @@ -6007,20 +5948,18 @@ target iqn.2012-06.com.example:target0 { </sect3> </sect2> - <sect2 id="network-iscsi-initiator"> + <sect2 xml:id="network-iscsi-initiator"> <title><acronym>iSCSI</acronym> Initiator</title> <note> <para>The current <acronym>iSCSI</acronym> initiator is supported starting with &os; 10.0-RELEASE. To use the <acronym>iSCSI</acronym> initiator available in - older versions, refer to <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscontrol&sektion=8&manpath=FreeBSD+10-current">iscontrol(8)</ulink>. + older versions, refer to <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscontrol&sektion=8&manpath=FreeBSD+10-current">iscontrol(8)</link>. This chapter only applies to the new initiator.</para> </note> - <para>The <acronym>iSCSI</acronym> initiator requires the <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink> + <para>The <acronym>iSCSI</acronym> initiator requires the <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</link> daemon to run. It does not use a configuration file. To start it automatically at boot, add this line to @@ -6029,15 +5968,13 @@ target iqn.2012-06.com.example:target0 { <programlisting>iscsid_enable="YES"</programlisting> <para>On a new machine being configured as an <acronym>iSCSI</acronym> initiator, - <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink> - can be started by running this command as <username>root</username>:</para> + <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</link> + can be started by running this command as <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>service iscsid start</userinput></screen> <para>Connecting to a target can be done with or without an - <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscsi.conf&sektion=5&manpath=FreeBSD+10-current">iscsi.conf(8)</ulink> + <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscsi.conf&sektion=5&manpath=FreeBSD+10-current">iscsi.conf(8)</link> configuration file.</para> <sect3> @@ -6045,7 +5982,7 @@ target iqn.2012-06.com.example:target0 { File</title> <para>To make the initiator connect to a single target, run - this command as <username>root</username>:</para> + this command as <systemitem class="username">root</systemitem>:</para> <screen>&prompt.root; <userinput>iscsictl -A -p 10.10.10.10 -t iqn.2012-06.com.example:target0</userinput></screen> @@ -6059,16 +5996,13 @@ iqn.2012-06.com.example:target0 10.10.10.10 Connected: da0</ established, with <filename>/dev/da0</filename> representing the attached <acronym>LUN</acronym>. If the <literal>iqn.2012-06.com.example:target0</literal> target exports more than one - <acronym>LUN</acronym>, multiple device nodes will be shown in the <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscsictl&sektion=8&manpath=FreeBSD+10-current">iscictl(8)</ulink> + <acronym>LUN</acronym>, multiple device nodes will be shown in the <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscsictl&sektion=8&manpath=FreeBSD+10-current">iscictl(8)</link> output:</para> <screen>Connected: da0 da1 da2.</screen> <para>Any errors are reported in the system logs, and also visible - in the <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscsictl&sektion=8&manpath=FreeBSD+10-current">iscictl(8)</ulink> - output. For example, this usually means the <ulink - url="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</ulink> + in the <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscsictl&sektion=8&manpath=FreeBSD+10-current">iscictl(8)</link> + output. For example, this usually means the <link xlink:href="http://www.freebsd.org/cgi/man.cgi?query=iscsid&sektion=8&manpath=FreeBSD+10-current">iscsid(8)</link> daemon is not running:</para> <programlisting>Target name Target portal State diff --git a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.xml b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.xml index d711c544fc..2f209f1d33 100644 --- a/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/pgpkeys/chapter.xml @@ -11,34 +11,34 @@ See the README file in head/share/pgpkeys for instructions. --> -<appendix id="pgpkeys"> +<appendix xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="pgpkeys"> <title>PGP Keys</title> <indexterm><primary>pgp keys</primary></indexterm> <para>In case you need to verify a signature or send encrypted email to one of the officers or developers a number of keys are provided - here for your convenience. A complete keyring of <hostid role="domainname">FreeBSD.org</hostid> - users is available for download from <ulink url="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</ulink>.</para> + here for your convenience. A complete keyring of <systemitem class="fqdomainname">FreeBSD.org</systemitem> + users is available for download from <link xlink:href="&url.base;/doc/pgpkeyring.txt">http://www.FreeBSD.org/doc/pgpkeyring.txt</link>.</para> - <sect1 id="pgpkeys-officers"> + <sect1 xml:id="pgpkeys-officers"> <title>Officers</title> §ion.pgpkeys-officers; </sect1> - <sect1 id="pgpkeys-core"> + <sect1 xml:id="pgpkeys-core"> <title>Core Team Members</title> §ion.pgpkeys-core; </sect1> - <sect1 id="pgpkeys-developers"> + <sect1 xml:id="pgpkeys-developers"> <title>Developers</title> §ion.pgpkeys-developers; </sect1> - <sect1 id="pgpkeys-other"> + <sect1 xml:id="pgpkeys-other"> <title>Other Cluster Account Holders</title> §ion.pgpkeys-other; diff --git a/en_US.ISO8859-1/books/handbook/ports/chapter.xml b/en_US.ISO8859-1/books/handbook/ports/chapter.xml index 77621e5ff0..39a2a0a0ea 100644 --- a/en_US.ISO8859-1/books/handbook/ports/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/ports/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - -<chapter id="ports"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ports"> <title>Installing Applications: Packages and Ports</title> - <sect1 id="ports-synopsis"> + <sect1 xml:id="ports-synopsis"> <title>Synopsis</title> <indexterm><primary>ports</primary></indexterm> @@ -59,7 +58,7 @@ </itemizedlist> </sect1> - <sect1 id="ports-overview"> + <sect1 xml:id="ports-overview"> <title>Overview of Software Installation</title> <para>The typical steps for installing third-party software on a @@ -205,10 +204,8 @@ &a.ports; and the &a.ports-bugs;.</para> <warning> - <para>Before installing any application, check <ulink - url="http://vuxml.freebsd.org/"></ulink> for security issues - related to the application or install <filename - role="package">ports-mgmt/portaudit</filename>. Once + <para>Before installing any application, check <uri xlink:href="http://vuxml.freebsd.org/">http://vuxml.freebsd.org/</uri> for security issues + related to the application or install <package>ports-mgmt/portaudit</package>. Once installed, type <command>portaudit -F -a</command> to check all installed applications for known vulnerabilities.</para> </warning> @@ -218,7 +215,7 @@ &os;.</para> </sect1> - <sect1 id="ports-finding-applications"> + <sect1 xml:id="ports-finding-applications"> <title>Finding Software</title> <para>&os;'s list of available applications is growing all the @@ -228,8 +225,7 @@ <itemizedlist> <listitem> <para>The &os; web site maintains an up-to-date searchable - list of all the available applications, at <ulink - url="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</ulink>. + list of all the available applications, at <link xlink:href="&url.base;/ports/index.html">http://www.FreeBSD.org/ports/</link>. The ports can be searched by application name or by software category.</para> </listitem> @@ -237,8 +233,7 @@ <listitem> <indexterm><primary>FreshPorts</primary></indexterm> - <para>Dan Langille maintains <ulink - url="http://www.FreshPorts.org/">FreshPorts.org</ulink> + <para>Dan Langille maintains <link xlink:href="http://www.FreshPorts.org/">FreshPorts.org</link> which provides a comprehensive search utility and also tracks changes to the applications in the Ports Collection. Registered users can create a customized watch list in order @@ -250,8 +245,7 @@ <indexterm><primary>Freecode</primary></indexterm> <para>If you do not know the name of an application, try - using a site like <ulink - url="http://www.freecode.com/">Freecode.com</ulink> to + using a site like <link xlink:href="http://www.freecode.com/">Freecode.com</link> to find an application, then check back at the &os; site to see if the application has been ported yet.</para> </listitem> @@ -260,7 +254,7 @@ <para>If the Ports Collection is already installed, there are several methods to query the local version of the ports tree. To find out which category a port is in, type - <command>whereis <replaceable>file</replaceable></command>, + <command>whereis file</command>, where <replaceable>file</replaceable> is the program to be installed:</para> @@ -274,18 +268,16 @@ lsof: /usr/ports/sysutils/lsof</screen> /usr/ports/sysutils/lsof</screen> <para>Note that this will also return any matched files - downloaded into the <filename - class="directory">/usr/ports/distfiles</filename> + downloaded into the <filename>/usr/ports/distfiles</filename> directory.</para> </listitem> <listitem> <para>Another way to find software is by using the Ports Collection's built-in search mechanism. To use the search - feature, <application>cd</application> to <filename - class="directory">/usr/ports</filename> then run - <command>make <maketarget>search</maketarget> - name=<replaceable>program-name</replaceable></command> + feature, <application>cd</application> to <filename>/usr/ports</filename> then run + <command>make search + name=program-name</command> where <replaceable>program-name</replaceable> is the name of the software. For example, to search for <command>lsof</command>:</para> @@ -323,18 +315,18 @@ Path: /usr/ports/sysutils/lsof Info: Lists information about open files (similar to fstat(1))</screen> <para>For more in-depth searching, use - <command>make <maketarget>search</maketarget> - key=<replaceable>string</replaceable></command> or - <command>make <maketarget>quicksearch</maketarget> - key=<replaceable>string</replaceable></command>, where + <command>make search + key=string</command> or + <command>make quicksearch + key=string</command>, where <replaceable>string</replaceable> is some text to search for. The text can be in comments, descriptions, or dependencies in order to find ports which relate to a particular subject when the name of the program is unknown.</para> - <para>When using <maketarget>search</maketarget> or - <maketarget>quicksearch</maketarget>, the search string + <para>When using <buildtarget>search</buildtarget> or + <buildtarget>quicksearch</buildtarget>, the search string is case-insensitive. Searching for <quote>LSOF</quote> will yield the same results as searching for <quote>lsof</quote>.</para> @@ -343,7 +335,7 @@ Info: Lists information about open files (similar to fstat(1))</screen> </sect1> - <sect1 id="packages-using"> + <sect1 xml:id="packages-using"> <!-- <sect1info> <authorgroup> @@ -368,7 +360,7 @@ Info: Lists information about open files (similar to fstat(1))</screen> <application>pkgng</application> format.</para> <para>This method of package management uses a package database - directory, <filename class="directory">/var/db/pkg</filename>, + directory, <filename>/var/db/pkg</filename>, to track installed software versions and the files installed with each application. Several utilities interact with the database directory and are used to manage binary packages. @@ -405,7 +397,7 @@ Info: Lists information about open files (similar to fstat(1))</screen> <indexterm> <primary><command>pkg_add</command></primary> </indexterm> - <screen>&prompt.root; <userinput>pkg_add -r <replaceable>lsof</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg_add -r lsof</userinput></screen> <para>In this example, <literal>lsof</literal> is used without specifying a version number as the version is not included @@ -437,15 +429,12 @@ Info: Lists information about open files (similar to fstat(1))</screen> <para>Package files are distributed in the <filename>.tbz</filename> format. Packages are available - from <ulink - url="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/"></ulink> + from <uri xlink:href="ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/">ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/packages/</uri> or the <filename>/packages</filename> directory of the &os; DVD distribution. The layout of the packages directory is - similar to that of the <filename - class="directory">/usr/ports</filename> tree. Each + similar to that of the <filename>/usr/ports</filename> tree. Each category has its own directory, and every package can be - found within the <filename - class="directory">All</filename> directory.</para> + found within the <filename>All</filename> directory.</para> </sect2> <sect2> @@ -557,7 +546,7 @@ docbook = <para>To remove a previously installed software package, use &man.pkg.delete.1;:</para> - <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat-2.8.8_1</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg_delete xchat-2.8.8_1</userinput></screen> <para>Note that &man.pkg.delete.1; requires the full package name and number and that the above command would not work if @@ -566,14 +555,14 @@ docbook = &man.pkg.version.1; to find the version of the installed package, or use a wildcard:</para> - <screen>&prompt.root; <userinput>pkg_delete <replaceable>xchat\*</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg_delete xchat\*</userinput></screen> <para>in this case, all packages whose names start with <literal>xchat</literal> will be deleted.</para> </sect2> </sect1> - <sect1 id="pkgng-intro"> + <sect1 xml:id="pkgng-intro"> <title>Using <application>pkgng</application> for Binary Package Management</title> @@ -583,15 +572,13 @@ docbook = faster and easier.</para> <para><application>pkgng</application> is not a replacement for - port management tools like <filename - role="package">ports-mgmt/portmaster</filename> or <filename - role="package">ports-mgmt/portupgrade</filename>. These + port management tools like <package>ports-mgmt/portmaster</package> or <package>ports-mgmt/portupgrade</package>. These tools can be used to install third-party software from both binary packages and the Ports Collection, while <application>pkgng</application> installs only binary packages.</para> - <sect2 id="pkgng-initial-setup"> + <sect2 xml:id="pkgng-initial-setup"> <title>Getting Started with <application>pkgng</application></title> @@ -682,7 +669,7 @@ docbook = examples.</para> </sect2> - <sect2 id="pkgng-pkg-info"> + <sect2 xml:id="pkgng-pkg-info"> <title>Obtaining Information About Installed Packages</title> <para>Information about the packages installed on a system @@ -698,14 +685,14 @@ docbook = pkg-1.1.4_1</screen> </sect2> - <sect2 id="pkgng-installing-deinstalling"> + <sect2 xml:id="pkgng-installing-deinstalling"> <title>Installing and Removing Packages</title> <para>To install a binary package use the following command, where <replaceable>packagename</replaceable> is the name of the package to install:</para> - <screen>&prompt.root; <userinput>pkg install <replaceable>packagename</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg install packagename</userinput></screen> <para>This command uses repository data to determine which version of the software to install and if it has any @@ -757,7 +744,7 @@ Proceed with deleting packages [y/N]: <userinput>y</userinput> [1/1] Deleting curl-7.31.0_1... done</screen> </sect2> - <sect2 id="pkgng-upgrading"> + <sect2 xml:id="pkgng-upgrading"> <title>Upgrading Installed Packages</title> <para>Packages that are outdated can be found with @@ -775,7 +762,7 @@ Proceed with deleting packages [y/N]: <userinput>y</userinput> <userinput>n</userinput> to cancel the upgrade.</para> </sect2> - <sect2 id="pkgng-auditing"> + <sect2 xml:id="pkgng-auditing"> <title>Auditing Installed Packages</title> <para>Occasionally, software vulnerabilities may be discovered @@ -788,7 +775,7 @@ Proceed with deleting packages [y/N]: <userinput>y</userinput> <screen>&prompt.root; <userinput>pkg audit -F</userinput></screen> </sect2> - <sect2 id="pkgng-autoremove"> + <sect2 xml:id="pkgng-autoremove"> <title>Automatically Removing Leaf Dependencies</title> <para>Removing a package may leave behind dependencies which @@ -806,7 +793,7 @@ Proceed with autoremoval of packages [y/N]: <userinput>y</userinput> Deinstalling ca_root_nss-3.15.1_1... done</screen> </sect2> - <sect2 id="pkgng-backup"> + <sect2 xml:id="pkgng-backup"> <title>Backing Up the Package Database</title> <para>Unlike the traditional package management system, @@ -816,7 +803,7 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <replaceable>pkgng.db</replaceable> with a suitable file name:</para> - <screen>&prompt.root; <userinput>pkg backup -d <replaceable>pkgng.db</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg backup -d pkgng.db</userinput></screen> <para>Additionally, <application>pkgng</application> includes a &man.periodic.8; script to automatically perform a daily @@ -834,10 +821,10 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para>To restore the contents of a previous package database backup, run:</para> - <screen>&prompt.root; <userinput>pkg backup -r <replaceable>/path/to/pkgng.db</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg backup -r /path/to/pkgng.db</userinput></screen> </sect2> - <sect2 id="pkgng-clean"> + <sect2 xml:id="pkgng-clean"> <title>Removing Stale Packages</title> <para>By default, <application>pkgng</application> stores @@ -851,16 +838,16 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <screen>&prompt.root; <userinput>pkg clean</userinput></screen> </sect2> - <sect2 id="pkgng-set"> + <sect2 xml:id="pkgng-set"> <title>Modifying Package Metadata</title> <para>Software within the &os; Ports Collection can undergo major version number changes. To address this, <application>pkgng</application> has a built-in command to update package origins. This can be useful, for example, if - <filename role="package">lang/php5</filename> is renamed to - <filename role="package">lang/php53</filename> so that - <filename role="package">lang/php5</filename> can now + <package>lang/php5</package> is renamed to + <package>lang/php53</package> so that + <package>lang/php5</package> can now represent version <literal>5.4</literal>.</para> <para>To change the package origin for the above example, @@ -868,16 +855,12 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <screen>&prompt.root; <userinput>pkg set -o lang/php5:lang/php53</userinput></screen> - <para>As another example, to update <filename - role="package">lang/ruby18</filename> to <filename - role="package">lang/ruby19</filename>, run:</para> + <para>As another example, to update <package>lang/ruby18</package> to <package>lang/ruby19</package>, run:</para> <screen>&prompt.root; <userinput>pkg set -o lang/ruby18:lang/ruby19</userinput></screen> <para>As a final example, to change the origin of the - <filename>libglut</filename> shared libraries from <filename - role="package">graphics/libglut</filename> to <filename - role="package">graphics/freeglut</filename>, run:</para> + <filename>libglut</filename> shared libraries from <package>graphics/libglut</package> to <package>graphics/freeglut</package>, run:</para> <screen>&prompt.root; <userinput>pkg set -o graphics/libglut:graphics/freeglut</userinput></screen> @@ -887,17 +870,17 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> the modified origin. To force a reinstallation of dependent packages, run:</para> - <screen>&prompt.root; <userinput>pkg install -Rf <replaceable>graphics/freeglut</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pkg install -Rf graphics/freeglut</userinput></screen> </note> </sect2> </sect1> - <sect1 id="ports-using"> + <sect1 xml:id="ports-using"> <title>Using the Ports Collection</title> <para>The Ports Collection is a set of <filename>Makefiles</filename>, patches, and description files - stored in <filename class="directory">/usr/ports</filename>. + stored in <filename>/usr/ports</filename>. This set of files is used to compile and install applications on &os;. Before an application can be compiled using a port, the Ports Collection must first be installed. If it was not @@ -909,22 +892,19 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para><application>Portsnap</application> is a fast and user-friendly tool for retrieving the Ports Collection and - is the recommended choice for most users. See <xref - linkend="updating-upgrading-portsnap"/> for a detailed + is the recommended choice for most users. See <xref linkend="updating-upgrading-portsnap"/> for a detailed description of <application>Portsnap</application>.</para> <step> <para>Download a compressed snapshot of the Ports Collection - into <filename - class="directory">/var/db/portsnap</filename>.</para> + into <filename>/var/db/portsnap</filename>.</para> <screen>&prompt.root; <userinput>portsnap fetch</userinput></screen> </step> <step> <para>When running <application>Portsnap</application> for - the first time, extract the snapshot into <filename - class="directory">/usr/ports</filename>:</para> + the first time, extract the snapshot into <filename>/usr/ports</filename>:</para> <screen>&prompt.root; <userinput>portsnap extract</userinput></screen> </step> @@ -932,8 +912,7 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <step> <para>After the first use of <application>Portsnap</application> has been completed as - shown above, <filename - class="directory">/usr/ports</filename> can be updated as + shown above, <filename>/usr/ports</filename> can be updated as needed by running:</para> <screen>&prompt.root; <userinput>portsnap fetch</userinput> @@ -947,9 +926,8 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para>If more control over the ports tree is needed or if local changes need to be maintained, <application>Subversion</application> can be used to - obtain the Ports Collection. Refer to <ulink - url="&url.articles.committers-guide;/subversion-primer.html">the - Subversion Primer</ulink> for a detailed description of + obtain the Ports Collection. Refer to <link xlink:href="&url.articles.committers-guide;/subversion-primer.html">the + Subversion Primer</link> for a detailed description of <application>Subversion</application>.</para> <step> @@ -979,16 +957,14 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para>Check out a copy of the ports tree. For better performance, replace <replaceable>svn0.us-east.FreeBSD.org</replaceable> with a - <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror</ulink> close to your geographic location:</para> + <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror</link> close to your geographic location:</para> - <screen>&prompt.root; <userinput>svn checkout https://<replaceable>svn0.us-east.FreeBSD.org</replaceable>/ports/head /usr/ports</userinput></screen> + <screen>&prompt.root; <userinput>svn checkout https://svn0.us-east.FreeBSD.org/ports/head /usr/ports</userinput></screen> </step> <step> - <para>As needed, update <filename - class="directory">/usr/ports</filename> after the initial + <para>As needed, update <filename>/usr/ports</filename> after the initial <application>Subversion</application> checkout:</para> <screen>&prompt.root; <userinput>svn update /usr/ports</userinput></screen> @@ -1037,17 +1013,15 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para>Some ports include <filename>pkg-message</filename> or other files to handle special situations. For more details - on these files, and on ports in general, refer to the <ulink - url="&url.books.porters-handbook;/index.html">&os; Porter's - Handbook</ulink>.</para> + on these files, and on ports in general, refer to the <link xlink:href="&url.books.porters-handbook;/index.html">&os; Porter's + Handbook</link>.</para> <para>The port does not include the actual source code, also known as a <filename>distfile</filename>. The extract portion of building a port will automatically save the downloaded - source to <filename - class="directory">/usr/ports/distfiles</filename>.</para> + source to <filename>/usr/ports/distfiles</filename>.</para> - <sect2 id="ports-skeleton"> + <sect2 xml:id="ports-skeleton"> <title>Installing Ports</title> <indexterm> @@ -1065,9 +1039,9 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> Collection as described in the previous section. Since the installation of any third-party software can introduce security vulnerabilities, it is recommended to first check - <ulink url="http://vuxml.freebsd.org/"></ulink> for known + <uri xlink:href="http://vuxml.freebsd.org/">http://vuxml.freebsd.org/</uri> for known security issues related to the port. Alternately, if - <filename role="package">ports-mgmt/portaudit</filename> + <package>ports-mgmt/portaudit</package> is installed, run <command>portaudit -F</command> before installing a new port. This command can be configured to automatically perform a security audit and an update of @@ -1081,12 +1055,10 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> connection. It also requires superuser privilege.</para> <para>Some third-party DVD products such as the &os; Toolkit - from <ulink - url="http://www.freebsdmall.com/">freebsdmall.com</ulink> + from <link xlink:href="http://www.freebsdmall.com/">freebsdmall.com</link> contain distfiles which can be used to install ports without - an Internet connection. Mount the DVD on <filename - class="directory">/cdrom</filename>. If you use a different - mount point, set the <makevar>CD_MOUNTPTS</makevar> make + an Internet connection. Mount the DVD on <filename>/cdrom</filename>. If you use a different + mount point, set the <varname>CD_MOUNTPTS</varname> make variable. The needed distfiles will be automatically used if they are present on the disk. However, the licenses of a few ports do not allow their inclusion on the DVD. This @@ -1161,7 +1133,7 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <note> <para>To save this extra step, instead use <command>make - <maketarget>install clean</maketarget></command> when + install clean</command> when compiling the port.</para> </note> @@ -1171,25 +1143,25 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para>Some ports provide build options which can be used to enable or disable application components, provide security options, or allow for other customizations. Examples - include <filename role="package">www/firefox</filename>, - <filename role="package">security/gpgme</filename>, and - <filename role="package">mail/sylpheed-claws</filename>. + include <package>www/firefox</package>, + <package>security/gpgme</package>, and + <package>mail/sylpheed-claws</package>. If the port depends upon other ports which have configurable options, it may pause several times for user interaction as the default behavior is to prompt the user to select options from a menu. To avoid this, run <command>make - <maketarget>config-recursive</maketarget></command> + config-recursive</command> within the port skeleton to do this configuration in one batch. Then, run <command>make - <maketarget>install [clean]</maketarget></command> to + install [clean]</command> to compile and install the port.</para> <tip> - <para>When using <maketarget>config-recursive</maketarget>, + <para>When using <buildtarget>config-recursive</buildtarget>, the list of ports to configure are gathered by the - <maketarget>all-depends-list</maketarget> target. It is + <buildtarget>all-depends-list</buildtarget> target. It is recommended to run <command>make - <maketarget>config-recursive</maketarget></command> + config-recursive</command> until all dependent ports options have been defined, and ports options screens no longer appear, to be certain that all dependency options have been configured.</para> @@ -1200,11 +1172,11 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> a port has been built. One method is to <command>cd</command> into the directory containing the port and type <command>make - <maketarget>config</maketarget></command>. Another + config</command>. Another option is to use <command>make - <maketarget>showconfig</maketarget></command>. Another + showconfig</command>. Another option is to execute <command>make - <maketarget>rmconfig</maketarget></command> which will + rmconfig</command> which will remove all selected options and allow you to start over. All of these options, and others, are explained in great detail in &man.ports.7;.</para> @@ -1219,46 +1191,42 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> <para>For users who cannot be connected to the Internet all the time, <command>make - <maketarget>fetch</maketarget></command> can be run - within <filename class="directory">/usr/ports</filename>, + fetch</command> can be run + within <filename>/usr/ports</filename>, to fetch all distfiles, or within a category, such as - <filename class="directory">/usr/ports/net</filename>, or + <filename>/usr/ports/net</filename>, or within the specific port skeleton. Note that if a port has any dependencies, running this command in a category or ports skeleton will <emphasis>not</emphasis> fetch the distfiles of ports from another category. Instead, use <command>make - <maketarget>fetch-recursive</maketarget></command> to + fetch-recursive</command> to also fetch the distfiles for all the dependencies of a port.</para> <para>In rare cases, such as when an organization has a local - distfiles repository, the <makevar>MASTER_SITES</makevar> + distfiles repository, the <varname>MASTER_SITES</varname> variable can be used to override the download locations specified in the <filename>Makefile</filename>. When using, specify the alternate location:</para> - <screen>&prompt.root; <userinput>cd /usr/ports/<replaceable>directory</replaceable></userinput> + <screen>&prompt.root; <userinput>cd /usr/ports/directory</userinput> &prompt.root; <userinput>make MASTER_SITE_OVERRIDE= \ -<replaceable>ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/</replaceable> fetch</userinput></screen> +ftp://ftp.organization.org/pub/FreeBSD/ports/distfiles/ fetch</userinput></screen> - <para>The <makevar>WRKDIRPREFIX</makevar> and - <makevar>PREFIX</makevar> variables can override the default + <para>The <varname>WRKDIRPREFIX</varname> and + <varname>PREFIX</varname> variables can override the default working and target directories. For example:</para> <screen>&prompt.root; <userinput>make WRKDIRPREFIX=/usr/home/example/ports install</userinput></screen> - <para>will compile the port in <filename - class="directory">/usr/home/example/ports</filename> and - install everything under <filename - class="directory">/usr/local</filename>.</para> + <para>will compile the port in <filename>/usr/home/example/ports</filename> and + install everything under <filename>/usr/local</filename>.</para> <screen>&prompt.root; <userinput>make PREFIX=/usr/home/example/local install</userinput></screen> - <para>will compile the port in <filename - class="directory">/usr/ports</filename> and install it - in <filename - class="directory">/usr/home/example/local</filename>. + <para>will compile the port in <filename>/usr/ports</filename> and install it + in <filename>/usr/home/example/local</filename>. And:</para> <screen>&prompt.root; <userinput>make WRKDIRPREFIX=../ports PREFIX=../local install</userinput></screen> @@ -1272,7 +1240,7 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> </sect3> </sect2> - <sect2 id="ports-removing"> + <sect2 xml:id="ports-removing"> <title>Removing Installed Ports</title> <indexterm> @@ -1284,17 +1252,15 @@ Deinstalling ca_root_nss-3.15.1_1... done</screen> &man.pkg.delete.1;. Alternately, if the &os; system has been configured to use <application>pkg</application>, a port can be uninstalled using <command>pkg delete</command>. Examples - for using these commands can be found in <xref - linkend="packages-using"/> and <xref - linkend="pkgng-intro"/></para> + for using these commands can be found in <xref linkend="packages-using"/> and <xref linkend="pkgng-intro"/></para> <para>Alternately, <command>make deinstall</command> can be run in the port's directory:</para> <screen>&prompt.root; <userinput>cd /usr/ports/sysutils/lsof</userinput> <userinput>make deinstall</userinput> -===> Deinstalling for sysutils/lsof -===> Deinstalling +===> Deinstalling for sysutils/lsof +===> Deinstalling Deinstallation has been requested for the following 1 packages: lsof-4.88.d,8 @@ -1310,7 +1276,7 @@ The deinstallation will free 229 kB dependencies.</para> </sect2> - <sect2 id="ports-upgrading"> + <sect2 xml:id="ports-upgrading"> <title>Upgrading Ports</title> <indexterm> @@ -1352,7 +1318,7 @@ The deinstallation will free 229 kB <application>Portmaster</application> or <application>Portupgrade</application>.</para> - <sect3 id="portmaster"> + <sect3 xml:id="portmaster"> <title>Upgrading Ports Using <application>Portmaster</application></title> @@ -1360,13 +1326,11 @@ The deinstallation will free 229 kB <primary>portmaster</primary> </indexterm> - <para>The <filename - role="package">ports-mgmt/portmaster</filename> + <para>The <package>ports-mgmt/portmaster</package> package or port is the recommended tool for upgrading installed ports as it is designed to use the tools installed with &os; without depending upon other ports. It uses the - information in <filename - class="directory">/var/db/pkg/</filename> to determine + information in <filename>/var/db/pkg/</filename> to determine which ports to upgrade. To install this utility as a port:</para> @@ -1401,26 +1365,26 @@ The deinstallation will free 229 kB <para>To list these categories and search for updates:</para> <screen>&prompt.root; <userinput>portmaster -L</userinput> -===>>> Root ports (No dependencies, not depended on) -===>>> ispell-3.2.06_18 -===>>> screen-4.0.3 - ===>>> New version available: screen-4.0.3_1 -===>>> tcpflow-0.21_1 -===>>> 7 root ports +===>>> Root ports (No dependencies, not depended on) +===>>> ispell-3.2.06_18 +===>>> screen-4.0.3 + ===>>> New version available: screen-4.0.3_1 +===>>> tcpflow-0.21_1 +===>>> 7 root ports ... -===>>> Branch ports (Have dependencies, are depended on) -===>>> apache22-2.2.3 - ===>>> New version available: apache22-2.2.8 +===>>> Branch ports (Have dependencies, are depended on) +===>>> apache22-2.2.3 + ===>>> New version available: apache22-2.2.8 ... -===>>> Leaf ports (Have dependencies, not depended on) -===>>> automake-1.9.6_2 -===>>> bash-3.1.17 - ===>>> New version available: bash-3.2.33 +===>>> Leaf ports (Have dependencies, not depended on) +===>>> automake-1.9.6_2 +===>>> bash-3.1.17 + ===>>> New version available: bash-3.2.33 ... -===>>> 32 leaf ports +===>>> 32 leaf ports -===>>> 137 total installed ports - ===>>> 83 have new versions available</screen> +===>>> 137 total installed ports + ===>>> 83 have new versions available</screen> <para>This command is used to upgrade all outdated ports:</para> @@ -1454,10 +1418,10 @@ The deinstallation will free 229 kB port. To use this function, specify the location of the port in the Ports Collection:</para> - <screen>&prompt.root; <userinput>portmaster <replaceable>shells/bash</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>portmaster shells/bash</userinput></screen> </sect3> - <sect3 id="portupgrade"> + <sect3 xml:id="portupgrade"> <title>Upgrading Ports Using Portupgrade</title> <indexterm> @@ -1466,8 +1430,7 @@ The deinstallation will free 229 kB <para>Another utility that can be used to upgrade ports is <application>Portupgrade</application>, which is - available as the <filename - role="package">ports-mgmt/portupgrade</filename> package + available as the <package>ports-mgmt/portupgrade</package> package or port. This utility installs a suite of applications which can be used to manage ports. However, it is dependent upon Ruby. To install the port:</para> @@ -1489,7 +1452,7 @@ The deinstallation will free 229 kB <para>To upgrade only a specified application instead of all available ports, use <command>portupgrade - <replaceable>pkgname</replaceable></command>. It is + pkgname</command>. It is very important to include <option>-R</option> to first upgrade all the ports required by the given application:</para> @@ -1519,7 +1482,7 @@ The deinstallation will free 229 kB </sect3> </sect2> - <sect2 id="ports-disk-space"> + <sect2 xml:id="ports-disk-space"> <title>Ports and Disk Space</title> <indexterm> @@ -1529,22 +1492,20 @@ The deinstallation will free 229 kB <para>Using the Ports Collection will use up disk space over time. After building and installing a port, running - <command>make <maketarget>clean</maketarget></command> + <command>make clean</command> within the ports skeleton will clean up the temporary - <filename class="directory">work</filename> directory. If + <filename>work</filename> directory. If <application>Portmaster</application> is used to install a port, it will automatically remove this directory unless <option>-K</option> is specified. If <application>Portupgrade</application> is installed, this - command will remove all <filename - class="directory">work</filename> directories found within + command will remove all <filename>work</filename> directories found within the local copy of the Ports Collection:</para> <screen>&prompt.root; <userinput>portsclean -C</userinput></screen> <para>In addition, a lot of out-dated source distribution files - will collect in <filename - class="directory">/usr/ports/distfiles</filename> over time. + will collect in <filename>/usr/ports/distfiles</filename> over time. If <application>Portupgrade</application> is installed, this command will delete all the distfiles that are no longer referenced by any ports:</para> @@ -1565,14 +1526,13 @@ The deinstallation will free 229 kB <para>By default, this command is interactive and will prompt the user to confirm if a distfile should be deleted.</para> - <para>In addition to these commands, the <filename - role="package">ports-mgmt/pkg_cutleaves</filename> package + <para>In addition to these commands, the <package>ports-mgmt/pkg_cutleaves</package> package or port automates the task of removing installed ports that are no longer needed.</para> </sect2> </sect1> - <sect1 id="ports-nextsteps"> + <sect1 xml:id="ports-nextsteps"> <title>Post-Installation Considerations</title> <para>Regardless of whether the software was installed from a @@ -1584,27 +1544,24 @@ The deinstallation will free 229 kB <itemizedlist> <listitem> <para>Most applications install at least one default - configuration file in <filename - class="directory">/usr/local/etc</filename>. The + configuration file in <filename>/usr/local/etc</filename>. The configuration files should be reviewed and possibly edited to meet the system's needs.</para> </listitem> <listitem> <para>Applications which provide documentation will install - it into <filename - class="directory">/usr/local/share/doc</filename> and many + it into <filename>/usr/local/share/doc</filename> and many applications also install manual pages. This documentation should be consulted before continuing.</para> </listitem> <listitem> <para>Some applications run services which must be added - to <filename class="directory">/etc/rc.conf</filename> + to <filename>/etc/rc.conf</filename> before starting the application. These applications usually install a startup script in - <filename>/usr/local/etc/rc.d</filename>. See <link - linkend="configtuning-starting-services">Starting + <filename>/usr/local/etc/rc.d</filename>. See <link linkend="configtuning-starting-services">Starting Services</link> for more information.</para> </listitem> @@ -1624,7 +1581,7 @@ The deinstallation will free 229 kB </itemizedlist> </sect1> - <sect1 id="ports-broken"> + <sect1 xml:id="ports-broken"> <title>Dealing with Broken Ports</title> <para>When a port does not build or @@ -1633,14 +1590,14 @@ The deinstallation will free 229 kB <orderedlist> <listitem> <para>Search to see if there is a fix pending for the port in - the <ulink url="&url.base;/support.html#gnats">Problem - Report database</ulink>. If so, implementing the proposed + the <link xlink:href="&url.base;/support.html#gnats">Problem + Report database</link>. If so, implementing the proposed fix may fix the issue.</para> </listitem> <listitem> <para>Ask the maintainer of the port for help. Type - <command>make <maketarget>maintainer</maketarget></command> + <command>make maintainer</command> in the ports skeleton or read the port's <filename>Makefile</filename> to find the maintainer's email address. Remember to include the @@ -1650,15 +1607,12 @@ The deinstallation will free 229 kB <note> <para>Some ports are not maintained by an individual but - instead by a <ulink - url="&url.articles.mailing-list-faq;/article.html">mailing - list</ulink>. Many, but not all, of these addresses - look like <email - role="nolink">freebsd-listname@FreeBSD.org</email>. + instead by a <link xlink:href="&url.articles.mailing-list-faq;/article.html">mailing + list</link>. Many, but not all, of these addresses + look like <email role="nolink">freebsd-listname@FreeBSD.org</email>. Take this into account when sending an email.</para> - <para>In particular, ports shown as maintained by <email - role="nolink">ports@FreeBSD.org</email> are not + <para>In particular, ports shown as maintained by <email role="nolink">ports@FreeBSD.org</email> are not maintained by a specific individual. Instead, any fixes and support come from the general community who subscribe to that mailing list. More volunteers are always @@ -1667,23 +1621,20 @@ The deinstallation will free 229 kB <para>If there is no response to the email, use &man.send-pr.1; to submit a bug report using the - instructions in <ulink - url="&url.articles.problem-reports;/article.html">Writing - &os; Problem Reports</ulink>.</para> + instructions in <link xlink:href="&url.articles.problem-reports;/article.html">Writing + &os; Problem Reports</link>.</para> </listitem> <listitem> - <para>Fix it! The <ulink - url="&url.books.porters-handbook;/index.html">Porter's - Handbook</ulink> includes detailed information on the + <para>Fix it! The <link xlink:href="&url.books.porters-handbook;/index.html">Porter's + Handbook</link> includes detailed information on the ports infrastructure so that you can fix the occasional broken port or even submit your own!</para> </listitem> <listitem> <para>Install the package instead of the port using the - instructions in <xref linkend="packages-using"/> or <xref - linkend="pkgng-intro"/>.</para> + instructions in <xref linkend="packages-using"/> or <xref linkend="pkgng-intro"/>.</para> </listitem> </orderedlist> </sect1> diff --git a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml index 63b70425d2..1917ab86e1 100644 --- a/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/ppp-and-slip/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="ppp-and-slip"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="ppp-and-slip"> <!-- <chapterinfo> <authorgroup> @@ -20,10 +19,10 @@ <title><acronym>PPP</acronym></title> - <sect1 id="ppp-and-slip-synopsis"> + <sect1 xml:id="ppp-and-slip-synopsis"> <title>Synopsis</title> - <indexterm id="ppp-ppp"> + <indexterm xml:id="ppp-ppp"> <primary><acronym>PPP</acronym></primary> </indexterm> @@ -71,7 +70,7 @@ </itemizedlist> </sect1> - <sect1 id="userppp"> + <sect1 xml:id="userppp"> <!-- <sect1info> <authorgroup> @@ -111,7 +110,7 @@ <para>&os; provides built-in support for managing dial-up <acronym>PPP</acronym> connections using &man.ppp.8;. The default &os; kernel provides support for - <devicename>tun</devicename> which is used to interact with a + <filename>tun</filename> which is used to interact with a modem hardware. Configuration is performed by editing at least one configuration file, and configuration files containing examples are provided. Finally, <command>ppp</command> is @@ -167,13 +166,12 @@ <listitem> <para>The subnet mask. If the <acronym>ISP</acronym> has not - provided one, <hostid - role="netmask">255.255.255.255</hostid> will be used in + provided one, <systemitem class="netmask">255.255.255.255</systemitem> will be used in the &man.ppp.8; configuration file.</para> </listitem> <listitem> - <indexterm id="ppp-static-ip"> + <indexterm xml:id="ppp-static-ip"> <primary>static <acronym>IP</acronym> address</primary> </indexterm> @@ -189,8 +187,7 @@ for common <acronym>PPP</acronym> connection scenarios. The required configuration file is <filename>/etc/ppp/ppp.conf</filename> and additional files and - examples are available in <filename - class="directory">/usr/share/examples/ppp/</filename>.</para> + examples are available in <filename>/usr/share/examples/ppp/</filename>.</para> <note> <para>Throughout this section, many of the file examples @@ -204,7 +201,7 @@ should be indented as shown using spaces or tabs.</para> </note> - <sect2 id="userppp-staticIP"> + <sect2 xml:id="userppp-staticIP"> <title>Basic Configuration</title> <indexterm> @@ -277,10 +274,9 @@ <listitem> <para>Identifies the device to which the modem is - connected, where <devicename>COM1</devicename> is - <filename class="devicefile">/dev/cuau0</filename> - and <devicename>COM2</devicename> is <filename - class="devicefile">/dev/cuau1</filename>.</para> + connected, where <filename>COM1</filename> is + <filename>/dev/cuau0</filename> + and <filename>COM2</filename> is <filename>/dev/cuau1</filename>.</para> </listitem> </varlistentry> @@ -412,8 +408,7 @@ gateway. If the <acronym>ISP</acronym> has only provided a static <acronym>IP</acronym> address without a gateway address, replace - <replaceable>y.y.y.y</replaceable> with <hostid - role="netmask">10.0.0.2/0</hostid>.</para> + <replaceable>y.y.y.y</replaceable> with <systemitem class="netmask">10.0.0.2/0</systemitem>.</para> <para>If the <acronym>IP</acronym> address changes whenever a connection is made, change this line to @@ -463,12 +458,10 @@ remove line 17 from <filename>ppp.conf</filename> and create <filename>/etc/ppp/ppp.linkup</filename> with the above two lines. More examples for this file can be found - in <filename - class="directory">/usr/share/examples/ppp/</filename>.</para> + in <filename>/usr/share/examples/ppp/</filename>.</para> </sect2> - <?ignore - <sect2> + <?ignore <sect2> <title>Receiving Incoming Calls</title> <indexterm> @@ -526,11 +519,11 @@ <title><application>PPP</application> Permissions</title> <para>The <command>ppp</command> command must normally be - run as the <username>root</username> user. To instead + run as the <systemitem class="username">root</systemitem> user. To instead allow <command>ppp</command> to run in server mode as a normal user, that user must be given permission to run <command>ppp</command> by adding them to the - <groupname>network</groupname> group in + <systemitem class="groupname">network</systemitem> group in <filename>/etc/group</filename>.</para> <para>The user also needs access to one or more sections of @@ -543,8 +536,7 @@ <literal>default</literal> section, it gives the specified users access to everything.</para> </sect2> - <?ignore - <sect2> + <?ignore <sect2> <title><acronym>PPP</acronym> Shells for Dynamic <acronym>IP</acronym> Users</title> @@ -689,7 +681,7 @@ mary: add 203.14.103.0 netmask 255.255.255.0 HISADDR</programlisting> </sect2> ?> - <sect2 id="userppp-mgetty"> + <sect2 xml:id="userppp-mgetty"> <title><command>mgetty</command> and AutoPPP</title> <indexterm> @@ -706,9 +698,8 @@ mary: <para><xref linkend="dialup"/> provides a good description on enabling dial-up services using &man.getty.8;.</para> - <para>An alternative to <command>getty</command> is <ulink - url="http://mgetty.greenie.net/">mgetty</ulink> (from - <filename role="package">comms/mgetty+sendfax</filename> + <para>An alternative to <command>getty</command> is <link xlink:href="http://mgetty.greenie.net/">mgetty</link> (from + <package>comms/mgetty+sendfax</package> port), a smarter version of <command>getty</command> designed with dial-up lines in mind.</para> @@ -726,8 +717,7 @@ mary: <para>Refer to <xref linkend="userppp-mgetty"/> for more information on <command>mgetty</command>.</para> - <para>By default the <filename - role="package">comms/mgetty+sendfax</filename> port + <para>By default the <package>comms/mgetty+sendfax</package> port comes with the <literal>AUTO_PPP</literal> option enabled allowing <command>mgetty</command> to detect the LCP phase of <acronym>PPP</acronym> connections and @@ -737,8 +727,7 @@ mary: CHAP.</para> <para>This section assumes the user has successfully - compiled, and installed the <filename - role="package">comms/mgetty+sendfax</filename> port on + compiled, and installed the <package>comms/mgetty+sendfax</package> port on his system.</para> <para>Ensure that @@ -830,7 +819,7 @@ set nbns 203.14.100.5</programlisting> <filename>/etc/resolv.conf</filename>.</para> </sect2> - <sect2 id="userppp-PAPnCHAP"> + <sect2 xml:id="userppp-PAPnCHAP"> <title>PAP and CHAP Authentication</title> <indexterm><primary>PAP</primary></indexterm> @@ -916,7 +905,7 @@ set nbns 203.14.100.5</programlisting> &unix; domain socket, asking clients for the specified password before allowing access. The <literal>%d</literal> in the name is replaced with the - <devicename>tun</devicename> device number that is in + <filename>tun</filename> device number that is in use.</para> <para>Once a socket has been set up, the &man.pppctl.8; @@ -924,7 +913,7 @@ set nbns 203.14.100.5</programlisting> the running program.</para> </sect2> - <sect2 id="userppp-nat"> + <sect2 xml:id="userppp-nat"> <title>Using <acronym>PPP</acronym> Network Address Translation Capability</title> @@ -957,7 +946,7 @@ nat port tcp 10.0.0.2:http http</programlisting> <programlisting>nat deny_incoming yes</programlisting> </sect2> - <sect2 id="userppp-final"> + <sect2 xml:id="userppp-final"> <title>Final System Configuration</title> <indexterm> @@ -980,7 +969,7 @@ nat port tcp 10.0.0.2:http http</programlisting> <para>Look for the <literal>network_interfaces</literal> variable. To configure the system to dial the <acronym>ISP</acronym> on demand, make sure the - <devicename>tun0</devicename> device is added to the list, + <filename>tun0</filename> device is added to the list, otherwise remove it.</para> <programlisting>network_interfaces="lo0 tun0" @@ -1062,7 +1051,7 @@ ifconfig_tun0=</programlisting> </sect2> </sect1> - <sect1 id="ppp-troubleshoot"> + <sect1 xml:id="ppp-troubleshoot"> <!-- <sect1info> <authorgroup> @@ -1099,7 +1088,7 @@ ifconfig_tun0=</programlisting> <programlisting>device uart</programlisting> - <para>The <devicename>uart</devicename> device is already + <para>The <filename>uart</filename> device is already included in the <literal>GENERIC</literal> kernel, so no additional steps are necessary in this case. Just check the <command>dmesg</command> output for the modem @@ -1108,13 +1097,13 @@ ifconfig_tun0=</programlisting> <screen>&prompt.root; <userinput>dmesg | grep uart</userinput></screen> <para>This should display some pertinent output about the - <devicename>uart</devicename> devices. These are the COM + <filename>uart</filename> devices. These are the COM ports we need. If the modem acts like a standard serial port, - it should be listed on <devicename>uart1</devicename>, or - <devicename>COM2</devicename>. If so, a kernel rebuild is not + it should be listed on <filename>uart1</filename>, or + <filename>COM2</filename>. If so, a kernel rebuild is not required. When matching up, if the modem is on - <devicename>uart1</devicename>, the modem device would be - <filename class="devicefile">/dev/cuau1</filename>.</para> + <filename>uart1</filename>, the modem device would be + <filename>/dev/cuau1</filename>.</para> </sect2> <sect2> @@ -1132,10 +1121,10 @@ ifconfig_tun0=</programlisting> <screen>&prompt.root; <userinput>ppp</userinput></screen> - <screen>ppp ON example> <userinput>set device <filename class="devicefile">/dev/cuau1</filename></userinput></screen> + <screen>ppp ON example> <userinput>set device /dev/cuau1</userinput></screen> <para>This second command sets the modem device to - <devicename>cuau1</devicename>.</para> + <filename>cuau1</filename>.</para> <screen>ppp ON example> <userinput>set speed 115200</userinput></screen> @@ -1155,12 +1144,12 @@ ifconfig_tun0=</programlisting> <para>This switches to <quote>terminal</quote> mode in order to manually control the modem.</para> - <programlisting>deflink: Entering terminal mode on <filename class="devicefile">/dev/cuau1</filename> + <programlisting>deflink: Entering terminal mode on <filename>/dev/cuau1</filename> type '~h' for help</programlisting> <screen><userinput>at</userinput> OK -<userinput>atdt<replaceable>123456789</replaceable></userinput></screen> +<userinput>atdt123456789</userinput></screen> <para>Use <command>at</command> to initialize the modem, then use <command>atdt</command> and the number for the @@ -1222,8 +1211,7 @@ OK <para>If everything went good we should now have an active connection to the Internet, which could be thrown into the - background using <keycombo - action="simul"><keycap>CTRL</keycap> + background using <keycombo action="simul"><keycap>CTRL</keycap> <keycap>z</keycap></keycombo> If <command>PPP</command> returns to <command>ppp</command> then the connection has bee lost. This is good to know because it @@ -1266,13 +1254,13 @@ OK <application>PPP</application> before going into terminal mode:</para> - <screen>ppp ON example> <userinput>set authname <replaceable>myusername</replaceable></userinput></screen> + <screen>ppp ON example> <userinput>set authname myusername</userinput></screen> <para>Where <replaceable>myusername</replaceable> should be replaced with the username that was assigned by the <acronym>ISP</acronym>.</para> - <screen>ppp ON example> <userinput>set authkey <replaceable>mypassword</replaceable></userinput></screen> + <screen>ppp ON example> <userinput>set authkey mypassword</userinput></screen> <para>Where <replaceable>mypassword</replaceable> should be replaced with the password that was assigned by the @@ -1308,7 +1296,7 @@ nameserver <replaceable>y.y.y.y</replaceable></programlisting> </sect2> </sect1> - <sect1 id="pppoe"> + <sect1 xml:id="pppoe"> <!-- <sect1info> <authorgroup> @@ -1347,7 +1335,7 @@ name_of_service_provider: set login add default HISADDR</programlisting> - <para>As <username>root</username>, run:</para> + <para>As <systemitem class="username">root</systemitem>, run:</para> <screen>&prompt.root; <userinput>ppp -ddial name_of_service_provider</userinput></screen> @@ -1370,8 +1358,7 @@ ppp_profile="name_of_service_provider"</programlisting> <para>Any required service tag information should be in the documentation provided by the <acronym>ISP</acronym>.</para> - <para>As a last resort, one could try installing the <filename - role="package">net/rr-pppoe</filename> package or port. + <para>As a last resort, one could try installing the <package>net/rr-pppoe</package> package or port. Bear in mind however, this may de-program your modem and render it useless, so think twice before doing it. Simply install the program shipped with the modem. Then, access the @@ -1393,22 +1380,20 @@ ppp_profile="name_of_service_provider"</programlisting> <para>Do not forget to change <replaceable>ISP</replaceable> to the profile.</para> - <para>For additional information, refer to <ulink - url="http://renaud.waldura.com/doc/freebsd/pppoe/">Cheaper - Broadband with &os; on DSL</ulink> by Renaud + <para>For additional information, refer to <link xlink:href="http://renaud.waldura.com/doc/freebsd/pppoe/">Cheaper + Broadband with &os; on DSL</link> by Renaud Waldura.</para> </sect2> - <sect2 id="ppp-3com"> + <sect2 xml:id="ppp-3com"> <title>PPPoE with a &tm.3com; <trademark class="registered">HomeConnect</trademark> ADSL Modem Dual Link</title> <para>This modem does not follow the PPPoE specification defined - in <ulink - url="http://www.faqs.org/rfcs/rfc2516.html">RFC - 2516</ulink>.</para> + in <link xlink:href="http://www.faqs.org/rfcs/rfc2516.html">RFC + 2516</link>.</para> <para>In order to make &os; capable of communicating with this device, a sysctl must be set. This can be done automatically @@ -1423,13 +1408,12 @@ ppp_profile="name_of_service_provider"</programlisting> <para>Unfortunately, because this is a system-wide setting, it is not possible to talk to a normal PPPoE client or server - and a &tm.3com; <trademark - class="registered">HomeConnect</trademark> ADSL Modem at + and a &tm.3com; <trademark class="registered">HomeConnect</trademark> ADSL Modem at the same time.</para> </sect2> </sect1> - <sect1 id="pppoa"> + <sect1 xml:id="pppoa"> <title>Using <application>PPP</application> over <acronym>ATM</acronym> (PPPoA)</title> @@ -1503,18 +1487,16 @@ ppp_profile="adsl"</programlisting> <para>The <application>mpd</application> application can be used to connect to a variety of services, in particular PPTP - services. It can be installed using the <filename - role="package">net/mpd5</filename> package or port. Many + services. It can be installed using the <package>net/mpd5</package> package or port. Many ADSL modems require that a PPTP tunnel is created between the modem and computer.</para> <para>Once installed, configure <application>mpd</application> to suit the provider's settings. The port places a set of sample configuration files which are well documented in - <filename class="directory">/usr/local/etc/mpd/</filename>. + <filename>/usr/local/etc/mpd/</filename>. A complete guide to configure <application>mpd</application> - is available in HTML format in <filename - class="directory">/usr/ports/share/doc/mpd/</filename>. + is available in HTML format in <filename>/usr/ports/share/doc/mpd/</filename>. Here is a sample configuration for connecting to an ADSL service with <application>mpd</application>. The configuration is spread over two files, first the @@ -1530,10 +1512,8 @@ ppp_profile="adsl"</programlisting> adsl: new -i ng0 adsl adsl - set bundle authname <replaceable>username</replaceable> <co - id="co-mpd-ex-user"/> - set bundle password <replaceable>password</replaceable> <co - id="co-mpd-ex-pass"/> + set bundle authname <replaceable>username</replaceable> <co xml:id="co-mpd-ex-user"/> + set bundle password <replaceable>password</replaceable> <co xml:id="co-mpd-ex-pass"/> set bundle disable multilink set link no pap acfcomp protocomp @@ -1571,10 +1551,8 @@ adsl: set link type pptp set pptp mode active set pptp enable originate outcall - set pptp self <replaceable>10.0.0.1</replaceable> <co - id="co-mpd-ex-self"/> - set pptp peer <replaceable>10.0.0.138</replaceable> <co - id="co-mpd-ex-peer"/></programlisting> + set pptp self <replaceable>10.0.0.1</replaceable> <co xml:id="co-mpd-ex-self"/> + set pptp peer <replaceable>10.0.0.138</replaceable> <co xml:id="co-mpd-ex-peer"/></programlisting> <calloutlist> <callout arearefs="co-mpd-ex-self"> @@ -1583,22 +1561,21 @@ adsl: </callout> <callout arearefs="co-mpd-ex-peer"> <para>The <acronym>IP</acronym> address of the ADSL modem. - The Alcatel &speedtouch; Home defaults to <hostid - role="ipaddr">10.0.0.138</hostid>.</para> + The Alcatel &speedtouch; Home defaults to <systemitem class="ipaddress">10.0.0.138</systemitem>.</para> </callout> </calloutlist> <para>It is possible to initialize the connection easily by issuing the following command as - <username>root</username>:</para> + <systemitem class="username">root</systemitem>:</para> - <screen>&prompt.root; <userinput>mpd -b <replaceable>adsl</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>mpd -b adsl</userinput></screen> <para>To view the status of the connection:</para> - <screen>&prompt.user; <userinput>ifconfig <replaceable>ng0</replaceable></userinput> + <screen>&prompt.user; <userinput>ifconfig ng0</userinput> ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 - inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff</screen> + inet 216.136.204.117 --> 204.152.186.171 netmask 0xffffffff</screen> <para>Using <application>mpd</application> is the recommended way to connect to an ADSL service with &os;.</para> @@ -1608,10 +1585,9 @@ ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 <title>Using pptpclient</title> <para>It is also possible to use &os; to connect to other - PPPoA services using <filename - role="package">net/pptpclient</filename>.</para> + PPPoA services using <package>net/pptpclient</package>.</para> - <para>To use <filename role="package">net/pptpclient</filename> + <para>To use <package>net/pptpclient</package> to connect to a DSL service, install the port or package, then edit <filename>/etc/ppp/ppp.conf</filename>. An example section of <filename>ppp.conf</filename> is given below. For further @@ -1622,8 +1598,8 @@ ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 set log phase chat lcp ipcp ccp tun command set timeout 0 enable dns - set authname <replaceable>username</replaceable> <co id="co-pptp-ex-user"/> - set authkey <replaceable>password</replaceable> <co id="co-pptp-ex-pass"/> + set authname <replaceable>username</replaceable> <co xml:id="co-pptp-ex-user"/> + set authkey <replaceable>password</replaceable> <co xml:id="co-pptp-ex-pass"/> set ifaddr 0 0 add default HISADDR</programlisting> @@ -1651,12 +1627,12 @@ ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 session to the DSL router. Ethernet DSL modems have a preconfigured LAN <acronym>IP</acronym> address to connect to. In the case of the Alcatel &speedtouch; Home, this address is - <hostid role="ipaddr">10.0.0.138</hostid>. The router's + <systemitem class="ipaddress">10.0.0.138</systemitem>. The router's documentation should list the address the device uses. To open the tunnel and start a <acronym>PPP</acronym> session:</para> - <screen>&prompt.root; <userinput>pptp <replaceable>address</replaceable> <replaceable>adsl</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pptp address adsl</userinput></screen> <tip> <para>If an ampersand (<quote>&</quote>) is added @@ -1665,7 +1641,7 @@ ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 prompt.</para> </tip> - <para>A <devicename>tun</devicename> virtual tunnel device + <para>A <filename>tun</filename> virtual tunnel device will be created for interaction between the <application>pptp</application> and <application>ppp</application> processes. Once the @@ -1673,9 +1649,9 @@ ng0: flags=88d1<UP,POINTOPOINT,RUNNING,NOARP,SIMPLEX,MULTICAST> mtu 1500 <application>pptp</application> process has confirmed a connection, examine the tunnel:</para> - <screen>&prompt.user; <userinput>ifconfig <replaceable>tun0</replaceable></userinput> + <screen>&prompt.user; <userinput>ifconfig tun0</userinput> tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1500 - inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 + inet 216.136.204.21 --> 204.152.186.171 netmask 0xffffff00 Opened by PID 918</screen> <para>If the connection fails, check the configuration of diff --git a/en_US.ISO8859-1/books/handbook/preface/preface.xml b/en_US.ISO8859-1/books/handbook/preface/preface.xml index c353e84b13..c1b53a7ba8 100644 --- a/en_US.ISO8859-1/books/handbook/preface/preface.xml +++ b/en_US.ISO8859-1/books/handbook/preface/preface.xml @@ -2,11 +2,10 @@ <!-- $FreeBSD$ --> - -<preface id="book-preface"> +<preface xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="book-preface"> <title>Preface</title> - <bridgehead id="preface-audience" renderas="sect1">Intended + <bridgehead xml:id="preface-audience" renderas="sect1">Intended Audience</bridgehead> <para>The &os; newcomer will find that the first section of this @@ -26,7 +25,7 @@ <para>For a list of additional sources of information, please see <xref linkend="bibliography"/>.</para> - <bridgehead id="preface-changes-from3" renderas="sect1">Changes + <bridgehead xml:id="preface-changes-from3" renderas="sect1">Changes from the Third Edition</bridgehead> <para>The current online version of the Handbook represents the @@ -64,7 +63,7 @@ </listitem> </itemizedlist> - <bridgehead id="preface-changes-from2" renderas="sect1">Changes + <bridgehead xml:id="preface-changes-from2" renderas="sect1">Changes from the Second Edition (2004)</bridgehead> <para>The third edition was the culmination of over two years of @@ -101,8 +100,7 @@ </listitem> <listitem> - <para>A troubleshooting section has been added to <xref - linkend="ppp-and-slip"/>.</para> + <para>A troubleshooting section has been added to <xref linkend="ppp-and-slip"/>.</para> </listitem> <listitem> @@ -119,8 +117,7 @@ the <application>Apache HTTP Server</application>, <application>ftpd</application>, and setting up a server for µsoft; &windows; clients with - <application>Samba</application>. Some sections from <xref - linkend="advanced-networking"/> were moved here to improve + <application>Samba</application>. Some sections from <xref linkend="advanced-networking"/> were moved here to improve the presentation.</para> </listitem> @@ -143,7 +140,7 @@ </listitem> </itemizedlist> - <bridgehead id="preface-changes" renderas="sect1">Changes from the + <bridgehead xml:id="preface-changes" renderas="sect1">Changes from the First Edition (2001)</bridgehead> <para>The second edition was the culmination of over two years of @@ -212,8 +209,7 @@ updated.</para> </listitem> <listitem> - <para>Many new sections have been added to <xref - linkend="advanced-networking"/>.</para> + <para>Many new sections have been added to <xref linkend="advanced-networking"/>.</para> </listitem> <listitem> <para><xref linkend="mail"/> has been expanded to include more @@ -231,8 +227,7 @@ edition:</para> <itemizedlist> <listitem> - <para><xref - linkend="config-tuning"/>.</para> + <para><xref linkend="config-tuning"/>.</para> </listitem> <listitem> <para><xref linkend="multimedia"/>.</para> @@ -241,7 +236,7 @@ </listitem> </itemizedlist> - <bridgehead id="preface-overview" renderas="sect1">Organization of + <bridgehead xml:id="preface-overview" renderas="sect1">Organization of This Book</bridgehead> <para>This book is split into five logically distinct sections. @@ -366,8 +361,7 @@ <!-- Part III - System Administration --> <varlistentry> - <term><emphasis><xref - linkend="config-tuning"/></emphasis></term> + <term><emphasis><xref linkend="config-tuning"/></emphasis></term> <listitem> <para>Describes the parameters available for system administrators to tune a &os; system for optimum @@ -438,8 +432,7 @@ </listitem> </varlistentry> <varlistentry> - <term><emphasis><xref - linkend="virtualization"/></emphasis></term> + <term><emphasis><xref linkend="virtualization"/></emphasis></term> <listitem> <para>Describes what virtualization systems offer, and how they can be used with &os;.</para> @@ -454,8 +447,7 @@ </listitem> </varlistentry> <varlistentry> - <term><emphasis><xref - linkend="updating-upgrading"/></emphasis></term> + <term><emphasis><xref linkend="updating-upgrading"/></emphasis></term> <listitem> <para>Explains the differences between &os;-STABLE, &os;-CURRENT, and &os; releases. Describes which users @@ -502,8 +494,7 @@ </listitem> </varlistentry> <varlistentry> - <term><emphasis><xref - linkend="network-servers"/></emphasis></term> + <term><emphasis><xref linkend="network-servers"/></emphasis></term> <listitem> <para>Provides detailed instructions and example configuration files to set up your &os; machine as a network filesystem @@ -520,8 +511,7 @@ </listitem> </varlistentry> <varlistentry> - <term><emphasis><xref - linkend="advanced-networking"/></emphasis></term> + <term><emphasis><xref linkend="advanced-networking"/></emphasis></term> <listitem> <para>Describes many networking topics, including sharing an Internet connection with other computers on your LAN, @@ -566,14 +556,13 @@ </varlistentry> </variablelist> - <bridgehead id="preface-conv" renderas="sect1">Conventions used + <bridgehead xml:id="preface-conv" renderas="sect1">Conventions used in this book</bridgehead> <para>To provide a consistent and easy to read text, several conventions are followed throughout the book.</para> - <bridgehead id="preface-conv-typographic" - renderas="sect2">Typographic + <bridgehead xml:id="preface-conv-typographic" renderas="sect2">Typographic Conventions</bridgehead> <variablelist> @@ -604,8 +593,7 @@ </variablelist> <!-- Var list --> - <bridgehead id="preface-conv-commands" - renderas="sect2">User Input</bridgehead> + <bridgehead xml:id="preface-conv-commands" renderas="sect2">User Input</bridgehead> <para>Keys are shown in <keycap>bold</keycap> to stand out from other text. Key combinations that are meant to be typed @@ -640,10 +628,9 @@ keys simultaneously.</para> <!-- How to type in key stokes, etc.. --> - <bridgehead id="preface-conv-examples" - renderas="sect2">Examples</bridgehead> + <bridgehead xml:id="preface-conv-examples" renderas="sect2">Examples</bridgehead> - <para>Examples starting with <devicename>C:\></devicename> + <para>Examples starting with <filename>C:\></filename> indicate a &ms-dos; command. Unless otherwise noted, these commands may be executed from a <quote>Command Prompt</quote> window in a modern µsoft.windows; @@ -653,7 +640,7 @@ <para>Examples starting with &prompt.root; indicate a command that must be invoked as the superuser in &os;. You can login as - <username>root</username> to type the command, or login as your + <systemitem class="username">root</systemitem> to type the command, or login as your normal account and use &man.su.1; to gain superuser privileges.</para> @@ -666,8 +653,7 @@ <screen>&prompt.user; <userinput>top</userinput></screen> - <bridgehead id="preface-acknowledgements" - renderas="sect1">Acknowledgments</bridgehead> + <bridgehead xml:id="preface-acknowledgements" renderas="sect1">Acknowledgments</bridgehead> <para>The book you are holding represents the efforts of many hundreds of people around the world. Whether they sent in fixes @@ -677,7 +663,7 @@ <para>Several companies have supported the development of this document by paying authors to work on it full-time, paying for publication, etc. In particular, BSDi (subsequently acquired by - <ulink url="http://www.windriver.com">Wind River Systems</ulink>) + <link xlink:href="http://www.windriver.com">Wind River Systems</link>) paid members of the &os; Documentation Project to work on improving this book full time leading up to the publication of the first printed edition in March 2000 (ISBN 1-57176-241-8). Wind @@ -685,8 +671,7 @@ number of improvements to the print-output infrastructure and to add additional chapters to the text. This work culminated in the publication of the second printed edition in November 2001 - (ISBN 1-57176-303-1). In 2003-2004, <ulink - url="http://www.freebsdmall.com">&os; Mall, Inc</ulink>, paid + (ISBN 1-57176-303-1). In 2003-2004, <link xlink:href="http://www.freebsdmall.com">&os; Mall, Inc</link>, paid several contributors to improve the Handbook in preparation for the third printed edition.</para> diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.xml b/en_US.ISO8859-1/books/handbook/printing/chapter.xml index caf27d4416..ca73704d6f 100644 --- a/en_US.ISO8859-1/books/handbook/printing/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/printing/chapter.xml @@ -4,30 +4,20 @@ $FreeBSD$ --> - -<chapter id="printing"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="printing"> + <info><title>Printing</title> <authorgroup> - <author> - <firstname>Sean</firstname> - <surname>Kelly</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Sean</firstname><surname>Kelly</surname></personname><contrib>Contributed by </contrib></author> <!-- 30 Sept 1995 --> </authorgroup> <authorgroup> - <author> - <firstname>Jim</firstname> - <surname>Mock</surname> - <contrib>Restructured and updated by </contrib> - <!-- Mar 2000 --> - </author> + <author><personname><firstname>Jim</firstname><surname>Mock</surname></personname><contrib>Restructured and updated by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Printing</title> + - <sect1 id="printing-synopsis"> + <sect1 xml:id="printing-synopsis"> <title>Synopsis</title> <indexterm><primary>LPD spooling system</primary></indexterm> @@ -101,7 +91,7 @@ </itemizedlist> </sect1> - <sect1 id="printing-intro-spooler"> + <sect1 xml:id="printing-intro-spooler"> <title>Introduction</title> <para>In order to use printers with &os; you may set them up to @@ -114,8 +104,7 @@ <para>If you are already familiar with <application>LPD</application> or another printer spooling - system, you may wish to skip to section <link - linkend="printing-intro-setup">Basic Setup</link>.</para> + system, you may wish to skip to section <link linkend="printing-intro-setup">Basic Setup</link>.</para> <para><application>LPD</application> controls everything about a host's printers. It is responsible for a number of @@ -173,7 +162,7 @@ <application>LPD</application> system to do all or some subset of the above for a great variety of printer hardware.</para> - <sect2 id="printing-intro-why"> + <sect2 xml:id="printing-intro-why"> <title>Why You Should Use the Spooler</title> <para>The spooler still provides benefit on a single-user system @@ -205,7 +194,7 @@ </sect2> </sect1> - <sect1 id="printing-intro-setup"> + <sect1 xml:id="printing-intro-setup"> <title>Basic Setup</title> <para>To use printers with the <application>LPD</application> @@ -230,7 +219,7 @@ </listitem> </itemizedlist> - <sect2 id="printing-simple"> + <sect2 xml:id="printing-simple"> <title>Simple Printer Setup</title> <para>This section tells how to configure printer hardware @@ -254,8 +243,7 @@ <para>If you are setting up a printer that uses a network protocol to accept data to print instead of a computer's local - interfaces, see <link - linkend="printing-advanced-network-net-if">Printers With + interfaces, see <link linkend="printing-advanced-network-net-if">Printers With Networked Data Stream Interfaces</link>.</para> <para>Although this section is called <quote>Simple Printer @@ -265,7 +253,7 @@ The advanced options like header pages and accounting are fairly easy once you get the printer working.</para> - <sect3 id="printing-hardware"> + <sect3 xml:id="printing-hardware"> <title>Hardware Setup</title> <para>This section tells about the various ways you can @@ -275,10 +263,9 @@ <para>If you have already connected your printer and have successfully printed with it under another operating system, - you can probably skip to section <link - linkend="printing-software">Software Setup</link>.</para> + you can probably skip to section <link linkend="printing-software">Software Setup</link>.</para> - <sect4 id="printing-ports"> + <sect4 xml:id="printing-ports"> <title>Ports and Cables</title> <para>Printers sold for use on PC's today generally come @@ -358,7 +345,7 @@ user.</para> </sect4> - <sect4 id="printing-parallel"> + <sect4 xml:id="printing-parallel"> <title>Parallel Ports</title> <para>To hook up a printer using a parallel interface, @@ -369,15 +356,14 @@ <para>Remember which parallel port you used on the computer. The first parallel port is - <filename class="devicefile">ppc0</filename> to &os;; - the second is <filename - class="devicefile">ppc1</filename>, and so on. The + <filename>ppc0</filename> to &os;; + the second is <filename>ppc1</filename>, and so on. The printer device name uses the same scheme: - <filename class="devicefile">/dev/lpt0</filename> for + <filename>/dev/lpt0</filename> for the printer on the first parallel ports etc.</para> </sect4> - <sect4 id="printing-serial"> + <sect4 xml:id="printing-serial"> <title>Serial Ports</title> <para>To hook up a printer using a serial interface, connect @@ -435,7 +421,7 @@ </sect4> </sect3> - <sect3 id="printing-software"> + <sect3 xml:id="printing-software"> <title>Software Setup</title> <para>This section describes the software setup necessary @@ -447,23 +433,20 @@ <procedure> <step> <para>Configure your kernel, if necessary, for the port - you are using for the printer; section <link - linkend="printing-kernel">Kernel Configuration</link> + you are using for the printer; section <link linkend="printing-kernel">Kernel Configuration</link> tells you what you need to do.</para> </step> <step> <para>Set the communications mode for the parallel port, - if you are using a parallel port; section <link - linkend="printing-parallel-port-mode">Setting the + if you are using a parallel port; section <link linkend="printing-parallel-port-mode">Setting the Communication Mode for the Parallel Port</link> gives details.</para> </step> <step> <para>Test if the operating system can send data to the - printer. Section <link - linkend="printing-testing">Checking Printer + printer. Section <link linkend="printing-testing">Checking Printer Communications</link> gives some suggestions on how to do this.</para> </step> @@ -476,7 +459,7 @@ </step> </procedure> - <sect4 id="printing-kernel"> + <sect4 xml:id="printing-kernel"> <title>Kernel Configuration</title> <para>The operating system kernel is compiled to work with @@ -489,7 +472,7 @@ <para>To find out if the kernel you are currently using supports a serial interface, type:</para> - <screen>&prompt.root; <userinput><command>grep sio<replaceable>N</replaceable> <filename>/var/run/dmesg.boot</filename></command></userinput></screen> + <screen>&prompt.root; <userinput>grep sioN /var/run/dmesg.boot</userinput></screen> <para>Where <replaceable>N</replaceable> is the number of the serial port, starting from zero. If you see output @@ -503,7 +486,7 @@ sio2: type 16550A</screen> <para>To find out if the kernel supports a parallel interface, type:</para> - <screen>&prompt.root; <userinput><command>grep ppc<replaceable>N</replaceable> /var/run/dmesg.boot</command></userinput></screen> + <screen>&prompt.root; <userinput>grep ppcN /var/run/dmesg.boot</userinput></screen> <para>Where <replaceable>N</replaceable> is the number of the parallel port, starting from zero. If you see output @@ -526,7 +509,7 @@ ppc0: FIFO with 16/16/8 bytes threshold</screen> </sect4> </sect3> - <sect3 id="printing-parallel-port-mode"> + <sect3 xml:id="printing-parallel-port-mode"> <title>Setting the Communication Mode for the Parallel Port</title> @@ -611,8 +594,7 @@ ppc0: FIFO with 16/16/8 bytes threshold</screen> <step> <para>Save the file. Then configure, build, and install - the kernel, then reboot. See <link - linkend="kernelconfig">kernel configuration</link> + the kernel, then reboot. See <link linkend="kernelconfig">kernel configuration</link> for more details.</para> </step> </procedure> @@ -624,19 +606,19 @@ ppc0: FIFO with 16/16/8 bytes threshold</screen> <step> <para>Type:</para> - <screen>&prompt.root; <userinput><command>lptcontrol <option>-i</option> <option>-d</option> <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + <screen>&prompt.root; <userinput>lptcontrol -i -d /dev/lptN</userinput></screen> <para>to set interrupt-driven mode for - <literal>lpt<replaceable>N</replaceable></literal>.</para> + <literal>lptN</literal>.</para> </step> <step> <para>Type:</para> - <screen>&prompt.root; <userinput><command>lptcontrol <option>-p</option> <option>-d</option> <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + <screen>&prompt.root; <userinput>lptcontrol -p -d /dev/lptN</userinput></screen> <para>to set polled-mode for - <literal>lpt<replaceable>N</replaceable></literal>.</para> + <literal>lptN</literal>.</para> </step> </procedure> @@ -646,7 +628,7 @@ ppc0: FIFO with 16/16/8 bytes threshold</screen> information.</para> </sect3> - <sect3 id="printing-testing"> + <sect3 xml:id="printing-testing"> <title>Checking Printer Communications</title> <para>Before proceeding to configure the spooling system, you @@ -685,7 +667,7 @@ showpage</programlisting> special accommodations.</para> </note> - <sect4 id="printing-checking-parallel"> + <sect4 xml:id="printing-checking-parallel"> <title>Checking a Parallel Printer</title> <para>This section tells you how to check if &os; can @@ -697,7 +679,7 @@ showpage</programlisting> <procedure> <step> - <para>Become <username>root</username> with + <para>Become <systemitem class="username">root</systemitem> with &man.su.1;.</para> </step> @@ -709,7 +691,7 @@ showpage</programlisting> <para>If the printer can print plain text, then use &man.lptest.1;. Type:</para> - <screen>&prompt.root; <userinput><command>lptest > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + <screen>&prompt.root; <userinput>lptest > /dev/lptN</userinput></screen> <para>Where <replaceable>N</replaceable> is the number of the parallel port, starting from @@ -721,7 +703,7 @@ showpage</programlisting> other printer language, then send a small program to the printer. Type:</para> - <screen>&prompt.root; <userinput><command>cat > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + <screen>&prompt.root; <userinput>cat > /dev/lptN</userinput></screen> <para>Then, line by line, type the program <emphasis>carefully</emphasis> as you cannot edit @@ -735,7 +717,7 @@ showpage</programlisting> <para>Alternatively, you can put the program in a file and type:</para> - <screen>&prompt.root; <userinput><command>cat <filename><replaceable>file</replaceable></filename> > <filename class="devicefile">/dev/lpt<replaceable>N</replaceable></filename></command></userinput></screen> + <screen>&prompt.root; <userinput>cat file > /dev/lptN</userinput></screen> <para>Where <replaceable>file</replaceable> is the name of the file containing the program you want @@ -750,7 +732,7 @@ showpage</programlisting> later.</para> </sect4> - <sect4 id="printing-checking-serial"> + <sect4 xml:id="printing-checking-serial"> <title>Checking a Serial Printer</title> <indexterm> @@ -765,7 +747,7 @@ showpage</programlisting> <procedure> <step> - <para>Become <username>root</username> with + <para>Become <systemitem class="username">root</systemitem> with &man.su.1;.</para> </step> @@ -773,7 +755,7 @@ showpage</programlisting> <para>Edit the file <filename>/etc/remote</filename>. Add the following entry:</para> - <programlisting>printer:dv=<filename class="devicefile">/dev/<replaceable>port</replaceable></filename>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting> + <programlisting>printer:dv=<filename>/dev/port</filename>:br#<replaceable>bps-rate</replaceable>:pa=<replaceable>parity</replaceable></programlisting> <indexterm><primary>bits-per-second</primary></indexterm> <indexterm><primary>serial port</primary></indexterm> @@ -793,22 +775,20 @@ showpage</programlisting> a serial line to the third serial port at 19200 bps with no parity:</para> - <programlisting>printer:dv=<filename class="devicefile">/dev/ttyu2</filename>:br#19200:pa=none</programlisting> + <programlisting>printer:dv=<filename>/dev/ttyu2</filename>:br#19200:pa=none</programlisting> </step> <step> <para>Connect to the printer with &man.tip.1;. Type:</para> - <screen>&prompt.root; <userinput><command>tip</command> printer</userinput></screen> + <screen>&prompt.root; <userinput>tip printer</userinput></screen> <para>If this step does not work, edit the file <filename>/etc/remote</filename> again and try using - <filename - class="devicefile">/dev/cuaa<replaceable>N</replaceable></filename> + <filename>/dev/cuaaN</filename> instead of - <filename - class="devicefile">/dev/ttyu<replaceable>N</replaceable></filename>.</para> + <filename>/dev/ttyuN</filename>.</para> </step> <step> @@ -837,7 +817,7 @@ showpage</programlisting> <para>Alternatively, you can put the program in a file and type:</para> - <screen>&prompt.user; <userinput>><replaceable>file</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>>file</userinput></screen> <para>Where <replaceable>file</replaceable> is the name of the file containing the program. After @@ -853,7 +833,7 @@ showpage</programlisting> </sect4> </sect3> - <sect3 id="printing-printcap"> + <sect3 xml:id="printing-printcap"> <title>Enabling the Spooler: the <filename>/etc/printcap</filename> File</title> @@ -905,28 +885,24 @@ showpage</programlisting> <step> <para>Make a spooling directory, and specify its location - with the <literal>sd</literal> capability; see the <link - linkend="printing-spooldir">Making the Spooling + with the <literal>sd</literal> capability; see the <link linkend="printing-spooldir">Making the Spooling Directory</link> section for more information.</para> </step> <step> - <para>Set the <filename class="directory">/dev</filename> + <para>Set the <filename>/dev</filename> entry to use for the printer, and note it in <filename>/etc/printcap</filename> with the - <literal>lp</literal> capability; see the <link - linkend="printing-device">Identifying the Printer + <literal>lp</literal> capability; see the <link linkend="printing-device">Identifying the Printer Device</link> for more information. Also, if the printer is on a serial port, set up the communication parameters with the <literal>ms#</literal> capability - which is discussed in the <link - linkend="printing-commparam">Configuring Spooler + which is discussed in the <link linkend="printing-commparam">Configuring Spooler Communications Parameters</link> section.</para> </step> <step> - <para>Install a plain text input filter; see the <link - linkend="printing-textfilter">Installing the Text + <para>Install a plain text input filter; see the <link linkend="printing-textfilter">Installing the Text Filter</link> section for details.</para> </step> @@ -934,8 +910,7 @@ showpage</programlisting> <para>Test the setup by printing something with the &man.lpr.1; command. More details are available in the <link linkend="printing-trying">Trying It Out</link> and - <link - linkend="printing-troubleshooting">Troubleshooting</link> + <link linkend="printing-troubleshooting">Troubleshooting</link> sections.</para> </step> </procedure> @@ -958,12 +933,11 @@ showpage</programlisting> text jobs, you are strongly urged to add an additional step to the simple setup outlined above: install an automatic plain-text-to-&postscript; (or other printer language) - conversion program. The section entitled <link - linkend="printing-advanced-if-conversion">Accommodating + conversion program. The section entitled <link linkend="printing-advanced-if-conversion">Accommodating Plain Text Jobs on &postscript; Printers</link> tells how to do this.</para> - <sect4 id="printing-naming"> + <sect4 xml:id="printing-naming"> <title>Naming the Printer</title> <para>The first (easy) step is to pick a name for your @@ -1015,7 +989,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:</programlisting> v51.4</literal>.</para> </sect4> - <sect4 id="printing-no-header-pages"> + <sect4 xml:id="printing-no-header-pages"> <title>Suppressing Header Pages</title> <indexterm> @@ -1053,7 +1027,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ in a backslash character.</para> </sect4> - <sect4 id="printing-spooldir"> + <sect4 xml:id="printing-spooldir"> <title>Making the Spooling Directory</title> <indexterm><primary>printer spool</primary></indexterm> @@ -1066,7 +1040,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>Because of the variable nature of spooling directories, it is customary to put these directories - under <filename class="directory">/var/spool</filename>. + under <filename>/var/spool</filename>. It is not necessary to backup the contents of spooling directories, either. Recreating them is as simple as running &man.mkdir.1;.</para> @@ -1075,7 +1049,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ that is identical to the name of the printer, as shown below:</para> - <screen>&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/<replaceable>printer-name</replaceable></filename></command></userinput></screen> + <screen>&prompt.root; <userinput>mkdir /var/spool/printer-name</userinput></screen> <para>However, if you have a lot of printers on your network, you might want to put the spooling directories @@ -1085,23 +1059,23 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <literal>rattan</literal> and <literal>bamboo</literal>:</para> - <screen>&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd</filename></command></userinput> -&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput> -&prompt.root; <userinput><command>mkdir <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen> + <screen>&prompt.root; <userinput>mkdir /var/spool/lpd</userinput> +&prompt.root; <userinput>mkdir /var/spool/lpd/rattan</userinput> +&prompt.root; <userinput>mkdir /var/spool/lpd/bamboo</userinput></screen> <note> <para>If you are concerned about the privacy of jobs that users print, you might want to protect the spooling directory so it is not publicly accessible. Spooling directories should be owned and be readable, writable, - and searchable by user <username>daemon</username> and - group <groupname>daemon</groupname>, and no one else. + and searchable by user <systemitem class="username">daemon</systemitem> and + group <systemitem class="groupname">daemon</systemitem>, and no one else. We will do this for our example printers:</para> - <screen>&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput> -&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput> -&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/rattan</filename></command></userinput> -&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen> + <screen>&prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/rattan</userinput> +&prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/bamboo</userinput> +&prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan</userinput> +&prompt.root; <userinput>chmod 770 /var/spool/lpd/bamboo</userinput></screen> </note> <para>Finally, you need to tell @@ -1114,10 +1088,10 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ # /etc/printcap for host rose - added spooling directories # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>: + :sh:sd=<filename>/var/spool/lpd/rattan</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:</programlisting> + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:</programlisting> <para>Note that the name of the printer starts in the first column but all other entries describing the printer should @@ -1126,16 +1100,16 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>If you do not specify a spooling directory with <literal>sd</literal>, the spooling system will use - <filename class="directory">/var/spool/lpd</filename> as + <filename>/var/spool/lpd</filename> as a default.</para> </sect4> - <sect4 id="printing-device"> + <sect4 xml:id="printing-device"> <title>Identifying the Printer Device</title> <para>In the <link linkend="printing-hardware">Hardware Setup</link> section, we identified the port and the - relevant <filename class="directory">/dev</filename> + relevant <filename>/dev</filename> directory entry that &os; will use to communicate with the printer. Now, we tell <application>LPD</application> that information. When the spooling system has a job to @@ -1143,7 +1117,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ filter program (which is responsible for passing data to the printer).</para> - <para>List the <filename class="directory">/dev</filename> + <para>List the <filename>/dev</filename> entry pathname in the <filename>/etc/printcap</filename> file using the <literal>lp</literal> capability.</para> @@ -1157,29 +1131,28 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ # /etc/printcap for host rose - identified what devices to use # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>: + :sh:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:</programlisting> + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:\ + :lp=<filename>/dev/ttyu5</filename>:</programlisting> <para>If you do not specify the <literal>lp</literal> capability for a printer in your <filename>/etc/printcap</filename> file, <application>LPD</application> uses - <filename class="devicefile">/dev/lp</filename> as a - default. <filename class="devicefile">/dev/lp</filename> + <filename>/dev/lp</filename> as a + default. <filename>/dev/lp</filename> currently does not exist in &os;.</para> <para>If the printer you are installing is connected to a - parallel port, skip to the section entitled, <link - linkend="printing-textfilter">Installing the Text + parallel port, skip to the section entitled, <link linkend="printing-textfilter">Installing the Text Filter</link>. Otherwise, be sure to follow the instructions in the next section.</para> </sect4> - <sect4 id="printing-commparam"> + <sect4 xml:id="printing-commparam"> <title>Configuring Spooler Communication Parameters</title> <indexterm> @@ -1215,7 +1188,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <variablelist> <varlistentry> - <term><literal>br#<replaceable>bps-rate</replaceable></literal></term> + <term><literal>br#bps-rate</literal></term> <listitem> <para>Sets the communications speed of the device to @@ -1228,7 +1201,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ </varlistentry> <varlistentry> - <term><literal>ms#<replaceable>stty-mode</replaceable></literal></term> + <term><literal>ms#stty-mode</literal></term> <listitem> <para>Sets the options for the terminal device after @@ -1259,11 +1232,11 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <literal>crtscts</literal>:</para> <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:</programlisting> + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:</programlisting> </sect4> - <sect4 id="printing-textfilter"> + <sect4 xml:id="printing-textfilter"> <title>Installing the Text Filter</title> <indexterm> @@ -1285,8 +1258,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ standard input, perform any necessary translation for the printer, and write the results to standard output, which will get printed. For more information on the text - filter, see the <link - linkend="printing-advanced-filters">Filters</link> + filter, see the <link linkend="printing-advanced-filters">Filters</link> section.</para> <para>For our simple printer setup, the text filter can be a @@ -1318,7 +1290,7 @@ exit 2</programlisting> <para>Make the file executable:</para> - <screen>&prompt.root; <userinput><command>chmod 555 <filename>/usr/local/libexec/if-simple</filename></command></userinput></screen> + <screen>&prompt.root; <userinput>chmod 555 /usr/local/libexec/if-simple</userinput></screen> <para>And then tell LPD to use it by specifying it with the <literal>if</literal> capability in @@ -1330,19 +1302,18 @@ exit 2</programlisting> # /etc/printcap for host rose - added text filter # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :sh:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>:\ :if=<filename>/usr/local/libexec/if-simple</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:\ + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:\ :if=<filename>/usr/local/libexec/if-simple</filename>:</programlisting> <note> <para>A copy of the <filename>if-simple</filename> script - can be found in the <filename - class="directory">/usr/share/examples/printing</filename> + can be found in the <filename>/usr/share/examples/printing</filename> directory.</para> </note> </sect4> @@ -1360,10 +1331,10 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>to <filename>/etc/rc.conf</filename>, and then either restart your machine, or just run &man.lpd.8;.</para> - <screen>&prompt.root; <userinput><command>lpd</command></userinput></screen> + <screen>&prompt.root; <userinput>lpd</userinput></screen> </sect4> - <sect4 id="printing-trying"> + <sect4 xml:id="printing-trying"> <title>Trying It Out</title> <para>You have reached the end of the simple @@ -1376,8 +1347,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ which submits a job for printing.</para> <para>You can combine &man.lpr.1; with the &man.lptest.1; - program, introduced in section <link - linkend="printing-testing">Checking Printer + program, introduced in section <link linkend="printing-testing">Checking Printer Communications</link> to generate some test text.</para> <para><emphasis>To test the simple @@ -1385,7 +1355,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>Type:</para> - <screen>&prompt.root; <userinput><command>lptest 20 5 | lpr <option>-P</option><replaceable>printer-name</replaceable></command></userinput></screen> + <screen>&prompt.root; <userinput>lptest 20 5 | lpr -Pprinter-name</userinput></screen> <para>Where <replaceable>printer-name</replaceable> is a the name of a printer (or an alias) specified in @@ -1395,7 +1365,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ expects &postscript;, send a &postscript; program in that language instead of using &man.lptest.1;. You can do so by putting the program in a file and typing <command>lpr - <replaceable>file</replaceable></command>.</para> + file</command>.</para> <para>For a &postscript; printer, you should get the results of the program. If you are using &man.lptest.1;, then @@ -1413,22 +1383,21 @@ $%&'()*+,-./01234567 <command>lptest 80 60</command> will produce 60 lines of 80 characters each.</para> - <para>If the printer did not work, see the <link - linkend="printing-troubleshooting">Troubleshooting</link> + <para>If the printer did not work, see the <link linkend="printing-troubleshooting">Troubleshooting</link> section.</para> </sect4> </sect3> </sect2> </sect1> - <sect1 id="printing-advanced"> + <sect1 xml:id="printing-advanced"> <title>Advanced Printer Setup</title> <para>This section describes filters for printing specially formatted files, header pages, printing across networks, and restricting and accounting for printer usage.</para> - <sect2 id="printing-advanced-filter-intro"> + <sect2 xml:id="printing-advanced-filter-intro"> <title>Filters</title> <indexterm> @@ -1443,8 +1412,7 @@ $%&'()*+,-./01234567 that communicate with the printer and handle its device dependencies and special requirements. In the simple printer setup, we installed a plain text filter—an extremely - simple one that should work with most printers (section <link - linkend="printing-textfilter">Installing the Text + simple one that should work with most printers (section <link linkend="printing-textfilter">Installing the Text Filter</link>).</para> <para>However, in order to take advantage of format conversion, @@ -1483,8 +1451,7 @@ $%&'()*+,-./01234567 to be able to print plain text by default. This presents a problem for &postscript; printers (or other language-based printers) which cannot directly print - plain text. Section <link - linkend="printing-advanced-if-conversion">Accommodating + plain text. Section <link linkend="printing-advanced-if-conversion">Accommodating Plain Text Jobs on &postscript; Printers</link> tells you what you should do to overcome this problem. You should read this section if you have a &postscript; @@ -1495,8 +1462,7 @@ $%&'()*+,-./01234567 <para>&postscript; is a popular output format for many programs. Some people even write &postscript; code directly. Unfortunately, &postscript; printers are - expensive. Section <link - linkend="printing-advanced-ps">Simulating &postscript; + expensive. Section <link linkend="printing-advanced-ps">Simulating &postscript; on Non &postscript; Printers</link> tells how you can further modify a printer's text filter to accept and print &postscript; data on a <emphasis>non @@ -1505,17 +1471,16 @@ $%&'()*+,-./01234567 </listitem> <listitem> - <para>Section <link - linkend="printing-advanced-convfilters">Conversion + <para>Section <link linkend="printing-advanced-convfilters">Conversion Filters</link> tells about a way you can automate the conversion of specific file formats, such as graphic or typesetting data, into formats your printer can understand. After reading this section, you should be able to set up your printers such that users can type - <command>lpr <option>-t</option></command> to print troff - data, or <command>lpr <option>-d</option></command> to + <command>lpr -t</command> to print troff + data, or <command>lpr -d</command> to print &tex; DVI data, or <command>lpr - <option>-v</option></command> to print raster image + -v</command> to print raster image data, and so forth. The reading of this section is recommended.</para> </listitem> @@ -1524,8 +1489,7 @@ $%&'()*+,-./01234567 <para>Section <link linkend="printing-advanced-of">Output Filters</link> tells all about a not often used feature of <application>LPD</application>: output filters. Unless - you are printing header pages (see <link - linkend="printing-advanced-header-pages">Header + you are printing header pages (see <link linkend="printing-advanced-header-pages">Header Pages</link>), you can probably skip that section altogether.</para> </listitem> @@ -1545,12 +1509,11 @@ $%&'()*+,-./01234567 <note> <para>A copy of the various scripts described below can be - found in the <filename - class="directory">/usr/share/examples/printing</filename> + found in the <filename>/usr/share/examples/printing</filename> directory.</para> </note> - <sect3 id="printing-advanced-filters"> + <sect3 xml:id="printing-advanced-filters"> <title>How Filters Work</title> <para>As mentioned before, a filter is an executable program @@ -1564,7 +1527,7 @@ $%&'()*+,-./01234567 output to the printer, and its standard error to the error logging file (specified in the <literal>lf</literal> capability in <filename>/etc/printcap</filename>, or - <filename class="devicefile">/dev/console</filename> by + <filename>/dev/console</filename> by default).</para> <indexterm> @@ -1575,13 +1538,12 @@ $%&'()*+,-./01234567 <filename>/etc/printcap</filename> file and what arguments the user specified for the job on the &man.lpr.1; command line. For example, if the user typed - <command>lpr <option>-t</option></command>, + <command>lpr -t</command>, <application>LPD</application> would start the troff filter, listed in the <literal>tf</literal> capability for the destination printer. If the user wanted to print plain text, it would start the <literal>if</literal> filter (this - is mostly true: see <link - linkend="printing-advanced-of">Output Filters</link> for + is mostly true: see <link linkend="printing-advanced-of">Output Filters</link> for details).</para> <para>There are three kinds of filters you can specify in @@ -1607,23 +1569,17 @@ $%&'()*+,-./01234567 <cmdsynopsis> <command>filter-name</command> <arg>-c</arg> - <arg - choice="plain">-w + <arg choice="plain">-w <replaceable>width</replaceable></arg> - <arg - choice="plain">-l + <arg choice="plain">-l <replaceable>length</replaceable></arg> - <arg - choice="plain">-i + <arg choice="plain">-i <replaceable>indent</replaceable></arg> - <arg - choice="plain">-n + <arg choice="plain">-n <replaceable>login</replaceable></arg> - <arg - choice="plain">-h + <arg choice="plain">-h <replaceable>host</replaceable></arg> - <arg - choice="plain"><replaceable>acct-file</replaceable></arg> + <arg choice="plain"><replaceable>acct-file</replaceable></arg> </cmdsynopsis> <para>where</para> @@ -1634,7 +1590,7 @@ $%&'()*+,-./01234567 <listitem> <para>appears if the job is submitted with - <command>lpr <option>-l</option></command></para> + <command>lpr -l</command></para> </listitem> </varlistentry> @@ -1663,7 +1619,7 @@ $%&'()*+,-./01234567 <listitem> <para>is the amount of the indentation from - <command>lpr <option>-i</option></command>, + <command>lpr -i</command>, default 0</para> </listitem> </varlistentry> @@ -1704,8 +1660,7 @@ $%&'()*+,-./01234567 cannot be directly printed, but you can install a conversion filter for ditroff files to convert the ditroff data into a form the printer can digest and - print. Section <link - linkend="printing-advanced-convfilters">Conversion + print. Section <link linkend="printing-advanced-convfilters">Conversion Filters</link> tells all about them. Conversion filters also need to do accounting, if you need printer accounting. Conversion filters are started with the @@ -1715,17 +1670,13 @@ $%&'()*+,-./01234567 <command>filter-name</command> <arg choice="plain">-x <replaceable>pixel-width</replaceable></arg> - <arg - choice="plain">-y + <arg choice="plain">-y <replaceable>pixel-height</replaceable></arg> - <arg - choice="plain">-n + <arg choice="plain">-n <replaceable>login</replaceable></arg> - <arg - choice="plain">-h + <arg choice="plain">-h <replaceable>host</replaceable></arg> - <arg - choice="plain"><replaceable>acct-file</replaceable></arg> + <arg choice="plain"><replaceable>acct-file</replaceable></arg> </cmdsynopsis> <para>where <replaceable>pixel-width</replaceable> is @@ -1739,18 +1690,15 @@ $%&'()*+,-./01234567 <para>The <emphasis>output filter</emphasis> is used only if there is no text filter, or if header pages are enabled. In our experience, output filters are rarely - used. Section <link - linkend="printing-advanced-of">Output Filters</link> + used. Section <link linkend="printing-advanced-of">Output Filters</link> describes them. There are only two arguments to an output filter:</para> <cmdsynopsis> <command>filter-name</command> - <arg - choice="plain">-w + <arg choice="plain">-w <replaceable>width</replaceable></arg> - <arg - choice="plain">-l + <arg choice="plain">-l <replaceable>length</replaceable></arg> </cmdsynopsis> @@ -1811,7 +1759,7 @@ $%&'()*+,-./01234567 and exit codes.</para> </sect3> - <sect3 id="printing-advanced-if-conversion"> + <sect3 xml:id="printing-advanced-if-conversion"> <title>Accommodating Plain Text Jobs on &postscript; Printers</title> @@ -1861,8 +1809,8 @@ $%&'()*+,-./01234567 <para><command>lprps</command> is part of the &os; Ports Collection (see <link linkend="ports">The Ports Collection</link>). You can install one of the both - <filename role="package">print/lprps-a4</filename> and - <filename role="package">print/lprps-letter</filename> ports + <package>print/lprps-a4</package> and + <package>print/lprps-letter</package> ports according to the paper size used. After installing <command>lprps</command>, just specify the pathname to the <command>psif</command> program that is part of @@ -1909,14 +1857,13 @@ fi</programlisting> <para>In the above script, <command>textps</command> is a program we installed separately to convert plain text to &postscript;. You can use any text-to-&postscript; program - you wish. The &os; Ports Collection (see <link - linkend="ports">The Ports Collection</link>) includes a + you wish. The &os; Ports Collection (see <link linkend="ports">The Ports Collection</link>) includes a full featured text-to-&postscript; program called <literal>a2ps</literal> that you might want to investigate.</para> </sect3> - <sect3 id="printing-advanced-ps"> + <sect3 xml:id="printing-advanced-ps"> <title>Simulating &postscript; on Non &postscript; Printers</title> @@ -1943,8 +1890,7 @@ fi</programlisting> <para><application>Ghostscript</application> is in the &os; Ports Collection, many versions are available, the most - commonly used version is <filename - role="package">print/ghostscript-gpl</filename>.</para> + commonly used version is <package>print/ghostscript-gpl</package>.</para> <para>To simulate &postscript;, we have the text filter detect if it is printing a &postscript; file. If it is not, then @@ -1958,7 +1904,7 @@ fi</programlisting> printers, substitute the <option>-sDEVICE</option> argument to the <command>gs</command> (<application>Ghostscript</application>) command. (Type - <command>gs <option>-h</option></command> to get a list of + <command>gs -h</command> to get a list of devices the current installation of <application>Ghostscript</application> supports.)</para> @@ -2004,18 +1950,17 @@ exit 2</programlisting> <para>That is it. You can type <command>lpr - <filename><replaceable>plain.text</replaceable></filename></command> + plain.text</command> and <command>lpr - <filename><replaceable>whatever.ps</replaceable></filename></command> + whatever.ps</command> and both should print successfully.</para> </sect3> - <sect3 id="printing-advanced-convfilters"> + <sect3 xml:id="printing-advanced-convfilters"> <title>Conversion Filters</title> - <para>After completing the simple setup described in <link - linkend="printing-simple">Simple Printer Setup</link>, + <para>After completing the simple setup described in <link linkend="printing-simple">Simple Printer Setup</link>, the first thing you will probably want to do is install conversion filters for your favorite file formats (besides plain ASCII text).</para> @@ -2036,8 +1981,8 @@ exit 2</programlisting> the DVI file into &postscript;. The command sequence goes like this:</para> - <screen>&prompt.user; <userinput><command>dvips <filename><replaceable>seaweed-analysis.dvi</replaceable></filename></command></userinput> -&prompt.user; <userinput><command>lpr <filename><replaceable>seaweed-analysis.ps</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>dvips seaweed-analysis.dvi</userinput> +&prompt.user; <userinput>lpr seaweed-analysis.ps</userinput></screen> <para>By installing a conversion filter for DVI files, we can skip the hand conversion step each time by having @@ -2045,12 +1990,11 @@ exit 2</programlisting> time we get a DVI file, we are just one step away from printing it:</para> - <screen>&prompt.user; <userinput><command>lpr <option>-d</option> <filename><replaceable>seaweed-analysis.dvi</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr -d seaweed-analysis.dvi</userinput></screen> <para>We got <application>LPD</application> to do the DVI file conversion for us by specifying the - <option>-d</option> option. Section <link - linkend="printing-lpr-options-format">Formatting and + <option>-d</option> option. Section <link linkend="printing-lpr-options-format">Formatting and Conversion Options</link> lists the conversion options.</para> @@ -2146,7 +2090,7 @@ exit 2</programlisting> </informaltable> <para>In our example, using - <command>lpr <option>-d</option></command> means the + <command>lpr -d</command> means the printer needs a <literal>df</literal> capability in its entry in <filename>/etc/printcap</filename>.</para> @@ -2160,7 +2104,7 @@ exit 2</programlisting> publishing program), but will never print plot files. You could install a Printerleaf conversion filter under the <literal>gf</literal> capability and then educate your - users that <command>lpr <option>-g</option></command> mean + users that <command>lpr -g</command> mean <quote>print Printerleaf files.</quote></para> </sect4> @@ -2169,10 +2113,8 @@ exit 2</programlisting> <para>Since conversion filters are programs you install outside of the base &os; installation, they should - probably go under <filename - class="directory">/usr/local</filename>. The - directory <filename - class="directory">/usr/local/libexec</filename> is a + probably go under <filename>/usr/local</filename>. The + directory <filename>/usr/local/libexec</filename> is a popular location, since they are specialized programs that only <application>LPD</application> will run; regular users should not ever need to run them.</para> @@ -2192,13 +2134,13 @@ exit 2</programlisting> # /etc/printcap for host rose - added df filter for bamboo # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :sh:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>:\ :if=<filename>/usr/local/libexec/if-simple</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ :if=<filename>/usr/local/libexec/psif</filename>:\ :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> @@ -2219,8 +2161,7 @@ exec /usr/local/bin/dvips -f | /usr/local/libexec/lprps "$@"</programlisting> mode (the <option>-f</option> argument) on standard input, which is the job to print. It then starts the &postscript; printer filter <command>lprps</command> - (see section <link - linkend="printing-advanced-if-conversion">Accommodating + (see section <link linkend="printing-advanced-if-conversion">Accommodating Plain Text Jobs on &postscript; Printers</link>) with the arguments <application>LPD</application> passed to this script. The <command>lprps</command> utility will @@ -2262,7 +2203,7 @@ giftopnm | ppmtopgm | pgmtopbm | pbmtolj -resolution 300 \ # /etc/printcap for host orchid # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:sh:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :lp=<filename>/dev/lpt0</filename>:sh:sd=<filename>/var/spool/lpd/teak</filename>:mx#0:\ :if=<filename>/usr/local/libexec/hpif</filename>:\ :vf=<filename>/usr/local/libexec/hpvf</filename>:</programlisting> @@ -2328,8 +2269,7 @@ exit 2</programlisting> <para>Now, for the hard part: making the filter. For that, we need a DVI-to-LaserJet/PCL conversion program. The &os; Ports Collection (see <link linkend="ports">The Ports - Collection</link>) has one: <filename - role="package">print/dvi2xx</filename>. Installing this + Collection</link>) has one: <package>print/dvi2xx</package>. Installing this port gives us the program we need, <command>dvilj2p</command>, which converts DVI into LaserJet IIp, LaserJet III, and LaserJet 2000 compatible @@ -2340,20 +2280,19 @@ exit 2</programlisting> <command>dvilj2p</command> cannot read from standard input. It wants to work with a filename. What is worse, the filename has to end in <filename>.dvi</filename> so - using <filename class="devicefile">/dev/fd/0</filename> + using <filename>/dev/fd/0</filename> for standard input is problematic. We can get around that problem by linking (symbolically) a temporary file name (one that ends in <filename>.dvi</filename>) to - <filename class="devicefile">/dev/fd/0</filename>, thereby + <filename>/dev/fd/0</filename>, thereby forcing <command>dvilj2p</command> to read from standard input.</para> <para>The only other fly in the ointment is the fact that - we cannot use <filename class="directory">/tmp</filename> + we cannot use <filename>/tmp</filename> for the temporary link. Symbolic links are owned by user - and group <username>bin</username>. The filter runs as - user <username>daemon</username>. And the <filename - class="directory">/tmp</filename> directory has the + and group <systemitem class="username">bin</systemitem>. The filter runs as + user <systemitem class="username">daemon</systemitem>. And the <filename>/tmp</filename> directory has the sticky bit set. The filter can create the link, but it will not be able clean up when done and remove it since the link will belong to a different user.</para> @@ -2365,7 +2304,7 @@ exit 2</programlisting> is a perfect place for filters to do their work, especially since there is (sometimes) more free disk space in the spooling directory than under - <filename class="directory">/tmp</filename>.</para> + <filename>/tmp</filename>.</para> <para>Here, finally, is the filter:</para> @@ -2430,7 +2369,7 @@ cleanup exit 0</programlisting> </sect4> - <sect4 id="printing-advanced-autoconv"> + <sect4 xml:id="printing-advanced-autoconv"> <title>Automated Conversion: an Alternative to Conversion Filters</title> @@ -2462,14 +2401,13 @@ exit 0</programlisting> </indexterm> <para>The &os; Ports Collection has a text filter that performs automatic conversion called - <command>apsfilter</command> (<filename - role="package">print/apsfilter</filename>). It can + <command>apsfilter</command> (<package>print/apsfilter</package>). It can detect plain text, &postscript;, DVI and almost any kind of files, run the proper conversions, and print.</para> </sect4> </sect3> - <sect3 id="printing-advanced-of"> + <sect3 xml:id="printing-advanced-of"> <title>Output Filters</title> <para>The <application>LPD</application> spooling system @@ -2500,10 +2438,8 @@ exit 0</programlisting> <cmdsynopsis> <command>filter-name</command> - <arg - choice="plain">-w<replaceable>width</replaceable></arg> - <arg - choice="plain">-l<replaceable>length</replaceable></arg> + <arg choice="plain">-w<replaceable>width</replaceable></arg> + <arg choice="plain">-l<replaceable>length</replaceable></arg> </cmdsynopsis> <para>Where <replaceable>width</replaceable> is from the @@ -2567,15 +2503,15 @@ exit 0</programlisting> initialization codes the printer might require.</para> </sect3> - <sect3 id="printing-advanced-lpf"> + <sect3 xml:id="printing-advanced-lpf"> <title><command>lpf</command>: a Text Filter</title> <para>The program <filename>/usr/libexec/lpr/lpf</filename> that comes with &os; binary distribution is a text filter (input filter) that can indent output (job submitted with - <command>lpr <option>-i</option></command>), allow literal + <command>lpr -i</command>), allow literal characters to pass (job submitted with - <command>lpr <option>-l</option></command>), adjust the + <command>lpr -l</command>), adjust the printing position for backspaces and tabs in the job, and account for pages printed. It can also act like an output filter.</para> @@ -2597,13 +2533,12 @@ exit 0</programlisting> capabilities in the <filename>/etc/printcap</filename> file. It uses these values to determine how much text can fit on a page and how many pages were in a user's job. For more - information on printer accounting, see <link - linkend="printing-advanced-acct">Accounting for Printer + information on printer accounting, see <link linkend="printing-advanced-acct">Accounting for Printer Usage</link>.</para> </sect3> </sect2> - <sect2 id="printing-advanced-header-pages"> + <sect2 xml:id="printing-advanced-header-pages"> <title>Header Pages</title> <para>If you have <emphasis>lots</emphasis> of users, all of @@ -2638,7 +2573,7 @@ exit 0</programlisting> <link linkend="printing-advanced-header-pages-ps">Header Pages on &postscript; Printers</link>.</para> - <sect3 id="printing-advanced-header-pages-enabling"> + <sect3 xml:id="printing-advanced-header-pages-enabling"> <title>Enabling Header Pages</title> <para>In the <link linkend="printing-simple">Simple Printer @@ -2664,8 +2599,7 @@ printf "\033&k2G" || exit 2 exec /usr/libexec/lpr/lpf</programlisting> <para>Specify the path to the output filter in the - <literal>of</literal> capability. See the <link - linkend="printing-advanced-of">Output Filters</link> + <literal>of</literal> capability. See the <link linkend="printing-advanced-of">Output Filters</link> section for more information.</para> <para>Here is an example <filename>/etc/printcap</filename> @@ -2677,7 +2611,7 @@ exec /usr/libexec/lpr/lpf</programlisting> # /etc/printcap for host orchid # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :lp=<filename>/dev/lpt0</filename>:sd=<filename>/var/spool/lpd/teak</filename>:mx#0:\ :if=<filename>/usr/local/libexec/hpif</filename>:\ :vf=<filename>/usr/local/libexec/hpvf</filename>:\ :of=<filename>/usr/local/libexec/hpof</filename>:</programlisting> @@ -2686,8 +2620,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ they get a header page with each job. If users want to spend time searching for their printouts, they can suppress header pages by submitting the job with <command>lpr - <option>-h</option></command>; see the <link - linkend="printing-lpr-options-misc">Header Page + -h</command>; see the <link linkend="printing-lpr-options-misc">Header Page Options</link> section for more &man.lpr.1; options.</para> @@ -2700,15 +2633,15 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ </note> </sect3> - <sect3 id="printing-advanced-header-pages-controlling"> + <sect3 xml:id="printing-advanced-header-pages-controlling"> <title>Controlling Header Pages</title> <para>By enabling header pages, <application>LPD</application> will produce a <emphasis>long header</emphasis>, a full page of large letters identifying the user, host, and job. - Here is an example (<username>kelly</username> printed the + Here is an example (<systemitem class="username">kelly</systemitem> printed the job named <quote>outline</quote> from host - <hostid>rose</hostid>):</para> + <systemitem>rose</systemitem>):</para> <screen> k ll ll k l l @@ -2778,7 +2711,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ <filename>/etc/printcap</filename>.</para> </sect3> - <sect3 id="printing-advanced-header-pages-accounting"> + <sect3 xml:id="printing-advanced-header-pages-accounting"> <title>Accounting for Header Pages</title> <para>Using <application>LPD</application>'s built-in header @@ -2797,9 +2730,9 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ the page count by one</quote> by modifying the text filter or any of the conversion filters (which do have user and host information) since users can suppress header pages - with <command>lpr <option>-h</option></command>. They could + with <command>lpr -h</command>. They could still be charged for header pages they did not print. - Basically, <command>lpr <option>-h</option></command> will + Basically, <command>lpr -h</command> will be the preferred option of environmentally-minded users, but you cannot offer any incentive to use it.</para> @@ -2807,7 +2740,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ of the filters generate their own header pages (thereby being able to charge for them). If users wanted the option of suppressing the header pages with <command>lpr - <option>-h</option></command>, they will still get them + -h</command>, they will still get them and be charged for them since <application>LPD</application> does not pass any knowledge of the <option>-h</option> option to any of the filters.</para> @@ -2825,8 +2758,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ <listitem> <para>Install an alternative to <application>LPD</application>, such as - <application>LPRng</application>. Section <link - linkend="printing-lpd-alternatives">Alternatives to + <application>LPRng</application>. Section <link linkend="printing-lpd-alternatives">Alternatives to the Standard Spooler</link> tells more about other spooling software you can substitute for <application>LPD</application>.</para> @@ -2859,7 +2791,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ </itemizedlist> </sect3> - <sect3 id="printing-advanced-header-pages-ps"> + <sect3 xml:id="printing-advanced-header-pages-ps"> <title>Header Pages on &postscript; Printers</title> <para>As described above, <application>LPD</application> can @@ -2875,7 +2807,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ to generate a suitable header page. The drawback of this method is that users will always get a header page, even if they submit jobs with <command>lpr - <option>-h</option></command>.</para> + -h</command>.</para> <para>Let us explore this method. The following script takes three arguments (user login name, host name, and job name) @@ -3016,12 +2948,11 @@ done <para>To allow users to shut off header pages on a per-job basis, you will need to use the trick introduced in section - <link - linkend="printing-advanced-header-pages-accounting">Accounting + <link linkend="printing-advanced-header-pages-accounting">Accounting for Header Pages</link>: write an output filter that parses the LPD-generated header page and produces a &postscript; version. If the user submits the job with - <command>lpr <option>-h</option></command>, + <command>lpr -h</command>, then <application>LPD</application> will not generate a header page, and neither will your output filter. Otherwise, your output filter will read the text from @@ -3036,7 +2967,7 @@ done </sect3> </sect2> - <sect2 id="printing-advanced-network-printers"> + <sect2 xml:id="printing-advanced-network-printers"> <title>Networked Printing</title> <indexterm> @@ -3054,8 +2985,7 @@ done install a printer that has a conventional serial or parallel interface on one host. Then, you set up <application>LPD</application> to enable access to the - printer from other hosts on the network. Section <link - linkend="printing-advanced-network-rm">Printers + printer from other hosts on the network. Section <link linkend="printing-advanced-network-rm">Printers Installed on Remote Hosts</link> tells how to do this.</para> </listitem> @@ -3073,8 +3003,7 @@ done queue jobs from remote hosts. In this case, it acts just like a regular host running <application>LPD</application>. Follow the same - procedure in section <link - linkend="printing-advanced-network-rm">Printers + procedure in section <link linkend="printing-advanced-network-rm">Printers Installed on Remote Hosts</link> to set up such a printer.</para> </listitem> @@ -3084,8 +3013,7 @@ done In this case, you <quote>attach</quote> the printer to one host on the network by making that host responsible for spooling jobs and sending them to the - printer. Section <link - linkend="printing-advanced-network-net-if">Printers + printer. Section <link linkend="printing-advanced-network-net-if">Printers with Networked Data Stream Interfaces</link> gives some suggestions on installing such printers.</para> </listitem> @@ -3093,7 +3021,7 @@ done </listitem> </itemizedlist> - <sect3 id="printing-advanced-network-rm"> + <sect3 xml:id="printing-advanced-network-rm"> <title>Printers Installed on Remote Hosts</title> <para>The <application>LPD</application> spooling system has @@ -3107,17 +3035,14 @@ done <para>To enable this kind of remote printing, first install a printer on one host, the <emphasis>printer host</emphasis>, - using the simple printer setup described in the <link - linkend="printing-simple">Simple Printer Setup</link> - section. Do any advanced setup in <link - linkend="printing-advanced">Advanced Printer Setup</link> + using the simple printer setup described in the <link linkend="printing-simple">Simple Printer Setup</link> + section. Do any advanced setup in <link linkend="printing-advanced">Advanced Printer Setup</link> that you need. Make sure to test the printer and see if it works with the features of <application>LPD</application> you have enabled. Also ensure that the <emphasis>local host</emphasis> has authorization to use the <application>LPD</application> service in the - <emphasis>remote host</emphasis> (see <link - linkend="printing-advanced-restricting-remote">Restricting + <emphasis>remote host</emphasis> (see <link linkend="printing-advanced-restricting-remote">Restricting Jobs from Remote Hosts</link>).</para> <indexterm> @@ -3180,16 +3105,15 @@ done page dimensions, or anything else in the <filename>/etc/printcap</filename> file.</para> - <para>Here is an example. The host <hostid>rose</hostid> has + <para>Here is an example. The host <systemitem>rose</systemitem> has two printers, <literal>bamboo</literal> and <literal>rattan</literal>. We will enable users on the host - <hostid>orchid</hostid> to print to those printers. Here is + <systemitem>orchid</systemitem> to print to those printers. Here is the <filename>/etc/printcap</filename> file for - <hostid>orchid</hostid> (back from section <link - linkend="printing-advanced-header-pages-enabling">Enabling + <systemitem>orchid</systemitem> (back from section <link linkend="printing-advanced-header-pages-enabling">Enabling Header Pages</link>). It already had the entry for the printer <literal>teak</literal>; we have added entries for - the two printers on the host <hostid>rose</hostid>:</para> + the two printers on the host <systemitem>rose</systemitem>:</para> <programlisting># # /etc/printcap for host orchid - added (remote) printers on rose @@ -3199,7 +3123,7 @@ done # teak is local; it is connected directly to orchid: # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :lp=<filename>/dev/lpt0</filename>:sd=<filename>/var/spool/lpd/teak</filename>:mx#0:\ :if=<filename>/usr/local/libexec/ifhp</filename>:\ :vf=<filename>/usr/local/libexec/vfhp</filename>:\ :of=<filename>/usr/local/libexec/ofhp</filename>: @@ -3208,44 +3132,43 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ # rattan is connected to rose; send jobs for rattan to rose: # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :lp=:rm=rose:rp=rattan:sd=<filename class="directory">/var/spool/lpd/rattan</filename>: + :lp=:rm=rose:rp=rattan:sd=<filename>/var/spool/lpd/rattan</filename>: # # bamboo is connected to rose as well: # bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :lp=:rm=rose:rp=bamboo:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:</programlisting> + :lp=:rm=rose:rp=bamboo:sd=<filename>/var/spool/lpd/bamboo</filename>:</programlisting> <para>Then, we just need to make spooling directories on - <hostid>orchid</hostid>:</para> + <systemitem>orchid</systemitem>:</para> - <screen>&prompt.root; <userinput><command>mkdir <option>-p</option> <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput> -&prompt.root; <userinput><command>chmod 770 <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput> -&prompt.root; <userinput><command>chown daemon:daemon <filename class="directory">/var/spool/lpd/rattan</filename> <filename class="directory">/var/spool/lpd/bamboo</filename></command></userinput></screen> + <screen>&prompt.root; <userinput>mkdir -p /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput> +&prompt.root; <userinput>chmod 770 /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput> +&prompt.root; <userinput>chown daemon:daemon /var/spool/lpd/rattan /var/spool/lpd/bamboo</userinput></screen> - <para>Now, users on <hostid>orchid</hostid> can print to + <para>Now, users on <systemitem>orchid</systemitem> can print to <literal>rattan</literal> and <literal>bamboo</literal>. - If, for example, a user on <hostid>orchid</hostid> + If, for example, a user on <systemitem>orchid</systemitem> typed:</para> - <screen>&prompt.user; <userinput><command>lpr <option>-P</option> bamboo <option>-d</option> <filename><replaceable>sushi-review.dvi</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr -P bamboo -d sushi-review.dvi</userinput></screen> <para>the <application>LPD</application> system on - <hostid>orchid</hostid> would copy the job to the spooling - directory <filename - class="directory">/var/spool/lpd/bamboo</filename> and + <systemitem>orchid</systemitem> would copy the job to the spooling + directory <filename>/var/spool/lpd/bamboo</filename> and note that it was a DVI job. As soon as the host - <hostid>rose</hostid> has room in its + <systemitem>rose</systemitem> has room in its <literal>bamboo</literal> spooling directory, the two <application>LPD</application>s would transfer the file to - <hostid>rose</hostid>. The file would wait in - <hostid>rose</hostid>'s queue until it was finally printed. + <systemitem>rose</systemitem>. The file would wait in + <systemitem>rose</systemitem>'s queue until it was finally printed. It would be converted from DVI to &postscript; (since <literal>bamboo</literal> is a &postscript; printer) on - <hostid>rose</hostid>.</para> + <systemitem>rose</systemitem>.</para> </sect3> - <sect3 id="printing-advanced-network-net-if"> + <sect3 xml:id="printing-advanced-network-net-if"> <title>Printers with Networked Data Stream Interfaces</title> <para>Often, when you buy a network interface card for a @@ -3255,8 +3178,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ you were using a serial or parallel port (the cheaper version). This section tells how to use the cheaper version. For the more expensive one, see the previous - section <link - linkend="printing-advanced-network-rm">Printers Installed + section <link linkend="printing-advanced-network-rm">Printers Installed on Remote Hosts</link>.</para> <para>The format of the <filename>/etc/printcap</filename> @@ -3307,7 +3229,7 @@ exit 0;</programlisting> <para>We can then use this script in various filters. Suppose we had a Diablo 750-N line printer connected to the network. The printer accepts data to print on port number 5100. The - host name of the printer is <hostid>scrivener</hostid>. + host name of the printer is <systemitem>scrivener</systemitem>. Here is the text filter for the printer:</para> <programlisting>#!/bin/sh @@ -3319,7 +3241,7 @@ exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</pro </sect3> </sect2> - <sect2 id="printing-advanced-restricting"> + <sect2 xml:id="printing-advanced-restricting"> <title>Restricting Printer Usage</title> <indexterm> @@ -3332,12 +3254,12 @@ exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</pro whether they can print multiple copies, how large their jobs can be, and how large the printer queues can get.</para> - <sect3 id="printing-advanced-restricting-copies"> + <sect3 xml:id="printing-advanced-restricting-copies"> <title>Restricting Multiple Copies</title> <para>The <application>LPD</application> system makes it easy for users to print multiple copies of a file. Users can - print jobs with <command>lpr <option>-#5</option></command> + print jobs with <command>lpr -#5</command> (for example) and get five copies of each file in the job. Whether this is a good thing is up to you.</para> @@ -3352,8 +3274,7 @@ exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</pro <screen>lpr: multiple copies are not allowed</screen> <para>Note that if you have set up access to a printer - remotely (see section <link - linkend="printing-advanced-network-rm">Printers + remotely (see section <link linkend="printing-advanced-network-rm">Printers Installed on Remote Hosts</link>), you need the <literal>sc</literal> capability on the remote <filename>/etc/printcap</filename> files as well, or else @@ -3362,7 +3283,7 @@ exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</pro <para>Here is an example. This is the <filename>/etc/printcap</filename> file for the host - <hostid>rose</hostid>. The printer + <systemitem>rose</systemitem>. The printer <literal>rattan</literal> is quite hearty, so we will allow multiple copies, but the laser printer <literal>bamboo</literal> is a bit more delicate, so @@ -3373,18 +3294,18 @@ exec /usr/libexec/lpr/lpf "$@" | /usr/local/libexec/netprint scrivener 5100</pro # /etc/printcap for host rose - restrict multiple copies on bamboo # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :sh:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>:\ :if=<filename>/usr/local/libexec/if-simple</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:sc:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ :if=<filename>/usr/local/libexec/psif</filename>:\ :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> <para>Now, we also need to add the <literal>sc</literal> - capability on the host <hostid>orchid</hostid>'s + capability on the host <systemitem>orchid</systemitem>'s <filename>/etc/printcap</filename> (and while we are at it, let us disable multiple copies for the printer <literal>teak</literal>):</para> @@ -3393,31 +3314,31 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ # /etc/printcap for host orchid - no multiple copies for local # printer teak or remote printer bamboo teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:sc:\ + :lp=<filename>/dev/lpt0</filename>:sd=<filename>/var/spool/lpd/teak</filename>:mx#0:sc:\ :if=<filename>/usr/local/libexec/ifhp</filename>:\ :vf=<filename>/usr/local/libexec/vfhp</filename>:\ :of=<filename>/usr/local/libexec/ofhp</filename>: rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :lp=:rm=rose:rp=rattan:sd=<filename class="directory">/var/spool/lpd/rattan</filename>: + :lp=:rm=rose:rp=rattan:sd=<filename>/var/spool/lpd/rattan</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :lp=:rm=rose:rp=bamboo:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:</programlisting> + :lp=:rm=rose:rp=bamboo:sd=<filename>/var/spool/lpd/bamboo</filename>:sc:</programlisting> <para>By using the <literal>sc</literal> capability, we prevent the use of <command>lpr - <option>-#</option></command>, but that still + -#</command>, but that still does not prevent users from running &man.lpr.1; multiple times, or from submitting the same file multiple times in one job like this:</para> - <screen>&prompt.user; <userinput>lpr <filename><replaceable>forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</replaceable></filename></userinput></screen> + <screen>&prompt.user; <userinput>lpr forsale.sign forsale.sign forsale.sign forsale.sign forsale.sign</userinput></screen> <para>There are many ways to prevent this abuse (including ignoring it) which you are free to explore.</para> </sect3> - <sect3 id="printing-advanced-restricting-access"> + <sect3 xml:id="printing-advanced-restricting-access"> <title>Restricting Access to Printers</title> <para>You can control who can print to what printers by using @@ -3428,7 +3349,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <literal>rg</literal> capability.</para> <para>If users outside the group (including - <username>root</username>) try to print to the controlled + <systemitem class="username">root</systemitem>) try to print to the controlled printer then they will be greeted with the following message:</para> @@ -3443,32 +3364,32 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>For example, we will let anyone access the printer <literal>rattan</literal>, but only those in group - <groupname>artists</groupname> can use + <systemitem class="groupname">artists</systemitem> can use <literal>bamboo</literal>. Here is the familiar <filename>/etc/printcap</filename> for host - <hostid>rose</hostid>:</para> + <systemitem>rose</systemitem>:</para> <programlisting># # /etc/printcap for host rose - restricted group for bamboo # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :sh:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>:\ :if=<filename>/usr/local/libexec/if-simple</filename>: bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:sc:rg=artists:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ :if=<filename>/usr/local/libexec/psif</filename>:\ :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> <para>Let us leave the other example <filename>/etc/printcap</filename> file (for the host - <hostid>orchid</hostid>) alone. Of course, anyone on - <hostid>orchid</hostid> can print to + <systemitem>orchid</systemitem>) alone. Of course, anyone on + <systemitem>orchid</systemitem> can print to <literal>bamboo</literal>. It might be the case that we only allow certain logins on - <hostid>orchid</hostid> anyway, and want them to have access + <systemitem>orchid</systemitem> anyway, and want them to have access to the printer. Or not.</para> <note> @@ -3477,7 +3398,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ </note> </sect3> - <sect3 id="printing-advanced-restricting-sizes"> + <sect3 xml:id="printing-advanced-restricting-sizes"> <title>Controlling Sizes of Jobs Submitted</title> <indexterm><primary>print jobs</primary></indexterm> @@ -3515,7 +3436,7 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>Let us add limits to our example printers <literal>rattan</literal> and <literal>bamboo</literal>. - Since those <groupname>artists</groupname>' &postscript; + Since those <systemitem class="groupname">artists</systemitem>' &postscript; files tend to be large, we will limit them to five megabytes. We will put no limit on the plain text line printer:</para> @@ -3528,16 +3449,16 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ # No limit on job size: # rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:mx#0:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :sh:mx#0:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>:\ :if=<filename>/usr/local/libexec/if-simple</filename>: # # Limit of five megabytes: # bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:\ :if=<filename>/usr/local/libexec/psif</filename>:\ :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> @@ -3546,18 +3467,16 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ will not get those limits. You will need to specify the <literal>mx</literal> capability in the remote <filename>/etc/printcap</filename> files as well. See - section <link - linkend="printing-advanced-network-rm">Printers Installed + section <link linkend="printing-advanced-network-rm">Printers Installed on Remote Hosts</link> for more information on remote printing.</para> <para>There is another specialized way to limit job sizes from - remote printers; see section <link - linkend="printing-advanced-restricting-remote">Restricting + remote printers; see section <link linkend="printing-advanced-restricting-remote">Restricting Jobs from Remote Hosts</link>.</para> </sect3> - <sect3 id="printing-advanced-restricting-remote"> + <sect3 xml:id="printing-advanced-restricting-remote"> <title>Restricting Jobs from Remote Hosts</title> <para>The <application>LPD</application> spooling system @@ -3588,17 +3507,16 @@ bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ <para>For example, here is the <filename>/etc/hosts.lpd</filename> file on the host - <hostid>rose</hostid>:</para> + <systemitem>rose</systemitem>:</para> <programlisting>orchid violet madrigal.fishbaum.de</programlisting> - <para>This means <hostid>rose</hostid> will accept - requests from the hosts <hostid>orchid</hostid>, - <hostid>violet</hostid>, and <hostid - role="fqdn">madrigal.fishbaum.de</hostid>. If any - other host tries to access <hostid>rose</hostid>'s + <para>This means <systemitem>rose</systemitem> will accept + requests from the hosts <systemitem>orchid</systemitem>, + <systemitem>violet</systemitem>, and <systemitem class="fqdomainname">madrigal.fishbaum.de</systemitem>. If any + other host tries to access <systemitem>rose</systemitem>'s <application>LPD</application>, the job will be refused.</para> </listitem> @@ -3632,8 +3550,8 @@ madrigal.fishbaum.de</programlisting> <literal>bamboo</literal>'s entry:</para> <programlisting>bamboo|ps|PS|S|panasonic|Panasonic KX-P4455 PostScript v51.4:\ - :sh:sd=<filename class="directory">/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\ - :lp=<filename class="devicefile">/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\ + :sh:sd=<filename>/var/spool/lpd/bamboo</filename>:sc:rg=artists:mx#5000:\ + :lp=<filename>/dev/ttyu5</filename>:ms#-parenb cs8 clocal crtscts:rw:mx#5000:\ :if=<filename>/usr/local/libexec/psif</filename>:\ :df=<filename>/usr/local/libexec/psdf</filename>:</programlisting> @@ -3644,7 +3562,7 @@ madrigal.fishbaum.de</programlisting> <application>LPD</application> to accept remote jobs:</para> - <screen>&prompt.root; <userinput><command>echo 6144 > <filename>/var/spool/lpd/bamboo/minfree</filename></command></userinput></screen> + <screen>&prompt.root; <userinput>echo 6144 > /var/spool/lpd/bamboo/minfree</userinput></screen> </listitem> </varlistentry> @@ -3680,7 +3598,7 @@ madrigal.fishbaum.de</programlisting> </sect3> </sect2> - <sect2 id="printing-advanced-acct"> + <sect2 xml:id="printing-advanced-acct"> <title>Accounting for Printer Usage</title> <indexterm> @@ -3706,8 +3624,7 @@ madrigal.fishbaum.de</programlisting> filters (to charge for other file formats), to count pages or query the printer for pages printed. You cannot get away with using the simple output filter, since it cannot do accounting. - See section <link - linkend="printing-advanced-filter-intro">Filters</link>.</para> + See section <link linkend="printing-advanced-filter-intro">Filters</link>.</para> <para>Generally, there are two ways to do accounting:</para> @@ -3758,8 +3675,7 @@ madrigal.fishbaum.de</programlisting> Filter</link>, and &man.pac.8;, a program to gather and total entries from printer accounting files.</para> - <para>As mentioned in the section on filters (<link - linkend="printing-advanced-filters">Filters</link>), + <para>As mentioned in the section on filters (<link linkend="printing-advanced-filters">Filters</link>), <application>LPD</application> starts the text and the conversion filters with the name of the accounting file to use on the filter command line. The filters can use this @@ -3840,10 +3756,10 @@ total 337.00 154 $ 6.74</screen> <listitem> <para>Ignore host name in the accounting files. With - this option, user <username>smith</username> on host - <hostid>alpha</hostid> is the same user - <username>smith</username> on host - <hostid>gamma</hostid>. Without, they are different + this option, user <systemitem class="username">smith</systemitem> on host + <systemitem>alpha</systemitem> is the same user + <systemitem class="username">smith</systemitem> on host + <systemitem>gamma</systemitem>. Without, they are different users.</para> </listitem> </varlistentry> @@ -3895,7 +3811,7 @@ total 337.00 154 $ 6.74</screen> see the number of pages printed by each user from various hosts. If, at your site, host does not matter (because users can use any host), run <command>pac - <option>-m</option></command>, to produce the following + -m</command>, to produce the following summary:</para> <screen> Login pages/feet runs price @@ -3918,13 +3834,13 @@ total 337.00 154 $ 6.74</screen> units for the <option>-p</option> option are in dollars, though, not hundredths of cents. For example,</para> - <screen>&prompt.root; <userinput><command>pac <option>-p1.50</option></command></userinput></screen> + <screen>&prompt.root; <userinput>pac -p1.50</userinput></screen> <para>makes each page cost one dollar and fifty cents. You can really rake in the profits by using this option.</para> <para>Finally, running <command>pac - <option>-s</option></command> will + -s</command> will save the summary information in a summary accounting file, which is named the same as the printer's accounting file, but with <literal>_sum</literal> appended to the name. It @@ -3989,7 +3905,7 @@ total 337.00 154 $ 6.74</screen> </sect2> </sect1> - <sect1 id="printing-using"> + <sect1 xml:id="printing-using"> <title>Using Printers</title> <indexterm> @@ -4027,8 +3943,7 @@ total 337.00 154 $ 6.74</screen> </variablelist> <para>There is also an administrative command, &man.lpc.8;, - described in the section <link - linkend="printing-lpc">Administering Printers</link>, used to + described in the section <link linkend="printing-lpc">Administering Printers</link>, used to control printers and their queues.</para> <para>All three of the commands &man.lpr.1;, &man.lprm.1;, and @@ -4049,12 +3964,12 @@ total 337.00 154 $ 6.74</screen> named <literal>lp</literal> when there is no <envar>PRINTER</envar> environment variable.</para> - <sect2 id="printing-lpr"> + <sect2 xml:id="printing-lpr"> <title>Printing Jobs</title> <para>To print files, type:</para> - <screen>&prompt.user; <userinput><command>lpr <filename><replaceable>filename</replaceable></filename> <replaceable>...</replaceable></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr filename ...</userinput></screen> <indexterm><primary>printing</primary></indexterm> <para>This prints each of the listed files to the default @@ -4062,22 +3977,22 @@ total 337.00 154 $ 6.74</screen> print from standard input. For example, this command prints some important system files:</para> - <screen>&prompt.user; <userinput><command>lpr <filename>/etc/host.conf</filename> <filename>/etc/hosts.equiv</filename></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr /etc/host.conf /etc/hosts.equiv</userinput></screen> <para>To select a specific printer, type:</para> - <screen>&prompt.user; <userinput><command>lpr <option>-P</option> <replaceable>printer-name</replaceable> <filename><replaceable>filename</replaceable></filename> <replaceable>...</replaceable></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr -P printer-name filename ...</userinput></screen> <para>This example prints a long listing of the current directory to the printer named <literal>rattan</literal>:</para> - <screen>&prompt.user; <userinput><command>ls <option>-l</option> | lpr <option>-P</option> rattan</command></userinput></screen> + <screen>&prompt.user; <userinput>ls -l | lpr -P rattan</userinput></screen> <para>Because no files were listed for the &man.lpr.1; command, <command>lpr</command> read the data to print from standard input, which was the output of the <command>ls - <option>-l</option></command> command.</para> + -l</command> command.</para> <para>The &man.lpr.1; command can also accept a wide variety of options to control formatting, apply file conversions, @@ -4086,7 +4001,7 @@ total 337.00 154 $ 6.74</screen> Options</link>.</para> </sect2> - <sect2 id="printing-lpq"> + <sect2 xml:id="printing-lpq"> <title>Checking Jobs</title> <indexterm><primary>print jobs</primary></indexterm> @@ -4103,7 +4018,7 @@ total 337.00 154 $ 6.74</screen> &man.lpq.1;. For a specific printer, use the <option>-P</option> option. For example, the command - <screen>&prompt.user; <userinput><command>lpq <option>-P</option> bamboo</command></userinput></screen> + <screen>&prompt.user; <userinput>lpq -P bamboo</userinput></screen> shows the queue for the printer named <literal>bamboo</literal>. Here is an example of the output @@ -4120,8 +4035,7 @@ active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes kelly, got assigned <quote>job number</quote> 9. Every job for a printer gets a unique job number. Most of the time you can ignore the job number, but you will need it if you want to - cancel the job; see section <link - linkend="printing-lprm">Removing Jobs</link> for + cancel the job; see section <link linkend="printing-lprm">Removing Jobs</link> for details.</para> <para>Job number nine consists of two files; multiple files @@ -4131,7 +4045,7 @@ active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes column), which means the printer should be currently printing that job. The second job consists of data passed as the standard input to the &man.lpr.1; command. The third job came - from user <username>mary</username>; it is a much larger job. + from user <systemitem class="username">mary</systemitem>; it is a much larger job. The pathname of the file she is trying to print is too long to fit, so the &man.lpq.1; command just shows three dots.</para> @@ -4142,7 +4056,7 @@ active kelly 9 /etc/host.conf, /etc/hosts.equiv 88 bytes <para>The &man.lpq.1; command also support a <option>-l</option> option to generate a detailed long listing. Here is an - example of <command>lpq <option>-l</option></command>:</para> + example of <command>lpq -l</command>:</para> <screen>waiting for bamboo to become ready (offline ?) kelly: 1st [job 009rose] @@ -4156,7 +4070,7 @@ mary: 3rd [job 011rose] /home/orchid/mary/research/venus/alpha-regio/mapping 78519 bytes</screen> </sect2> - <sect2 id="printing-lprm"> + <sect2 xml:id="printing-lprm"> <title>Removing Jobs</title> <para>If you change your mind about printing a job, you can @@ -4167,14 +4081,14 @@ mary: 3rd [job 011rose] <para>To remove a job from the default printer, first use &man.lpq.1; to find the job number. Then type:</para> - <screen>&prompt.user; <userinput><command>lprm <replaceable>job-number</replaceable></command></userinput></screen> + <screen>&prompt.user; <userinput>lprm job-number</userinput></screen> <para>To remove the job from a specific printer, add the <option>-P</option> option. The following command removes job number 10 from the queue for the printer <literal>bamboo</literal>:</para> - <screen>&prompt.user; <userinput><command>lprm <option>-P</option> bamboo 10</command></userinput></screen> + <screen>&prompt.user; <userinput>lprm -P bamboo 10</userinput></screen> <para>The &man.lprm.1; command has a few shortcuts:</para> @@ -4218,7 +4132,7 @@ mary: 3rd [job 011rose] for the current user in the queue for the printer named <literal>rattan</literal>:</para> - <screen>&prompt.user; <userinput><command>lprm <option>-P</option> rattan -</command></userinput></screen> + <screen>&prompt.user; <userinput>lprm -P rattan -</userinput></screen> <note> <para>If you are working in a networked environment, @@ -4227,22 +4141,22 @@ mary: 3rd [job 011rose] is available from other hosts. The following command sequence demonstrates this:</para> - <screen>&prompt.user; <userinput><command>lpr <option>-P</option> rattan <filename><replaceable>myfile</replaceable></filename></command></userinput> -&prompt.user; <userinput><command>rlogin orchid</command></userinput> -&prompt.user; <userinput><command>lpq <option>-P</option> rattan</command></userinput> + <screen>&prompt.user; <userinput>lpr -P rattan myfile</userinput> +&prompt.user; <userinput>rlogin orchid</userinput> +&prompt.user; <userinput>lpq -P rattan</userinput> Rank Owner Job Files Total Size active seeyan 12 ... 49123 bytes 2nd kelly 13 myfile 12 bytes -&prompt.user; <userinput><command>lprm <option>-P</option> rattan 13</command></userinput> +&prompt.user; <userinput>lprm -P rattan 13</userinput> rose: Permission denied -&prompt.user; <userinput><command>logout</command></userinput> -&prompt.user; <userinput><command>lprm <option>-P</option> rattan 13</command></userinput> +&prompt.user; <userinput>logout</userinput> +&prompt.user; <userinput>lprm -P rattan 13</userinput> dfA013rose dequeued cfA013rose dequeued</screen> </note> </sect2> - <sect2 id="printing-lpr-options"> + <sect2 xml:id="printing-lpr-options"> <title>Beyond Plain Text: Printing Options</title> <para>The &man.lpr.1; command supports a number of options that @@ -4250,7 +4164,7 @@ cfA013rose dequeued</screen> formats, producing multiple copies, handling of the job, and more. This section describes the options.</para> - <sect3 id="printing-lpr-options-format"> + <sect3 xml:id="printing-lpr-options-format"> <title>Formatting and Conversion Options</title> <para>The following &man.lpr.1; options control formatting of @@ -4261,10 +4175,10 @@ cfA013rose dequeued</screen> <indexterm><primary>&tex;</primary></indexterm> <para>For example, the following command prints a DVI file (from the &tex; typesetting system) named - <filename><replaceable>fish-report.dvi</replaceable></filename> + <filename>fish-report.dvi</filename> to the printer named <literal>bamboo</literal>:</para> - <screen>&prompt.user; <userinput><command>lpr <option>-P</option> bamboo -d <filename><replaceable>fish-report.dvi</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr -P bamboo -d fish-report.dvi</userinput></screen> <para>These options apply to every file in the job, so you cannot mix (say) DVI and ditroff files together in a job. @@ -4276,8 +4190,7 @@ cfA013rose dequeued</screen> <option>-T</option> require conversion filters installed for the destination printer. For example, the <option>-d</option> option requires the DVI conversion - filter. Section <link - linkend="printing-advanced-convfilters">Conversion + filter. Section <link linkend="printing-advanced-convfilters">Conversion Filters</link> gives details.</para> </note> @@ -4393,7 +4306,7 @@ cfA013rose dequeued</screen> formatted version of the &man.ls.1; manual page on the default printer:</para> - <screen>&prompt.user; <userinput><command>zcat <filename>/usr/share/man/man1/ls.1.gz</filename> | troff <option>-t</option> -man | lpr <option>-t</option></command></userinput></screen> + <screen>&prompt.user; <userinput>zcat /usr/share/man/man1/ls.1.gz | troff -t -man | lpr -t</userinput></screen> <para>The &man.zcat.1; command uncompresses the source of the &man.ls.1; manual page and passes it to the &man.troff.1; @@ -4406,7 +4319,7 @@ cfA013rose dequeued</screen> job.</para> </sect3> - <sect3 id="printing-lpr-options-job-handling"> + <sect3 xml:id="printing-lpr-options-job-handling"> <title>Job Handling Options</title> <para>The following options to &man.lpr.1; tell @@ -4422,17 +4335,16 @@ cfA013rose dequeued</screen> <replaceable>copies</replaceable> of each file in the job instead of just one copy. An administrator may disable this option to reduce printer wear-and-tear - and encourage photocopier usage. See section <link - linkend="printing-advanced-restricting-copies">Restricting + and encourage photocopier usage. See section <link linkend="printing-advanced-restricting-copies">Restricting Multiple Copies</link>.</para> <para>This example prints three copies of - <filename><replaceable>parser.c</replaceable></filename> + <filename>parser.c</filename> followed by three copies of - <filename><replaceable>parser.h</replaceable></filename> + <filename>parser.h</filename> to the default printer:</para> - <screen>&prompt.user; <userinput><command>lpr <option>-#3</option> <filename><replaceable>parser.c parser.h</replaceable></filename></command></userinput></screen> + <screen>&prompt.user; <userinput>lpr -#3 parser.c parser.h</userinput></screen> </listitem> </varlistentry> @@ -4494,14 +4406,13 @@ cfA013rose dequeued</screen> </variablelist> </sect3> - <sect3 id="printing-lpr-options-misc"> + <sect3 xml:id="printing-lpr-options-misc"> <title>Header Page Options</title> <para>These options to &man.lpr.1; adjust the text that normally appears on a job's header page. If header pages are suppressed for the destination printer, these options - have no effect. See section <link - linkend="printing-advanced-header-pages">Header + have no effect. See section <link linkend="printing-advanced-header-pages">Header Pages</link> for information about setting up header pages.</para> @@ -4538,8 +4449,7 @@ cfA013rose dequeued</screen> <note> <para>At some sites, this option may have no effect due to the way header pages are generated. See - <link - linkend="printing-advanced-header-pages">Header + <link linkend="printing-advanced-header-pages">Header Pages</link> for details.</para> </note> </listitem> @@ -4548,7 +4458,7 @@ cfA013rose dequeued</screen> </sect3> </sect2> - <sect2 id="printing-lpc"> + <sect2 xml:id="printing-lpc"> <title>Administering Printers</title> <para>As an administrator for your printers, you have had to @@ -4577,13 +4487,13 @@ cfA013rose dequeued</screen> the queue is cleared.</para> <para>If a queue is <emphasis>disabled</emphasis>, no user - (except <username>root</username>) can submit jobs for the + (except <systemitem class="username">root</systemitem>) can submit jobs for the printer. An <emphasis>enabled</emphasis> queue allows jobs to be submitted. A printer can be <emphasis>started</emphasis> for a disabled queue, in which case it will continue to print jobs in the queue until the queue is empty.</para> - <para>In general, you have to have <username>root</username> + <para>In general, you have to have <systemitem class="username">root</systemitem> privileges to use the &man.lpc.8; command. Ordinary users can use the &man.lpc.8; command to get printer status and to restart a hung printer only.</para> @@ -4598,7 +4508,7 @@ cfA013rose dequeued</screen> <variablelist> <varlistentry> <term><command>abort - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Cancel the current job and stop the printer. Users @@ -4608,7 +4518,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>clean - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Remove old files from the printer's spooling @@ -4624,17 +4534,17 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>disable - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Disable queuing of new jobs. If the printer is running, it will continue to print any jobs remaining in - the queue. The superuser (<username>root</username>) + the queue. The superuser (<systemitem class="username">root</systemitem>) can always submit jobs, even to a disabled queue.</para> <para>This command is useful while you are testing a new printer or filter installation: disable the queue and - submit jobs as <username>root</username>. Other users + submit jobs as <systemitem class="username">root</systemitem>. Other users will not be able to submit jobs until you complete your testing and re-enable the queue with the <command>enable</command> command.</para> @@ -4642,8 +4552,8 @@ cfA013rose dequeued</screen> </varlistentry> <varlistentry> - <term><command>down <replaceable>printer-name</replaceable> - <replaceable>message</replaceable></command></term> + <term><command>down printer-name + message</command></term> <listitem> <para>Take a printer down. Equivalent to @@ -4658,7 +4568,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>enable - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Enable the queue for a printer. Users can submit @@ -4669,7 +4579,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>help - <replaceable>command-name</replaceable></command></term> + command-name</command></term> <listitem> <para>Print help on the command @@ -4681,7 +4591,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>restart - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Start the printer. Ordinary users can use this @@ -4698,7 +4608,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>start - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Start the printer. The printer will print jobs in @@ -4708,7 +4618,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>stop - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Stop the printer. The printer will finish the @@ -4719,8 +4629,8 @@ cfA013rose dequeued</screen> </varlistentry> <varlistentry> - <term><command>topq <replaceable>printer-name</replaceable> - <replaceable>job-or-username</replaceable></command></term> + <term><command>topq printer-name + job-or-username</command></term> <listitem> <para>Rearrange the queue for @@ -4736,7 +4646,7 @@ cfA013rose dequeued</screen> <varlistentry> <term><command>up - <replaceable>printer-name</replaceable></command></term> + printer-name</command></term> <listitem> <para>Bring a printer up; the opposite of the @@ -4755,7 +4665,7 @@ cfA013rose dequeued</screen> </sect2> </sect1> - <sect1 id="printing-lpd-alternatives"> + <sect1 xml:id="printing-lpd-alternatives"> <title>Alternatives to the Standard Spooler</title> <para>If you have been reading straight through this manual, by @@ -4776,8 +4686,7 @@ cfA013rose dequeued</screen> complete rewrite of PLP. Patrick Powell and Justin Mason (the principal maintainer of PLP) collaborated to make <application>LPRng</application>. The main site for - <application>LPRng</application> is <ulink - url="http://www.lprng.org/"></ulink>.</para> + <application>LPRng</application> is <uri xlink:href="http://www.lprng.org/">http://www.lprng.org/</uri>.</para> </listitem> </varlistentry> @@ -4803,7 +4712,7 @@ cfA013rose dequeued</screen> &unix;.</para> <para>The main site for <application>CUPS</application> is - <ulink url="http://www.cups.org/"></ulink>.</para> + <uri xlink:href="http://www.cups.org/">http://www.cups.org/</uri>.</para> </listitem> </varlistentry> @@ -4820,14 +4729,13 @@ cfA013rose dequeued</screen> features.</para> <para>The main site for <application>HPLIP</application> - is <ulink - url="http://hplipopensource.com/hplip-web/index.html"></ulink>.</para> + is <uri xlink:href="http://hplipopensource.com/hplip-web/index.html">http://hplipopensource.com/hplip-web/index.html</uri>.</para> </listitem> </varlistentry> </variablelist> </sect1> - <sect1 id="printing-troubleshooting"> + <sect1 xml:id="printing-troubleshooting"> <title>Troubleshooting</title> <para>After performing the simple test with &man.lptest.1;, you @@ -4977,7 +4885,7 @@ exit 2</programlisting> <para>Here is an example <filename>/etc/printcap</filename> - from a host called <hostid>orchid</hostid>. It has a + from a host called <systemitem>orchid</systemitem>. It has a single printer attached to its first parallel port, a Hewlett Packard LaserJet 3Si named <literal>teak</literal>. It is using the above script @@ -4987,7 +4895,7 @@ exit 2</programlisting> # /etc/printcap for host orchid # teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:sh:sd=<filename class="directory">/var/spool/lpd/teak</filename>:mx#0:\ + :lp=<filename>/dev/lpt0</filename>:sh:sd=<filename>/var/spool/lpd/teak</filename>:mx#0:\ :if=<filename>/usr/local/libexec/hpif</filename>:</programlisting> </listitem> </itemizedlist> @@ -5104,8 +5012,8 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ <literal>lf</literal> capability:</para> <programlisting>rattan|line|diablo|lp|Diablo 630 Line Printer:\ - :sh:sd=<filename class="directory">/var/spool/lpd/rattan</filename>:\ - :lp=<filename class="devicefile">/dev/lpt0</filename>:\ + :sh:sd=<filename>/var/spool/lpd/rattan</filename>:\ + :lp=<filename>/dev/lpt0</filename>:\ :if=<filename>/usr/local/libexec/if-simple</filename>:\ :lf=<filename>/var/log/rattan.log</filename></programlisting> @@ -5116,7 +5024,7 @@ teak|hp|laserjet|Hewlett Packard LaserJet 3Si:\ <para>If you do not specify a <literal>lf</literal> capability, <application>LPD</application> uses - <filename class="devicefile">/dev/console</filename> as a + <filename>/dev/console</filename> as a default.</para> </listitem> </varlistentry> diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.xml b/en_US.ISO8859-1/books/handbook/security/chapter.xml index f93d841cf7..10e9901a74 100644 --- a/en_US.ISO8859-1/books/handbook/security/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/security/chapter.xml @@ -4,24 +4,19 @@ $FreeBSD$ --> - -<chapter id="security"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="security"> + <info><title>Security</title> <authorgroup> - <author> - <firstname>Matthew</firstname> - <surname>Dillon</surname> - <contrib>Much of this chapter has been taken from the - security(7) manual page by </contrib> - </author> + <author><personname><firstname>Matthew</firstname><surname>Dillon</surname></personname><contrib>Much of this chapter has been taken from the + security(7) manual page by </contrib></author> </authorgroup> - </chapterinfo> + </info> - <title>Security</title> + <indexterm><primary>security</primary></indexterm> - <sect1 id="security-synopsis"> + <sect1 xml:id="security-synopsis"> <title>Synopsis</title> <para>This chapter provides a basic introduction to system @@ -110,7 +105,7 @@ <xref linkend="firewalls"/>.</para> </sect1> - <sect1 id="security-intro"> + <sect1 xml:id="security-intro"> <title>Introduction</title> <para>Security is a function that begins and ends with the system @@ -122,7 +117,7 @@ <para>System security also pertains to dealing with various forms of attack, including attacks that attempt to crash, or otherwise make a system unusable, but do not attempt to compromise the - <username>root</username> account. Security concerns can be + <systemitem class="username">root</systemitem> account. Security concerns can be split up into several categories:</para> <orderedlist> @@ -184,7 +179,7 @@ <para>In a well secured and maintained system, access to a user account does not necessarily give the attacker access to - <username>root</username>. Without <username>root</username> + <systemitem class="username">root</systemitem>. Without <systemitem class="username">root</systemitem> access, the attacker cannot generally hide his tracks and may, at best, be able to do nothing more than mess with the user's files or crash the machine. User account compromises are common @@ -197,9 +192,9 @@ </indexterm> <para>There are potentially many ways to break - <username>root</username>: the attacker may know the - <username>root</username> password, the attacker may exploit a - bug in a service which runs as <username>root</username>, or the + <systemitem class="username">root</systemitem>: the attacker may know the + <systemitem class="username">root</systemitem> password, the attacker may exploit a + bug in a service which runs as <systemitem class="username">root</systemitem>, or the attacker may know of a bug in a SUID-root program. An attacker may utilize a program known as a backdoor to search for vulnerable systems, take advantage of unpatched exploits to @@ -211,12 +206,12 @@ <orderedlist> <listitem> - <para>Secure <username>root</username> and staff + <para>Secure <systemitem class="username">root</systemitem> and staff accounts.</para> </listitem> <listitem> - <para>Secure <username>root</username>–run servers + <para>Secure <systemitem class="username">root</systemitem>–run servers and SUID/SGID binaries.</para> </listitem> @@ -246,7 +241,7 @@ <para>The next section covers these items in greater depth.</para> </sect1> - <sect1 id="securing-freebsd"> + <sect1 xml:id="securing-freebsd"> <title>Securing &os;</title> <indexterm> @@ -255,11 +250,10 @@ </indexterm> <para>This section describes methods for securing a &os; system - against the attacks that were mentioned in the <link - linkend="security-intro">previous section</link>.</para> + against the attacks that were mentioned in the <link linkend="security-intro">previous section</link>.</para> - <sect2 id="securing-root-and-staff"> - <title>Securing the <username>root</username> Account</title> + <sect2 xml:id="securing-root-and-staff"> + <title>Securing the <systemitem class="username">root</systemitem> Account</title> <indexterm> <primary>&man.su.1;</primary> @@ -267,7 +261,7 @@ <para>Most systems have a password assigned to the - <username>root</username> account. Assume that this password + <systemitem class="username">root</systemitem> account. Assume that this password is <emphasis>always</emphasis> at risk of being compromised. This does not mean that the password should be disabled as the password is almost always necessary for console access to the @@ -275,37 +269,37 @@ password outside of the console or possibly even with &man.su.1;. For example, setting the entries in <filename>/etc/ttys</filename> to <literal>insecure</literal> - prevents <username>root</username> logins to the specified - terminals. In &os;, <username>root</username> logins using + prevents <systemitem class="username">root</systemitem> logins to the specified + terminals. In &os;, <systemitem class="username">root</systemitem> logins using &man.ssh.1; are disabled by default as <literal>PermitRootLogin</literal> is set to <literal>no</literal> in <filename>/etc/ssh/sshd_config</filename>. Consider every access method as services such as FTP often fall through the - cracks. Direct <username>root</username> logins should only + cracks. Direct <systemitem class="username">root</systemitem> logins should only be allowed via the system console.</para> <indexterm> - <primary><groupname>wheel</groupname></primary> + <primary><systemitem class="groupname">wheel</systemitem></primary> </indexterm> <para>Since a sysadmin needs access to - <username>root</username>, additional password verification + <systemitem class="username">root</systemitem>, additional password verification should be configured. One method is to add appropriate user - accounts to <groupname>wheel</groupname> in + accounts to <systemitem class="groupname">wheel</systemitem> in <filename>/etc/group</filename>. Members of - <groupname>wheel</groupname> are allowed to &man.su.1; to - <username>root</username>. Only those users who actually need - to have <username>root</username> access should be placed in - <groupname>wheel</groupname>. When using Kerberos for + <systemitem class="groupname">wheel</systemitem> are allowed to &man.su.1; to + <systemitem class="username">root</systemitem>. Only those users who actually need + to have <systemitem class="username">root</systemitem> access should be placed in + <systemitem class="groupname">wheel</systemitem>. When using Kerberos for authentication, create a <filename>.k5login</filename> in - the home directory of <username>root</username> to allow + the home directory of <systemitem class="username">root</systemitem> to allow &man.ksu.1; to be used without having to place anyone in - <groupname>wheel</groupname>.</para> + <systemitem class="groupname">wheel</systemitem>.</para> <para>To lock an account completely, use &man.pw.8;:</para> - <screen>&prompt.root; <userinput>pw lock <replaceable>staff</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw lock staff</userinput></screen> <para>This will prevent the specified user from logging in using any mechanism, including &man.ssh.1;.</para> @@ -323,7 +317,7 @@ <programlisting>foobar:*:1000:1000::0:0:Foo Bar:/home/foobar:/usr/local/bin/tcsh</programlisting> - <para>This prevents <username>foobar</username> from logging in + <para>This prevents <systemitem class="username">foobar</systemitem> from logging in using conventional methods. This method for access restriction is flawed on sites using <application>Kerberos</application> or in situations where the @@ -365,17 +359,15 @@ aware that third party servers are often the most bug-prone. Never run a server that has not been checked out carefully. Think twice before running any service as - <username>root</username> as many daemons can be run as a + <systemitem class="username">root</systemitem> as many daemons can be run as a separate service account or can be started in a <firstterm>sandbox</firstterm>. Do not activate insecure services such as &man.telnetd.8; or &man.rlogind.8;.</para> <para>Another potential security hole is SUID-root and SGID binaries. Most of these binaries, such as &man.rlogin.1;, - reside in <filename class="directory">/bin</filename>, - <filename class="directory">/sbin</filename>, <filename - class="directory">/usr/bin</filename>, or <filename - class="directory">/usr/sbin</filename>. While nothing is + reside in <filename>/bin</filename>, + <filename>/sbin</filename>, <filename>/usr/bin</filename>, or <filename>/usr/sbin</filename>. While nothing is 100% safe, the system-default SUID and SGID binaries can be considered reasonably safe. It is recommended to restrict SUID binaries to a special group that only staff can access, @@ -388,7 +380,7 @@ <literal>kmem</literal> can monitor keystrokes sent through ptys, including ptys used by users who login through secure methods. An intruder that breaks the - <groupname>tty</groupname> group can write to almost any + <systemitem class="groupname">tty</systemitem> group can write to almost any user's tty. If a user is running a terminal program or emulator with a keyboard-simulation feature, the intruder can potentially generate a data stream that causes the user's @@ -396,7 +388,7 @@ user.</para> </sect2> - <sect2 id="secure-users"> + <sect2 xml:id="secure-users"> <title>Securing User Accounts</title> <para>User accounts are usually the most difficult to secure. @@ -413,13 +405,12 @@ possible and use &man.ssh.1; or Kerberos for access to those accounts. Even though the encrypted password file (<filename>/etc/spwd.db</filename>) can only be read by - <username>root</username>, it may be possible for an intruder + <systemitem class="username">root</systemitem>, it may be possible for an intruder to obtain read access to that file even if the attacker cannot obtain root-write access.</para> <para>Security scripts should be used to check for and report - changes to the password file as described in the <link - linkend="security-integrity">Checking file integrity</link> + changes to the password file as described in the <link linkend="security-integrity">Checking file integrity</link> section.</para> </sect2> @@ -429,7 +420,7 @@ <para>Most modern kernels have a packet sniffing device driver built in. Under &os; it is called - <devicename>bpf</devicename>. This device is needed for DHCP, + <filename>bpf</filename>. This device is needed for DHCP, but can be removed in the custom kernel configuration file of systems that do not provide or use DHCP.</para> @@ -437,12 +428,12 @@ <primary>&man.sysctl.8;</primary> </indexterm> - <para>Even if <devicename>bpf</devicename> is disabled, + <para>Even if <filename>bpf</filename> is disabled, <filename>/dev/mem</filename> and <filename>/dev/kmem</filename> are still problematic. An intruder can still write to raw disk devices. An enterprising intruder can use &man.kldload.8; to install his own - <devicename>bpf</devicename>, or another sniffing device, on a + <filename>bpf</filename>, or another sniffing device, on a running kernel. To avoid these problems, run the kernel at a higher security level, at least security level 1.</para> @@ -451,7 +442,7 @@ running kernel is to set <varname>kern.securelevel</varname>:</para> - <screen>&prompt.root; <userinput>sysctl kern.securelevel=<replaceable>1</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>sysctl kern.securelevel=1</userinput></screen> <para>By default, the &os; kernel boots with a security level of -1. This is called <quote>insecure mode</quote> because @@ -478,7 +469,7 @@ few problems to <application>&xorg;</application>, as access to <filename>/dev/io</filename> will be blocked, or to the installation of &os; built from source as - <maketarget>installworld</maketarget> needs to temporarily + <buildtarget>installworld</buildtarget> needs to temporarily reset the append-only and immutable flags of some files. In the case of <application>&xorg;</application>, it may be possible to work around this by starting &man.xdm.1; early @@ -499,21 +490,18 @@ security level is set. A less strict compromise is to run the system at a higher security level but skip setting the <literal>schg</literal> flag. Another possibility is to - mount <filename class="directory">/</filename> and <filename - class="directory">/usr</filename> read-only. It should be + mount <filename>/</filename> and <filename>/usr</filename> read-only. It should be noted that being too draconian about what is permitted may prevent detection of an intrusion.</para> </sect2> - <sect2 id="security-integrity"> + <sect2 xml:id="security-integrity"> <title>Checking File Integrity</title> <para>One can only protect the core system configuration and control files so much before the convenience factor rears its ugly head. For example, using &man.chflags.1; to set the - <literal>schg</literal> bit on most of the files in <filename - class="directory">/</filename> and <filename - class="directory">/usr</filename> is probably + <literal>schg</literal> bit on most of the files in <filename>/</filename> and <filename>/usr</filename> is probably counterproductive, because while it may protect the files, it also closes an intrusion detection window. Security measures are useless or, worse, present a false sense of security, if @@ -547,16 +535,12 @@ mount, write scripts out of simple system utilities such as &man.find.1; and &man.md5.1;. It is best to physically &man.md5.1; the client system's files at least once a day, and - to test control files such as those found in <filename - class="directory">/etc</filename> and <filename - class="directory">/usr/local/etc</filename> even more often. + to test control files such as those found in <filename>/etc</filename> and <filename>/usr/local/etc</filename> even more often. When mismatches are found, relative to the base md5 information the limited-access machine knows is valid, it should alert the sysadmin. A good security script will also check for inappropriate SUID binaries and for new or deleted - files on system partitions such as <filename - class="directory">/</filename> and <filename - class="directory">/usr</filename>.</para> + files on system partitions such as <filename>/</filename> and <filename>/usr</filename>.</para> <para>When using &man.ssh.1; rather than <acronym>NFS</acronym>, writing the security script is more difficult. For example, @@ -690,7 +674,7 @@ external access by firewalling them at the border routers. This is to prevent saturation attacks from outside the LAN, not so much to protect internal services from network-based - <username>root</username> compromise. Always configure an + <systemitem class="username">root</systemitem> compromise. Always configure an exclusive firewall which denies everything by default except for traffic which is explicitly allowed. The range of port numbers used for dynamic binding in &os; is controlled by @@ -785,7 +769,7 @@ uses &man.ssh.1; to access an insecure machine from a secure workstation. The keys themselves are not exposed, but &man.ssh.1; installs a forwarding port for the duration of the - login. If an attacker has broken <username>root</username> on + login. If an attacker has broken <systemitem class="username">root</systemitem> on the insecure machine, he can utilize that port to gain access to any other machine that those keys unlock.</para> @@ -804,19 +788,15 @@ </sect2> </sect1> - <sect1 id="crypt"> - <sect1info> + <sect1 xml:id="crypt"> + <info><title>DES, Blowfish, MD5, SHA256, SHA512, and Crypt</title> <authorgroup> - <author> - <firstname>Bill</firstname> - <surname>Swingle</surname> - <contrib>Parts rewritten and updated by </contrib> - </author> + <author><personname><firstname>Bill</firstname><surname>Swingle</surname></personname><contrib>Parts rewritten and updated by </contrib></author> </authorgroup> - <!-- 21 Mar 2000 --> - </sect1info> + + </info> - <title>DES, Blowfish, MD5, SHA256, SHA512, and Crypt</title> + <indexterm> <primary>security</primary> @@ -880,7 +860,7 @@ </sect2> </sect1> - <sect1 id="one-time-passwords"> + <sect1 xml:id="one-time-passwords"> <title>One-time Passwords</title> <indexterm><primary>one-time passwords</primary></indexterm> @@ -1126,18 +1106,14 @@ Enter secret pass phrase: <userinput><secret password></userinput> </sect2> </sect1> - <sect1 id="tcpwrappers"> - <sect1info> + <sect1 xml:id="tcpwrappers"> + <info><title>TCP Wrappers</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>TCP Wrappers</title> + <indexterm><primary>TCP Wrappers</primary></indexterm> @@ -1191,7 +1167,7 @@ Enter secret pass phrase: <userinput><secret password></userinput> the rule is applied and the search process stops.</para> <para>For example, to allow <acronym>POP</acronym>3 connections - via the <filename role="package">mail/qpopper</filename> + via the <package>mail/qpopper</package> daemon, the following lines should be appended to <filename>hosts.allow</filename>:</para> @@ -1265,8 +1241,7 @@ ALL : .example.com \ /var/log/connections.log) \ : deny</programlisting> - <para>This will deny all connection attempts from <hostid - role="fqdn">*.example.com</hostid> and log the hostname, + <para>This will deny all connection attempts from <systemitem class="fqdomainname">*.example.com</systemitem> and log the hostname, <acronym>IP</acronym> address, and the daemon to which access was attempted to <filename>/var/log/connections.log</filename>.</para> @@ -1312,25 +1287,17 @@ sendmail : PARANOID : deny</programlisting> </sect2> </sect1> - <sect1 id="kerberos5"> - <sect1info> + <sect1 xml:id="kerberos5"> + <info><title><application>Kerberos5</application></title> <authorgroup> - <author> - <firstname>Tillman</firstname> - <surname>Hodgson</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tillman</firstname><surname>Hodgson</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> <authorgroup> - <author> - <firstname>Mark</firstname> - <surname>Murray</surname> - <contrib>Based on a contribution by </contrib> - </author> + <author><personname><firstname>Mark</firstname><surname>Murray</surname></personname><contrib>Based on a contribution by </contrib></author> </authorgroup> - </sect1info> + </info> - <title><application>Kerberos5</application></title> + <para><application>Kerberos</application> is a network add-on system/protocol that allows users to authenticate themselves @@ -1362,7 +1329,7 @@ sendmail : PARANOID : deny</programlisting> <itemizedlist> <listitem> <para>The <acronym>DNS</acronym> domain (<quote>zone</quote>) - will be <hostid role="fqdn">example.org</hostid>.</para> + will be <systemitem class="fqdomainname">example.org</systemitem>.</para> </listitem> <listitem> @@ -1411,14 +1378,12 @@ sendmail : PARANOID : deny</programlisting> a cryptography product, and has historically been affected by <acronym>US</acronym> export regulations. The <acronym>MIT</acronym> <application>Kerberos</application> is - available as the <filename - role="package">security/krb5</filename> package or port. + available as the <package>security/krb5</package> package or port. Heimdal <application>Kerberos</application> is another version 5 implementation, and was explicitly developed outside of the <acronym>US</acronym> to avoid export regulations. The Heimdal <application>Kerberos</application> distribution is - available as a the <filename - role="package">security/heimdal</filename> package or port, + available as a the <package>security/heimdal</package> package or port, and a minimal installation is included in the base &os; install.</para> @@ -1471,7 +1436,7 @@ kadmind5_server_enable="YES"</programlisting> <para>This <filename>/etc/krb5.conf</filename> implies that the <acronym>KDC</acronym> will use the fully-qualified hostname - <hostid role="fqdn">kerberos.example.org</hostid>. Add a + <systemitem class="fqdomainname">kerberos.example.org</systemitem>. Add a CNAME (alias) entry to the zone file to accomplish this if the <acronym>KDC</acronym> has a different hostname.</para> @@ -1484,7 +1449,7 @@ kadmind5_server_enable="YES"</programlisting> default_realm = EXAMPLE.ORG</programlisting> <para>With the following lines being appended to the - <hostid role="fqdn">example.org</hostid> zone file:</para> + <systemitem class="fqdomainname">example.org</systemitem> zone file:</para> <programlisting>_kerberos._udp IN SRV 01 00 88 kerberos.example.org. _kerberos._tcp IN SRV 01 00 88 kerberos.example.org. @@ -1533,9 +1498,9 @@ Master key: <userinput>xxxxxxxx</userinput> Verifying password - Master key: <userinput>xxxxxxxx</userinput> &prompt.root; <userinput>kadmin -l</userinput> -kadmin> <userinput>init EXAMPLE.ORG</userinput> +kadmin> <userinput>init EXAMPLE.ORG</userinput> Realm max ticket life [unlimited]: -kadmin> <userinput>add tillman</userinput> +kadmin> <userinput>add tillman</userinput> Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: @@ -1552,7 +1517,7 @@ Verifying password - Password: <userinput>xxxxxxxx</userinput></screen> created from the command-line of the <acronym>KDC</acronym> itself:</para> - <screen>&prompt.user; <userinput>kinit <replaceable>tillman</replaceable></userinput> + <screen>&prompt.user; <userinput>kinit tillman</userinput> tillman@EXAMPLE.ORG's Password: &prompt.user; <userinput>klist</userinput> @@ -1618,12 +1583,12 @@ Aug 27 15:37:58 Aug 28 01:37:58 krbtgt/EXAMPLE.ORG@EXAMPLE.ORG</screen> example:</para> <screen>&prompt.root; <userinput>kadmin</userinput> -kadmin><userinput> add --random-key host/myserver.example.org</userinput> +kadmin><userinput> add --random-key host/myserver.example.org</userinput> Max ticket life [unlimited]: Max renewable life [unlimited]: Attributes []: -kadmin><userinput> ext host/myserver.example.org</userinput> -kadmin><userinput> exit</userinput></screen> +kadmin><userinput> ext host/myserver.example.org</userinput> +kadmin><userinput> exit</userinput></screen> <para>Note that <command>ext</command> stores the extracted key in <filename>/etc/krb5.keytab</filename> by default.</para> @@ -1631,15 +1596,15 @@ kadmin><userinput> exit</userinput></screen> <para>If &man.kadmind.8; is not running on the <acronym>KDC</acronym> and there is no access to &man.kadmin.8; remotely, add the host principal - (<username>host/myserver.EXAMPLE.ORG</username>) directly on + (<systemitem class="username">host/myserver.EXAMPLE.ORG</systemitem>) directly on the <acronym>KDC</acronym> and then extract it to a temporary file to avoid overwriting the <filename>/etc/krb5.keytab</filename> on the <acronym>KDC</acronym>, using something like this:</para> <screen>&prompt.root; <userinput>kadmin</userinput> -kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput> -kadmin><userinput> exit</userinput></screen> +kadmin><userinput> ext --keytab=/tmp/example.keytab host/myserver.example.org</userinput> +kadmin><userinput> exit</userinput></screen> <para>The keytab can then be securely copied to the server using &man.scp.1; or a removable media. Be sure to specify a @@ -1722,9 +1687,9 @@ kadmin><userinput> exit</userinput></screen> local user account. Occasionally, one needs to grant access to a local user account to someone who does not have a matching <application>Kerberos</application> principal. For - example, <username>tillman@EXAMPLE.ORG</username> may need + example, <systemitem class="username">tillman@EXAMPLE.ORG</systemitem> may need access to the local user account - <username>webdevelopers</username>. Other principals may also + <systemitem class="username">webdevelopers</systemitem>. Other principals may also need access to that local account.</para> <para>The <filename>.k5login</filename> and @@ -1732,7 +1697,7 @@ kadmin><userinput> exit</userinput></screen> directory, can be used to solve this problem. For example, if <filename>.k5login</filename> with the following contents is placed in the home directory of - <username>webdevelopers</username>, both principals listed + <systemitem class="username">webdevelopers</systemitem>, both principals listed will have access to that account without requiring a shared password.:</para> @@ -1772,11 +1737,10 @@ jdoe@example.org</screen> <listitem> <para>If the hostname is changed, the - <username>host/</username> principal must be changed and + <systemitem class="username">host/</systemitem> principal must be changed and the keytab updated. This also applies to special keytab - entries like the <username>www/</username> principal - used for Apache's <filename - role="package">www/mod_auth_kerb</filename>.</para> + entries like the <systemitem class="username">www/</systemitem> principal + used for Apache's <package>www/mod_auth_kerb</package>.</para> </listitem> <listitem> @@ -1793,7 +1757,7 @@ jdoe@example.org</screen> <listitem> <para>Some operating systems that act as clients to the <acronym>KDC</acronym> do not set the permissions for - &man.ksu.1; to be setuid <username>root</username>. This + &man.ksu.1; to be setuid <systemitem class="username">root</systemitem>. This means that &man.ksu.1; does not work. This is not a <acronym>KDC</acronym> error.</para> </listitem> @@ -1805,7 +1769,7 @@ jdoe@example.org</screen> ten hours, use <command>modify_principal</command> at the &man.kadmin.8; prompt to change the maxlife of both the principal in question and the - <username>krbtgt</username> principal. Then the + <systemitem class="username">krbtgt</systemitem> principal. Then the principal can use <command>kinit -l</command> to request a ticket with a longer lifetime.</para> </listitem> @@ -1887,18 +1851,15 @@ jdoe@example.org</screen> <para>The client applications may also use slightly different command line options to accomplish the same tasks. Following the instructions on the <acronym>MIT</acronym> - <application>Kerberos</application> <ulink - url="http://web.mit.edu/Kerberos/www/">web site</ulink> is + <application>Kerberos</application> <link xlink:href="http://web.mit.edu/Kerberos/www/">web site</link> is recommended. Be careful of path issues: the - <acronym>MIT</acronym> port installs into <filename - class="directory">/usr/local/</filename> by default, and the + <acronym>MIT</acronym> port installs into <filename>/usr/local/</filename> by default, and the <quote>normal</quote> system applications run instead of <acronym>MIT</acronym> versions if <envar>PATH</envar> lists the system directories first.</para> <note> - <para>With the &os; <acronym>MIT</acronym> <filename - role="package">security/krb5</filename> port, be sure to + <para>With the &os; <acronym>MIT</acronym> <package>security/krb5</package> port, be sure to read <filename>/usr/local/share/doc/krb5/README.FreeBSD</filename> installed by the port to understand why logins via @@ -1921,7 +1882,7 @@ kadmind5_server_enable="YES"</programlisting> <para>This is done because the applications for <acronym>MIT</acronym> Kerberos installs binaries in the - <filename class="directory">/usr/local</filename> + <filename>/usr/local</filename> hierarchy.</para> </sect2> @@ -1954,8 +1915,7 @@ kadmind5_server_enable="YES"</programlisting> <para>In a multi-user environment, <application>Kerberos</application> is less secure. This is - because it stores the tickets in <filename - class="directory">/tmp</filename>, which is readable by + because it stores the tickets in <filename>/tmp</filename>, which is readable by all users. If a user is sharing a computer with other users, it is possible that the user's tickets can be stolen or copied by another user.</para> @@ -2004,8 +1964,7 @@ kadmind5_server_enable="YES"</programlisting> <acronym>KDC</acronym> to the users, hosts or services. This means that a trojanned &man.kinit.1; could record all user names and passwords. Filesystem integrity checking - tools like <filename - role="package">security/tripwire</filename> can alleviate + tools like <package>security/tripwire</package> can alleviate this.</para> </sect3> </sect2> @@ -2020,54 +1979,46 @@ kadmind5_server_enable="YES"</programlisting> <itemizedlist> <listitem> - <para><ulink - url="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html"> + <para><link xlink:href="http://www.faqs.org/faqs/Kerberos-faq/general/preamble.html"> The <application>Kerberos</application> - FAQ</ulink></para> + FAQ</link></para> </listitem> <listitem> - <para><ulink - url="http://web.mit.edu/Kerberos/www/dialogue.html">Designing + <para><link xlink:href="http://web.mit.edu/Kerberos/www/dialogue.html">Designing an Authentication System: a Dialog in Four - Scenes</ulink></para> + Scenes</link></para> </listitem> <listitem> - <para><ulink - url="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC + <para><link xlink:href="http://www.ietf.org/rfc/rfc1510.txt?number=1510">RFC 1510, The <application>Kerberos</application> Network - Authentication Service (V5)</ulink></para> + Authentication Service (V5)</link></para> </listitem> <listitem> - <para><ulink - url="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym> + <para><link xlink:href="http://web.mit.edu/Kerberos/www/"><acronym>MIT</acronym> <application>Kerberos</application> home - page</ulink></para> + page</link></para> </listitem> <listitem> - <para><ulink url="http://www.pdc.kth.se/heimdal/">Heimdal + <para><link xlink:href="http://www.pdc.kth.se/heimdal/">Heimdal <application>Kerberos</application> home - page</ulink></para> + page</link></para> </listitem> </itemizedlist> </sect2> </sect1> - <sect1 id="openssl"> - <sect1info> + <sect1 xml:id="openssl"> + <info><title>OpenSSL</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Written by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Written by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>OpenSSL</title> + <indexterm> <primary>security</primary> @@ -2083,15 +2034,15 @@ kadmind5_server_enable="YES"</programlisting> <para>Some uses of <application>OpenSSL</application> may include encrypted authentication of mail clients and web based transactions such as credit card payments. Many ports such as - <filename role="package">www/apache22</filename>, and - <filename role="package">mail/claws-mail</filename> offer + <package>www/apache22</package>, and + <package>mail/claws-mail</package> offer compilation support for building with <application>OpenSSL</application>.</para> <note> <para>In most cases, the Ports Collection will attempt to build - the <filename role="package">security/openssl</filename> - port unless <makevar>WITH_OPENSSL_BASE</makevar> is explicitly + the <package>security/openssl</package> + port unless <varname>WITH_OPENSSL_BASE</varname> is explicitly set to <quote>yes</quote>.</para> </note> @@ -2105,7 +2056,7 @@ kadmind5_server_enable="YES"</programlisting> <acronym>IDEA</acronym> algorithm, it is disabled by default due to United States patents. To use it, the license should be reviewed and, if the restrictions are acceptable, the - <makevar>MAKE_IDEA</makevar> variable must be set in + <varname>MAKE_IDEA</varname> variable must be set in <filename>/etc/make.conf</filename>.</para> </note> @@ -2116,8 +2067,7 @@ kadmind5_server_enable="YES"</programlisting> and not fraudulent. If the certificate in question has not been verified by a <quote>Certificate Authority</quote> (<acronym>CA</acronym>), a warning is produced. A - <acronym>CA</acronym> is a company, such as <ulink - url="http://www.verisign.com">VeriSign</ulink>, signs + <acronym>CA</acronym> is a company, such as <link xlink:href="http://www.verisign.com">VeriSign</link>, signs certificates in order to validate the credentials of individuals or companies. This process has a cost associated with it and is not a requirement for using certificates; however, it can put @@ -2147,18 +2097,18 @@ There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- -Country Name (2 letter code) [AU]:<userinput><replaceable>US</replaceable></userinput> -State or Province Name (full name) [Some-State]:<userinput><replaceable>PA</replaceable></userinput> -Locality Name (eg, city) []:<userinput><replaceable>Pittsburgh</replaceable></userinput> -Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput><replaceable>My Company</replaceable></userinput> -Organizational Unit Name (eg, section) []:<userinput><replaceable>Systems Administrator</replaceable></userinput> -Common Name (eg, YOUR name) []:<userinput><replaceable>localhost.example.org</replaceable></userinput> -Email Address []:<userinput><replaceable>trhodes@FreeBSD.org</replaceable></userinput> +Country Name (2 letter code) [AU]:<userinput>US</userinput> +State or Province Name (full name) [Some-State]:<userinput>PA</userinput> +Locality Name (eg, city) []:<userinput>Pittsburgh</userinput> +Organization Name (eg, company) [Internet Widgits Pty Ltd]:<userinput>My Company</userinput> +Organizational Unit Name (eg, section) []:<userinput>Systems Administrator</userinput> +Common Name (eg, YOUR name) []:<userinput>localhost.example.org</userinput> +Email Address []:<userinput>trhodes@FreeBSD.org</userinput> Please enter the following 'extra' attributes to be sent with your certificate request -A challenge password []:<userinput><replaceable>SOME PASSWORD</replaceable></userinput> -An optional company name []:<userinput><replaceable>Another Name</replaceable></userinput></screen> +A challenge password []:<userinput>SOME PASSWORD</userinput> +An optional company name []:<userinput>Another Name</userinput></screen> <para>Notice the response directly after the <quote>Common Name</quote> prompt shows a domain name. This prompt @@ -2184,23 +2134,22 @@ An optional company name []:<userinput><replaceable>Another Name</replaceable></ is not required, a self signed certificate can be created. First, generate the <acronym>RSA</acronym> key:</para> - <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out <filename>myRSA.key</filename> 1024</userinput></screen> + <screen>&prompt.root; <userinput>openssl dsaparam -rand -genkey -out myRSA.key 1024</userinput></screen> <para>Next, generate the <acronym>CA</acronym> key:</para> - <screen>&prompt.root; <userinput>openssl gendsa -des3 -out <filename>myca.key</filename> <filename>myRSA.key</filename></userinput></screen> + <screen>&prompt.root; <userinput>openssl gendsa -des3 -out myca.key myRSA.key</userinput></screen> <para>Use this key to create the certificate:</para> - <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key <filename>myca.key</filename> -out <filename>new.crt</filename></userinput></screen> + <screen>&prompt.root; <userinput>openssl req -new -x509 -days 365 -key myca.key -out new.crt</userinput></screen> <para>Two new files should appear in the directory: a certificate authority signature file, <filename>myca.key</filename> and the certificate itself, <filename>new.crt</filename>. These should be placed in a - directory, preferably under <filename - class="directory">/etc</filename>, which is readable only by - <username>root</username>. Permissions of 0700 are + directory, preferably under <filename>/etc</filename>, which is readable only by + <systemitem class="username">root</systemitem>. Permissions of 0700 are appropriate and can be set using &man.chmod.1;.</para> </sect2> @@ -2230,15 +2179,14 @@ define(`confSERVER_CERT',`/etc/certs/new.crt')dnl define(`confSERVER_KEY',`/etc/certs/myca.key')dnl define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting> - <para>In this example, <filename - class="directory">/etc/certs/</filename> + <para>In this example, <filename>/etc/certs/</filename> stores the certificate and key files locally. After saving the edits, rebuild the local <filename>.cf</filename> file by typing - <command>make <maketarget>install</maketarget></command> - within <filename class="directory">/etc/mail</filename>. + <command>make install</command> + within <filename>/etc/mail</filename>. Follow that up with <command>make - <maketarget>restart</maketarget></command> which should + restart</command> which should start the <application>Sendmail</application> daemon.</para> <para>If all went well, there will be no error messages in @@ -2249,12 +2197,12 @@ define(`confTLS_SRV_OPTIONS', `V')dnl</programlisting> <para>For a simple test, connect to the mail server using &man.telnet.1;:</para> - <screen>&prompt.root; <userinput>telnet <replaceable>example.com</replaceable> 25</userinput> + <screen>&prompt.root; <userinput>telnet example.com 25</userinput> Trying 192.0.34.166... -Connected to <hostid role="fqdn">example.com</hostid>. +Connected to <systemitem class="fqdomainname">example.com</systemitem>. Escape character is '^]'. -220 <hostid role="fqdn">example.com</hostid> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT) -<userinput>ehlo <replaceable>example.com</replaceable></userinput> +220 <systemitem class="fqdomainname">example.com</systemitem> ESMTP Sendmail 8.12.10/8.12.10; Tue, 31 Aug 2004 03:41:22 -0400 (EDT) +<userinput>ehlo example.com</userinput> 250-example.com Hello example.com [192.0.34.166], pleased to meet you 250-ENHANCEDSTATUSCODES 250-PIPELINING @@ -2267,7 +2215,7 @@ Escape character is '^]'. 250-DELIVERBY 250 HELP <userinput>quit</userinput> -221 2.0.0 <hostid role="fqdn">example.com</hostid> closing connection +221 2.0.0 <systemitem class="fqdomainname">example.com</systemitem> closing connection Connection closed by foreign host.</screen> <para>If the <quote>STARTTLS</quote> line appears in the @@ -2275,41 +2223,31 @@ Connection closed by foreign host.</screen> </sect2> </sect1> - <sect1 id="ipsec"> - <sect1info> + <sect1 xml:id="ipsec"> + <info><title><acronym>VPN</acronym> over IPsec</title> <authorgroup> - <author> - <firstname>Nik</firstname> - <surname>Clayton</surname> - <affiliation> + <author><personname><firstname>Nik</firstname><surname>Clayton</surname></personname><affiliation> <address><email>nik@FreeBSD.org</email></address> - </affiliation> - <contrib>Written by </contrib> - </author> + </affiliation><contrib>Written by </contrib></author> </authorgroup> - </sect1info> + </info> - <title><acronym>VPN</acronym> over IPsec</title> + <indexterm> <primary>IPsec</primary> </indexterm> <sect2> - <sect2info> + <info><title>Understanding IPsec</title> <authorgroup> - <author> - <firstname>Hiten M.</firstname> - <surname>Pandya</surname> - <affiliation> + <author><personname><firstname>Hiten M.</firstname><surname>Pandya</surname></personname><affiliation> <address><email>hmp@FreeBSD.org</email></address> - </affiliation> - <contrib>Written by </contrib> - </author> + </affiliation><contrib>Written by </contrib></author> </authorgroup> - </sect2info> + </info> - <title>Understanding IPsec</title> + <para>This section demonstrates the process of setting up IPsec. It assumes familiarity with the concepts of building a custom @@ -2319,7 +2257,7 @@ Connection closed by foreign host.</screen> top of the Internet Protocol (<acronym>IP</acronym>) layer. It allows two or more hosts to communicate in a secure manner. The &os; IPsec <quote>network stack</quote> is based on the - <ulink url="http://www.kame.net/">KAME</ulink> implementation, + <link xlink:href="http://www.kame.net/">KAME</link> implementation, which has support for both IPv4 and IPv6.</para> <indexterm> @@ -2436,28 +2374,23 @@ device crypto</screen> either public or private IP addresses. However, the address space must not collide. For example, both networks cannot use - <hostid role="ipaddr">192.168.1.x</hostid>.</para> + <systemitem class="ipaddress">192.168.1.x</systemitem>.</para> </listitem> </itemizedlist> <sect3> - <sect3info> + <info><title>Configuring IPsec on &os;</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <affiliation> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><affiliation> <address><email>trhodes@FreeBSD.org</email></address> - </affiliation> - <contrib>Written by </contrib> - </author> + </affiliation><contrib>Written by </contrib></author> </authorgroup> - </sect3info> + </info> - <title>Configuring IPsec on &os;</title> + <para>To begin, - <filename role="package">security/ipsec-tools</filename> + <package>security/ipsec-tools</package> must be installed from the Ports Collection. This software provides a number of applications which support the configuration.</para> @@ -2465,7 +2398,7 @@ device crypto</screen> <para>The next requirement is to create two &man.gif.4; pseudo-devices which will be used to tunnel packets and allow both networks to communicate properly. As - <username>root</username>, run the following commands, + <systemitem class="username">root</systemitem>, run the following commands, replacing <replaceable>internal</replaceable> and <replaceable>external</replaceable> with the real IP addresses of the internal and external interfaces of the two @@ -2473,19 +2406,19 @@ device crypto</screen> <screen>&prompt.root; <userinput>ifconfig gif0 create</userinput></screen> - <screen>&prompt.root; <userinput>ifconfig gif0 <replaceable>internal1 internal2</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig gif0 internal1 internal2</userinput></screen> - <screen>&prompt.root; <userinput>ifconfig gif0 tunnel <replaceable>external1 external2</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>ifconfig gif0 tunnel external1 external2</userinput></screen> <para>In this example, the corporate <acronym>LAN</acronym>'s external <acronym>IP</acronym> address is - <hostid role="ipaddr">172.16.5.4</hostid> and its internal + <systemitem class="ipaddress">172.16.5.4</systemitem> and its internal <acronym>IP</acronym> address is - <hostid role="ipaddr">10.246.38.1</hostid>. The home + <systemitem class="ipaddress">10.246.38.1</systemitem>. The home <acronym>LAN</acronym>'s external <acronym>IP</acronym> - address is <hostid role="ipaddr">192.168.1.12</hostid> and + address is <systemitem class="ipaddress">192.168.1.12</systemitem> and its internal private <acronym>IP</acronym> address is - <hostid role="ipaddr">10.0.0.5</hostid>.</para> + <systemitem class="ipaddress">10.0.0.5</systemitem>.</para> <para>If this is confusing, review the following example output from &man.ifconfig.8;:</para> @@ -2535,13 +2468,13 @@ round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms</programlisting> either network. The following command will achieve this goal:</para> - <screen>&prompt.root; <userinput>corp-net# route add <replaceable>10.0.0.0 10.0.0.5 255.255.255.0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>corp-net# route add 10.0.0.0 10.0.0.5 255.255.255.0</userinput></screen> - <screen>&prompt.root; <userinput>corp-net# route add net <replaceable>10.0.0.0: gateway 10.0.0.5</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>corp-net# route add net 10.0.0.0: gateway 10.0.0.5</userinput></screen> - <screen>&prompt.root; <userinput>priv-net# route add <replaceable>10.246.38.0 10.246.38.1 255.255.255.0</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>priv-net# route add 10.246.38.0 10.246.38.1 255.255.255.0</userinput></screen> - <screen>&prompt.root; <userinput>priv-net# route add host <replaceable>10.246.38.0: gateway 10.246.38.1</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>priv-net# route add host 10.246.38.0: gateway 10.246.38.1</userinput></screen> <para>At this point, internal machines should be reachable from each gateway as well as from machines behind the @@ -2680,7 +2613,7 @@ Foreground mode. <literal>em0</literal> with the network interface card as required:</para> - <screen>&prompt.root; <userinput>tcpdump -i em0 host <replaceable>172.16.5.4 and dst 192.168.1.12</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>tcpdump -i em0 host 172.16.5.4 and dst 192.168.1.12</userinput></screen> <para>Data similar to the following should appear on the console. If not, there is an issue and debugging the @@ -2733,19 +2666,15 @@ racoon_enable="yes"</programlisting> </sect2> </sect1> - <sect1 id="openssh"> - <sect1info> + <sect1 xml:id="openssh"> + <info><title>OpenSSH</title> <authorgroup> - <author> - <firstname>Chern</firstname> - <surname>Lee</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Chern</firstname><surname>Lee</surname></personname><contrib>Contributed by </contrib></author> <!-- 21 April 2001 --> </authorgroup> - </sect1info> + </info> - <title>OpenSSH</title> + <indexterm><primary>OpenSSH</primary></indexterm> <indexterm> @@ -2812,7 +2741,7 @@ racoon_enable="yes"</programlisting> &man.sshd.8;, specify the username and host to log into:</para> - <screen>&prompt.root; <userinput>ssh <replaceable>user@example.com</replaceable></userinput> + <screen>&prompt.root; <userinput>ssh user@example.com</userinput> Host key not found from the list of known hosts. Are you sure you want to continue connecting (yes/no)? <userinput>yes</userinput> Host 'example.com' added to the list of known hosts. @@ -2852,7 +2781,7 @@ user@example.com's password: <userinput>*******</userinput></screen> <para>Use &man.scp.1; to copy a file to or from a remote machine in a secure fashion.</para> - <screen>&prompt.root; <userinput> scp <replaceable>user@example.com:/COPYRIGHT COPYRIGHT</replaceable></userinput> + <screen>&prompt.root; <userinput> scp user@example.com:/COPYRIGHT COPYRIGHT</userinput> user@example.com's password: <userinput>*******</userinput> COPYRIGHT 100% |*****************************| 4735 00:00 @@ -2881,7 +2810,7 @@ COPYRIGHT 100% |*****************************| 4735 <para>The system-wide configuration files for both the <application>OpenSSH</application> daemon and client reside - in <filename class="directory">/etc/ssh</filename>.</para> + in <filename>/etc/ssh</filename>.</para> <para><filename>ssh_config</filename> configures the client settings, while <filename>sshd_config</filename> configures @@ -2889,14 +2818,14 @@ COPYRIGHT 100% |*****************************| 4735 the available configuration options.</para> </sect2> - <sect2 id="security-ssh-keygen"> + <sect2 xml:id="security-ssh-keygen"> <title>&man.ssh-keygen.1;</title> <para>Instead of using passwords, &man.ssh-keygen.1; can be used to generate <acronym>DSA</acronym> or <acronym>RSA</acronym> keys to authenticate a user:</para> - <screen>&prompt.user; <userinput>ssh-keygen -t <replaceable>dsa</replaceable></userinput> + <screen>&prompt.user; <userinput>ssh-keygen -t dsa</userinput> Generating public/private dsa key pair. Enter file in which to save the key (/home/user/.ssh/id_dsa): Created directory '/home/user/.ssh'. @@ -2955,7 +2884,7 @@ bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</screen> </warning> </sect2> - <sect2 id="security-ssh-agent"> + <sect2 xml:id="security-ssh-agent"> <title>Using SSH Agent to Cache Keys</title> <para>To load <acronym>SSH</acronym> keys into memory for use, @@ -2999,7 +2928,7 @@ Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) of the <acronym>SSH</acronym> keys.</para> </sect2> - <sect2 id="security-ssh-tunneling"> + <sect2 xml:id="security-ssh-tunneling"> <title><acronym>SSH</acronym> Tunneling</title> <indexterm> @@ -3014,7 +2943,7 @@ Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) <para>The following command tells &man.ssh.1; to create a tunnel for &man.telnet.1;:</para> - <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5023:localhost:23 user@foo.example.com</replaceable></userinput> + <screen>&prompt.user; <userinput>ssh -2 -N -f -L 5023:localhost:23 user@foo.example.com</userinput> &prompt.user;</screen> <para>This example uses the following options:</para> @@ -3067,14 +2996,14 @@ Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) </variablelist> <para>An <acronym>SSH</acronym> tunnel works by creating a - listen socket on <hostid>localhost</hostid> on the specified + listen socket on <systemitem>localhost</systemitem> on the specified port. It then forwards any connections received on the local host/port via the <acronym>SSH</acronym> connection to the specified remote host and port.</para> <para>In the example, port <replaceable>5023</replaceable> on - <hostid>localhost</hostid> is forwarded to port - <replaceable>23</replaceable> on <hostid>localhost</hostid> + <systemitem>localhost</systemitem> is forwarded to port + <replaceable>23</replaceable> on <systemitem>localhost</systemitem> of the remote machine. Since <replaceable>23</replaceable> is used by &man.telnet.1;, this creates an encrypted &man.telnet.1; session through an @@ -3087,7 +3016,7 @@ Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) <title>Using &man.ssh.1; to Create a Secure Tunnel for SMTP</title> - <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>5025:localhost:25 user@mailserver.example.com</replaceable></userinput> + <screen>&prompt.user; <userinput>ssh -2 -N -f -L 5025:localhost:25 user@mailserver.example.com</userinput> user@mailserver.example.com's password: <userinput>*****</userinput> &prompt.user; <userinput>telnet localhost 5025</userinput> Trying 127.0.0.1... @@ -3117,14 +3046,14 @@ Escape character is '^]'. <acronym>SSH</acronym> server, and tunnel through to the mail server.</para> - <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>2110:mail.example.com:110 user@ssh-server.example.com</replaceable></userinput> + <screen>&prompt.user; <userinput>ssh -2 -N -f -L 2110:mail.example.com:110 user@ssh-server.example.com</userinput> user@ssh-server.example.com's password: <userinput>******</userinput></screen> <para>Once the tunnel is up and running, point the email - client to send POP3 requests to <hostid>localhost</hostid> + client to send POP3 requests to <systemitem>localhost</systemitem> on port 2110. This connection will be forwarded securely across the tunnel to - <hostid>mail.example.com</hostid>.</para> + <systemitem>mail.example.com</systemitem>.</para> </sect4> <sect4> @@ -3141,13 +3070,13 @@ user@ssh-server.example.com's password: <userinput>******</userinput></screen> connection to a machine outside of the network's firewall and use it to tunnel to the desired service.</para> - <screen>&prompt.user; <userinput>ssh -2 -N -f -L <replaceable>8888:music.example.com:8000 user@unfirewalled-system.example.org</replaceable></userinput> + <screen>&prompt.user; <userinput>ssh -2 -N -f -L 8888:music.example.com:8000 user@unfirewalled-system.example.org</userinput> user@unfirewalled-system.example.org's password: <userinput>*******</userinput></screen> <para>In this example, a streaming Ogg Vorbis client can now - be pointed to <hostid>localhost</hostid> port 8888, which + be pointed to <systemitem>localhost</systemitem> port 8888, which will be forwarded over to - <hostid>music.example.com</hostid> on port 8000, + <systemitem>music.example.com</systemitem> on port 8000, successfully bypassing the firewall.</para> </sect4> </sect3> @@ -3158,13 +3087,13 @@ user@unfirewalled-system.example.org's password: <userinput>*******</userinput>< <para>It is often a good idea to limit which users can log in and from where using <literal>AllowUsers</literal>. For - example, to only allow <username>root</username> to log in - from <hostid role="ipaddr">192.168.1.32</hostid>, add this + example, to only allow <systemitem class="username">root</systemitem> to log in + from <systemitem class="ipaddress">192.168.1.32</systemitem>, add this line to <filename>/etc/ssh/sshd_config</filename>:</para> <programlisting>AllowUsers root@192.168.1.32</programlisting> - <para>To allow <username>admin</username> to log in from + <para>To allow <systemitem class="username">admin</systemitem> to log in from anywhere, list that username by itself:</para> <programlisting>AllowUsers admin</programlisting> @@ -3189,7 +3118,7 @@ user@unfirewalled-system.example.org's password: <userinput>*******</userinput>< <sect2> <title>Further Reading</title> - <para>The <ulink url="http://www.openssh.com/">OpenSSH</ulink> + <para>The <link xlink:href="http://www.openssh.com/">OpenSSH</link> website.</para> <para>&man.ssh.1;, &man.scp.1;, &man.ssh-keygen.1;, @@ -3201,19 +3130,15 @@ user@unfirewalled-system.example.org's password: <userinput>*******</userinput>< </sect2> </sect1> - <sect1 id="fs-acl"> - <sect1info> + <sect1 xml:id="fs-acl"> + <info><title>Filesystem Access Control Lists + (<acronym>ACL</acronym>)s</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Filesystem Access Control Lists - (<acronym>ACL</acronym>)s</title> + <indexterm> <primary>ACL</primary> @@ -3304,11 +3229,11 @@ drwxrwx---+ 2 robert robert 512 Dec 27 11:57 directory3 drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> <para>In this example, - <filename class="directory">directory1</filename>, - <filename class="directory">directory2</filename>, and - <filename class="directory">directory3</filename> + <filename>directory1</filename>, + <filename>directory2</filename>, and + <filename>directory3</filename> are all taking advantage of <acronym>ACL</acronym>s, whereas - <filename class="directory">public_html</filename> + <filename>public_html</filename> is not.</para> <sect2> @@ -3319,7 +3244,7 @@ drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> <acronym>ACL</acronym> settings on <filename>test</filename>:</para> - <screen>&prompt.user; <userinput>getfacl <filename>test</filename></userinput> + <screen>&prompt.user; <userinput>getfacl test</userinput> #file:test #owner:1001 #group:1001 @@ -3330,7 +3255,7 @@ drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> <para>To change the <acronym>ACL</acronym> settings on this file, use &man.setfacl.1;:</para> - <screen>&prompt.user; <userinput>setfacl -k <filename>test</filename></userinput></screen> + <screen>&prompt.user; <userinput>setfacl -k test</userinput></screen> <para>To remove all of the currently defined <acronym>ACL</acronym>s from a file or filesystem, one can use @@ -3338,7 +3263,7 @@ drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> <option>-b</option> as it leaves the basic fields required for <acronym>ACL</acronym>s to work.</para> - <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- <filename>test</filename></userinput></screen> + <screen>&prompt.user; <userinput>setfacl -m u:trhodes:rwx,group:web:r--,o::--- test</userinput></screen> <para>In this example, <option>-m</option> is used to modify the default <acronym>ACL</acronym> entries. Since there were no @@ -3350,18 +3275,14 @@ drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> </sect2> </sect1> - <sect1 id="security-portaudit"> - <sect1info> + <sect1 xml:id="security-portaudit"> + <info><title>Monitoring Third Party Security Issues</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Monitoring Third Party Security Issues</title> + <indexterm> <primary>portaudit</primary> @@ -3383,7 +3304,7 @@ drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> purpose.</para> <para>The - <filename role="package">ports-mgmt/portaudit</filename> + <package>ports-mgmt/portaudit</package> port polls a database, which is updated and maintained by the &os; Security Team and ports developers, for known security issues.</para> @@ -3397,7 +3318,7 @@ drwxr-xr-x 2 robert robert 512 Nov 10 11:54 public_html</programlisting> &man.periodic.8; will be updated, permitting <application>portaudit</application> output in the daily security runs. Ensure that the daily security run emails, which - are sent to <username>root</username>'s email account, are + are sent to <systemitem class="username">root</systemitem>'s email account, are being read. No other configuration is required.</para> <para>After installation, an administrator can update the @@ -3440,18 +3361,14 @@ You are advised to update or deinstall the affected package(s) immediately.</pro <application>portmaster</application> port.</para> </sect1> - <sect1 id="security-advisories"> - <sect1info> + <sect1 xml:id="security-advisories"> + <info><title>&os; Security Advisories</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>&os; Security Advisories</title> + <indexterm> <primary>&os; Security Advisories</primary> @@ -3475,13 +3392,13 @@ You are advised to update or deinstall the affected package(s) immediately.</pro FreeBSD-SA-XX:XX.UTIL Security Advisory The FreeBSD Project -Topic: denial of service due to some problem <co id="co-topic"/> +Topic: denial of service due to some problem <co xml:id="co-topic"/> -Category: core <co id="co-category"/> -Module: sys <co id="co-module"/> -Announced: 2003-09-23 <co id="co-announce"/> -Credits: Person <co id="co-credit"/> -Affects: All releases of &os; <co id="co-affects"/> +Category: core <co xml:id="co-category"/> +Module: sys <co xml:id="co-module"/> +Announced: 2003-09-23 <co xml:id="co-announce"/> +Credits: Person <co xml:id="co-credit"/> +Affects: All releases of &os; <co xml:id="co-affects"/> &os; 4-STABLE prior to the correction date Corrected: 2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE) 2003-09-23 20:08:42 UTC (RELENG_5_1, 5.1-RELEASE-p6) @@ -3491,33 +3408,33 @@ Corrected: 2003-09-23 16:42:59 UTC (RELENG_4, 4.9-PRERELEASE) 2003-09-23 16:49:46 UTC (RELENG_4_6, 4.6-RELEASE-p21) 2003-09-23 16:51:24 UTC (RELENG_4_5, 4.5-RELEASE-p33) 2003-09-23 16:52:45 UTC (RELENG_4_4, 4.4-RELEASE-p43) - 2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) <co id="co-corrected"/> -<acronym>CVE</acronym> Name: CVE-XXXX-XXXX <co id="co-cve"/> + 2003-09-23 16:54:39 UTC (RELENG_4_3, 4.3-RELEASE-p39) <co xml:id="co-corrected"/> +<acronym>CVE</acronym> Name: CVE-XXXX-XXXX <co xml:id="co-cve"/> For general information regarding FreeBSD Security Advisories, including descriptions of the fields above, security branches, and the following sections, please visit http://www.FreeBSD.org/security/. -I. Background <co id="co-backround"/> +I. Background <co xml:id="co-backround"/> -II. Problem Description <co id="co-descript"/> +II. Problem Description <co xml:id="co-descript"/> -III. Impact <co id="co-impact"/> +III. Impact <co xml:id="co-impact"/> -IV. Workaround <co id="co-workaround"/> +IV. Workaround <co xml:id="co-workaround"/> -V. Solution <co id="co-solution"/> +V. Solution <co xml:id="co-solution"/> -VI. Correction details <co id="co-details"/> +VI. Correction details <co xml:id="co-details"/> -VII. References <co id="co-ref"/></programlisting> +VII. References <co xml:id="co-ref"/></programlisting> <calloutlist> <callout arearefs="co-topic"> @@ -3570,8 +3487,7 @@ VII. References <co id="co-ref"/></programlisting> For the kernel, a quick look over the output from &man.ident.1; on the affected files will help in determining the revision. For ports, the version number - is listed after the port name in <filename - class="directory">/var/db/pkg</filename>. If the + is listed after the port name in <filename>/var/db/pkg</filename>. If the system does not sync with the &os; Subversion repository and is not rebuilt daily, chances are that it is affected.</para> @@ -3585,9 +3501,8 @@ VII. References <co id="co-ref"/></programlisting> <callout arearefs="co-cve"> <para>Reserved for the identification information used to - look up vulnerabilities in the <ulink - url="http://cve.mitre.org">Common Vulnerabilities - and Exposures</ulink> database.</para> + look up vulnerabilities in the <link xlink:href="http://cve.mitre.org">Common Vulnerabilities + and Exposures</link> database.</para> </callout> <callout arearefs="co-backround"> @@ -3647,18 +3562,14 @@ VII. References <co id="co-ref"/></programlisting> </sect2> </sect1> - <sect1 id="security-accounting"> - <sect1info> + <sect1 xml:id="security-accounting"> + <info><title>Process Accounting</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Process Accounting</title> + <indexterm> <primary>Process Accounting</primary> @@ -3700,7 +3611,7 @@ VII. References <co id="co-ref"/></programlisting> &man.lastcomm.1;. This command displays the commands issued by users on specific &man.ttys.5;. For example, this command prints out all known usage of &man.ls.1; by - <username>trhodes</username> on the <literal>ttyp1</literal> + <systemitem class="username">trhodes</systemitem> on the <literal>ttyp1</literal> terminal:</para> <screen>&prompt.root; <userinput>lastcomm ls trhodes ttyp1</userinput></screen> @@ -3710,18 +3621,14 @@ VII. References <co id="co-ref"/></programlisting> </sect2> </sect1> - <sect1 id="security-resourcelimits"> - <sect1info> + <sect1 xml:id="security-resourcelimits"> + <info><title>Resource Limits</title> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Tom</firstname><surname>Rhodes</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - </sect1info> + </info> - <title>Resource Limits</title> + <indexterm> <primary>Resource limits</primary> diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml index 9e9f31ba5b..2ec77639c7 100644 --- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml @@ -4,11 +4,10 @@ $FreeBSD$ --> - -<chapter id="serialcomms"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="serialcomms"> <title>Serial Communications</title> - <sect1 id="serial-synopsis"> + <sect1 xml:id="serial-synopsis"> <title>Synopsis</title> <indexterm><primary>serial communications</primary></indexterm> @@ -56,7 +55,7 @@ </itemizedlist> </sect1> - <sect1 id="serial"> + <sect1 xml:id="serial"> <title>Serial Terminology and Hardware</title> <para>The following terms are often used in serial @@ -117,7 +116,7 @@ with serial hardware and cabling can safely skip this section.</para> - <sect2 id="term-cables-null"> + <sect2 xml:id="term-cables-null"> <title>Serial Cables and Ports</title> <para>There are several different kinds of serial cables. The @@ -136,8 +135,7 @@ <quote>Received Data</quote> pin on the other end.</para> <para>A null-modem cable can be constructed for use with - terminals. The following table shows the RS-232C <link - linkend="serialcomms-signal-names">signal names</link> + terminals. The following table shows the RS-232C <link linkend="serialcomms-signal-names">signal names</link> and the pin numbers on a DB-25 connector. While the standard calls for a straight-through pin 1 to pin 1 <emphasis>Protective Ground</emphasis> line, it is often @@ -153,7 +151,7 @@ <row> <entry align="left">Signal</entry> <entry align="left">Pin #</entry> - <entry></entry> + <entry/> <entry align="left">Pin #</entry> <entry align="left">Signal</entry> </row> @@ -246,7 +244,7 @@ <row> <entry align="left">Signal</entry> <entry align="left">Pin #</entry> - <entry></entry> + <entry/> <entry align="left">Pin #</entry> <entry align="left">Signal</entry> </row> @@ -336,7 +334,7 @@ <row> <entry align="left">Signal</entry> <entry align="left">Pin #</entry> - <entry></entry> + <entry/> <entry align="left">Pin #</entry> <entry align="left">Signal</entry> </row> @@ -459,13 +457,13 @@ the type of port.</para> <para>In &os;, each serial port is accessed through an - entry in <filename class="directory">/dev</filename>. + entry in <filename>/dev</filename>. There are two different kinds of entries:</para> <itemizedlist> <listitem> <para>Call-in ports are named - <filename>/dev/ttyu<replaceable>N</replaceable></filename> + <filename>/dev/ttyuN</filename> where <replaceable>N</replaceable> is the port number, starting from zero. Generally, the call-in port is used for terminals. Call-in ports require that the @@ -476,7 +474,7 @@ <listitem> <para>Call-out ports are named - <filename>/dev/cuau<replaceable>N</replaceable></filename>. + <filename>/dev/cuauN</filename>. Call-out ports are usually not used for terminals, but are used for modems. The call-out port can be used if the serial cable or the terminal does not support the @@ -485,10 +483,10 @@ </itemizedlist> <para>If a terminal is connected to the first serial - port(<devicename>COM1</devicename>), use + port(<filename>COM1</filename>), use <filename>/dev/ttyu0</filename> to refer to the terminal. If the terminal is on the second serial port - (<devicename>COM2</devicename>), use + (<filename>COM2</filename>), use <filename>/dev/ttyu1</filename>, and so forth.</para> </sect2> @@ -497,10 +495,10 @@ <para>&os; supports four serial ports by default. In the &ms-dos; world, these are known as - <devicename>COM1</devicename>, - <devicename>COM2</devicename>, - <devicename>COM3</devicename>, and - <devicename>COM4</devicename>. &os; currently supports + <filename>COM1</filename>, + <filename>COM2</filename>, + <filename>COM3</filename>, and + <filename>COM4</filename>. &os; currently supports <quote>dumb</quote> multiport serial interface cards, such as the BocaBoard 1008 and 2016, as well as more intelligent multi-port cards such as those made by Digiboard and Stallion @@ -542,20 +540,20 @@ <para>Most devices in the kernel are accessed through <quote>device special files</quote> which are located in - <filename class="directory">/dev</filename>. The - <devicename>sio</devicename> devices are accessed through the - <filename>/dev/ttyu<replaceable>N</replaceable></filename> + <filename>/dev</filename>. The + <filename>sio</filename> devices are accessed through the + <filename>/dev/ttyuN</filename> (dial-in) and - <filename>/dev/cuau<replaceable>N</replaceable></filename> + <filename>/dev/cuauN</filename> (call-out) devices. &os; also provides initialization devices - (<filename>/dev/ttyu<replaceable>N</replaceable>.init</filename> + (<filename>/dev/ttyuN.init</filename> and - <filename>/dev/cuau<replaceable>N</replaceable>.init</filename>) + <filename>/dev/cuauN.init</filename>) and locking devices - (<filename>/dev/ttyu<replaceable>N</replaceable>.lock</filename> + (<filename>/dev/ttyuN.lock</filename> and - <filename>/dev/cuau<replaceable>N</replaceable>.lock</filename>). + <filename>/dev/cuauN.lock</filename>). The initialization devices are used to initialize communications port parameters each time a port is opened, such as <literal>crtscts</literal> for modems which use @@ -568,15 +566,15 @@ </sect2> - <sect2 id="serial-hw-config"> + <sect2 xml:id="serial-hw-config"> <title>Serial Port Configuration</title> - <indexterm><primary><devicename>ttyu</devicename></primary></indexterm> - <indexterm><primary><devicename>cuau</devicename></primary></indexterm> + <indexterm><primary><filename>ttyu</filename></primary></indexterm> + <indexterm><primary><filename>cuau</filename></primary></indexterm> <para>The - <devicename>ttyu<replaceable>N</replaceable></devicename> (or - <devicename>cuau<replaceable>N</replaceable></devicename>) + <filename>ttyuN</filename> (or + <filename>cuauN</filename>) is the regular device to open for applications. When a process opens the device, it will have a default set of terminal I/O settings. These settings can be viewed with the @@ -591,7 +589,7 @@ <quote>initial state</quote> device. For example, to turn on <option>CLOCAL</option> mode, 8 bit communication, and <option>XON/XOFF</option> flow control for - <devicename>ttyu5</devicename>, type:</para> + <filename>ttyu5</filename>, type:</para> <screen>&prompt.root; <userinput>stty -f /dev/ttyu5.init clocal cs8 ixon ixoff</userinput></screen> @@ -607,20 +605,20 @@ <para>To prevent certain settings from being changed by an application, make adjustments to the <quote>lock state</quote> device. For example, to lock the speed of - <devicename>ttyu5</devicename> to 57600 bps, type:</para> + <filename>ttyu5</filename> to 57600 bps, type:</para> <screen>&prompt.root; <userinput>stty -f /dev/ttyu5.lock 57600</userinput></screen> <para>Now, an application that opens - <devicename>ttyu5</devicename> and tries to change the speed + <filename>ttyu5</filename> and tries to change the speed of the port will be stuck with 57600 bps.</para> <para>The initial state and lock state devices should only be - writable by <username>root</username>.</para> + writable by <systemitem class="username">root</systemitem>.</para> </sect2> </sect1> - <sect1 id="term"> + <sect1 xml:id="term"> <!-- <sect1info> <authorgroup> @@ -707,26 +705,25 @@ <para>To connect from a client system that runs &os; to the serial connection of another system, use:</para> - <screen>&prompt.root; <userinput>cu -l <replaceable>serial-port-device</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cu -l serial-port-device</userinput></screen> <para>Where <quote>serial-port-device</quote> is the name of a special device file denoting a serial port on the system. These device files are called - <devicename>/dev/cuau<replaceable>N</replaceable></devicename>.</para> + <filename>/dev/cuauN</filename>.</para> <para>The <quote>N</quote>-part of a device name is the serial port number.</para> <note> <para>Note that device numbers in &os; start from zero and - not one. This means that <devicename>COM1</devicename> + not one. This means that <filename>COM1</filename> is <filename>/dev/cuau0</filename> in &os;.</para> </note> <note> <para>Some people prefer to use other programs available - through the Ports Collection, such as <filename - role="package">comms/minicom</filename>.</para> + through the Ports Collection, such as <package>comms/minicom</package>.</para> </note> </listitem> </varlistentry> @@ -746,7 +743,7 @@ </varlistentry> </variablelist> - <sect2 id="term-config"> + <sect2 xml:id="term-config"> <title>Configuration</title> <para>This section describes how to configure a &os; system to @@ -765,12 +762,12 @@ program.</para> <para>To configure terminals for a &os; system, the following - steps should be taken as <username>root</username>:</para> + steps should be taken as <systemitem class="username">root</systemitem>:</para> <procedure> <step> <para>Add a line to <filename>/etc/ttys</filename> for the - entry in <filename class="directory">/dev</filename> for + entry in <filename>/dev</filename> for the serial port if it is not already there.</para> </step> @@ -806,31 +803,30 @@ more information, refer to &man.gettytab.5; and &man.getty.8;.</para> - <sect3 id="term-etcttys"> + <sect3 xml:id="term-etcttys"> <title>Adding an Entry to <filename>/etc/ttys</filename></title> <para><filename>/etc/ttys</filename> lists all of the ports on the &os; system which allow logins. For example, the first virtual console, - <devicename>ttyv0</devicename>, has an entry in this file, + <filename>ttyv0</filename>, has an entry in this file, allowing logins on the console. This file also contains entries for the other virtual consoles, serial ports, and pseudo-ttys. For a hardwired terminal, - list the serial port's <filename - class="directory">/dev</filename> entry without the + list the serial port's <filename>/dev</filename> entry without the <literal>/dev</literal> part. For example, <filename>/dev/ttyv0</filename> would be listed as <literal>ttyv0</literal>.</para> <para>A default &os; install includes an <filename>/etc/ttys</filename> with support for the - first four serial ports: <devicename>ttyu0</devicename> - through <devicename>ttyu3</devicename>. When + first four serial ports: <filename>ttyu0</filename> + through <filename>ttyu3</filename>. When attaching a terminal to one of those ports, this file does not need to be edited.</para> - <example id="ex-etc-ttys"> + <example xml:id="ex-etc-ttys"> <title>Adding Terminal Entries to <filename>/etc/ttys</filename></title> @@ -843,19 +839,14 @@ <filename>/etc/ttys</filename> would look like this:</para> - <programlisting>ttyu1<co - id="co-ttys-line1col1"/> "/usr/libexec/getty std.38400"<co - id="co-ttys-line1col2"/> wy50<co - id="co-ttys-line1col3"/> on<co - id="co-ttys-line1col4"/> insecure<co - id="co-ttys-line1col5"/> + <programlisting>ttyu1<co xml:id="co-ttys-line1col1"/> "/usr/libexec/getty std.38400"<co xml:id="co-ttys-line1col2"/> wy50<co xml:id="co-ttys-line1col3"/> on<co xml:id="co-ttys-line1col4"/> insecure<co xml:id="co-ttys-line1col5"/> ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> <calloutlist> <callout arearefs="co-ttys-line1col1"> <para>The first field normally specifies the name of the terminal special file as it is found in - <filename class="directory">/dev</filename>.</para> + <filename>/dev</filename>.</para> </callout> <callout arearefs="co-ttys-line1col2"> @@ -924,10 +915,10 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> <para>The final field is used to specify whether the port is secure. Marking a port as <literal>secure</literal> means that it is trusted - enough to allow <username>root</username>, or any + enough to allow <systemitem class="username">root</systemitem>, or any account with a <acronym>UID</acronym> of 0, to login from that port. Insecure ports do not allow - <username>root</username> logins. On an insecure + <systemitem class="username">root</systemitem> logins. On an insecure port, users must login from unprivileged accounts and then use &man.su.1; or a similar mechanism to gain superuser privileges.</para> @@ -942,7 +933,7 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> </example> </sect3> - <sect3 id="term-hup"> + <sect3 xml:id="term-hup"> <title>Force <command>init</command> to Reread <filename>/etc/ttys</filename></title> @@ -967,7 +958,7 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> </sect3> </sect2> - <sect2 id="term-debug"> + <sect2 xml:id="term-debug"> <title>Troubleshooting the Connection</title> <para>Even with the most meticulous attention to detail, @@ -1000,7 +991,7 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> <para>There should be an entry for the terminal. For example, the following display shows that a <command>getty</command> is running on the second serial - port, <devicename>ttyu1</devicename>, and is using the + port, <filename>ttyu1</filename>, and is using the <literal>std.38400</literal> entry in <filename>/etc/gettytab</filename>:</para> @@ -1042,7 +1033,7 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> </sect2> </sect1> - <sect1 id="dialup"> + <sect1 xml:id="dialup"> <!-- <sect1info> <authorgroup> @@ -1087,7 +1078,7 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> standard RS-232C serial cable should suffice as long as all of the normal signals are wired:</para> - <table frame="none" pgwide="1" id="serialcomms-signal-names"> + <table frame="none" pgwide="1" xml:id="serialcomms-signal-names"> <title>Signal Names</title> <tgroup cols="2"> @@ -1216,13 +1207,13 @@ ttyu5 "/usr/libexec/getty std.19200" vt100 on insecure</programlisting> <title>Configuration Files</title> <para>There are three system configuration files in - <filename class="directory">/etc</filename> that probably + <filename>/etc</filename> that probably need to be edited to allow dial-up access to the &os; system. <filename>/etc/gettytab</filename> contains configuration information for the <filename>/usr/libexec/getty</filename> daemon. <filename>/etc/ttys</filename> holds information that tells <command>init</command> which - <devicename>tty</devicename>s should have + <filename>tty</filename>s should have <command>getty</command> processes running on them. Lastly, port initialization commands can be placed in <filename>/etc/rc.d/serial</filename>.</para> @@ -1356,7 +1347,7 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\ <quote>silo</quote> errors at 57.6 Kbps.</para> </sect3> - <sect3 id="dialup-ttys"> + <sect3 xml:id="dialup-ttys"> <title><filename>/etc/ttys</filename></title> <indexterm> @@ -1376,7 +1367,7 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\ <para>The first item in the above line is the device special file for this entry. <literal>ttyu0</literal> indicates that <command>getty</command> is watching - <devicename>/dev/ttyu0</devicename>. The + <filename>/dev/ttyu0</filename>. The <replaceable>xxx</replaceable> will replace the initial <filename>gettytab</filename> capability and is the process <command>init</command> will run on the device. The third @@ -1418,7 +1409,7 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\ <para>If the modem is locked at a different data rate, substitute the appropriate value for - <literal>std.<replaceable>speed</replaceable></literal> + <literal>std.speed</literal> instead of <literal>std.19200</literal>. Make sure to use a valid type listed in <filename>/etc/gettytab</filename>.</para> @@ -1451,7 +1442,7 @@ vq|VH57600|Very High Speed Modem at 57600,8-bit:\ <para>For example, to set the <literal>termios</literal> flag <varname>crtscts</varname> on - <devicename>COM2</devicename>'s dial-in and dial-out + <filename>COM2</filename>'s dial-in and dial-out initialization devices, the following lines could be added to <filename>/etc/rc.d/serial</filename>:</para> @@ -1646,7 +1637,7 @@ AT&B2&W</programlisting> <para>If no <command>getty</command> processes are waiting to open the desired - <devicename>ttyu<replaceable>N</replaceable></devicename> + <filename>ttyuN</filename> port, double-check the entries in <filename>/etc/ttys</filename> to see if there are any mistakes. Also, check @@ -1704,7 +1695,7 @@ AT&B2&W</programlisting> </sect2> </sect1> - <sect1 id="dialout"> + <sect1 xml:id="dialout"> <title>Dial-out Service</title> <indexterm><primary>dial-out service</primary></indexterm> @@ -1718,7 +1709,7 @@ AT&B2&W</programlisting> working, use the terminal session to FTP the needed file. Then use zmodem to transfer it to the machine.</para> - <sect2 id="hayes-unsupported"> + <sect2 xml:id="hayes-unsupported"> <title>Using a Stock Hayes Modem</title> <para>A generic Hayes dialer is built into @@ -1738,7 +1729,7 @@ AT&B2&W</programlisting> problem. Try <command>ATS7=45&W</command>.</para> </sect2> - <sect2 id="direct-at"> + <sect2 xml:id="direct-at"> <title>Using <literal>AT</literal> Commands</title> <indexterm> @@ -1756,10 +1747,10 @@ AT&B2&W</programlisting> supports in the <literal>br</literal> capability. Then, type <command>tip cuau0</command> to connect to the modem.</para> - <para>Or, use <command>cu</command> as <username>root</username> + <para>Or, use <command>cu</command> as <systemitem class="username">root</systemitem> with the following command:</para> - <screen>&prompt.root; <userinput>cu -l<replaceable>line</replaceable> -s<replaceable>speed</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>cu -lline -sspeed</userinput></screen> <para><replaceable>line</replaceable> is the serial port, such as <filename>/dev/cuau0</filename>, and @@ -1768,7 +1759,7 @@ AT&B2&W</programlisting> commands, type <command>~.</command> to exit.</para> </sect2> - <sect2 id="gt-failure"> + <sect2 xml:id="gt-failure"> <title>The <literal>@</literal> Sign Does Not Work</title> <para>The <literal>@</literal> sign in the phone number @@ -1781,7 +1772,7 @@ AT&B2&W</programlisting> <programlisting>pn=\@</programlisting> </sect2> - <sect2 id="dial-command-line"> + <sect2 xml:id="dial-command-line"> <title>Dialing from the Command Line</title> <para>Put a <quote>generic</quote> entry in @@ -1808,7 +1799,7 @@ tip57600|Dial any phone number at 57600 bps:\ <screen>&prompt.root; <userinput>cu 5551234 -s 115200</userinput></screen> </sect2> - <sect2 id="set-bps"> + <sect2 xml:id="set-bps"> <title>Setting the <acronym>bps</acronym> Rate</title> <para>Put in an entry for <literal>tip1200</literal> or @@ -1820,18 +1811,18 @@ tip57600|Dial any phone number at 57600 bps:\ 1200 bps does not have to be used, though.</para> </sect2> - <sect2 id="terminal-server"> + <sect2 xml:id="terminal-server"> <title>Accessing a Number of Hosts Through a Terminal Server</title> <para>Rather than waiting until connected and typing - <command>CONNECT <replaceable>host</replaceable></command> + <command>CONNECT host</command> each time, use <command>tip</command>'s <literal>cm</literal> capability. For example, these entries in <filename>/etc/remote</filename> will let you type <command>tip pain</command> or <command>tip muffin</command> to connect to the hosts - <hostid>pain</hostid> or <hostid>muffin</hostid>, and + <systemitem>pain</systemitem> or <systemitem>muffin</systemitem>, and <command>tip deep13</command> to connect to the terminal server.</para> @@ -1844,7 +1835,7 @@ deep13:Gizmonics Institute terminal server:\ </sect2> - <sect2 id="tip-multiline"> + <sect2 xml:id="tip-multiline"> <title>Using More Than One Line with <command>tip</command></title> @@ -1875,7 +1866,7 @@ big-university 5551114</programlisting> loop.</para> </sect2> - <sect2 id="multi-controlp"> + <sect2 xml:id="multi-controlp"> <title>Using the Force Character</title> <para><keycombo action="simul"> @@ -1888,7 +1879,7 @@ big-university 5551114</programlisting> <quote>set a variable.</quote></para> <para>Type - <command>~sforce=<replaceable>single-char</replaceable></command> + <command>~sforce=single-char</command> followed by a newline. <replaceable>single-char</replaceable> is any single character. If <replaceable>single-char</replaceable> is left out, then the @@ -1914,7 +1905,7 @@ big-university 5551114</programlisting> <programlisting>force=<replaceable>single-char</replaceable></programlisting> </sect2> - <sect2 id="uppercase"> + <sect2 xml:id="uppercase"> <title>Upper Case Characters</title> <para>This happens when @@ -1948,7 +1939,7 @@ raisechar=^^</programlisting> </sect2> - <sect2 id="tip-filetransfer"> + <sect2 xml:id="tip-filetransfer"> <title>File Transfers with <command>tip</command></title> <para>When talking to another &unix;-like operating system, @@ -1973,7 +1964,7 @@ raisechar=^^</programlisting> zmodem, should probably be used.</para> </sect2> - <sect2 id="zmodem-tip"> + <sect2 xml:id="zmodem-tip"> <title>Using <application>zmodem</application> with <command>tip</command>?</title> @@ -1983,12 +1974,12 @@ raisechar=^^</programlisting> <para>To send files, start the receiving program on the remote end. Then, type <command>~C sz - <replaceable>files</replaceable></command> to send them to the + files</command> to send them to the remote system.</para> </sect2> </sect1> - <sect1 id="serialconsole-setup"> + <sect1 xml:id="serialconsole-setup"> <!-- <sect1info> <authorgroup> @@ -2028,7 +2019,7 @@ raisechar=^^</programlisting> block code, the boot loader code, and the kernel need to be configured.</para> - <sect2 id="serialconsole-howto-fast"> + <sect2 xml:id="serialconsole-howto-fast"> <title>Quick Serial Console Configuration</title> <para>This section assumes the default setup and provides a fast @@ -2038,7 +2029,7 @@ raisechar=^^</programlisting> <step> <para>Connect the serial cable to - <devicename>COM1</devicename> and the controlling + <filename>COM1</filename> and the controlling terminal.</para> </step> @@ -2053,7 +2044,7 @@ raisechar=^^</programlisting> <para>Edit <filename>/etc/ttys</filename> and change <literal>off</literal> to <literal>on</literal> and <literal>dialup</literal> to <literal>vt100</literal> for - the <devicename>ttyu0</devicename> entry. Otherwise, a + the <filename>ttyu0</filename> entry. Otherwise, a password will not be required to connect via the serial console, resulting in a potential security hole.</para> </step> @@ -2069,7 +2060,7 @@ raisechar=^^</programlisting> section for a more in-depth configuration explanation.</para> </sect2> - <sect2 id="serialconsole-howto"> + <sect2 xml:id="serialconsole-howto"> <title>In-Depth Serial Console Configuration</title> <procedure> @@ -2079,8 +2070,7 @@ raisechar=^^</programlisting> <indexterm><primary>null-modem cable</primary></indexterm> <para>Use either a null-modem cable or a standard serial - cable and a null-modem adapter. See <xref - linkend="term-cables-null"/> for a discussion + cable and a null-modem adapter. See <xref linkend="term-cables-null"/> for a discussion on serial cables.</para> </step> @@ -2128,18 +2118,18 @@ raisechar=^^</programlisting> <step> <para>Plug a dumb terminal into - <devicename>COM1</devicename> - (<devicename>sio0</devicename>).</para> + <filename>COM1</filename> + (<filename>sio0</filename>).</para> <para>If a dumb terminal is not available, use an old computer with a modem program, or the serial port on another &unix; box. If there is no - <devicename>COM1</devicename> - (<devicename>sio0</devicename>), get one. At this time, + <filename>COM1</filename> + (<filename>sio0</filename>), get one. At this time, there is no way to select a port other than - <devicename>COM1</devicename> for the boot blocks without + <filename>COM1</filename> for the boot blocks without recompiling the boot blocks. If - <devicename>COM1</devicename> is being used by another + <filename>COM1</filename> is being used by another device, temporarily remove that device and install a new boot block and kernel once &os; is up and running.</para> </step> @@ -2147,8 +2137,8 @@ raisechar=^^</programlisting> <step> <para>Make sure the configuration file of the custom kernel has appropriate flags set for - <devicename>COM1</devicename> - (<devicename>sio0</devicename>).</para> + <filename>COM1</filename> + (<filename>sio0</filename>).</para> <para>Relevant flags are:</para> @@ -2189,9 +2179,8 @@ raisechar=^^</programlisting> unavailable for normal access. This flag should not be set to the serial port to use as the serial console. The only use of this flag is to designate - the unit for kernel remote debugging. See <ulink - url="&url.books.developers-handbook;/index.html">The - Developer's Handbook</ulink> for more information on + the unit for kernel remote debugging. See <link xlink:href="&url.books.developers-handbook;/index.html">The + Developer's Handbook</link> for more information on remote debugging.</para> </listitem> </varlistentry> @@ -2399,7 +2388,7 @@ boot:</screen> information.</para> </sect2> - <sect2 id="serialconsole-summary"> + <sect2 xml:id="serialconsole-summary"> <title>Summary</title> <para>The following tables provide a summary of the various @@ -2407,7 +2396,7 @@ boot:</screen> <table frame="none" pgwide="1"> <title>Case 1: Set the Flags to 0x10 for - <devicename>sio0</devicename></title> + <filename>sio0</filename></title> <tgroup cols="4"> <thead> @@ -2467,7 +2456,7 @@ boot:</screen> <table frame="none" pgwide="1"> <title>Case 2: Set the Flags to 0x30 for - <devicename>sio0</devicename></title> + <filename>sio0</filename></title> <tgroup cols="4"> <thead> @@ -2526,7 +2515,7 @@ boot:</screen> </table> </sect2> - <sect2 id="serialconsole-tips"> + <sect2 xml:id="serialconsole-tips"> <title>Tips for the Serial Console</title> <sect3> @@ -2539,9 +2528,8 @@ boot:</screen> <itemizedlist> <listitem> <para>Recompile the boot blocks with - <makevar>BOOT_COMCONSOLE_SPEED</makevar> set to the - new console speed. See <xref - linkend="serialconsole-com2"/> for detailed + <varname>BOOT_COMCONSOLE_SPEED</varname> set to the + new console speed. See <xref linkend="serialconsole-com2"/> for detailed instructions about building and installing new boot blocks.</para> @@ -2581,28 +2569,27 @@ console="comconsole,vidconsole"</programlisting> </itemizedlist> </sect3> - <sect3 id="serialconsole-com2"> + <sect3 xml:id="serialconsole-com2"> <title>Using a Serial Port Other Than - <devicename>sio0</devicename> for the Console</title> + <filename>sio0</filename> for the Console</title> - <para>Using a port other than <devicename>sio0</devicename> as + <para>Using a port other than <filename>sio0</filename> as the console requires the boot blocks, the boot loader, and the kernel to be recompiled as follows.</para> <procedure> <step> - <para>Get the kernel source as described in <xref - linkend="updating-upgrading"/>.</para> + <para>Get the kernel source as described in <xref linkend="updating-upgrading"/>.</para> </step> <step> <para>Edit <filename>/etc/make.conf</filename> and set <literal>BOOT_COMCONSOLE_PORT</literal> to the address of the port to use: 0x3F8, 0x2F8, 0x3E8 or 0x2E8. Only - <devicename>sio0</devicename> through - <devicename>sio3</devicename> - (<devicename>COM1</devicename> through - <devicename>COM4</devicename>) can be used as multiport + <filename>sio0</filename> through + <filename>sio3</filename> + (<filename>COM1</filename> through + <filename>COM4</filename>) can be used as multiport serial cards will not work. No interrupt setting is needed.</para> </step> @@ -2610,8 +2597,8 @@ console="comconsole,vidconsole"</programlisting> <step> <para>Create a custom kernel configuration file and add appropriate flags for the serial port to use. For - example, to make <devicename>sio1</devicename> - (<devicename>COM2</devicename>) the console:</para> + example, to make <filename>sio1</filename> + (<filename>COM2</filename>) the console:</para> <programlisting>device sio1 flags 0x10</programlisting> @@ -2644,7 +2631,7 @@ console="comconsole,vidconsole"</programlisting> </procedure> </sect3> - <sect3 id="serialconsole-ddb"> + <sect3 xml:id="serialconsole-ddb"> <title>Entering the DDB Debugger from the Serial Line</title> <para>To drop into the kernel debugger from the serial @@ -2674,10 +2661,10 @@ ttyu1 "/usr/libexec/getty std.9600" unknown off secure ttyu2 "/usr/libexec/getty std.9600" unknown off secure ttyu3 "/usr/libexec/getty std.9600" unknown off secure</programlisting> - <para><devicename>ttyu0</devicename> through - <devicename>ttyu3</devicename> correspond to - <devicename>COM1</devicename> through - <devicename>COM4</devicename>. Change + <para><filename>ttyu0</filename> through + <filename>ttyu3</filename> correspond to + <filename>COM1</filename> through + <filename>COM4</filename>. Change <literal>off</literal> to <literal>on</literal> for the desired port. If the speed of the serial port has been changed, change <literal>std.9600</literal> to match the @@ -2692,7 +2679,7 @@ ttyu3 "/usr/libexec/getty std.9600" unknown off secure</programlisting> </sect3> </sect2> - <sect2 id="serialconsole-loader"> + <sect2 xml:id="serialconsole-loader"> <title>Changing Console from the Boot Loader</title> <para>Previous sections described how to set up the serial @@ -2745,16 +2732,15 @@ ttyu3 "/usr/libexec/getty std.9600" unknown off secure</programlisting> <sect3> <title>Using a Serial Port Other Than - <devicename>sio0</devicename> for the Console</title> + <filename>sio0</filename> for the Console</title> <para>The boot loader needs to be compiled in order to use a - serial port other than <devicename>sio0</devicename> for the - serial console. Follow the procedure described in <xref - linkend="serialconsole-com2"/>.</para> + serial port other than <filename>sio0</filename> for the + serial console. Follow the procedure described in <xref linkend="serialconsole-com2"/>.</para> </sect3> </sect2> - <sect2 id="serialconsole-caveats"> + <sect2 xml:id="serialconsole-caveats"> <title>Caveats</title> <para>While most systems will boot without a keyboard, quite a diff --git a/en_US.ISO8859-1/books/handbook/users/Makefile b/en_US.ISO8859-1/books/handbook/users/Makefile new file mode 100644 index 0000000000..b44bd80628 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/users/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= users/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/users/chapter.xml b/en_US.ISO8859-1/books/handbook/users/chapter.xml new file mode 100644 index 0000000000..03f2dcca59 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/users/chapter.xml @@ -0,0 +1,1026 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + The FreeBSD Documentation Project + + $FreeBSD$ +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="users"> + <info><title>Users and Basic Account Management</title> + <authorgroup> + <author><personname><firstname>Neil</firstname><surname>Blakey-Milner</surname></personname><contrib>Contributed by </contrib></author> + </authorgroup> + + </info> + + + + <sect1 xml:id="users-synopsis"> + <title>Synopsis</title> + + <para>&os; allows multiple users to use the computer at the same + time. While only one user can sit in front of the screen and + use the keyboard at any one time, any number of users can log + in to the system through the network. To use the system, every + user must have a user account.</para> + + <para>After reading this chapter, you will know:</para> + + <itemizedlist> + <listitem> + <para>The differences between the various user accounts on a + &os; system.</para> + </listitem> + + <listitem> + <para>How to add and remove user accounts.</para> + </listitem> + + <listitem> + <para>How to change account details, such as the user's full + name or preferred shell.</para> + </listitem> + + <listitem> + <para>How to set limits on a per-account basis to control the + resources, such as memory and CPU time, that accounts and + groups of accounts are allowed to access.</para> + </listitem> + + <listitem> + <para>How to use groups to make account management + easier.</para> + </listitem> + </itemizedlist> + + <para>Before reading this chapter, you should:</para> + + <itemizedlist> + <listitem> + <para>Understand the <link linkend="basics">basics of &unix; + and &os;</link>.</para> + </listitem> + </itemizedlist> + </sect1> + + <sect1 xml:id="users-introduction"> + <title>Introduction</title> + + <para>Since all access to the &os; system is achieved via accounts + and all processes are run by users, user and account management + is important.</para> + + <para>Every account on a &os; system has certain information + associated with it to identify the account.</para> + + <variablelist> + <varlistentry> + <term>User name</term> + + <listitem> + <para>The user name is typed at the <prompt>login:</prompt> + prompt. User names must be unique on the system as no two + users can have the same user name. There are a number of + rules for creating valid user names, documented in + &man.passwd.5;. Typically user names consist of eight or + fewer all lower case characters in order to maintain + backwards compatibility with applications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password</term> + + <listitem> + <para>Each account has an associated password. While the + password can be blank, this is highly discouraged and + every account should have a password.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User ID (<acronym>UID</acronym>)</term> + + <listitem> + <para>The User ID (<acronym>UID</acronym>) is a number, + traditionally from 0 to 65535<footnote xml:id="users-largeuidgid"> + <para>It is possible to use + <acronym>UID</acronym>s/<acronym>GID</acronym>s as + large as 4294967295, but such IDs can cause serious + problems with software that makes assumptions about + the values of IDs.</para> + </footnote>, used to uniquely identify the user to the + system. Internally, &os; uses the + <acronym>UID</acronym> to identify users. Commands that + allow a user name to be specified will first convert it to + the <acronym>UID</acronym>. Though unlikely, it is + possible for several accounts with different user names to + share the same <acronym>UID</acronym>. As far as &os; is + concerned, these accounts are one user.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Group ID (<acronym>GID</acronym>)</term> + + <listitem> + <para>The Group ID (<acronym>GID</acronym>) is a number, + traditionally from 0 to 65535<footnoteref linkend="users-largeuidgid"/>, used to uniquely identify + the primary group that the user belongs to. Groups are a + mechanism for controlling access to resources based on a + user's <acronym>GID</acronym> rather than their + <acronym>UID</acronym>. This can significantly reduce the + size of some configuration files. A user may also be a + member of more than one group.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Login class</term> + + <listitem> + <para>Login classes are an extension to the group mechanism + that provide additional flexibility when tailoring the + system to different users.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Password change time</term> + + <listitem> + <para>By default &os; does not force users to change their + passwords periodically. Password expiration can be + enforced on a per-user basis, forcing some or all users to + change their passwords after a certain amount of time has + elapsed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Account expiry time</term> + + <listitem> + <para>By default &os; does not expire accounts. When + creating accounts that need a limited lifespan, such as + student accounts in a school, specify the account expiry + date. After the expiry time has elapsed, the account + cannot be used to log in to the system, although the + account's directories and files will remain.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User's full name</term> + + <listitem> + <para>The user name uniquely identifies the account to &os;, + but does not necessarily reflect the user's real name. + This information can be associated with the + account.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>Home directory</term> + + <listitem> + <para>The home directory is the full path to a directory on + the system. This is the user's starting directory when + the user logs in. A common convention is to put all user + home directories under <filename>/home/username</filename> + or <filename>/usr/home/username</filename>. + Each user stores their personal files and subdirectories + in their own home directory.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>User shell</term> + + <listitem> + <para>The shell provides the default environment users use + to interact with the system. There are many different + kinds of shells, and experienced users will have their own + preferences, which can be reflected in their account + settings.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>There are three main types of accounts: the <link linkend="users-superuser">superuser</link>, <link linkend="users-system">system accounts</link>, and <link linkend="users-user">user accounts</link>. The superuser + account, usually called <systemitem class="username">root</systemitem>, is used to + manage the system with no limitations on privileges. System + accounts are used to run services. User accounts are + assigned to real people and are used to log in and use the + system.</para> + + <sect2 xml:id="users-superuser"> + <title>The Superuser Account</title> + + <indexterm> + <primary>accounts</primary> + <secondary>superuser (root)</secondary> + </indexterm> + <para>The superuser account, usually called + <systemitem class="username">root</systemitem>, is used to perform system + administration tasks and should not be used for day-to-day + tasks like sending and receiving mail, general exploration of + the system, or programming.</para> + + <para>This is because the superuser, unlike normal user + accounts, can operate without limits, and misuse of the + superuser account may result in spectacular disasters. User + accounts are unable to destroy the system by mistake, so it is + generally best to use normal user accounts whenever possible, + unless extra privilege is required.</para> + + <para>Always double and triple-check any commands issued as the + superuser, since an extra space or missing character can mean + irreparable data loss.</para> + + <para>Always create a user account for the system administrator + and use this account to log in to the system for general + usage. This applies equally to multi-user or single-user + systems. Later sections will discuss how to create additional + accounts and how to change between the normal user and + superuser.</para> + </sect2> + + <sect2 xml:id="users-system"> + <title>System Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>system</secondary> + </indexterm> + <para>System accounts are used to run services such as DNS, + mail, and web servers. The reason for this is security; if + all services ran as the superuser, they could act without + restriction.</para> + + <indexterm> + <primary>accounts</primary> + <secondary><systemitem class="username">daemon</systemitem></secondary> + </indexterm> + <indexterm> + <primary>accounts</primary> + <secondary><systemitem class="username">operator</systemitem></secondary> + </indexterm> + <para>Examples of system accounts are + <systemitem class="username">daemon</systemitem>, <systemitem class="username">operator</systemitem>, + <systemitem class="username">bind</systemitem>, <systemitem class="username">news</systemitem>, and + <systemitem class="username">www</systemitem>.</para> + + <indexterm> + <primary>accounts</primary> + <secondary><systemitem class="username">nobody</systemitem></secondary> + </indexterm> + <para><systemitem class="username">nobody</systemitem> is the generic unprivileged + system account. However, the more services that use + <systemitem class="username">nobody</systemitem>, the more files and processes that + user will become associated with, and hence the more + privileged that user becomes.</para> + </sect2> + + <sect2 xml:id="users-user"> + <title>User Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>user</secondary> + </indexterm> + <para>User accounts are the primary means of access for real + people to the system. User accounts insulate the user and + the environment, preventing users from damaging the system + or other users, and allowing users to customize their + environment without affecting others.</para> + + <para>Every person accessing the system should have a unique + user account. This allows the administrator to find out who + is doing what, prevents users from clobbering each others' + settings or reading each others' mail, and so forth.</para> + + <para>Each user can set up their own environment to accommodate + their use of the system, by using alternate shells, editors, + key bindings, and language.</para> + </sect2> + </sect1> + + <sect1 xml:id="users-modifying"> + <title>Modifying Accounts</title> + + <indexterm> + <primary>accounts</primary> + <secondary>modifying</secondary> + </indexterm> + + <para>&os; provides a variety of different commands to manage + user accounts. The most common commands are summarized below, + followed by more detailed examples of their usage.</para> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="2"> + <colspec colwidth="1*"/> + <colspec colwidth="2*"/> + + <thead> + <row> + <entry>Command</entry> + <entry>Summary</entry> + </row> + </thead> + <tbody> + <row> + <entry>&man.adduser.8;</entry> + <entry>The recommended command-line application for adding + new users.</entry> + </row> + + <row> + <entry>&man.rmuser.8;</entry> + <entry>The recommended command-line application for + removing users.</entry> + </row> + + <row> + <entry>&man.chpass.1;</entry> + <entry>A flexible tool for changing user database + information.</entry> + </row> + + <row> + <entry>&man.passwd.1;</entry> + <entry>The simple command-line tool to change user + passwords.</entry> + </row> + + <row> + <entry>&man.pw.8;</entry> + <entry>A powerful and flexible tool for modifying all + aspects of user accounts.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <sect2 xml:id="users-adduser"> + <title><command>adduser</command></title> + + <indexterm> + <primary>accounts</primary> + <secondary>adding</secondary> + </indexterm> + <indexterm> + <primary><command>adduser</command></primary> + </indexterm> + <indexterm> + <primary><filename>/usr/share/skel</filename></primary> + </indexterm> + <indexterm><primary>skeleton directory</primary></indexterm> + <para>&man.adduser.8; is a simple program for adding new users + When a new user is added, this program automatically updates + <filename>/etc/passwd</filename> and + <filename>/etc/group</filename>. It also creates a home + directory for the new user, copies in the default + configuration files from <filename>/usr/share/skel</filename>, and can + optionally mail the new user a welcome message.</para> + + <example> + <title>Adding a User on &os;</title> + + <screen>&prompt.root; <userinput>adduser</userinput> +Username: <userinput>jru</userinput> +Full name: <userinput>J. Random User</userinput> +Uid (Leave empty for default): +Login group [jru]: +Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput> +Login class [default]: +Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput> +Home directory [/home/jru]: +Home directory permissions (Leave empty for default): +Use password-based authentication? [yes]: +Use an empty password? (yes/no) [no]: +Use a random password? (yes/no) [no]: +Enter password: +Enter password again: +Lock out the account after creation? [no]: +Username : jru +Password : **** +Full Name : J. Random User +Uid : 1001 +Class : +Groups : jru wheel +Home : /home/jru +Shell : /usr/local/bin/zsh +Locked : no +OK? (yes/no): <userinput>yes</userinput> +adduser: INFO: Successfully added (jru) to the user database. +Add another user? (yes/no): <userinput>no</userinput> +Goodbye! +&prompt.root;</screen> + </example> + + <note> + <para>Since the password is not echoed when typed, be careful + to not mistype the password when creating the user + account.</para> + </note> + </sect2> + + <sect2 xml:id="users-rmuser"> + <title><command>rmuser</command></title> + + <indexterm><primary><command>rmuser</command></primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>removing</secondary> + </indexterm> + + <para>To completely remove a user from the system use + &man.rmuser.8;. This command performs the following + steps:</para> + + <procedure> + <step> + <para>Removes the user's &man.crontab.1; entry if one + exists.</para> + </step> + + <step> + <para>Removes any &man.at.1; jobs belonging to the + user.</para> + </step> + + <step> + <para>Kills all processes owned by the user.</para> + </step> + + <step> + <para>Removes the user from the system's local password + file.</para> + </step> + + <step> + <para>Removes the user's home directory, if it is owned by + the user.</para> + </step> + + <step> + <para>Removes the incoming mail files belonging to the user + from <filename>/var/mail</filename>.</para> + </step> + + <step> + <para>Removes all files owned by the user from temporary + file storage areas such as <filename>/tmp</filename>.</para> + </step> + + <step> + <para>Finally, removes the username from all groups to which + it belongs in <filename>/etc/group</filename>.</para> + + <note> + <para>If a group becomes empty and the group name is the + same as the username, the group is removed. This + complements the per-user unique groups created by + &man.adduser.8;.</para> + </note> + </step> + </procedure> + + <para>&man.rmuser.8; cannot be used to remove superuser + accounts since that is almost always an indication of massive + destruction.</para> + + <para>By default, an interactive mode is used, as shown + in the following example.</para> + + <example> + <title><command>rmuser</command> Interactive Account + Removal</title> + + <screen>&prompt.root; <userinput>rmuser jru</userinput> +Matching password entry: +jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh +Is this the entry you wish to remove? <userinput>y</userinput> +Remove user's home directory (/home/jru)? <userinput>y</userinput> +Updating password file, updating databases, done. +Updating group file: trusted (removing group jru -- personal group is empty) done. +Removing user's incoming mail file /var/mail/jru: done. +Removing files belonging to jru from /tmp: done. +Removing files belonging to jru from /var/tmp: done. +Removing files belonging to jru from /var/tmp/vi.recover: done. +&prompt.root;</screen> + </example> + </sect2> + + <sect2 xml:id="users-chpass"> + <title><command>chpass</command></title> + + <indexterm><primary><command>chpass</command></primary></indexterm> + <para>&man.chpass.1; can be used to change user database + information such as passwords, shells, and personal + information.</para> + + <para>Only the superuser can change other users' information and + passwords with &man.chpass.1;.</para> + + <para>When passed no options, aside from an optional username, + &man.chpass.1; displays an editor containing user information. + When the user exists from the editor, the user database is + updated with the new information.</para> + + <note> + <para>You will be asked for your password after exiting the + editor if you are not the superuser.</para> + </note> + + <example> + <title>Interactive <command>chpass</command> by + Superuser</title> + + <screen>#Changing user database information for jru. +Login: jru +Password: * +Uid [#]: 1001 +Gid [# or name]: 1001 +Change [month day year]: +Expire [month day year]: +Class: +Home directory: /home/jru +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information:</screen> + </example> + + <para>A user can change only a small subset of this + information, and only for their own user account.</para> + + <example> + <title>Interactive <command>chpass</command> by Normal + User</title> + + <screen>#Changing user database information for jru. +Shell: /usr/local/bin/zsh +Full Name: J. Random User +Office Location: +Office Phone: +Home Phone: +Other information:</screen> + </example> + + <note> + <para>&man.chfn.1; and &man.chsh.1; are links to + &man.chpass.1;, as are &man.ypchpass.1;, &man.ypchfn.1;, and + &man.ypchsh.1;. <acronym>NIS</acronym> support is + automatic, so specifying the <literal>yp</literal> before + the command is not necessary. How to configure NIS is + covered in <xref linkend="network-servers"/>.</para> + </note> + </sect2> + <sect2 xml:id="users-passwd"> + <title><command>passwd</command></title> + + <indexterm><primary><command>passwd</command></primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>changing password</secondary> + </indexterm> + <para>&man.passwd.1; is the usual way to change your own + password as a user, or another user's password as the + superuser.</para> + + <note> + <para>To prevent accidental or unauthorized changes, the user + must enter their original password before a new password can + be set. This is not the case when the superuser changes a + user's password.</para> + </note> + + <example> + <title>Changing Your Password</title> + + <screen>&prompt.user; <userinput>passwd</userinput> +Changing local password for jru. +Old password: +New password: +Retype new password: +passwd: updating the database... +passwd: done</screen> + </example> + + <example> + <title>Changing Another User's Password as the + Superuser</title> + + <screen>&prompt.root; <userinput>passwd jru</userinput> +Changing local password for jru. +New password: +Retype new password: +passwd: updating the database... +passwd: done</screen> + </example> + + <note> + <para>As with &man.chpass.1;, &man.yppasswd.1; is a link to + &man.passwd.1;, so NIS works with either command.</para> + </note> + </sect2> + + + <sect2 xml:id="users-pw"> + <title><command>pw</command></title> + + <indexterm><primary><command>pw</command></primary></indexterm> + + <para>&man.pw.8; is a command line utility to create, remove, + modify, and display users and groups. It functions as a front + end to the system user and group files. &man.pw.8; has a very + powerful set of command line options that make it suitable for + use in shell scripts, but new users may find it more + complicated than the other commands presented in this + section.</para> + </sect2> + + + </sect1> + + <sect1 xml:id="users-limiting"> + <title>Limiting Users</title> + + <indexterm><primary>limiting users</primary></indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>limiting</secondary> + </indexterm> + <para>&os; provides several methods for an administrator to limit + the amount of system resources an individual may use. These + limits are discussed in two sections: disk quotas and other + resource limits.</para> + + <indexterm><primary>quotas</primary></indexterm> + <indexterm> + <primary>limiting users</primary> + <secondary>quotas</secondary> + </indexterm> + <indexterm><primary>disk quotas</primary></indexterm> + <para>Disk quotas limit the amount of disk space available to + users and provide a way to quickly check that usage without + calculating it every time. Quotas are discussed in <xref linkend="quotas"/>.</para> + + <para>The other resource limits include ways to limit the amount + of CPU, memory, and other resources a user may consume. These + are defined using login classes and are discussed here.</para> + + <indexterm> + <primary><filename>/etc/login.conf</filename></primary> + </indexterm> + <para>Login classes are defined in + <filename>/etc/login.conf</filename> and are described in detail + in &man.login.conf.5;. Each user account is assigned to a login + class, <literal>default</literal> by default, and each login + class has a set of login capabilities associated with it. A + login capability is a + <literal>name=value</literal> + pair, where <replaceable>name</replaceable> is a well-known + identifier and <replaceable>value</replaceable> is an arbitrary + string which is processed accordingly depending on the + <replaceable>name</replaceable>. Setting up login classes and + capabilities is rather straightforward and is also described in + &man.login.conf.5;.</para> + + <note> + <para>&os; does not normally read the configuration in + <filename>/etc/login.conf</filename> directly, but instead + reads the <filename>/etc/login.conf.db</filename> database + which provides faster lookups. Whenever + <filename>/etc/login.conf</filename> is edited, the + <filename>/etc/login.conf.db</filename> must be updated by + executing the following command:</para> + + <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen> + </note> + + <para>Resource limits differ from the default login capabilities + in two ways. First, for every limit, there is a soft (current) + and hard limit. A soft limit may be adjusted by the user or + application, but may not be set higher than the hard limit. The + hard limit may be lowered by the user, but can only be raised + by the superuser. Second, most resource limits apply per + process to a specific user, not to the user as a whole. These + differences are mandated by the specific handling of the limits, + not by the implementation of the login capability + framework.</para> + + <para>Below are the most commonly used resource limits. The rest + of the limits, along with all the other login capabilities, can + be found in &man.login.conf.5;.</para> + + <variablelist> + <varlistentry> + <term><literal>coredumpsize</literal></term> + + <listitem> + <para>The limit on the size of a core file<indexterm><primary>coredumpsize</primary></indexterm> generated by a + program is subordinate to other limits<indexterm><primary>limiting users</primary><secondary>coredumpsize</secondary></indexterm> on disk usage, such + as <literal>filesize</literal>, or disk quotas. + This limit is often used as a less-severe method of + controlling disk space consumption. Since users do not + generate core files themselves, and often do not delete + them, setting this may save them from running out of disk + space should a large program crash.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>cputime</literal></term> + + <listitem> + <para>The maximum amount of CPU<indexterm><primary>cputime</primary></indexterm><indexterm><primary>limiting users</primary><secondary>cputime</secondary></indexterm> time a user's process may + consume. Offending processes will be killed by the + kernel.</para> + + <note> + <para>This is a limit on CPU <emphasis>time</emphasis> + consumed, not percentage of the CPU as displayed in + some fields by &man.top.1; and &man.ps.1;.</para> + </note> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>filesize</literal></term> + + <listitem> + <para>The maximum size of a file<indexterm><primary>filesize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>filesize</secondary></indexterm> the user may own. Unlike + <link linkend="quotas">disk quotas</link>, this limit is + enforced on individual files, not the set of all files a + user owns.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>maxproc</literal></term> + + <listitem> + <para>The maximum number of processes<indexterm><primary>maxproc</primary></indexterm><indexterm><primary>limiting users</primary><secondary>maxproc</secondary></indexterm> a user can run. This + includes foreground and background processes. This limit + may not be larger than the system limit specified by the + <varname>kern.maxproc</varname> &man.sysctl.8;. Setting + this limit too small may hinder a user's productivity as + it is often useful to be logged in multiple times or to + execute pipelines. Some tasks, such as compiling a large + program, spawn multiple processes and other intermediate + preprocessors.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>memorylocked</literal></term> + + <listitem> + <para>The maximum amount of memory<indexterm><primary>memorylocked</primary></indexterm><indexterm><primary>limiting users</primary><secondary>memorylocked</secondary></indexterm> a process may request + to be locked into main memory using &man.mlock.2;. Some + system-critical programs, such as &man.amd.8;, lock into + main memory so that if the system begins to swap, they do + not contribute to disk thrashing.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>memoryuse</literal></term> + + <listitem> + <para>The maximum amount of memory<indexterm><primary>memoryuse</primary></indexterm><indexterm><primary>limiting users</primary><secondary>memoryuse</secondary></indexterm> a process may consume at + any given time. It includes both core memory and swap + usage. This is not a catch-all limit for restricting + memory consumption, but is a good start.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>openfiles</literal></term> + + <listitem> + <para>The maximum number of files a process may have open<indexterm><primary>openfiles</primary></indexterm><indexterm><primary>limiting users</primary><secondary>openfiles</secondary></indexterm>. + In &os;, files are used to represent sockets and IPC + channels, so be careful not to set this too low. The + system-wide limit for this is defined by the + <varname>kern.maxfiles</varname> &man.sysctl.8;.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>sbsize</literal></term> + + <listitem> + <para>The limit on the amount of network memory, and + thus mbufs<indexterm><primary>sbsize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>sbsize</secondary></indexterm>, a user may consume in order to limit network + communications.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><literal>stacksize</literal></term> + + <listitem> + <para>The maximum size of a process stack<indexterm><primary>stacksize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>stacksize</secondary></indexterm>. This alone is + not sufficient to limit the amount of memory a program + may use so it should be used in conjunction with other + limits.</para> + </listitem> + </varlistentry> + </variablelist> + + <para>There are a few other things to remember when setting + resource limits. Following are some general tips, suggestions, + and miscellaneous comments.</para> + + <itemizedlist> + <listitem> + <para>Processes started at system startup by + <filename>/etc/rc</filename> are assigned to the + <literal>daemon</literal> login class.</para> + </listitem> + + <listitem> + <para>Although the <filename>/etc/login.conf</filename> that + comes with the system is a good source of reasonable values + for most limits, they may not be appropriate for every + system. Setting a limit too high may open the system up to + abuse, while setting it too low may put a strain on + productivity.</para> + </listitem> + + <listitem> + <para>Users of <application>&xorg;</application> should + probably be granted more resources than other users. + <application>&xorg;</application> by itself takes a lot of + resources, but it also encourages users to run more programs + simultaneously.</para> + </listitem> + + <listitem> + <para>Many limits apply to individual processes, not the user + as a whole. For example, setting + <varname>openfiles</varname> to 50 means that each process + the user runs may open up to 50 files. The total amount + of files a user may open is the value of + <literal>openfiles</literal> multiplied by the value of + <literal>maxproc</literal>. This also applies to memory + consumption.</para> + </listitem> + </itemizedlist> + + <para>For further information on resource limits and login classes + and capabilities in general, refer to &man.cap.mkdb.1;, + &man.getrlimit.2;, and &man.login.conf.5;.</para> + </sect1> + + <sect1 xml:id="users-groups"> + <title>Groups</title> + + <indexterm><primary>groups</primary></indexterm> + <indexterm> + <primary><filename>/etc/groups</filename></primary> + </indexterm> + <indexterm> + <primary>accounts</primary> + <secondary>groups</secondary> + </indexterm> + <para>A group is a list of users. A group is identified by its + group name and <acronym>GID</acronym>. In &os;, the + kernel uses the <acronym>UID</acronym> of a process, and the + list of groups it belongs to, to determine what the process is + allowed to do. Most of the time, the <acronym>GID</acronym> of + a user or process usually means the first group in the + list.</para> + + <para>The group name to <acronym>GID</acronym> mapping is listed + in <filename>/etc/group</filename>. This is a plain text file + with four colon-delimited fields. The first field is the group + name, the second is the encrypted password, the third the + <acronym>GID</acronym>, and the fourth the comma-delimited list + of members. For a more complete description of the syntax, + refer to &man.group.5;.</para> + + <para>The superuser can modify <filename>/etc/group</filename> + using a text editor. Alternatively, &man.pw.8; can be used to + add and edit groups. For example, to add a group called + <systemitem class="groupname">teamtwo</systemitem> and then confirm that it + exists:</para> + + <example> + <title>Adding a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:</screen> + </example> + + <para>In this example, <literal>1100</literal> is the + <acronym>GID</acronym> of <systemitem class="groupname">teamtwo</systemitem>. Right + now, <systemitem class="groupname">teamtwo</systemitem> has no members. This + command will add <systemitem class="username">jru</systemitem> as a member of + <systemitem class="groupname">teamtwo</systemitem>.</para> + + <example> + <title>Adding User Accounts to a New Group Using + &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:jru</screen> + </example> + + <para>The argument to <option>-M</option> is a comma-delimited + list of users to be added to a new (empty) group or to replace + the members of an existing group. To the user, this group + membership is different from (and in addition to) the user's + primary group listed in the password file. This means that + the user will not show up as a member when using + <option>groupshow</option> with &man.pw.8;, but will show up + when the information is queried via &man.id.1; or a similar + tool. When &man.pw.8; is used to add a user to a group, it only + manipulates <filename>/etc/group</filename> and does not attempt + to read additional data from + <filename>/etc/passwd</filename>.</para> + + <example> + <title>Adding a New Member to a Group Using &man.pw.8;</title> + + <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput> +&prompt.root; <userinput>pw groupshow teamtwo</userinput> +teamtwo:*:1100:jru,db</screen> + </example> + + <para>In this example, the argument to <option>-m</option> is a + comma-delimited list of users who are to be added to the group. + Unlike the previous example, these users are appended to the + group list and do not replace the list of existing users in the + group.</para> + + <example> + <title>Using &man.id.1; to Determine Group Membership</title> + + <screen>&prompt.user; <userinput>id jru</userinput> +uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen> + </example> + + <para>In this example, <systemitem class="username">jru</systemitem> is a member of the + groups <systemitem class="groupname">jru</systemitem> and + <systemitem class="groupname">teamtwo</systemitem>.</para> + + <para>For more information about this command and the format of + <filename>/etc/group</filename>, refer to &man.pw.8; and + &man.group.5;.</para> + </sect1> + + <sect1 xml:id="users-becomesuper"> + <title>Becoming Superuser</title> + + <para>There are several ways to do things as the superuser. The + worst way is to log in as <systemitem class="username">root</systemitem> directly. + Usually very little activity requires <systemitem class="username">root</systemitem> + so logging off and logging in as <systemitem class="username">root</systemitem>, + performing tasks, then logging off and on again as a normal user + is a waste of time.</para> + + <para>A better way is to use &man.su.1; without providing a login + but using <literal>-</literal> to inherit the root environment. + Not providing a login will imply super user. For this to work + the login that must be in the <systemitem class="groupname">wheel</systemitem> group. + An example of a typical software installation would involve the + administrator unpacking the software as a normal user and then + elevating their privileges for the build and installation of + the software.</para> + + <example> + <title>Install a Program As The Superuser</title> + + <screen>&prompt.user; <userinput>configure</userinput> +&prompt.user; <userinput>make</userinput> +&prompt.user; <userinput>su -</userinput> +Password: +&prompt.root; <userinput>make install</userinput> +&prompt.root; <userinput>exit</userinput> +&prompt.user;</screen> + </example> + + <para>Note in this example the transition to + <systemitem class="username">root</systemitem> is less painful than logging off + and back on twice.</para> + + <para>Using &man.su.1; works well for single systems or small + networks with just one system administrator. For more complex + environments (or even for these simple environments) + <command>sudo</command> should be used. It is provided as a port, + <package>security/sudo</package>. It allows for + things like activity logging, granting users the ability to only + run certain commands as the superuser, and several other + options.</para> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/handbook/vinum/Makefile b/en_US.ISO8859-1/books/handbook/vinum/Makefile new file mode 100644 index 0000000000..b970524581 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/vinum/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= vinum/chapter.xml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/vinum/chapter.xml b/en_US.ISO8859-1/books/handbook/vinum/chapter.xml new file mode 100644 index 0000000000..a18b8491ec --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/vinum/chapter.xml @@ -0,0 +1,1236 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- + The Vinum Volume Manager + By Greg Lehey (grog at lemis dot com) + + Added to the Handbook by Hiten Pandya <hmp@FreeBSD.org> + and Tom Rhodes <trhodes@FreeBSD.org> + + For the FreeBSD Documentation Project + $FreeBSD$ +--> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="vinum-vinum"> + <info><title>The <filename>vinum</filename> Volume Manager</title> + <authorgroup> + <author><personname><firstname>Greg</firstname><surname>Lehey</surname></personname><contrib>Originally written by </contrib></author> + </authorgroup> + </info> + + + + <sect1 xml:id="vinum-synopsis"> + <title>Synopsis</title> + + <para>No matter the type of disks, there are always potential + problems. The disks can be too small, too slow, or too + unreliable to meet the system's requirements. While disks are + getting bigger, so are data storage requirements. Often a file + system is needed that is bigger than a disk's capacity. Various + solutions to these problems have been proposed and + implemented.</para> + + <para>One method is through the use of multiple, and sometimes + redundant, disks. In addition to supporting various cards and + controllers for hardware Redundant Array of Independent + Disks <acronym>RAID</acronym> systems, the base &os; system + includes the <filename>vinum</filename> volume manager, a + block device driver that implements virtual disk drives and + addresses these three problems. <filename>vinum</filename> + provides more flexibility, performance, and reliability than + traditional disk storage and implements + <acronym>RAID</acronym>-0, <acronym>RAID</acronym>-1, and + <acronym>RAID</acronym>-5 models, both individually and in + combination.</para> + + <para>This chapter provides an overview of potential problems with + traditional disk storage, and an introduction to the + <filename>vinum</filename> volume manager.</para> + + <note> + <para>Starting with &os; 5, <filename>vinum</filename> + has been rewritten in order to fit into the <link linkend="GEOM">GEOM architecture</link>, while retaining the + original ideas, terminology, and on-disk metadata. This + rewrite is called <emphasis>gvinum</emphasis> (for <emphasis> + GEOM vinum</emphasis>). While this chapter uses the term + <filename>vinum</filename>, any command invocations should + be performed with <command>gvinum</command>. The name of the + kernel module has changed from the original + <filename>vinum.ko</filename> to + <filename>geom_vinum.ko</filename>, and all device nodes + reside under <filename>/dev/gvinum</filename> instead of + <filename>/dev/vinum</filename>. As of + &os; 6, the original <filename>vinum</filename> + implementation is no longer available in the code base.</para> + </note> + </sect1> + + <sect1 xml:id="vinum-access-bottlenecks"> + <title>Access Bottlenecks</title> + + <para>Modern systems frequently need to access data in a highly + concurrent manner. For example, large FTP or HTTP servers can + maintain thousands of concurrent sessions and have multiple + 100 Mbit/s connections to the outside world, well beyond + the sustained transfer rate of most disks.</para> + + <para>Current disk drives can transfer data sequentially at up to + 70 MB/s, but this value is of little importance in an + environment where many independent processes access a drive, and + where they may achieve only a fraction of these values. In such + cases, it is more interesting to view the problem from the + viewpoint of the disk subsystem. The important parameter is the + load that a transfer places on the subsystem, or the time for + which a transfer occupies the drives involved in the + transfer.</para> + + <para>In any disk transfer, the drive must first position the + heads, wait for the first sector to pass under the read head, + and then perform the transfer. These actions can be considered + to be atomic as it does not make any sense to interrupt + them.</para> + + <para><anchor xml:id="vinum-latency"/> Consider a typical transfer of + about 10 kB: the current generation of high-performance + disks can position the heads in an average of 3.5 ms. The + fastest drives spin at 15,000 rpm, so the average + rotational latency (half a revolution) is 2 ms. At + 70 MB/s, the transfer itself takes about 150 μs, + almost nothing compared to the positioning time. In such a + case, the effective transfer rate drops to a little over + 1 MB/s and is clearly highly dependent on the transfer + size.</para> + + <para>The traditional and obvious solution to this bottleneck is + <quote>more spindles</quote>: rather than using one large disk, + use several smaller disks with the same aggregate storage + space. Each disk is capable of positioning and transferring + independently, so the effective throughput increases by a factor + close to the number of disks used.</para> + + <para>The actual throughput improvement is smaller than the + number of disks involved. Although each drive is capable of + transferring in parallel, there is no way to ensure that the + requests are evenly distributed across the drives. Inevitably + the load on one drive will be higher than on another.</para> + + <indexterm> + <primary>disk concatenation</primary> + </indexterm> + <indexterm> + <primary>Vinum</primary> + <secondary>concatenation</secondary> + </indexterm> + + <para>The evenness of the load on the disks is strongly dependent + on the way the data is shared across the drives. In the + following discussion, it is convenient to think of the disk + storage as a large number of data sectors which are addressable + by number, rather like the pages in a book. The most obvious + method is to divide the virtual disk into groups of consecutive + sectors the size of the individual physical disks and store them + in this manner, rather like taking a large book and tearing it + into smaller sections. This method is called + <emphasis>concatenation</emphasis> and has the advantage that + the disks are not required to have any specific size + relationships. It works well when the access to the virtual + disk is spread evenly about its address space. When access is + concentrated on a smaller area, the improvement is less marked. + <xref linkend="vinum-concat"/> illustrates the sequence in + which storage units are allocated in a concatenated + organization.</para> + + <para> + <figure xml:id="vinum-concat"> + <title>Concatenated Organization</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-concat"/></imageobject></mediaobject> + </figure></para> + + <indexterm> + <primary>disk striping</primary> + </indexterm> + <indexterm> + <primary>Vinum</primary> + <secondary>striping</secondary> + </indexterm> + <indexterm> + <primary><acronym>RAID</acronym></primary> + </indexterm> + + <para>An alternative mapping is to divide the address space into + smaller, equal-sized components and store them sequentially on + different devices. For example, the first 256 sectors may be + stored on the first disk, the next 256 sectors on the next disk + and so on. After filling the last disk, the process repeats + until the disks are full. This mapping is called + <emphasis>striping</emphasis> or + <acronym>RAID-0</acronym>.</para> + + <para><acronym>RAID</acronym> offers various forms of fault + tolerance, though <acronym>RAID-0</acronym> is somewhat + misleading as it provides no redundancy. Striping requires + somewhat more effort to locate the data, and it can cause + additional I/O load where a transfer is spread over multiple + disks, but it can also provide a more constant load across the + disks. <xref linkend="vinum-striped"/> illustrates the + sequence in which storage units are allocated in a striped + organization.</para> + + <para> + <figure xml:id="vinum-striped"> + <title>Striped Organization</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-striped"/></imageobject></mediaobject> + </figure></para> + </sect1> + + <sect1 xml:id="vinum-data-integrity"> + <title>Data Integrity</title> + + <para>The final problem with disks is that they are unreliable. + Although reliability has increased tremendously over the last + few years, disk drives are still the most likely core component + of a server to fail. When they do, the results can be + catastrophic and replacing a failed disk drive and restoring + data can result in server downtime.</para> + + <indexterm> + <primary>disk mirroring</primary> + </indexterm> + <indexterm><primary>vinum</primary> + <secondary>mirroring</secondary> + </indexterm> + <indexterm><primary><acronym>RAID</acronym>-1</primary> + </indexterm> + + <para>One approach to this problem is + <emphasis>mirroring</emphasis>, or + <acronym>RAID-1</acronym>, which keeps two copies of the + data on different physical hardware. Any write to the volume + writes to both disks; a read can be satisfied from either, so if + one drive fails, the data is still available on the other + drive.</para> + + <para>Mirroring has two problems:</para> + + <itemizedlist> + <listitem> + <para>It requires twice as much disk storage as a + non-redundant solution.</para> + </listitem> + + <listitem> + <para>Writes must be performed to both drives, so they take up + twice the bandwidth of a non-mirrored volume. Reads do not + suffer from a performance penalty and can even be + faster.</para> + </listitem> + </itemizedlist> + + <indexterm><primary><acronym>RAID</acronym>-5</primary></indexterm> + + <para>An alternative solution is <emphasis>parity</emphasis>, + implemented in <acronym>RAID</acronym> levels 2, 3, 4 and 5. + Of these, <acronym>RAID-5</acronym> is the most interesting. As + implemented in <filename>vinum</filename>, it is a variant + on a striped organization which dedicates one block of each + stripe to parity one of the other blocks. As implemented by + <filename>vinum</filename>, a + <acronym>RAID-5</acronym> plex is similar to a striped plex, + except that it implements <acronym>RAID-5</acronym> by + including a parity block in each stripe. As required by + <acronym>RAID-5</acronym>, the location of this parity block + changes from one stripe to the next. The numbers in the data + blocks indicate the relative block numbers.</para> + + <para> + <figure xml:id="vinum-raid5-org"> + <title><acronym>RAID</acronym>-5 Organization</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-raid5-org"/></imageobject></mediaobject> + </figure></para> + + <para>Compared to mirroring, <acronym>RAID-5</acronym> has the + advantage of requiring significantly less storage space. Read + access is similar to that of striped organizations, but write + access is significantly slower, approximately 25% of the read + performance. If one drive fails, the array can continue to + operate in degraded mode where a read from one of the remaining + accessible drives continues normally, but a read from the + failed drive is recalculated from the corresponding block from + all the remaining drives.</para> + </sect1> + + <sect1 xml:id="vinum-objects"> + <title><filename>vinum</filename> Objects</title> + + <para>In order to address these problems, + <filename>vinum</filename> implements a four-level hierarchy + of objects:</para> + + <itemizedlist> + <listitem> + <para>The most visible object is the virtual disk, called a + <emphasis>volume</emphasis>. Volumes have essentially the + same properties as a &unix; disk drive, though there are + some minor differences. For one, they have no size + limitations.</para> + </listitem> + + <listitem> + <para>Volumes are composed of <emphasis>plexes</emphasis>, + each of which represent the total address space of a + volume. This level in the hierarchy provides redundancy. + Think of plexes as individual disks in a mirrored array, + each containing the same data.</para> + </listitem> + + <listitem> + <para>Since <filename>vinum</filename> exists within the + &unix; disk storage framework, it would be possible to use + &unix; partitions as the building block for multi-disk + plexes. In fact, this turns out to be too inflexible as + &unix; disks can have only a limited number of partitions. + Instead, <filename>vinum</filename> subdivides a single + &unix; partition, the <emphasis>drive</emphasis>, into + contiguous areas called <emphasis>subdisks</emphasis>, which + are used as building blocks for plexes.</para> + </listitem> + + <listitem> + <para>Subdisks reside on <filename>vinum</filename> + <emphasis>drives</emphasis>, currently &unix; partitions. + <filename>vinum</filename> drives can contain any + number of subdisks. With the exception of a small area at + the beginning of the drive, which is used for storing + configuration and state information, the entire drive is + available for data storage.</para> + </listitem> + </itemizedlist> + + <para>The following sections describe the way these objects + provide the functionality required of + <filename>vinum</filename>.</para> + + <sect2> + <title>Volume Size Considerations</title> + + <para>Plexes can include multiple subdisks spread over all + drives in the <filename>vinum</filename> configuration. + As a result, the size of an individual drive does not limit + the size of a plex or a volume.</para> + </sect2> + + <sect2> + <title>Redundant Data Storage</title> + + <para><filename>vinum</filename> implements mirroring by + attaching multiple plexes to a volume. Each plex is a + representation of the data in a volume. A volume may contain + between one and eight plexes.</para> + + <para>Although a plex represents the complete data of a volume, + it is possible for parts of the representation to be + physically missing, either by design (by not defining a + subdisk for parts of the plex) or by accident (as a result of + the failure of a drive). As long as at least one plex can + provide the data for the complete address range of the volume, + the volume is fully functional.</para> + </sect2> + + <sect2> + <title>Which Plex Organization?</title> + + <para><filename>vinum</filename> implements both + concatenation and striping at the plex level:</para> + + <itemizedlist> + <listitem> + <para>A <emphasis>concatenated plex</emphasis> uses the + address space of each subdisk in turn. Concatenated + plexes are the most flexible as they can contain any + number of subdisks, and the subdisks may be of different + length. The plex may be extended by adding additional + subdisks. They require less <acronym>CPU</acronym> + time than striped plexes, though the difference in + <acronym>CPU</acronym> overhead is not measurable. On + the other hand, they are most susceptible to hot spots, + where one disk is very active and others are idle.</para> + </listitem> + + <listitem> + <para>A <emphasis>striped plex</emphasis> stripes the data + across each subdisk. The subdisks must all be the same + size and there must be at least two subdisks in order to + distinguish it from a concatenated plex. The greatest + advantage of striped plexes is that they reduce hot spots. + By choosing an optimum sized stripe, about 256 kB, + the load can be evened out on the component drives. + Extending a plex by adding new subdisks is so complicated + that <filename>vinum</filename> does not implement + it.</para> + </listitem> + </itemizedlist> + + <para><xref linkend="vinum-comparison"/> summarizes the + advantages and disadvantages of each plex organization.</para> + + <table xml:id="vinum-comparison" frame="none"> + <title><filename>vinum</filename> Plex + Organizations</title> + + <tgroup cols="5"> + <thead> + <row> + <entry>Plex type</entry> + <entry>Minimum subdisks</entry> + <entry>Can add subdisks</entry> + <entry>Must be equal size</entry> + <entry>Application</entry> + </row> + </thead> + + <tbody> + <row> + <entry>concatenated</entry> + <entry>1</entry> + <entry>yes</entry> + <entry>no</entry> + <entry>Large data storage with maximum placement + flexibility and moderate performance</entry> + </row> + + <row> + <entry>striped</entry> + <entry>2</entry> + <entry>no</entry> + <entry>yes</entry> + <entry>High performance in combination with highly + concurrent access</entry> + </row> + </tbody> + </tgroup> + </table> + </sect2> + </sect1> + + <sect1 xml:id="vinum-examples"> + <title>Some Examples</title> + + <para><filename>vinum</filename> maintains a + <emphasis>configuration database</emphasis> which describes the + objects known to an individual system. Initially, the user + creates the configuration database from one or more + configuration files using &man.gvinum.8;. + <filename>vinum</filename> stores a copy of its + configuration database on each disk + <emphasis>device</emphasis> under its control. This database is + updated on each state change, so that a restart accurately + restores the state of each + <filename>vinum</filename> object.</para> + + <sect2> + <title>The Configuration File</title> + + <para>The configuration file describes individual + <filename>vinum</filename> objects. The definition of a + simple volume might be:</para> + + <programlisting> drive a device /dev/da3h + volume myvol + plex org concat + sd length 512m drive a</programlisting> + + <para>This file describes four <filename>vinum</filename> + objects:</para> + + <itemizedlist> + <listitem> + <para>The <emphasis>drive</emphasis> line describes a disk + partition (<emphasis>drive</emphasis>) and its location + relative to the underlying hardware. It is given the + symbolic name <emphasis>a</emphasis>. This separation of + symbolic names from device names allows disks to be moved + from one location to another without confusion.</para> + </listitem> + + <listitem> + <para>The <emphasis>volume</emphasis> line describes a + volume. The only required attribute is the name, in this + case <emphasis>myvol</emphasis>.</para> + </listitem> + + <listitem> + <para>The <emphasis>plex</emphasis> line defines a plex. + The only required parameter is the organization, in this + case <emphasis>concat</emphasis>. No name is necessary as + the system automatically generates a name from the volume + name by adding the suffix + <emphasis>.p</emphasis><emphasis>x</emphasis>, where + <emphasis>x</emphasis> is the number of the plex in the + volume. Thus this plex will be called + <emphasis>myvol.p0</emphasis>.</para> + </listitem> + + <listitem> + <para>The <emphasis>sd</emphasis> line describes a subdisk. + The minimum specifications are the name of a drive on + which to store it, and the length of the subdisk. No name + is necessary as the system automatically assigns names + derived from the plex name by adding the suffix + <emphasis>.s</emphasis><emphasis>x</emphasis>, where + <emphasis>x</emphasis> is the number of the subdisk in + the plex. Thus <filename>vinum</filename> gives this + subdisk the name <emphasis>myvol.p0.s0</emphasis>.</para> + </listitem> + </itemizedlist> + + <para>After processing this file, &man.gvinum.8; produces the + following output:</para> + + <programlisting width="97"> + &prompt.root; gvinum -> <userinput>create config1</userinput> + Configuration summary + Drives: 1 (4 configured) + Volumes: 1 (4 configured) + Plexes: 1 (8 configured) + Subdisks: 1 (16 configured) + + D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%) + + V myvol State: up Plexes: 1 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting> + + <para>This output shows the brief listing format of + &man.gvinum.8;. It is represented graphically in <xref linkend="vinum-simple-vol"/>.</para> + + <para> + <figure xml:id="vinum-simple-vol"> + <title>A Simple <filename>vinum</filename> + Volume</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-simple-vol"/></imageobject></mediaobject> + </figure></para> + + <para>This figure, and the ones which follow, represent a + volume, which contains the plexes, which in turn contains the + subdisks. In this example, the volume contains one plex, and + the plex contains one subdisk.</para> + + <para>This particular volume has no specific advantage over a + conventional disk partition. It contains a single plex, so it + is not redundant. The plex contains a single subdisk, so + there is no difference in storage allocation from a + conventional disk partition. The following sections + illustrate various more interesting configuration + methods.</para> + </sect2> + + <sect2> + <title>Increased Resilience: Mirroring</title> + + <para>The resilience of a volume can be increased by mirroring. + When laying out a mirrored volume, it is important to ensure + that the subdisks of each plex are on different drives, so + that a drive failure will not take down both plexes. The + following configuration mirrors a volume:</para> + + <programlisting> drive b device /dev/da4h + volume mirror + plex org concat + sd length 512m drive a + plex org concat + sd length 512m drive b</programlisting> + + <para>In this example, it was not necessary to specify a + definition of drive <emphasis>a</emphasis> again, since + <filename>vinum</filename> keeps track of all objects in + its configuration database. After processing this definition, + the configuration looks like:</para> + + <programlisting width="97"> + Drives: 2 (4 configured) + Volumes: 2 (4 configured) + Plexes: 3 (8 configured) + Subdisks: 3 (16 configured) + + D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%) + D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%) + + V myvol State: up Plexes: 1 Size: 512 MB + V mirror State: up Plexes: 2 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB</programlisting> + + <para><xref linkend="vinum-mirrored-vol"/> shows the + structure graphically.</para> + + <para> + <figure xml:id="vinum-mirrored-vol"> + <title>A Mirrored <filename>vinum</filename> + Volume</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-mirrored-vol"/></imageobject></mediaobject> + </figure></para> + + <para>In this example, each plex contains the full 512 MB + of address space. As in the previous example, each plex + contains only a single subdisk.</para> + </sect2> + + <sect2> + <title>Optimizing Performance</title> + + <para>The mirrored volume in the previous example is more + resistant to failure than an unmirrored volume, but its + performance is less as each write to the volume requires a + write to both drives, using up a greater proportion of the + total disk bandwidth. Performance considerations demand a + different approach: instead of mirroring, the data is striped + across as many disk drives as possible. The following + configuration shows a volume with a plex striped across four + disk drives:</para> + + <programlisting> drive c device /dev/da5h + drive d device /dev/da6h + volume stripe + plex org striped 512k + sd length 128m drive a + sd length 128m drive b + sd length 128m drive c + sd length 128m drive d</programlisting> + + <para>As before, it is not necessary to define the drives which + are already known to <filename>vinum</filename>. After + processing this definition, the configuration looks + like:</para> + + <programlisting width="92"> + Drives: 4 (4 configured) + Volumes: 3 (4 configured) + Plexes: 4 (8 configured) + Subdisks: 7 (16 configured) + + D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%) + D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%) + D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%) + D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%) + + V myvol State: up Plexes: 1 Size: 512 MB + V mirror State: up Plexes: 2 Size: 512 MB + V striped State: up Plexes: 1 Size: 512 MB + + P myvol.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p0 C State: up Subdisks: 1 Size: 512 MB + P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB + P striped.p1 State: up Subdisks: 1 Size: 512 MB + + S myvol.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p0.s0 State: up PO: 0 B Size: 512 MB + S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB + S striped.p0.s0 State: up PO: 0 B Size: 128 MB + S striped.p0.s1 State: up PO: 512 kB Size: 128 MB + S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB + S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB</programlisting> + + <para> + <figure xml:id="vinum-striped-vol"> + <title>A Striped <filename>vinum</filename> + Volume</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-striped-vol"/></imageobject></mediaobject> + </figure></para> + + <para>This volume is represented in <xref linkend="vinum-striped-vol"/>. The darkness of the + stripes indicates the position within the plex address space, + where the lightest stripes come first and the darkest + last.</para> + </sect2> + + <sect2> + <title>Resilience and Performance</title> + + <para><anchor xml:id="vinum-resilience"/>With sufficient hardware, + it is possible to build volumes which show both increased + resilience and increased performance compared to standard + &unix; partitions. A typical configuration file might + be:</para> + + <programlisting> volume raid10 + plex org striped 512k + sd length 102480k drive a + sd length 102480k drive b + sd length 102480k drive c + sd length 102480k drive d + sd length 102480k drive e + plex org striped 512k + sd length 102480k drive c + sd length 102480k drive d + sd length 102480k drive e + sd length 102480k drive a + sd length 102480k drive b</programlisting> + + <para>The subdisks of the second plex are offset by two drives + from those of the first plex. This helps to ensure that + writes do not go to the same subdisks even if a transfer goes + over two drives.</para> + + <para><xref linkend="vinum-raid10-vol"/> represents the + structure of this volume.</para> + + <para> + <figure xml:id="vinum-raid10-vol"> + <title>A Mirrored, Striped <filename>vinum</filename> + Volume</title> + + <mediaobject><imageobject><imagedata fileref="vinum/vinum-raid10-vol"/></imageobject></mediaobject> + </figure></para> + </sect2> + </sect1> + + <sect1 xml:id="vinum-object-naming"> + <title>Object Naming</title> + + <para><filename>vinum</filename> assigns default names to + plexes and subdisks, although they may be overridden. + Overriding the default names is not recommended as it does not + bring a significant advantage and it can cause + confusion.</para> + + <para>Names may contain any non-blank character, but it is + recommended to restrict them to letters, digits and the + underscore characters. The names of volumes, plexes, and + subdisks may be up to 64 characters long, and the names of + drives may be up to 32 characters long.</para> + + <para><filename>vinum</filename> objects are assigned device + nodes in the hierarchy <filename>/dev/gvinum</filename>. The configuration + shown above would cause <filename>vinum</filename> to create + the following device nodes:</para> + + <itemizedlist> + <listitem> + <para>Device entries for each volume. These are the main + devices used by <filename>vinum</filename>. The + configuration above would include the devices + <filename>/dev/gvinum/myvol</filename>, + <filename>/dev/gvinum/mirror</filename>, + <filename>/dev/gvinum/striped</filename>, + <filename>/dev/gvinum/raid5</filename> + and <filename>/dev/gvinum/raid10</filename>.</para> + </listitem> + + <listitem> + <para>All volumes get direct entries under + <filename>/dev/gvinum/</filename>.</para> + </listitem> + + <listitem> + <para>The directories + <filename>/dev/gvinum/plex</filename>, and + <filename>/dev/gvinum/sd</filename>, which + contain device nodes for each plex and for each subdisk, + respectively.</para> + </listitem> + </itemizedlist> + + <para>For example, consider the following configuration + file:</para> + + <programlisting> drive drive1 device /dev/sd1h + drive drive2 device /dev/sd2h + drive drive3 device /dev/sd3h + drive drive4 device /dev/sd4h + volume s64 setupstate + plex org striped 64k + sd length 100m drive drive1 + sd length 100m drive drive2 + sd length 100m drive drive3 + sd length 100m drive drive4</programlisting> + + <para>After processing this file, &man.gvinum.8; creates the + following structure in <filename>/dev/gvinum</filename>:</para> + + <programlisting> drwxr-xr-x 2 root wheel 512 Apr 13 +16:46 plex + crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64 + drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd + + /dev/vinum/plex: + total 0 + crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0 + + /dev/vinum/sd: + total 0 + crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0 + crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1 + crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2 + crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting> + + <para>Although it is recommended that plexes and subdisks should + not be allocated specific names, + <filename>vinum</filename> drives must be named. This makes + it possible to move a drive to a different location and still + recognize it automatically. Drive names may be up to 32 + characters long.</para> + + <sect2> + <title>Creating File Systems</title> + + <para>Volumes appear to the system to be identical to disks, + with one exception. Unlike &unix; drives, + <filename>vinum</filename> does not partition volumes, + which thus do not contain a partition table. This has + required modification to some disk utilities, notably + &man.newfs.8;, so that it does not try to interpret the last + letter of a <filename>vinum</filename> volume name as a + partition identifier. For example, a disk drive may have a + name like <filename>/dev/ad0a</filename> + or <filename>/dev/da2h</filename>. These + names represent the first partition + (<filename>a</filename>) on the first (0) IDE disk + (<filename>ad</filename>) and the eighth partition + (<filename>h</filename>) on the third (2) SCSI disk + (<filename>da</filename>) respectively. By contrast, a + <filename>vinum</filename> volume might be called + <filename>/dev/gvinum/concat</filename>, + which has no relationship with a partition name.</para> + + <para>In order to create a file system on this volume, use + &man.newfs.8;:</para> + + <screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput></screen> + </sect2> + </sect1> + + <sect1 xml:id="vinum-config"> + <title>Configuring <filename>vinum</filename></title> + + <para>The <filename>GENERIC</filename> kernel does not contain + <filename>vinum</filename>. It is possible to build a + custom kernel which includes <filename>vinum</filename>, but + this is not recommended. The standard way to start + <filename>vinum</filename> is as a kernel module. + &man.kldload.8; is not needed because when &man.gvinum.8; + starts, it checks whether the module has been loaded, and if it + is not, it loads it automatically.</para> + + + <sect2> + <title>Startup</title> + + <para><filename>vinum</filename> stores configuration + information on the disk slices in essentially the same form as + in the configuration files. When reading from the + configuration database, <filename>vinum</filename> + recognizes a number of keywords which are not allowed in the + configuration files. For example, a disk configuration might + contain the following text:</para> + + <programlisting width="119">volume myvol state up +volume bigraid state down +plex name myvol.p0 state up org concat vol myvol +plex name myvol.p1 state up org concat vol myvol +plex name myvol.p2 state init org striped 512b vol myvol +plex name bigraid.p0 state initializing org raid5 512b vol bigraid +sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b +sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b +sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b +sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b +sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b +sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b +sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b +sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b +sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b +sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b +sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b +sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b +sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b</programlisting> + + <para>The obvious differences here are the presence of + explicit location information and naming, both of which are + allowed but discouraged, and the information on the states. + <filename>vinum</filename> does not store information + about drives in the configuration information. It finds the + drives by scanning the configured disk drives for partitions + with a <filename>vinum</filename> label. This enables + <filename>vinum</filename> to identify drives correctly + even if they have been assigned different &unix; drive + IDs.</para> + + <sect3 xml:id="vinum-rc-startup"> + <title>Automatic Startup</title> + + <para><emphasis>Gvinum</emphasis> always features an + automatic startup once the kernel module is loaded, via + &man.loader.conf.5;. To load the + <emphasis>Gvinum</emphasis> module at boot time, add + <literal>geom_vinum_load="YES"</literal> to + <filename>/boot/loader.conf</filename>.</para> + + <para>When <filename>vinum</filename> is started with + <command>gvinum start</command>, + <filename>vinum</filename> reads the configuration + database from one of the <filename>vinum</filename> + drives. Under normal circumstances, each drive contains + an identical copy of the configuration database, so it + does not matter which drive is read. After a crash, + however, <filename>vinum</filename> must determine + which drive was updated most recently and read the + configuration from this drive. It then updates the + configuration, if necessary, from progressively older + drives.</para> + </sect3> + </sect2> + </sect1> + + <sect1 xml:id="vinum-root"> + <title>Using <filename>vinum</filename> for the Root + File System</title> + + <para>For a machine that has fully-mirrored file systems using + <filename>vinum</filename>, it is desirable to also + mirror the root file system. Setting up such a configuration + is less trivial than mirroring an arbitrary file system + because:</para> + + <itemizedlist> + <listitem> + <para>The root file system must be available very early + during the boot process, so the + <filename>vinum</filename> infrastructure must + already be available at this time.</para> + </listitem> + <listitem> + <para>The volume containing the root file system also + contains the system bootstrap and the kernel. These must + be read using the host system's native utilities, such as + the BIOS, which often cannot be taught about the details + of <filename>vinum</filename>.</para> + </listitem> + </itemizedlist> + + <para>In the following sections, the term <quote>root + volume</quote> is generally used to describe the + <filename>vinum</filename> volume that contains the root + file system.</para> + + <sect2> + <title>Starting up <filename>vinum</filename> Early + Enough for the Root File System</title> + + <para><filename>vinum</filename> must be available early + in the system boot as &man.loader.8; must be able to load + the vinum kernel module before starting the kernel. This + can be accomplished by putting this line in + <filename>/boot/loader.conf</filename>:</para> + + <programlisting>geom_vinum_load="YES"</programlisting> + + </sect2> + + <sect2> + <title>Making a <filename>vinum</filename>-based Root + Volume Accessible to the Bootstrap</title> + + <para>The current &os; bootstrap is only 7.5 KB of code and + does not understand the internal + <filename>vinum</filename> structures. This means that it + cannot parse the <filename>vinum</filename> configuration + data or figure out the elements of a boot volume. Thus, some + workarounds are necessary to provide the bootstrap code with + the illusion of a standard <literal>a</literal> partition + that contains the root file system.</para> + + <para>For this to be possible, the following requirements must + be met for the root volume:</para> + + <itemizedlist> + <listitem> + <para>The root volume must not be a stripe or + <acronym>RAID</acronym>-5.</para> + </listitem> + + <listitem> + <para>The root volume must not contain more than one + concatenated subdisk per plex.</para> + </listitem> + </itemizedlist> + + <para>Note that it is desirable and possible to use multiple + plexes, each containing one replica of the root file system. + The bootstrap process will only use one replica for finding + the bootstrap and all boot files, until the kernel mounts the + root file system. Each single subdisk within these plexes + needs its own <literal>a</literal> partition illusion, for + the respective device to be bootable. It is not strictly + needed that each of these faked <literal>a</literal> + partitions is located at the same offset within its device, + compared with other devices containing plexes of the root + volume. However, it is probably a good idea to create the + <filename>vinum</filename> volumes that way so the + resulting mirrored devices are symmetric, to avoid + confusion.</para> + + <para>In order to set up these <literal>a</literal> + partitions for each device containing part of the root + volume, the following is required:</para> + + <procedure> + <step> + <para>The location, offset from the beginning of the device, + and size of this device's subdisk that is part of the root + volume needs to be examined, using the command:</para> + + <screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen> + + <para><filename>vinum</filename> offsets and sizes are + measured in bytes. They must be divided by 512 in order + to obtain the block numbers that are to be used by + <command>bsdlabel</command>.</para> + </step> + + <step> + <para>Run this command for each device that participates in + the root volume:</para> + + <screen>&prompt.root; <userinput>bsdlabel -e devname</userinput></screen> + + <para><replaceable>devname</replaceable> must be either the + name of the disk, like <filename>da0</filename> for + disks without a slice table, or the name of the + slice, like <filename>ad0s1</filename>.</para> + + <para>If there is already an <literal>a</literal> + partition on the device from a + pre-<filename>vinum</filename> root file system, it + should be renamed to something else so that it remains + accessible (just in case), but will no longer be used by + default to bootstrap the system. A currently mounted root + file system cannot be renamed, so this must be executed + either when being booted from a <quote>Fixit</quote> + media, or in a two-step process where, in a mirror, the + disk that is not been currently booted is manipulated + first.</para> + + <para>The offset of the <filename>vinum</filename> + partition on this device (if any) must be added to the + offset of the respective root volume subdisk on this + device. The resulting value will become the + <literal>offset</literal> value for the new + <literal>a</literal> partition. The + <literal>size</literal> value for this partition can be + taken verbatim from the calculation above. The + <literal>fstype</literal> should be + <literal>4.2BSD</literal>. The + <literal>fsize</literal>, <literal>bsize</literal>, + and <literal>cpg</literal> values should be chosen + to match the actual file system, though they are fairly + unimportant within this context.</para> + + <para>That way, a new <literal>a</literal> partition will + be established that overlaps the + <filename>vinum</filename> partition on this device. + <command>bsdlabel</command> will only allow for this + overlap if the <filename>vinum</filename> partition + has properly been marked using the + <literal>vinum</literal> fstype.</para> + </step> + + <step> + <para>A faked <literal>a</literal> partition now exists + on each device that has one replica of the root volume. + It is highly recommendable to verify the result using a + command like:</para> + + <screen>&prompt.root; <userinput>fsck -n /dev/devnamea</userinput></screen> + </step> + </procedure> + + <para>It should be remembered that all files containing control + information must be relative to the root file system in the + <filename>vinum</filename> volume which, when setting up + a new <filename>vinum</filename> root volume, might not + match the root file system that is currently active. So in + particular, <filename>/etc/fstab</filename> and + <filename>/boot/loader.conf</filename> need to be taken care + of.</para> + + <para>At next reboot, the bootstrap should figure out the + appropriate control information from the new + <filename>vinum</filename>-based root file system, and act + accordingly. At the end of the kernel initialization process, + after all devices have been announced, the prominent notice + that shows the success of this setup is a message like:</para> + + <screen>Mounting root from ufs:/dev/gvinum/root</screen> + </sect2> + + <sect2> + <title>Example of a <filename>vinum</filename>-based Root + Setup</title> + + <para>After the <filename>vinum</filename> root volume has + been set up, the output of <command>gvinum l -rv + root</command> could look like:</para> + + <screen>... +Subdisk root.p0.s0: + Size: 125829120 bytes (120 MB) + State: up + Plex root.p0 at offset 0 (0 B) + Drive disk0 (/dev/da0h) at offset 135680 (132 kB) + +Subdisk root.p1.s0: + Size: 125829120 bytes (120 MB) + State: up + Plex root.p1 at offset 0 (0 B) + Drive disk1 (/dev/da1h) at offset 135680 (132 kB)</screen> + + <para>The values to note are <literal>135680</literal> for the + offset, relative to partition + <filename>/dev/da0h</filename>. This + translates to 265 512-byte disk blocks in + <command>bsdlabel</command>'s terms. Likewise, the size of + this root volume is 245760 512-byte blocks. <filename>/dev/da1h</filename>, containing the + second replica of this root volume, has a symmetric + setup.</para> + + <para>The bsdlabel for these devices might look like:</para> + + <screen>... +8 partitions: +# size offset fstype [fsize bsize bps/cpg] + a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*) + c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*) + h: 71771672 16 vinum # (Cyl. 0*- 4467*)</screen> + + <para>It can be observed that the <literal>size</literal> + parameter for the faked <literal>a</literal> partition + matches the value outlined above, while the + <literal>offset</literal> parameter is the sum of the offset + within the <filename>vinum</filename> partition + <literal>h</literal>, and the offset of this partition + within the device or slice. This is a typical setup that is + necessary to avoid the problem described in <xref linkend="vinum-root-panic"/>. The entire + <literal>a</literal> partition is completely within the + <literal>h</literal> partition containing all the + <filename>vinum</filename> data for this device.</para> + + <para>In the above example, the entire device is dedicated to + <filename>vinum</filename> and there is no leftover + pre-<filename>vinum</filename> root partition.</para> + </sect2> + + <sect2> + <title>Troubleshooting</title> + + <para>The following list contains a few known pitfalls and + solutions.</para> + + <sect3> + <title>System Bootstrap Loads, but System Does Not + Boot</title> + + <para>If for any reason the system does not continue to boot, + the bootstrap can be interrupted by pressing + <keycap>space</keycap> at the 10-seconds warning. The + loader variable <literal>vinum.autostart</literal> can be + examined by typing <command>show</command> and manipulated + using <command>set</command> or + <command>unset</command>.</para> + + <para>If the <filename>vinum</filename> kernel module was + not yet in the list of modules to load automatically, type + <command>load geom_vinum</command>.</para> + + <para>When ready, the boot process can be continued by typing + <command>boot -as</command> which + <option>-as</option> requests the kernel to ask for the + root file system to mount (<option>-a</option>) and make the + boot process stop in single-user mode (<option>-s</option>), + where the root file system is mounted read-only. That way, + even if only one plex of a multi-plex volume has been + mounted, no data inconsistency between plexes is being + risked.</para> + + <para>At the prompt asking for a root file system to mount, + any device that contains a valid root file system can be + entered. If <filename>/etc/fstab</filename> is set up + correctly, the default should be something like + <literal>ufs:/dev/gvinum/root</literal>. A typical + alternate choice would be something like + <literal>ufs:da0d</literal> which could be a + hypothetical partition containing the + pre-<filename>vinum</filename> root file system. Care + should be taken if one of the alias + <literal>a</literal> partitions is entered here, that it + actually references the subdisks of the + <filename>vinum</filename> root device, because in a + mirrored setup, this would only mount one piece of a + mirrored root device. If this file system is to be mounted + read-write later on, it is necessary to remove the other + plex(es) of the <filename>vinum</filename> root volume + since these plexes would otherwise carry inconsistent + data.</para> + </sect3> + + <sect3> + <title>Only Primary Bootstrap Loads</title> + + <para>If <filename>/boot/loader</filename> fails to load, but + the primary bootstrap still loads (visible by a single dash + in the left column of the screen right after the boot + process starts), an attempt can be made to interrupt the + primary bootstrap by pressing + <keycap>space</keycap>. This will make the bootstrap stop + in <link linkend="boot-boot1">stage two</link>. An attempt + can be made here to boot off an alternate partition, like + the partition containing the previous root file system that + has been moved away from <literal>a</literal>.</para> + </sect3> + + <sect3 xml:id="vinum-root-panic"> + <title>Nothing Boots, the Bootstrap + Panics</title> + + <para>This situation will happen if the bootstrap had been + destroyed by the <filename>vinum</filename> + installation. Unfortunately, <filename>vinum</filename> + accidentally leaves only 4 KB at the beginning of its + partition free before starting to write its + <filename>vinum</filename> header information. However, + the stage one and two bootstraps plus the bsdlabel require 8 + KB. So if a <filename>vinum</filename> partition was + started at offset 0 within a slice or disk that was meant to + be bootable, the <filename>vinum</filename> setup will + trash the bootstrap.</para> + + <para>Similarly, if the above situation has been recovered, + by booting from a <quote>Fixit</quote> media, and the + bootstrap has been re-installed using + <command>bsdlabel -B</command> as described in <xref linkend="boot-boot1"/>, the bootstrap will trash the + <filename>vinum</filename> header, and + <filename>vinum</filename> will no longer find its + disk(s). Though no actual <filename>vinum</filename> + configuration data or data in <filename>vinum</filename> + volumes will be trashed, and it would be possible to recover + all the data by entering exactly the same + <filename>vinum</filename> configuration data again, the + situation is hard to fix. It is necessary to move the + entire <filename>vinum</filename> partition by at least + 4 KB, in order to have the <filename>vinum</filename> + header and the system bootstrap no longer collide.</para> + </sect3> + </sect2> + </sect1> +</chapter> diff --git a/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml b/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml index 10cf700741..a8db6aecd5 100644 --- a/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/virtualization/chapter.xml @@ -4,22 +4,17 @@ $FreeBSD$ --> - -<chapter id="virtualization"> - <chapterinfo> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="virtualization"> + <info><title>Virtualization</title> <authorgroup> - <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Contributed by </contrib> - </author> + <author><personname><firstname>Murray</firstname><surname>Stokely</surname></personname><contrib>Contributed by </contrib></author> </authorgroup> - <!-- Mar 2007 --> - </chapterinfo> + + </info> - <title>Virtualization</title> + - <sect1 id="virtualization-synopsis"> + <sect1 xml:id="virtualization-synopsis"> <title>Synopsis</title> <para>Virtualization software allows multiple operating systems @@ -87,10 +82,10 @@ </itemizedlist> </sect1> - <sect1 id="virtualization-guest"> + <sect1 xml:id="virtualization-guest"> <title>&os; as a Guest OS</title> - <sect2 id="virtualization-guest-parallels"> + <sect2 xml:id="virtualization-guest-parallels"> <title><application>Parallels</application> on &macos; X</title> <para><application>Parallels Desktop</application> for &mac; is @@ -101,7 +96,7 @@ &macos; X, the user must configure a virtual machine and then install the desired guest operating system.</para> - <sect3 id="virtualization-guest-parallels-install"> + <sect3 xml:id="virtualization-guest-parallels-install"> <title>Installing &os; on Parallels/&macos; X</title> <para>The first step in installing &os; on @@ -223,7 +218,7 @@ </mediaobject> </sect3> - <sect3 id="virtualization-guest-parallels-configure"> + <sect3 xml:id="virtualization-guest-parallels-configure"> <title>Configuring &os; on <application>Parallels</application> </title> @@ -270,8 +265,7 @@ the host &mac;. This can be accomplished by adding <literal>ifconfig_ed0="DHCP"</literal> to <filename>/etc/rc.conf</filename>. More advanced - networking setups are described in <xref - linkend="advanced-networking"/>.</para> + networking setups are described in <xref linkend="advanced-networking"/>.</para> </step> </procedure> </sect3> @@ -586,20 +580,19 @@ xenbr1 8000.feffffffffff no vif0.1 </sect3> </sect2> --> - <sect2 id="virtualization-guest-virtualpc"> + <sect2 xml:id="virtualization-guest-virtualpc"> <title><application>Virtual PC</application> on &windows;</title> <para><application>Virtual PC</application> for &windows; is a µsoft; software product available for free download. - See this website for the <ulink - url="http://www.microsoft.com/windows/downloads/virtualpc/sysreq.mspx"> - system requirements</ulink>. Once <application> Virtual PC + See this website for the <link xlink:href="http://www.microsoft.com/windows/downloads/virtualpc/sysreq.mspx"> + system requirements</link>. Once <application> Virtual PC </application> has been installed on µsoft.windows;, the user can configure a virtual machine and then install the desired guest operating system.</para> - <sect3 id="virtualization-guest-virtualpc-install"> + <sect3 xml:id="virtualization-guest-virtualpc-install"> <title>Installing &os; on <application>Virtual PC</application></title> @@ -731,7 +724,7 @@ xenbr1 8000.feffffffffff no vif0.1 </mediaobject> </sect3> - <sect3 id="virtualization-guest-virtualpc-configure"> + <sect3 xml:id="virtualization-guest-virtualpc-configure"> <title>Configuring &os; on <application>Virtual PC</application></title> @@ -780,14 +773,13 @@ xenbr1 8000.feffffffffff no vif0.1 the µsoft.windows; host. This can be accomplished by adding <literal>ifconfig_de0="DHCP"</literal> to <filename>/etc/rc.conf</filename>. More advanced - networking setups are described in <xref - linkend="advanced-networking"/>.</para> + networking setups are described in <xref linkend="advanced-networking"/>.</para> </step> </procedure> </sect3> </sect2> - <sect2 id="virtualization-guest-vmware"> + <sect2 xml:id="virtualization-guest-vmware"> <title><application>VMware Fusion</application> on &macos;</title> @@ -800,7 +792,7 @@ xenbr1 8000.feffffffffff no vif0.1 machine and then install the desired guest operating system.</para> - <sect3 id="virtualization-guest-vmware-install"> + <sect3 xml:id="virtualization-guest-vmware-install"> <title>Installing &os; on <application>VMware Fusion</application></title> @@ -935,7 +927,7 @@ xenbr1 8000.feffffffffff no vif0.1 &os; virtual machine.</para> </sect3> - <sect3 id="virtualization-guest-vmware-configure"> + <sect3 xml:id="virtualization-guest-vmware-configure"> <title>Configuring &os; on <application>VMware Fusion</application></title> @@ -983,14 +975,13 @@ xenbr1 8000.feffffffffff no vif0.1 the host &mac;. This can be accomplished by adding <literal>ifconfig_em0="DHCP"</literal> to <filename>/etc/rc.conf</filename>. More advanced - networking setups are described in <xref - linkend="advanced-networking"/>.</para> + networking setups are described in <xref linkend="advanced-networking"/>.</para> </step> </procedure> </sect3> </sect2> - <sect2 id="virtualization-guest-virtualbox-guest-additions"> + <sect2 xml:id="virtualization-guest-virtualbox-guest-additions"> <title>&virtualbox; Guest Additions on a &os; Guest</title> <para>The <application>&virtualbox;</application> guest @@ -1022,8 +1013,7 @@ xenbr1 8000.feffffffffff no vif0.1 <para>The following commands are run in the &os; guest.</para> </note> - <para>First, install the <filename - role="package">emulators/virtualbox-ose-additions</filename> + <para>First, install the <package>emulators/virtualbox-ose-additions</package> package or port in the &os; guest. This will install the port:</para> @@ -1107,7 +1097,7 @@ EndSection</programlisting> </sect2> </sect1> - <sect1 id="virtualization-host"> + <sect1 xml:id="virtualization-host"> <title>&os; as a Host</title> <para><application>&virtualbox;</application> is an actively @@ -1117,18 +1107,16 @@ EndSection</programlisting> &unix;-like guests. It is released as open source software, but with closed-source components available in a separate extension pack. These components include support for USB 2.0 devices. - More information may be found on the <ulink - url="http://www.virtualbox.org/wiki/Downloads"> + More information may be found on the <link xlink:href="http://www.virtualbox.org/wiki/Downloads"> <quote>Downloads</quote> page of the - <application>&virtualbox;</application> wiki</ulink>. + <application>&virtualbox;</application> wiki</link>. Currently, these extensions are not available for &os;.</para> - <sect2 id="virtualization-virtualbox-install"> + <sect2 xml:id="virtualization-virtualbox-install"> <title>Installing &virtualbox;</title> <para><application>&virtualbox;</application> is available as a - &os; package or port in <filename - role="package">emulators/virtualbox-ose</filename>. The + &os; package or port in <package>emulators/virtualbox-ose</package>. The port can be installed using these commands:</para> <screen>&prompt.root; <userinput>cd /usr/ports/emulators/virtualbox-ose</userinput> @@ -1147,7 +1135,7 @@ EndSection</programlisting> <para>A few configuration changes are needed before <application>&virtualbox;</application> is started for the first time. The port installs a kernel module in - <filename class="directory">/boot/modules</filename> which + <filename>/boot/modules</filename> which must be loaded into the running kernel:</para> <screen>&prompt.root; <userinput>kldload vboxdrv</userinput></screen> @@ -1165,17 +1153,16 @@ EndSection</programlisting> <programlisting>vboxnet_enable="YES"</programlisting> - <para>The <groupname>vboxusers</groupname> group is created + <para>The <systemitem class="groupname">vboxusers</systemitem> group is created during installation of <application>&virtualbox;</application>. All users that need access to <application>&virtualbox;</application> will have to be added as members of this group. <command>pw</command> can be used to add new members:</para> - <screen>&prompt.root; <userinput>pw groupmod vboxusers -m <replaceable>yourusername</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw groupmod vboxusers -m yourusername</userinput></screen> - <para>The default permissions for <filename - class="devicefile">/dev/vboxnetctl</filename> are + <para>The default permissions for <filename>/dev/vboxnetctl</filename> are restrictive and need to be changed for bridged networking:</para> @@ -1195,21 +1182,20 @@ perm vboxnetctl 0660</programlisting> <para>For more information on configuring and using <application>&virtualbox;</application>, refer to the - <ulink url="http://www.virtualbox.org">official - website</ulink>. For &os;-specific information and - troubleshooting instructions, refer to the <ulink - url="http://wiki.FreeBSD.org/VirtualBox">relevant page in - the &os; wiki</ulink>.</para> + <link xlink:href="http://www.virtualbox.org">official + website</link>. For &os;-specific information and + troubleshooting instructions, refer to the <link xlink:href="http://wiki.FreeBSD.org/VirtualBox">relevant page in + the &os; wiki</link>.</para> </sect2> - <sect2 id="virtualization-virtualbox-usb-support"> + <sect2 xml:id="virtualization-virtualbox-usb-support"> <title>&virtualbox; USB Support</title> <para>In order to be able to read and write to USB devices, users need to be members of - <groupname>operator</groupname>:</para> + <systemitem class="groupname">operator</systemitem>:</para> - <screen>&prompt.root; <userinput>pw groupmod operator -m <replaceable>jerry</replaceable></userinput></screen> + <screen>&prompt.root; <userinput>pw groupmod operator -m jerry</userinput></screen> <para>Then, add the following to <filename>/etc/devfs.rules</filename>, or create this file if @@ -1232,7 +1218,7 @@ add path 'usb/*' mode 0660 group operator</programlisting> preferences.</para> </sect2> - <sect2 id="virtualization-virtualbox-host-dvd-cd-access"> + <sect2 xml:id="virtualization-virtualbox-host-dvd-cd-access"> <title>&virtualbox; Host DVD/CD Access</title> <para>Access to the host DVD/CD drives from guests is achieved @@ -1257,13 +1243,10 @@ add path 'usb/*' mode 0660 group operator</programlisting> <para>In order for users to be able to use <application>&virtualbox;</application> DVD/CD functions, they - need access to <filename - class="devicefile">/dev/xpt0</filename>, <filename - class="devicefile">/dev/cd<replaceable>N</replaceable></filename>, - and <filename - class="devicefile">/dev/pass<replaceable>N</replaceable></filename>. + need access to <filename>/dev/xpt0</filename>, <filename>/dev/cdN</filename>, + and <filename>/dev/passN</filename>. This is usually achieved by making the user a member of - <groupname>operator</groupname>. Permissions to these devices + <systemitem class="groupname">operator</systemitem>. Permissions to these devices have to be corrected by adding the following lines to <filename>/etc/devfs.conf</filename>:</para> diff --git a/en_US.ISO8859-1/books/handbook/x11/chapter.xml b/en_US.ISO8859-1/books/handbook/x11/chapter.xml index 5c6147b893..b9697ec5a6 100644 --- a/en_US.ISO8859-1/books/handbook/x11/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/x11/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="x11"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="x11"> <!-- <chapterinfo> <authorgroup> @@ -24,7 +23,7 @@ <title>The X Window System</title> - <sect1 id="x11-synopsis"> + <sect1 xml:id="x11-synopsis"> <title>Synopsis</title> <para>An installation of &os; using @@ -39,14 +38,13 @@ <para>Users who prefer an installation method that automatically configures the <application>&xorg;</application> and offers a choice of window managers during installation should - refer to the <ulink - url="http://www.pcbsd.org/">pcbsd.org</ulink> + refer to the <link xlink:href="http://www.pcbsd.org/">pcbsd.org</link> website.</para> </note> <para>For more information on the video hardware that <application>&xorg;</application> supports, refer to the - <ulink url="http://www.x.org/">x.org</ulink> website.</para> + <link xlink:href="http://www.x.org/">x.org</link> website.</para> <para>After reading this chapter, you will know:</para> @@ -87,7 +85,7 @@ </itemizedlist> </sect1> - <sect1 id="x-understanding"> + <sect1 xml:id="x-understanding"> <title>Terminology</title> <para>While it is not necessary to understand all of the details @@ -149,9 +147,8 @@ the title bars on each window should look like, whether or not they have close buttons on them, and so on. Instead, X delegates this responsibility to a separate - window manager application. There are <ulink - url="http://xwinman.org/">dozens of window - managers</ulink> available. Each window manager + window manager application. There are <link xlink:href="http://xwinman.org/">dozens of window + managers</link> available. Each window manager provides a different look and feel: some support virtual desktops, some allow customized keystrokes to manage the desktop, some have a <quote>Start</quote> button, and @@ -235,7 +232,7 @@ </variablelist> </sect1> - <sect1 id="x-install"> + <sect1 xml:id="x-install"> <title>Installing <application>&xorg;</application></title> <para><application>&xorg;</application> is the @@ -243,10 +240,8 @@ released by the X.Org Foundation. In &os;, it can be installed as a package or port. The meta-port for the complete distribution which includes X servers, clients, - libraries, and fonts is located in <filename - role="package">x11/xorg</filename>. A minimal distribution - is located in <filename - role="package">x11/xorg-minimal</filename>, with separate + libraries, and fonts is located in <package>x11/xorg</package>. A minimal distribution + is located in <package>x11/xorg-minimal</package>, with separate ports available for docs, libraries, and apps. The examples in this section install the complete <application>&xorg;</application> distribution.</para> @@ -275,7 +270,7 @@ <screen>&prompt.root; <userinput>pkg install xorg</userinput></screen> </sect1> - <sect1 id="x-config"> + <sect1 xml:id="x-config"> <!-- <sect1info> <authorgroup> @@ -391,10 +386,9 @@ <para><application>&xorg;</application> uses <acronym>HAL</acronym> to autodetect keyboards and mice. The - <filename role="package">sysutils/hal</filename> and - <filename role="package">devel/dbus</filename> ports are - automatically installed as dependencies of <filename - role="package">x11/xorg</filename>, but must be enabled by + <package>sysutils/hal</package> and + <package>devel/dbus</package> ports are + automatically installed as dependencies of <package>x11/xorg</package>, but must be enabled by adding the following entries to <filename>/etc/rc.conf</filename>:</para> @@ -451,8 +445,7 @@ dbus_enable="YES"</programlisting> <para>or create a keyboard configuration file for <application>hald</application> called <filename>x11-input.fdi</filename> and saved in the - <filename - class="directory">/usr/local/etc/hal/fdi/policy</filename> + <filename>/usr/local/etc/hal/fdi/policy</filename> directory. This file should contain the following lines:</para> @@ -476,8 +469,7 @@ dbus_enable="YES"</programlisting> <programlisting>Option "DontZap" "off"</programlisting> </note> - <para>If the test is unsuccessful, skip ahead to <xref - linkend="x11-understanding"/>. Once the test is successful, + <para>If the test is unsuccessful, skip ahead to <xref linkend="x11-understanding"/>. Once the test is successful, copy the configuration file to <filename>/etc/X11/xorg.conf</filename>:</para> @@ -495,7 +487,7 @@ dbus_enable="YES"</programlisting> </sect2> </sect1> - <sect1 id="x-fonts"> + <sect1 xml:id="x-fonts"> <!-- <sect1info> <authorgroup> @@ -509,7 +501,7 @@ dbus_enable="YES"</programlisting> --> <title>Using Fonts in <application>&xorg;</application></title> - <sect2 id="type1"> + <sect2 xml:id="type1"> <title>Type1 Fonts</title> <para>The default fonts that ship with @@ -520,14 +512,9 @@ dbus_enable="YES"</programlisting> are several free, high quality Type1 (&postscript;) fonts available which can be readily used with <application>&xorg;</application>. For instance, the URW - font collection (<filename - role="package">x11-fonts/urwfonts</filename>) includes high - quality versions of standard type1 fonts (<trademark - class="registered">Times Roman</trademark>, <trademark - class="registered">Helvetica</trademark>, <trademark - class="registered">Palatino</trademark> and others). The - Freefonts collection (<filename - role="package">x11-fonts/freefonts</filename>) includes + font collection (<package>x11-fonts/urwfonts</package>) includes high + quality versions of standard type1 fonts (<trademark class="registered">Times Roman</trademark>, <trademark class="registered">Helvetica</trademark>, <trademark class="registered">Palatino</trademark> and others). The + Freefonts collection (<package>x11-fonts/freefonts</package>) includes many more fonts, but most of them are intended for use in graphics software such as the <application>Gimp</application>, and are not complete enough to serve as screen fonts. In @@ -568,7 +555,7 @@ dbus_enable="YES"</programlisting> <link linkend="antialias">anti-aliasing</link>.</para> </sect2> - <sect2 id="truetype"> + <sect2 xml:id="truetype"> <title>&truetype; Fonts</title> <indexterm> @@ -602,15 +589,13 @@ dbus_enable="YES"</programlisting> <filename>fonts.dir</filename> file, so that the X font renderer knows that these new files have been installed. <command>ttmkfdir</command> is available from the FreeBSD - Ports Collection as <filename - role="package">x11-fonts/ttmkfdir</filename>.</para> + Ports Collection as <package>x11-fonts/ttmkfdir</package>.</para> <screen>&prompt.root; <userinput>cd /usr/local/lib/X11/fonts/TrueType</userinput> &prompt.root; <userinput>ttmkfdir -o fonts.dir</userinput></screen> <para>Now add the &truetype; directory to the font path. This - is just the same as described above for <link - linkend="type1">Type1</link> fonts, that is, use</para> + is just the same as described above for <link linkend="type1">Type1</link> fonts, that is, use</para> <screen>&prompt.user; <userinput>xset fp+ /usr/local/lib/X11/fonts/TrueType</userinput> &prompt.user; <userinput>xset fp rehash</userinput></screen> @@ -627,7 +612,7 @@ dbus_enable="YES"</programlisting> look much better now.</para> </sect2> - <sect2 id="antialias"> + <sect2 xml:id="antialias"> <!-- <sect2info> <authorgroup> @@ -817,7 +802,7 @@ dbus_enable="YES"</programlisting> </sect2> </sect1> - <sect1 id="x-xdm"> + <sect1 xml:id="x-xdm"> <!-- <sect1info> <authorgroup> @@ -864,12 +849,12 @@ dbus_enable="YES"</programlisting> <title>Using XDM</title> <para>To start using <application>XDM</application>, install - the <filename role="package">x11/xdm</filename> port (it is + the <package>x11/xdm</package> port (it is not installed by default in recent versions of <application>&xorg;</application>). The <application>XDM</application> daemon program may then be found in <filename>/usr/local/bin/xdm</filename>. This - program can be run at any time as <username>root</username> + program can be run at any time as <systemitem class="username">root</systemitem> and it will start managing the X display on the local machine. If <application>XDM</application> is to be run every time the machine boots up, a convenient way to do this is by adding an @@ -1080,7 +1065,7 @@ DisplayManager.requestPort: 0</screen> </sect2> </sect1> - <sect1 id="x11-wm"> + <sect1 xml:id="x11-wm"> <!-- <sect1info> <authorgroup> @@ -1102,10 +1087,10 @@ DisplayManager.requestPort: 0</screen> applications, such as <application>KDE</application> or <application>GNOME</application>.</para> - <sect2 id="x11-wm-gnome"> + <sect2 xml:id="x11-wm-gnome"> <title>GNOME</title> - <sect3 id="x11-wm-gnome-about"> + <sect3 xml:id="x11-wm-gnome-about"> <title>About GNOME</title> <indexterm><primary>GNOME</primary></indexterm> @@ -1122,13 +1107,13 @@ DisplayManager.requestPort: 0</screen> <application>GNOME</application> provides. More information regarding <application>GNOME</application> on FreeBSD can be found on the - <ulink url="http://www.FreeBSD.org/gnome">FreeBSD GNOME - Project</ulink>'s web site. The web site also contains + <link xlink:href="http://www.FreeBSD.org/gnome">FreeBSD GNOME + Project</link>'s web site. The web site also contains fairly comprehensive FAQs about installing, configuring, and managing <application>GNOME</application>.</para> </sect3> - <sect3 id="x11-wm-gnome-install"> + <sect3 xml:id="x11-wm-gnome-install"> <title>Installing GNOME</title> <para>The software can be easily installed from a package @@ -1225,11 +1210,11 @@ DisplayManager.requestPort: 0</screen> </sect3> </sect2> - <sect2 id="x11-wm-kde"> + <sect2 xml:id="x11-wm-kde"> <title>KDE</title> <indexterm><primary>KDE</primary></indexterm> - <sect3 id="x11-wm-kde-about"> + <sect3 xml:id="x11-wm-kde-about"> <title>About KDE</title> <para><application>KDE</application> is an easy to use @@ -1285,14 +1270,14 @@ DisplayManager.requestPort: 0</screen> is a solid competitor to other existing web browsers on &unix; systems. More information on <application>KDE</application> can be found on the - <ulink url="http://www.kde.org/">KDE website</ulink>. For + <link xlink:href="http://www.kde.org/">KDE website</link>. For FreeBSD specific information and resources on <application>KDE</application>, consult the - <ulink url="http://freebsd.kde.org/">KDE/FreeBSD - initiative</ulink>'s website.</para> + <link xlink:href="http://freebsd.kde.org/">KDE/FreeBSD + initiative</link>'s website.</para> </sect3> - <sect3 id="x11-wm-kde-install"> + <sect3 xml:id="x11-wm-kde-install"> <title>Installing KDE</title> <para>Just as with <application>GNOME</application> or any @@ -1346,7 +1331,7 @@ DisplayManager.requestPort: 0</screen> </sect3> </sect2> - <sect2 id="x11-wm-kde-details"> + <sect2 xml:id="x11-wm-kde-details"> <title>More Details on KDE</title> <para>Now that <application>KDE</application> is installed on @@ -1362,7 +1347,7 @@ DisplayManager.requestPort: 0</screen> this section discusses the technical items that are difficult to learn by random exploration.</para> - <sect3 id="x11-wm-kde-kdm"> + <sect3 xml:id="x11-wm-kde-kdm"> <title>The KDE Display Manager</title> <indexterm> @@ -1389,10 +1374,10 @@ DisplayManager.requestPort: 0</screen> </sect3> </sect2> - <sect2 id="x11-wm-xfce"> + <sect2 xml:id="x11-wm-xfce"> <title>Xfce</title> - <sect3 id="x11-wm-xfce-about"> + <sect3 xml:id="x11-wm-xfce-about"> <title>About Xfce</title> <para><application>Xfce</application> is a desktop environment @@ -1438,11 +1423,10 @@ DisplayManager.requestPort: 0</screen> </itemizedlist> <para>More information on <application>Xfce</application> - can be found on the <ulink - url="http://www.xfce.org/">Xfce website</ulink>.</para> + can be found on the <link xlink:href="http://www.xfce.org/">Xfce website</link>.</para> </sect3> - <sect3 id="x11-wm-xfce-install"> + <sect3 xml:id="x11-wm-xfce-install"> <title>Installing Xfce</title> <para>To install the <application>Xfce</application> from the @@ -1481,7 +1465,7 @@ DisplayManager.requestPort: 0</screen> </sect2> </sect1> - <sect1 id="x11-understanding"> + <sect1 xml:id="x11-understanding"> <title>Troubleshooting</title> @@ -1518,8 +1502,7 @@ DisplayManager.requestPort: 0</screen> coming with a french layout, we have to create a keyboard configuration file for <application>hald</application> called <filename>x11-input.fdi</filename> and saved in the - <filename - class="directory">/usr/local/etc/hal/fdi/policy</filename> + <filename>/usr/local/etc/hal/fdi/policy</filename> directory. This file should contain the following lines:</para> @@ -1653,7 +1636,7 @@ EndSection</programlisting> </indexterm> <para>Configuration with &intel; i810 integrated chipsets - requires the <devicename>agpgart</devicename> AGP + requires the <filename>agpgart</filename> AGP programming interface for <application>&xorg;</application> to drive the card. See the &man.agp.4; driver manual page for more information.</para> diff --git a/en_US.ISO8859-1/books/pmake/answers/chapter.xml b/en_US.ISO8859-1/books/pmake/answers/chapter.xml index 68d86a9db3..9796854e87 100644 --- a/en_US.ISO8859-1/books/pmake/answers/chapter.xml +++ b/en_US.ISO8859-1/books/pmake/answers/chapter.xml @@ -2,8 +2,7 @@ <!-- $FreeBSD$ --> - -<chapter id="answers"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="answers"> <title>Answers to Exercises</title> <bridgehead>Exercise 3.1</bridgehead> diff --git a/en_US.ISO8859-1/books/pmake/basics/chapter.xml b/en_US.ISO8859-1/books/pmake/basics/chapter.xml index 4ae0a8b799..fd5dc0f101 100644 --- a/en_US.ISO8859-1/books/pmake/basics/chapter.xml +++ b/en_US.ISO8859-1/books/pmake/basics/chapter.xml @@ -2,8 +2,7 @@ <!-- $FreeBSD$ --> - -<chapter id="basics"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="basics"> <title>The Basics of PMake</title> <para><application>PMake</application> takes as input a file that @@ -18,7 +17,7 @@ otherwise. To specify a different makefile, use the <option>-f</option> flag, e.g.</para> - <screen>&prompt.user; <userinput>pmake <option>-f</option> <replaceable>program.mk</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>pmake -f program.mk</userinput></screen> <para>A makefile has four different types of lines in it:</para> @@ -46,7 +45,7 @@ single space before the input line is examined by <application>PMake</application>.</para> - <section id="deplines"> + <section xml:id="deplines"> <title>Dependency Lines</title> <para>As mentioned in the introduction, in any system, there are @@ -144,7 +143,7 @@ c.o : c.c</programlisting> <filename>a.o</filename>, <filename>b.o</filename> and <filename>c.o</filename> came in and why they depend on <filename>defs.h</filename> and the C files do not. - The reason is quite simple: <maketarget>program</maketarget> + The reason is quite simple: <buildtarget>program</buildtarget> cannot be made by linking together <filename>.c</filename> files—it must be made from <filename>.o</filename> files. Likewise, if you change <filename>defs.h</filename>, it is not @@ -201,7 +200,7 @@ c.o : c.c</programlisting> <filename>src/*.c</filename> will expand to the same three words as above as long as src contains those three files (and no other files that end in - <filename>.c</filename>).></entry> + <filename>.c</filename>).></entry> </row> <row valign="top"> @@ -228,7 +227,7 @@ c.o : c.c</programlisting> </informaltable> </section> - <section id="shellcmds" xreflabel="Shell Commands"> + <section xml:id="shellcmds" xreflabel="Shell Commands"> <title>Shell Commands</title> <para><quote>Is not that nice,</quote> you say to yourself, @@ -357,7 +356,7 @@ Linking index</screen> input, something they probably will not find to their liking. A simple way around this is to give a command like this:</para> - <screen><command>ci $(SRCS) < <devicename>/dev/tty</devicename></command></screen> + <screen><command>ci $(SRCS) < /dev/tty</command></screen> <para>This would force the program's input to come from the terminal. If you cannot do this for some reason, your only @@ -367,7 +366,7 @@ Linking index</screen> </section> - <section id="variables"> + <section xml:id="variables"> <title>Variables</title> <para><application>PMake</application>, like @@ -504,7 +503,7 @@ Linking index</screen> (environment) when looking up a variable. The first one found wins.</para> - <section id="localvariables"> + <section xml:id="localvariables"> <title>Local Variables</title> <para>Each target can have as many as seven local variables. @@ -516,7 +515,7 @@ Linking index</screen> <variablelist> <varlistentry> - <term><makevar>.TARGET</makevar></term> + <term><varname>.TARGET</varname></term> <listitem> <para>The name of the target.</para> @@ -524,7 +523,7 @@ Linking index</screen> </varlistentry> <varlistentry> - <term><makevar>.OODATE</makevar></term> + <term><varname>.OODATE</varname></term> <listitem> <para>The list of the sources for the target that were @@ -535,7 +534,7 @@ Linking index</screen> </varlistentry> <varlistentry> - <term><makevar>.ALLSRC</makevar></term> + <term><varname>.ALLSRC</varname></term> <listitem> <para>The list of all sources for this target in the order @@ -544,7 +543,7 @@ Linking index</screen> </varlistentry> <varlistentry> - <term><makevar>.PREFIX</makevar></term> + <term><varname>.PREFIX</varname></term> <listitem> <para>The target without its suffix and without any @@ -557,14 +556,14 @@ Linking index</screen> <para>Three other local variables are set only for certain targets under special circumstances. These are the - <makevar>.IMPSRC,</makevar> <makevar>.ARCHIVE,</makevar> and - <makevar>.MEMBER</makevar> variables. When they are set and + <varname>.IMPSRC,</varname> <varname>.ARCHIVE,</varname> and + <varname>.MEMBER</varname> variables. When they are set and how they are used is described later.</para> <para>Four of these variables may be used in sources as well as - in shell scripts. These are <makevar>.TARGET</makevar>, - <makevar>.PREFIX</makevar>, <makevar>.ARCHIVE</makevar> and - <makevar>.MEMBER</makevar>. The variables in the sources are + in shell scripts. These are <varname>.TARGET</varname>, + <varname>.PREFIX</varname>, <varname>.ARCHIVE</varname> and + <varname>.MEMBER</varname>. The variables in the sources are expanded once for each target on the dependency line, providing what is known as a <quote>dynamic source,</quote> allowing you to specify several dependency lines at once. @@ -576,7 +575,7 @@ Linking index</screen> corresponding C source file.</para> </section> - <section id="cmdvars"> + <section xml:id="cmdvars"> <title>Command-line Variables</title> <para>Command-line variables are set when @@ -608,7 +607,7 @@ Linking index</screen> substitution mechanisms (backquotes and all that).</para> </section> - <section id="globalvariables"> + <section xml:id="globalvariables"> <title>Global Variables</title> <para>Global variables are those set or appended-to in the @@ -623,32 +622,32 @@ Linking index</screen> <variablelist> <varlistentry> - <term><makevar>.PMAKE</makevar></term> + <term><varname>.PMAKE</varname></term> <listitem> <para>The name by which <application>PMake</application> was invoked is stored in this variable. For compatibility, the name is also stored in the - <makevar>MAKE</makevar> variable.</para> + <varname>MAKE</varname> variable.</para> </listitem> </varlistentry> <varlistentry> - <term><makevar>.MAKEFLAGS</makevar></term> + <term><varname>.MAKEFLAGS</varname></term> <listitem> <para>All the relevant flags with which <application>PMake</application> was invoked. This does not include such things as <option>-f</option> or variable assignments. Again for compatibility, this - value is stored in the <makevar>MFLAGS</makevar> + value is stored in the <varname>MFLAGS</varname> variable as well.</para> </listitem> </varlistentry> </variablelist> - <para>Two other variables, <makevar>.INCLUDES</makevar> and - <makevar>.LIBS,</makevar> are covered in the section on + <para>Two other variables, <varname>.INCLUDES</varname> and + <varname>.LIBS,</varname> are covered in the section on special targets in <xref linkend="shortcuts"/>.</para> <para>Global variables may be deleted using lines of the @@ -661,7 +660,7 @@ Linking index</screen> variables.</para> </section> - <section id="envvars"> + <section xml:id="envvars"> <title>Environment Variables</title> <para>Environment variables are passed by the shell that invoked @@ -703,7 +702,7 @@ c.o : c.c </section> </section> - <section id="comments"> + <section xml:id="comments"> <title>Comments</title> <para>Comments in a makefile start with a <literal>#</literal> @@ -721,7 +720,7 @@ c.o : c.c </note> </section> - <section id="parellelism"> + <section xml:id="parellelism"> <title>Parallelism</title> <para><application>PMake</application> was specifically designed @@ -754,8 +753,7 @@ c.o : c.c dependencies that worked in <application>Make</application> because of its sequential, depth-first way of examining them. While I do not want to go into depth on how - <application>PMake</application> works (look in <xref - linkend="gods"/> if you are interested), I will warn you that + <application>PMake</application> works (look in <xref linkend="gods"/> if you are interested), I will warn you that files in two different levels of the dependency tree may be examined in a different order in <application>PMake</application> than they were in @@ -767,28 +765,28 @@ c.o : c.c b c b : d</programlisting> <para><application>PMake</application> will examine the targets in - the order <maketarget>c</maketarget>, - <maketarget>d</maketarget>, <maketarget>b</maketarget>, - <maketarget>a</maketarget>. If the makefile's author expected + the order <buildtarget>c</buildtarget>, + <buildtarget>d</buildtarget>, <buildtarget>b</buildtarget>, + <buildtarget>a</buildtarget>. If the makefile's author expected <application>PMake</application> to abort before making - <maketarget>c</maketarget> if an error occurred while making - <maketarget>b</maketarget>, or if <maketarget>b</maketarget> - needed to exist before <maketarget>c</maketarget> was made, + <buildtarget>c</buildtarget> if an error occurred while making + <buildtarget>b</buildtarget>, or if <buildtarget>b</buildtarget> + needed to exist before <buildtarget>c</buildtarget> was made, (s)he will be sorely disappointed. The dependencies are incomplete, since in both these cases, - <maketarget>c</maketarget> would depend on - <maketarget>b</maketarget>. So watch out.</para> + <buildtarget>c</buildtarget> would depend on + <buildtarget>b</buildtarget>. So watch out.</para> <para>Another problem you may face is that, while <application>PMake</application> is set up to handle the output from multiple jobs in a graceful fashion, the same is not so for input. It has no way to regulate input to different jobs, so if - you use the redirection from <devicename>/dev/tty</devicename> I + you use the redirection from <filename>/dev/tty</filename> I mentioned earlier, you must be careful not to run two of the jobs at once.</para> </section> - <section id="writeanddebug"> + <section xml:id="writeanddebug"> <title>Writing and Debugging a Makefile</title> <para>Now you know most of what is in a @@ -969,11 +967,11 @@ d : a</programlisting> <para>In this case, because of how <application>PMake</application> works, - <maketarget>c</maketarget> is the only thing + <buildtarget>c</buildtarget> is the only thing <application>PMake</application> will examine, because - <maketarget>d</maketarget> and <maketarget>a</maketarget> will + <buildtarget>d</buildtarget> and <buildtarget>a</buildtarget> will effectively fall off the edge of the universe, making it - impossible to examine <maketarget>b</maketarget> (or them, for + impossible to examine <buildtarget>b</buildtarget> (or them, for that matter). <application>PMake</application> will tell you (if run in its normal mode) all the targets involved in any cycle it looked at (i.e. if you have two cycles in the @@ -984,7 +982,7 @@ d : a</programlisting> it will only print the first target in the cycle.</para> </section> - <section id="invoking"> + <section xml:id="invoking"> <title>Invoking PMake</title> <para><application>PMake</application> comes with a wide variety @@ -1327,7 +1325,7 @@ d : a</programlisting> <application>make</application> or has things set in the environment that tell it to be compatible. <option>-C</option> is not placed in the <envar>PMAKE</envar> - environment variable or the <makevar>.MAKEFLAGS</makevar> or + environment variable or the <varname>.MAKEFLAGS</varname> or <envar>MFLAGS</envar> global variables.</para> </listitem> </varlistentry> @@ -1460,12 +1458,12 @@ d : a</programlisting> <para>will cause <application>PMake</application> to read <filename>server.mk</filename> as the input makefile, - define the variable <makevar>DEBUG</makevar> as a global variable and + define the variable <varname>DEBUG</varname> as a global variable and look for included makefiles in the directory <filename>/chip2/X/server/include</filename>.</para> </section> - <section id="summary"> + <section xml:id="summary"> <title>Summary</title> <para>A makefile is made of four types of lines:</para> @@ -1514,12 +1512,12 @@ d : a</programlisting> braces, preceded by a dollar sign. A dollar sign may be escaped with another dollar sign. Variables are not expanded if <application>PMake</application> does not know about them. - There are seven local variables: <makevar>.TARGET</makevar>, - <makevar>.ALLSRC</makevar>, <makevar>.OODATE</makevar>, - <makevar>.PREFIX</makevar>, <makevar>.IMPSRC</makevar>, - <makevar>.ARCHIVE</makevar>, and <makevar>.MEMBER</makevar>. - Four of them (<makevar>.TARGET</makevar>, <makevar>.PREFIX</makevar>, - <makevar>.ARCHIVE</makevar>, and <makevar>.MEMBER</makevar>) may be used + There are seven local variables: <varname>.TARGET</varname>, + <varname>.ALLSRC</varname>, <varname>.OODATE</varname>, + <varname>.PREFIX</varname>, <varname>.IMPSRC</varname>, + <varname>.ARCHIVE</varname>, and <varname>.MEMBER</varname>. + Four of them (<varname>.TARGET</varname>, <varname>.PREFIX</varname>, + <varname>.ARCHIVE</varname>, and <varname>.MEMBER</varname>) may be used to specify <quote>dynamic sources</quote>. Variables are good. Know them. Love them. Live them.</para> diff --git a/en_US.ISO8859-1/books/pmake/book.xml b/en_US.ISO8859-1/books/pmake/book.xml index 6fd4709813..49064d6433 100644 --- a/en_US.ISO8859-1/books/pmake/book.xml +++ b/en_US.ISO8859-1/books/pmake/book.xml @@ -1,18 +1,14 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY % chapters.ent SYSTEM "chapters.ent"> %chapters.ent; ]> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>PMake — A Tutorial</title> + -<book lang='en'> - <bookinfo> - <title>PMake — A Tutorial</title> - - <author> - <firstname>Adam</firstname> - <surname>de Boor</surname> - </author> + <author><personname><firstname>Adam</firstname><surname>de Boor</surname></personname></author> <copyright> <year>1988</year> @@ -35,7 +31,7 @@ &pmake.legalnotice; <releaseinfo>$FreeBSD$</releaseinfo> - </bookinfo> + </info> &chap.intro; &chap.basics; diff --git a/en_US.ISO8859-1/books/pmake/glossary/glossary.xml b/en_US.ISO8859-1/books/pmake/glossary/glossary.xml index d983027d75..33b8eb6096 100644 --- a/en_US.ISO8859-1/books/pmake/glossary/glossary.xml +++ b/en_US.ISO8859-1/books/pmake/glossary/glossary.xml @@ -2,8 +2,7 @@ <!-- $FreeBSD$ --> - -<glossary id="glossary"> +<glossary xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="glossary"> <title>Glossary of Jargon</title> <glossentry> @@ -16,7 +15,7 @@ </glossentry> <glossentry> - <glossterm id="cmdscript">command script</glossterm> + <glossterm xml:id="cmdscript">command script</glossterm> <glossdef> <para>The lines immediately following a dependency line that specify @@ -107,12 +106,12 @@ <para>A variable defined by <application>PMake</application> visible only in a target's shell script. There are seven local variables, not all of which are defined for - every target: <makevar>.TARGET</makevar>, <makevar>.ALLSRC</makevar>, - <makevar>.OODATE</makevar>, <makevar>.PREFIX</makevar>, - <makevar>.IMPSRC</makevar>, <makevar>.ARCHIVE</makevar>, and - <makevar>.MEMBER</makevar>. - <makevar>.TARGET</makevar>, <makevar>.PREFIX</makevar>, - <makevar>.ARCHIVE</makevar>, and <makevar>.MEMBER</makevar> + every target: <varname>.TARGET</varname>, <varname>.ALLSRC</varname>, + <varname>.OODATE</varname>, <varname>.PREFIX</varname>, + <varname>.IMPSRC</varname>, <varname>.ARCHIVE</varname>, and + <varname>.MEMBER</varname>. + <varname>.TARGET</varname>, <varname>.PREFIX</varname>, + <varname>.ARCHIVE</varname>, and <varname>.MEMBER</varname> may be used on dependency lines to create <quote>dynamic sources</quote>.</para> </glossdef> diff --git a/en_US.ISO8859-1/books/pmake/gods/chapter.xml b/en_US.ISO8859-1/books/pmake/gods/chapter.xml index c2360b3226..8287b08104 100644 --- a/en_US.ISO8859-1/books/pmake/gods/chapter.xml +++ b/en_US.ISO8859-1/books/pmake/gods/chapter.xml @@ -2,8 +2,7 @@ <!-- $FreeBSD$ --> - -<chapter id="gods"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="gods"> <title>PMake for Gods</title> <para>This chapter is devoted to those facilities in @@ -17,12 +16,12 @@ <para>Once more, I assume a greater familiarity with &unix; or Sprite than I did in the previous two chapters.</para> - <section id="searchpaths"> + <section xml:id="searchpaths"> <title>Search Paths</title> <para><application>PMake</application> supports the dispersal of files into multiple directories by allowing you to specify - places to look for sources with <maketarget>.PATH</maketarget> + places to look for sources with <buildtarget>.PATH</buildtarget> targets in the makefile. The directories you give as sources for these targets make up a <quote>search path</quote>. Only those files used exclusively as sources are actually sought on a @@ -33,18 +32,18 @@ <para>There are two types of search paths in <application>PMake</application>: one is used for all types of files (including included makefiles) and is specified with a - plain <maketarget>.PATH</maketarget> target (e.g. <literal>.PATH + plain <buildtarget>.PATH</buildtarget> target (e.g. <literal>.PATH : RCS</literal>), while the other is specific to a certain type of file, as indicated by the file's suffix. A specific search path is indicated by immediately following the - <maketarget>.PATH</maketarget> with the suffix of the file. For + <buildtarget>.PATH</buildtarget> with the suffix of the file. For instance:</para> <programlisting>.PATH.h : /sprite/lib/include /sprite/att/lib/include</programlisting> <para>would tell <application>PMake</application> to look in the - directories <filename class="directory">/sprite/lib/include</filename> and - <filename class="directory">/sprite/att/lib/include</filename> for any + directories <filename>/sprite/lib/include</filename> and + <filename>/sprite/att/lib/include</filename> for any files whose suffix is <filename>.h</filename>.</para> <para>The current directory is always consulted first to see if a @@ -59,8 +58,8 @@ <para>When a file is found in some directory other than the current one, all local variables that would have contained the - target's name (<makevar>.ALLSRC</makevar>, and - <makevar>.IMPSRC</makevar>) will instead contain + target's name (<varname>.ALLSRC</varname>, and + <varname>.IMPSRC</varname>) will instead contain the path to the file, as found by <application>PMake</application>. Thus if you have a file <filename>../lib/mumble.c</filename> @@ -104,7 +103,7 @@ mumble : mumble.c suffix is not changed from <filename>.out</filename>.</para> </section> - <section id="archivesandlibraries"> + <section xml:id="archivesandlibraries"> <title>Archives and Libraries</title> <para>&unix; and Sprite allow you to merge files into an archive @@ -130,7 +129,7 @@ mumble : mumble.c <para>A library is any target that looks like <option>-lname</option> or that ends in a suffix that was marked as a library using the - <maketarget>.LIBS</maketarget> target. <filename>.a</filename> + <buildtarget>.LIBS</buildtarget> target. <filename>.a</filename> is so marked in the system makefile. Members of an archive are specified as <literal>archive(member[member...])</literal>. Thus <literal>libdix.a(window.o)</literal> specifies the @@ -158,29 +157,29 @@ mumble : mumble.c </listitem> <listitem> - <para>The archive(member)'s <makevar>.TARGET</makevar> + <para>The archive(member)'s <varname>.TARGET</varname> variable is set to the name of the member if member is actually a target, or the path to the member file if member is only a source.</para> </listitem> <listitem> - <para>The <makevar>.ARCHIVE</makevar> variable for the + <para>The <varname>.ARCHIVE</varname> variable for the archive(member) target is set to the name of the archive.</para> </listitem> <listitem> - <para>The <makevar>.MEMBER</makevar> variable is set to the + <para>The <varname>.MEMBER</varname> variable is set to the actual string inside the parentheses. In most cases, - this will be the same as the <makevar>.TARGET</makevar> + this will be the same as the <varname>.TARGET</varname> variable.</para> </listitem> <listitem> <para>The archive(member)'s place in the local variables of the targets that depend on it is taken by the value of its - <makevar>.TARGET</makevar> variable.</para> + <varname>.TARGET</varname> variable.</para> </listitem> </itemizedlist> @@ -249,7 +248,7 @@ MAKELIB : .USE .PRECIOUS #endif _MAKELIB_MK</programlisting> </section> - <section id="condition"> + <section xml:id="condition"> <title>On the Condition...</title> <para>Like the C compiler before it, <application>PMake</application> @@ -299,9 +298,9 @@ still more lines <entry>The syntax is make(target) where target is a target in the makefile. This is true if the given target was specified on the command line, or - as the source for a <maketarget>.MAIN</maketarget> + as the source for a <buildtarget>.MAIN</buildtarget> target (note that the sources for - <maketarget>.MAIN</maketarget> are only used if no + <buildtarget>.MAIN</buildtarget> are only used if no targets were given on the command line).</entry> </row> @@ -323,8 +322,8 @@ still more lines <entry>The syntax is <literal>exists(file)</literal> and is true if the file can be found on the global search path (i.e. - that defined by <makevar>.PATH</makevar> targets, not by - <maketarget>.PATH<replaceable>suffix</replaceable></maketarget> + that defined by <varname>.PATH</varname> targets, not by + <buildtarget>.PATH<replaceable>suffix</replaceable></buildtarget> targets).</entry> </row> @@ -459,8 +458,8 @@ FORMATTER = nroff -Pdot_matrix_printer this all gets somewhat complicated.</para> </section> - <section id="ashell"> - <title id="ashelltitle">A Shell is a Shell is a Shell</title> + <section xml:id="ashell"> + <title xml:id="ashelltitle">A Shell is a Shell is a Shell</title> <para>In normal operation, the Bourne Shell (better known as <application>sh</application>) is used to execute the @@ -469,7 +468,7 @@ FORMATTER = nroff -Pdot_matrix_printer executing these commands. There are several things <application>PMake</application> must know about the shell you wish to use. These things are specified as the - sources for the <maketarget>.SHELL</maketarget> target by + sources for the <buildtarget>.SHELL</buildtarget> target by keyword, as follows:</para> <variablelist> @@ -640,7 +639,7 @@ FORMATTER = nroff -Pdot_matrix_printer single-quotes, <literal>\"</literal> escapes a double-quote inside double-quotes). Now for an example.</para> - <para>This is actually the contents of the <shx.mk> system + <para>This is actually the contents of the <shx.mk> system makefile, and causes <application>PMake</application> to use the <application>Bourne Shell</application> in such a way that each command is printed as it is executed. That is, if @@ -737,14 +736,14 @@ sh -c 'cmd || true'</programlisting> <para>for each command for which errors are to be ignored. (In case you are wondering, the thing for ignore tells the shell to execute another shell without error checking on and - always exit 0, since the ||<literal></literal> causes the + always exit 0, since the ||<literal/> causes the exit 0 to be executed only if the first command exited non-zero, and if the first command exited zero, the shell will also exit zero, since that is the last command it executed).</para> </section> - <section id="compatibility"> + <section xml:id="compatibility"> <title>Compatibility</title> <para>There are three (well, 3 1/2) levels of @@ -757,7 +756,7 @@ sh -c 'cmd || true'</programlisting> following three sections.</para> </section> - <section id="defcon3"> + <section xml:id="defcon3"> <title>DEFCON 3 – Variable Expansion</title> <para>As noted before, <application>PMake</application> will not @@ -777,10 +776,10 @@ sh -c 'cmd || true'</programlisting> since that is where they would have been set if you used <application>Make</application>, anyway) or always give the <option>-V</option> flag (this can be done with the - <maketarget>.MAKEFLAGS</maketarget> target, if you want).</para> + <buildtarget>.MAKEFLAGS</buildtarget> target, if you want).</para> </section> - <section id="defcon2"> + <section xml:id="defcon2"> <title>DEFCON 2 – The Number of the Beast</title> <para>Then there are the makefiles that expect certain commands, @@ -810,7 +809,7 @@ sh -c 'cmd || true'</programlisting> which it started.</para> </section> - <section id="defcon1"> + <section xml:id="defcon1"> <title>DEFCON 1 – Imitation is the Not the Highest Form of Flattery</title> @@ -877,7 +876,7 @@ sh -c 'cmd || true'</programlisting> </itemizedlist> </section> - <section id="theway"> + <section xml:id="theway"> <title>The Way Things Work</title> <para>When <application>PMake</application> reads the makefile, it @@ -895,7 +894,7 @@ sh -c 'cmd || true'</programlisting> <para>After <application>PMake</application> has parsed the makefile, it begins with the nodes the user has told it to make (either on the command line, or via a - <maketarget>.MAIN</maketarget> target, or by the target being + <buildtarget>.MAIN</buildtarget> target, or by the target being the first in the file not labeled with the <literal>.NOTMAIN</literal> attribute) placed in a queue. It continues to take the node off the front of the queue, mark it @@ -903,14 +902,14 @@ sh -c 'cmd || true'</programlisting> <literal>Suff_FindDeps</literal> (mentioned earlier) to find any implicit sources for the node, and place all the node's children that have yet to be marked at the end of the queue. If any of - the children is a <maketarget>.USE</maketarget> rule, its + the children is a <buildtarget>.USE</buildtarget> rule, its attributes are applied to the parent, then its commands are appended to the parent's list of commands and its children are linked to its parent. The parent's unmade children counter is - then decremented (since the <maketarget>.USE</maketarget> node + then decremented (since the <buildtarget>.USE</buildtarget> node has been processed). You will note that this allows a - <maketarget>.USE</maketarget> node to have children that are - <maketarget>.USE</maketarget> nodes and the rules will be + <buildtarget>.USE</buildtarget> node to have children that are + <buildtarget>.USE</buildtarget> nodes and the rules will be applied in sequence. If the node has no children, it is placed at the end of another queue to be examined in the second pass. This process continues until the first queue is empty.</para> @@ -932,7 +931,7 @@ sh -c 'cmd || true'</programlisting> <para>Once all targets have been processed, <application>PMake</application> executes the commands attached - to the <maketarget>.END</maketarget> target, either explicitly + to the <buildtarget>.END</buildtarget> target, either explicitly or through the use of an ellipsis in a shell script. If there were no errors during the entire process but there are still some targets unmade (<application>PMake</application> keeps a diff --git a/en_US.ISO8859-1/books/pmake/intro/chapter.xml b/en_US.ISO8859-1/books/pmake/intro/chapter.xml index b1cfcec310..b77fde752f 100644 --- a/en_US.ISO8859-1/books/pmake/intro/chapter.xml +++ b/en_US.ISO8859-1/books/pmake/intro/chapter.xml @@ -4,8 +4,7 @@ $FreeBSD$ --> - -<chapter id="intro"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="intro"> <title>Introduction</title> <para><application>PMake</application> is a program for creating other diff --git a/en_US.ISO8859-1/books/pmake/legalnotice.xml b/en_US.ISO8859-1/books/pmake/legalnotice.xml index 5226e208a0..364bafa294 100644 --- a/en_US.ISO8859-1/books/pmake/legalnotice.xml +++ b/en_US.ISO8859-1/books/pmake/legalnotice.xml @@ -2,8 +2,7 @@ <!-- $FreeBSD$ --> - -<legalnotice id="legalnotice"> +<legalnotice xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="legalnotice"> <para>All rights reserved.</para> <para>This code is derived from software contributed to Berkeley diff --git a/en_US.ISO8859-1/books/pmake/shortcuts/chapter.xml b/en_US.ISO8859-1/books/pmake/shortcuts/chapter.xml index 9c7a90cac9..6383e90286 100644 --- a/en_US.ISO8859-1/books/pmake/shortcuts/chapter.xml +++ b/en_US.ISO8859-1/books/pmake/shortcuts/chapter.xml @@ -2,8 +2,7 @@ <!-- $FreeBSD$ --> - -<chapter id="shortcuts"> +<chapter xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:id="shortcuts"> <title>Short-cuts and Other Nice Things</title> <para>Based on what I have told you so far, you may have gotten the @@ -18,7 +17,7 @@ what you are using) than I did in <xref linkend="basics"/>, just so you are on your toes. So without further ado…</para> - <section id="rules"> + <section xml:id="rules"> <title>Transformation Rules</title> <para>As you know, a file's name consists of two parts: a base @@ -47,7 +46,7 @@ together. Suffixes are made known to <application>PMake</application> by placing them as sources on a dependency line whose target is the special - target <makevar>.SUFFIXES</makevar>. E.g.:</para> + target <varname>.SUFFIXES</varname>. E.g.:</para> <programlisting>.SUFFIXES : .o .c .c.o : @@ -73,7 +72,7 @@ <orderedlist> <listitem> - <para>The <makevar>.IMPSRC</makevar> variable. + <para>The <varname>.IMPSRC</varname> variable. This variable is set to the <quote>implied source</quote> (the file from which the target is being created; the one with the first @@ -184,12 +183,12 @@ cc a.o b.o</screen> but only the most recent one will be used). You will notice, however, that there is a definite order to the suffixes that are tried. This order is set by the relative positions of - the suffixes on the <makevar>.SUFFIXES</makevar> line + the suffixes on the <varname>.SUFFIXES</varname> line – the earlier a suffix appears, the earlier it is checked as the source of a transformation. Once a suffix has been defined, the only way to change its position in the pecking order is to remove all the suffixes (by having a - <makevar>.SUFFIXES</makevar> dependency line with no sources) + <varname>.SUFFIXES</varname> dependency line with no sources) and redefine them in the order you want. (Previously-defined transformation rules will be automatically redefined as the suffixes they involve are @@ -252,7 +251,7 @@ cc a.o b.o</screen> create the <filename>.c</filename> file from either a <filename>.y</filename> file or a <filename>.l</filename> file. Since <filename>.y</filename> came first on the - <makevar>.SUFFIXES</makevar> line, it checks for + <varname>.SUFFIXES</varname> line, it checks for <filename>jive.y</filename> first, but can not find it, so it looks for <filename>jive.l</filename> and, lo and behold, there it is. At this point, it has defined a transformation path as follows:</para> @@ -290,7 +289,7 @@ cc -o jive.out jive.o</screen> known suffix? <application>PMake</application> simply pretends it actually has a known suffix and searches for transformations accordingly. The suffix it chooses is the - source for the <maketarget>.NULL</maketarget> target mentioned + source for the <buildtarget>.NULL</buildtarget> target mentioned later. In the system makefile, <filename>.out</filename> is chosen as the <quote>null suffix</quote> because most people use <application>PMake</application> to create programs. You @@ -300,7 +299,7 @@ cc -o jive.out jive.o</screen> mode (see <xref linkend="gods"/>).</para> </section> - <section id="including"> + <section xml:id="including"> <title>Including Other Makefiles</title> <para>Just as for programs, it is often useful to extract certain @@ -351,7 +350,7 @@ cc -o jive.out jive.o</screen> <listitem> <para>Directories given by - <makevar>.PATH</makevar> dependency lines (see + <varname>.PATH</varname> dependency lines (see <xref linkend="gods"/>).</para> </listitem> @@ -375,7 +374,7 @@ cc -o jive.out jive.o</screen> <para>will not work.</para> </section> - <section id="savingcmds"> + <section xml:id="savingcmds"> <title>Saving Commands</title> <para>There may come a time when you will want to save certain @@ -416,14 +415,14 @@ lib2.a : $(LIB2OBJS) <para>commands until the end, when they would run one after the other (using the correct value for the - <makevar>.TARGET</makevar> variable, of course).</para> + <varname>.TARGET</varname> variable, of course).</para> <para>Commands saved in this manner are only executed if <application>PMake</application> manages to re-create everything without an error.</para> </section> - <section id="targetattr"> + <section xml:id="targetattr"> <title>Target Attributes</title> <para><application>PMake</application> allows you to give @@ -480,7 +479,7 @@ lib2.a : $(LIB2OBJS) through the loading and dumping unless one of your files has changed. Your makefile might look a little bit like this (remember, this is an educational example, - and do not worry about the <maketarget>COMPILE</maketarget> + and do not worry about the <buildtarget>COMPILE</buildtarget> rule, all will soon become clear, grasshopper): <programlisting>system : init a.fasl b.fasl c.fasl @@ -561,10 +560,10 @@ prog2 : $(PROG2OBJS) .INVISIBLE MAKEINSTALL</programlisting> where <literal>MAKEINSTALL</literal> is some complex <literal>.USE</literal> rule (see - below) that depends on the <makevar>.ALLSRC</makevar> + below) that depends on the <varname>.ALLSRC</varname> variable containing the right things. Without the <literal>.INVISIBLE</literal> - attribute for <maketarget>prog2</maketarget>, + attribute for <buildtarget>prog2</buildtarget>, the <literal>MAKEINSTALL</literal> rule could not be applied. This is not as useful as it should be, and the semantics may change (or the @@ -581,10 +580,10 @@ prog2 : $(PROG2OBJS) .INVISIBLE MAKEINSTALL</programlisting> the target's shell script to be executed only if one or more of the sources was out-of-date. In addition, the target's name, in both its - <makevar>.TARGET</makevar> + <varname>.TARGET</varname> variable and all the local variables of any target that depends on it, is replaced by the value - of its <makevar>.ALLSRC</makevar> variable. As an + of its <varname>.ALLSRC</varname> variable. As an example, suppose you have a program that has four libraries that compile in the same directory along with, and at @@ -607,7 +606,7 @@ libraries : lib1.a lib2.a lib3.a lib4.a .JOIN <filename>lib2.a</filename>, <filename>lib3.a</filename> and <filename>lib4.a</filename>. It will then execute ranlib on any library that was changed and set - program's <makevar>.ALLSRC</makevar> variable to contain + program's <varname>.ALLSRC</varname> variable to contain what's in <literal>$(OBJS)</literal> followed by <quote><filename>lib1.a</filename> <filename>lib2.a</filename> @@ -706,7 +705,7 @@ libraries : lib1.a lib2.a lib3.a lib4.a .JOIN <entry><literal>.USE</literal></entry> <entry><para>By giving a target this attribute, you turn it - into <application></application>PMake's equivalent of + into <application/>PMake's equivalent of a macro. When the target is used as a source for another target, the other target acquires the commands, sources and attributes (except @@ -717,7 +716,7 @@ libraries : lib1.a lib2.a lib3.a lib4.a .JOIN target, the rules are applied sequentially. The typical <literal>.USE</literal> rule (as I call them) will use the sources of the target to which it is applied (as - stored in the <makevar>.ALLSRC</makevar> variable for + stored in the <varname>.ALLSRC</varname> variable for the target) as its <quote>arguments,</quote> if you will. For example, you probably noticed that the commands for creating <filename>lib1.a</filename> and @@ -741,10 +740,10 @@ MAKELIB : .USE easier (they are in the default, system makefile directory...take a look). Note that the <literal>.USE</literal> rule source itself - (<maketarget>MAKELIB</maketarget>) does not appear in + (<buildtarget>MAKELIB</buildtarget>) does not appear in any of the targets's local variables. There is no limit to the number of times I could use the - <maketarget>MAKELIB</maketarget> rule. If there were + <buildtarget>MAKELIB</buildtarget> rule. If there were more libraries, I could continue with <literal>lib3.a : $(LIB3OBJS) MAKELIB</literal> and so on and so forth.</para></entry> @@ -754,7 +753,7 @@ MAKELIB : .USE </informaltable> </section> - <section id="specialtargets"> + <section xml:id="specialtargets"> <title>Special Targets</title> <para>As there were in <application>Make</application>, so there @@ -775,7 +774,7 @@ MAKELIB : .USE <tbody> <row valign="top"> - <entry><maketarget>.BEGIN</maketarget></entry> + <entry><buildtarget>.BEGIN</buildtarget></entry> <entry>Any commands attached to this target are executed before anything else is done. You can use @@ -784,7 +783,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.DEFAULT</maketarget></entry> + <entry><buildtarget>.DEFAULT</buildtarget></entry> <entry>This is sort of a <literal>.USE</literal> rule for any target (that was used only as a source) @@ -792,18 +791,18 @@ MAKELIB : .USE out any other way to create. It is only <quote>sort of</quote> a <literal>.USE</literal> rule because only the shell script attached to the - <maketarget>.DEFAULT</maketarget> target is used. - The <makevar>.IMPSRC</makevar> variable of a target - that inherits <maketarget>.DEFAULT</maketarget>'s + <buildtarget>.DEFAULT</buildtarget> target is used. + The <varname>.IMPSRC</varname> variable of a target + that inherits <buildtarget>.DEFAULT</buildtarget>'s commands is set to the target's own name.</entry> </row> <row valign="top"> - <entry><maketarget>.END</maketarget></entry> + <entry><buildtarget>.END</buildtarget></entry> <entry>This serves a function similar to - <maketarget>.BEGIN</maketarget>, in that commands + <buildtarget>.BEGIN</buildtarget>, in that commands attached to it are executed once everything has been re-created (so long as no errors occurred). It also serves the extra function of @@ -815,7 +814,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.EXPORT</maketarget></entry> + <entry><buildtarget>.EXPORT</buildtarget></entry> <entry>The sources for this target are passed to the exportation system compiled into @@ -825,7 +824,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.IGNORE</maketarget></entry> + <entry><buildtarget>.IGNORE</buildtarget></entry> <entry>This target marks each of its sources with the <literal>.IGNORE</literal> attribute. @@ -836,7 +835,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.INCLUDES</maketarget></entry> + <entry><buildtarget>.INCLUDES</buildtarget></entry> <entry><para>The sources for this target are taken to be suffixes that indicate a file that can be included in @@ -844,8 +843,8 @@ MAKELIB : .USE already been declared with <literal>.SUFFIXES</literal> (see below). Any suffix so marked will have the directories on - its search path (see <maketarget>.PATH</maketarget>, - below) placed in the <makevar>.INCLUDES</makevar> + its search path (see <buildtarget>.PATH</buildtarget>, + below) placed in the <varname>.INCLUDES</varname> variable, each preceded by a <option>-I</option> flag. This variable can then be used as an argument for the compiler in the normal fashion. The @@ -858,18 +857,18 @@ MAKELIB : .USE <application>PMake</application> will place <literal>-I/usr/local/X/lib/bitmaps</literal> - in the <makevar>.INCLUDES</makevar> variable and you can + in the <varname>.INCLUDES</varname> variable and you can then say <programlisting>cc $(.INCLUDES) -c xprogram.c</programlisting> - (Note: the <makevar>.INCLUDES</makevar> variable is + (Note: the <varname>.INCLUDES</varname> variable is not actually filled in until the entire makefile has been read.)</para></entry> </row> <row valign="top"> - <entry><maketarget>.INTERRUPT</maketarget></entry> + <entry><buildtarget>.INTERRUPT</buildtarget></entry> <entry>When <application>PMake</application> is interrupted, it will execute the commands in the @@ -877,24 +876,24 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.LIBS</maketarget></entry> + <entry><buildtarget>.LIBS</buildtarget></entry> <entry>This does for libraries what - <maketarget>.INCLUDES</maketarget> does for include + <buildtarget>.INCLUDES</buildtarget> does for include files, except the flag used is <option>-L</option>, as required by those linkers that allow you to tell them where to find libraries. - The variable used is <makevar>.LIBS</makevar>. + The variable used is <varname>.LIBS</varname>. Be forewarned that <application>PMake</application> may not have been compiled to do this if the linker on your system does not accept the <option>-L</option> - flag, though the <makevar>.LIBS</makevar> variable + flag, though the <varname>.LIBS</varname> variable will always be defined once the makefile has been read.</entry> </row> <row valign="top"> - <entry><maketarget>.MAIN</maketarget></entry> + <entry><buildtarget>.MAIN</buildtarget></entry> <entry>If you did not give a target (or targets) to create when you invoked @@ -904,7 +903,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.MAKEFLAGS</maketarget></entry> + <entry><buildtarget>.MAKEFLAGS</buildtarget></entry> <entry>This target provides a way for you to always specify flags for <application>PMake</application> @@ -916,7 +915,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.NULL</maketarget></entry> + <entry><buildtarget>.NULL</buildtarget></entry> <entry>This allows you to specify what suffix <application>PMake</application> should pretend @@ -927,7 +926,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.PATH</maketarget></entry> + <entry><buildtarget>.PATH</buildtarget></entry> <entry>If you give sources for this target, <application>PMake</application> will take them as @@ -935,16 +934,15 @@ MAKELIB : .USE find in the current directory. If you give no sources, it will clear out any directories added to the search path before. Since the effects of this - all get very complex, we will leave it till <xref - linkend="gods"/> to give you a complete + all get very complex, we will leave it till <xref linkend="gods"/> to give you a complete explanation.</entry> </row> <row valign="top"> - <entry><maketarget>.PATH<replaceable>suffix</replaceable></maketarget></entry> + <entry><buildtarget>.PATH<replaceable>suffix</replaceable></buildtarget></entry> <entry>This does a similar thing to - <maketarget>.PATH</maketarget>, but it does it only + <buildtarget>.PATH</buildtarget>, but it does it only for files with the given suffix. The suffix must have been defined already. Look at Search Paths (<xref linkend="searchpaths"/>) for more @@ -952,9 +950,9 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.PRECIOUS</maketarget></entry> + <entry><buildtarget>.PRECIOUS</buildtarget></entry> - <entry>Similar to <maketarget>.IGNORE</maketarget>, + <entry>Similar to <buildtarget>.IGNORE</buildtarget>, this gives the <literal>.PRECIOUS</literal> attribute to each source on the dependency line, unless there are no sources, in which case the <literal>.PRECIOUS</literal> @@ -962,7 +960,7 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.RECURSIVE</maketarget></entry> + <entry><buildtarget>.RECURSIVE</buildtarget></entry> <entry>This target applies the <literal>.MAKE</literal> attribute to all its sources. It does nothing if you @@ -970,23 +968,21 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.SHELL</maketarget></entry> + <entry><buildtarget>.SHELL</buildtarget></entry> <entry><application>PMake</application> is not constrained to only using the Bourne shell to execute the commands you put in the makefile. You can tell it some other shell to use with this - target. Check out <quote><xref linkend="ashell" - endterm="ashelltitle"/></quote> (<xref - linkend="ashell"/>) for more + target. Check out <quote><xref linkend="ashell" endterm="ashelltitle"/></quote> (<xref linkend="ashell"/>) for more information.</entry> </row> <row valign="top"> - <entry><maketarget>.SILENT</maketarget></entry> + <entry><buildtarget>.SILENT</buildtarget></entry> <entry>When you use - <maketarget>.SILENT</maketarget> as a target, it + <buildtarget>.SILENT</buildtarget> as a target, it applies the <literal>.SILENT</literal> attribute to each of its sources. If there are no sources on the dependency line, then it is as if you gave @@ -996,14 +992,14 @@ MAKELIB : .USE </row> <row valign="top"> - <entry><maketarget>.SUFFIXES</maketarget></entry> + <entry><buildtarget>.SUFFIXES</buildtarget></entry> <entry>This is used to give new file suffixes for <application>PMake</application> to handle. Each source is a suffix <application>PMake</application> should recognize. If you give a - <maketarget>.SUFFIXES</maketarget> dependency line + <buildtarget>.SUFFIXES</buildtarget> dependency line with no sources, <application>PMake</application> will forget about all the suffixes it knew (this also nukes the null suffix). For those @@ -1021,7 +1017,7 @@ MAKELIB : .USE <para>applies the attribute to all the targets listed as sources.</para> </section> - <section id="modyvarex"> + <section xml:id="modyvarex"> <title>Modifying Variable Expansion</title> <para>Variables need not always be expanded verbatim. @@ -1131,7 +1127,7 @@ MAKELIB : .USE <programlisting>OBJS = ../lib/a.o b /usr/lib/libm.a TAILS = $(OBJS:T)</programlisting> - <para>the variable <makevar>TAILS</makevar> would expand + <para>the variable <varname>TAILS</varname> would expand to <literal>a.o b libm.a.</literal></para> </listitem> </varlistentry> @@ -1143,7 +1139,7 @@ TAILS = $(OBJS:T)</programlisting> <para>This is similar to <literal>:T</literal>, except that every word is replaced by everything but the tail (the <quote>head</quote>). Using the same definition of - <makevar>OBJS</makevar>, the string + <varname>OBJS</varname>, the string <literal>$(OBJS:H)</literal> would expand to <literal>../lib /usr/lib.</literal> Note that the final slash on the heads is removed and anything without @@ -1184,7 +1180,7 @@ TAILS = $(OBJS:T)</programlisting> words may be replaced.</para> </section> - <section id="moreexercises"> + <section xml:id="moreexercises"> <title>More Exercises</title> <bridgehead>Exercise 3.1</bridgehead> diff --git a/en_US.ISO8859-1/books/porters-handbook/book.xml b/en_US.ISO8859-1/books/porters-handbook/book.xml index 5f2709929a..f325a8ba76 100644 --- a/en_US.ISO8859-1/books/porters-handbook/book.xml +++ b/en_US.ISO8859-1/books/porters-handbook/book.xml @@ -1,22 +1,20 @@ <?xml version="1.0" encoding="iso-8859-1"?> -<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V4.5-Based Extension//EN" - "../../../share/xml/freebsd45.dtd" [ +<!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" + "../../../share/xml/freebsd50.dtd" [ <!ENTITY values.uses SYSTEM "uses.xml"> <!ENTITY values.versions SYSTEM "versions.xml"> ]> - <!-- The FreeBSD Documentation Project $FreeBSD$ --> - -<book lang='en'> - <bookinfo> - <title>FreeBSD Porter's Handbook</title> +<book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en"> + <info><title>FreeBSD Porter's Handbook</title> + <authorgroup> - <corpauthor>The FreeBSD Documentation Project</corpauthor> + <author><orgname>The FreeBSD Documentation Project</orgname></author> </authorgroup> <pubdate>$FreeBSD$</pubdate> @@ -42,7 +40,7 @@ &legalnotice; - <legalnotice id="trademarks" role="trademarks"> + <legalnotice xml:id="trademarks" role="trademarks"> &tm-attrib.freebsd; &tm-attrib.unix; &tm-attrib.sun; @@ -50,9 +48,9 @@ </legalnotice> <releaseinfo>$FreeBSD$</releaseinfo> - </bookinfo> + </info> - <chapter id="why-port"> + <chapter xml:id="why-port"> <title>Introduction</title> <para>The FreeBSD ports collection is the way almost everyone @@ -67,7 +65,7 @@ </chapter> - <chapter id="own-port"> + <chapter xml:id="own-port"> <title>Making a New Port Yourself</title> <para>So, you are interested in making your own port or @@ -86,7 +84,7 @@ <note> <para>Only a fraction of the variables - (<makevar><replaceable>VAR</replaceable></makevar>) that can + (<varname><replaceable>VAR</replaceable></varname>) that can be overridden are mentioned in this document. Most (if not all) are documented at the start of <filename>/usr/ports/Mk/bsd.port.mk</filename>; the others @@ -101,12 +99,12 @@ <para> Looking for something easy to start with? Take a look at the - <ulink url="http://wiki.freebsd.org/WantedPorts">list of - requested ports</ulink> and see if you can work on one (or + <link xlink:href="http://wiki.freebsd.org/WantedPorts">list of + requested ports</link> and see if you can work on one (or more).</para> </chapter> - <chapter id="quick-porting"> + <chapter xml:id="quick-porting"> <title>Quick Porting</title> <para>This section tells you how to quickly create a new port. In @@ -114,7 +112,7 @@ further on into the document.</para> <para>First, get the original tarball and put it into - <makevar>DISTDIR</makevar>, which defaults to + <varname>DISTDIR</varname>, which defaults to <filename>/usr/ports/distfiles</filename>.</para> <note> @@ -126,18 +124,18 @@ </note> <note> - <para>It is recommended to set the <makevar>DEVELOPER</makevar> + <para>It is recommended to set the <varname>DEVELOPER</varname> &man.make.1; variable in <filename>/etc/make.conf</filename> before getting into porting.</para> - <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> + <screen>&prompt.root; <userinput>echo DEVELOPER=yes >> /etc/make.conf</userinput></screen> <para>This setting enables the <quote>developer mode</quote> that displays deprecation warnings and activates some further quality checks on calling the <command>make</command> command.</para> </note> - <sect1 id="porting-makefile"> + <sect1 xml:id="porting-makefile"> <title>Writing the <filename>Makefile</filename></title> <para>The minimal <filename>Makefile</filename> would look @@ -171,7 +169,7 @@ COMMENT= Cat chasing a mouse all over the screen section.</para> </sect1> - <sect1 id="porting-desc"> + <sect1 xml:id="porting-desc"> <title>Writing the Description Files</title> <para>There are two description files that are required for @@ -275,8 +273,8 @@ lib/X11/oneko/mouse.xpm <filename>pkg-plist</filename> can be omitted from a port. If the port installs just a handful of files, and perhaps directories, the files and directories may be listed in the - variables <makevar>PLIST_FILES</makevar> and - <makevar>PLIST_DIRS</makevar>, respectively, within the + variables <varname>PLIST_FILES</varname> and + <varname>PLIST_DIRS</varname>, respectively, within the port's <filename>Makefile</filename>. For instance, we could get along without <filename>pkg-plist</filename> in the above <filename>oneko</filename> port by adding the @@ -290,17 +288,17 @@ lib/X11/oneko/mouse.xpm lib/X11/oneko/mouse.xpm PLIST_DIRS= lib/X11/oneko</programlisting> - <para>Of course, <makevar>PLIST_DIRS</makevar> should be left + <para>Of course, <varname>PLIST_DIRS</varname> should be left unset if a port installs no directories of its own.</para> <note> <para>Several ports can share a common directory. In that - case, <makevar>PLIST_DIRS</makevar> should be replaced by - <makevar>PLIST_DIRSTRY</makevar> so that the directory is + case, <varname>PLIST_DIRS</varname> should be replaced by + <varname>PLIST_DIRSTRY</varname> so that the directory is removed only if empty, otherwise it is silently ignored. - <makevar>PLIST_DIRS</makevar> and - <makevar>PLIST_DIRSTRY</makevar> are equivalent to using + <varname>PLIST_DIRS</varname> and + <varname>PLIST_DIRSTRY</varname> are equivalent to using <literal>@dirrm</literal> and <literal>@dirrmtry</literal> in <filename>pkg-plist</filename>, as described in <xref linkend="plist-dir-cleaning"/>.</para> @@ -316,13 +314,13 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <filename>pkg-plist</filename>.</para> <para>Later we will see how <filename>pkg-plist</filename> - and <makevar>PLIST_FILES</makevar> can be used to fulfill + and <varname>PLIST_FILES</varname> can be used to fulfill <link linkend="plist">more sophisticated tasks</link>.</para> </sect2> </sect1> - <sect1 id="porting-checksum"> + <sect1 xml:id="porting-checksum"> <title>Creating the Checksum File</title> <para>Just type <command>make makesum</command>. The ports make @@ -332,13 +330,13 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>If a file fetched has its checksum changed regularly and you are certain the source is trusted (i.e., it comes from manufacturer CDs or documentation generated daily), you should - specify these files in the <makevar>IGNOREFILES</makevar> + specify these files in the <varname>IGNOREFILES</varname> variable. Then the checksum is not calculated for that file when you run <command>make makesum</command>, but set to <literal>IGNORE</literal>.</para> </sect1> - <sect1 id="porting-testing"> + <sect1 xml:id="porting-testing"> <title>Testing the Port</title> <para>You should make sure that the port rules do exactly what @@ -358,20 +356,20 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <listitem> <para>The port can be installed using the - <maketarget>install</maketarget> target. This verifies + <buildtarget>install</buildtarget> target. This verifies that the install script works correctly.</para> </listitem> <listitem> <para>The port can be deinstalled properly using the - <maketarget>deinstall</maketarget> target. This verifies + <buildtarget>deinstall</buildtarget> target. This verifies that the deinstall script works correctly.</para> </listitem> <listitem> <para>Make sure that <command>make package</command> can be run as a normal user (that is, not as - <username>root</username>). If that fails, + <systemitem class="username">root</systemitem>). If that fails, <literal>NEED_ROOT=yes</literal> must be added to the port <filename>Makefile</filename>.</para> </listitem> @@ -401,11 +399,11 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </step> <step> - <para><command>pkg_add <replaceable>package-name</replaceable></command></para> + <para><command>pkg_add package-name</command></para> <para>Or, for users of <emphasis>pkg</emphasis>:</para> - <para><command>pkg add <replaceable>package-name</replaceable></command></para> + <para><command>pkg add package-name</command></para> </step> <step> @@ -416,20 +414,20 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>Make certain no warnings are shown in any of the stages.</para> - <para>Thorough automated testing can be done with <filename role="package">ports-mgmt/tinderbox</filename> or - <filename role="package">ports-mgmt/poudriere</filename> from the Ports Collection. + <para>Thorough automated testing can be done with <package>ports-mgmt/tinderbox</package> or + <package>ports-mgmt/poudriere</package> from the Ports Collection. These applications maintain <literal>jails</literal> where all of the steps shown above can be tested without affecting the state of the host system.</para> </sect1> - <sect1 id="porting-portlint"> + <sect1 xml:id="porting-portlint"> <title>Checking Your Port with <command>portlint</command></title> <para>Please use <command>portlint</command> to see if your port conforms to our guidelines. The - <filename role="package">ports-mgmt/portlint</filename> + <package>ports-mgmt/portlint</package> program is part of the ports collection. In particular, you may want to check if the <link linkend="porting-samplem">Makefile</link> is in the @@ -438,7 +436,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> appropriately.</para> </sect1> - <sect1 id="porting-submitting"> + <sect1 xml:id="porting-submitting"> <title>Submitting the New Port</title> <para>Before you submit the new port, make sure you have read @@ -458,16 +456,15 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>Include your <literal>oneko.shar</literal> file in a bug report and send it with the &man.send-pr.1; program (see - <ulink - url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</ulink> for more information + <link xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug + Reports and General Commentary</link> for more information about &man.send-pr.1;). Be sure to classify the bug report as category <literal>ports</literal> and class <literal>change-request</literal> (Do not mark the report <literal>confidential</literal>!). Also add a short description of the program you ported to the <quote>Description</quote> field of the PR (e.g., perhaps a - short version of the <makevar>COMMENT</makevar>), and add + short version of the <varname>COMMENT</varname>), and add the shar file to the <quote>Fix</quote> field.</para> <note> @@ -489,19 +486,17 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>After you have submitted your port, please be patient. Sometimes it can take a few months before a port is included in &os;, although it might only take a few days. You can - view the list of <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports - PRs waiting to be committed to &os;</ulink>.</para> + view the list of <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?category=ports">ports + PRs waiting to be committed to &os;</link>.</para> <para>Once we have looked at your port, we will get back to you if necessary, and put it in the tree. Your name will also - be added to the list of <ulink - url="&url.articles.contributors;/contrib-additional.html">Additional - FreeBSD Contributors</ulink> and other files.</para> + be added to the list of <link xlink:href="&url.articles.contributors;/contrib-additional.html">Additional + FreeBSD Contributors</link> and other files.</para> </sect1> </chapter> - <chapter id="slow"> + <chapter xml:id="slow"> <title>Slow Porting</title> <para>Ok, so it was not that simple, and the port required some @@ -509,7 +504,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> explain, step by step, how to modify it to get it to work with the ports paradigm.</para> - <sect1 id="slow-work"> + <sect1 xml:id="slow-work"> <title>How Things Work</title> <para>First, this is the sequence of events which occurs when @@ -524,44 +519,44 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <procedure> <step> - <para>The <maketarget>fetch</maketarget> target is run. The - <maketarget>fetch</maketarget> target is responsible for + <para>The <buildtarget>fetch</buildtarget> target is run. The + <buildtarget>fetch</buildtarget> target is responsible for making sure that the tarball exists locally in - <makevar>DISTDIR</makevar>. If - <maketarget>fetch</maketarget> cannot find the required - files in <makevar>DISTDIR</makevar> it will look up the - URL <makevar>MASTER_SITES</makevar>, which is set in the + <varname>DISTDIR</varname>. If + <buildtarget>fetch</buildtarget> cannot find the required + files in <varname>DISTDIR</varname> it will look up the + URL <varname>MASTER_SITES</varname>, which is set in the Makefile, as well as our FTP mirrors where we put distfiles as backup. It will then attempt to fetch the named distribution file with - <makevar>FETCH</makevar>, assuming that the requesting + <varname>FETCH</varname>, assuming that the requesting site has direct access to the Internet. If that succeeds, - it will save the file in <makevar>DISTDIR</makevar> for + it will save the file in <varname>DISTDIR</varname> for future use and proceed.</para> </step> <step> - <para>The <maketarget>extract</maketarget> target is run. + <para>The <buildtarget>extract</buildtarget> target is run. It looks for your port's distribution file (typically a <command>gzip</command>ped tarball) in - <makevar>DISTDIR</makevar> and unpacks it into a temporary - subdirectory specified by <makevar>WRKDIR</makevar> + <varname>DISTDIR</varname> and unpacks it into a temporary + subdirectory specified by <varname>WRKDIR</varname> (defaults to <filename>work</filename>).</para> </step> <step> - <para>The <maketarget>patch</maketarget> target is run. + <para>The <buildtarget>patch</buildtarget> target is run. First, any patches defined in - <makevar>PATCHFILES</makevar> are applied. Second, if any + <varname>PATCHFILES</varname> are applied. Second, if any patch files named - <filename>patch-<replaceable>*</replaceable></filename> - are found in <makevar>PATCHDIR</makevar> (defaults to the + <filename>patch-*</filename> + are found in <varname>PATCHDIR</varname> (defaults to the <filename>files</filename> subdirectory), they are applied at this time in alphabetical order.</para> </step> <step> - <para>The <maketarget>configure</maketarget> target is run. + <para>The <buildtarget>configure</buildtarget> target is run. This can do any one of many different things.</para> <orderedlist> @@ -571,9 +566,9 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </listitem> <listitem> - <para>If <makevar>HAS_CONFIGURE</makevar> or - <makevar>GNU_CONFIGURE</makevar> is set, - <filename><makevar>WRKSRC</makevar>/configure</filename> + <para>If <varname>HAS_CONFIGURE</varname> or + <varname>GNU_CONFIGURE</varname> is set, + <filename>WRKSRC/configure</filename> is run.</para> </listitem> @@ -581,23 +576,22 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </step> <step> - <para>The <maketarget>build</maketarget> target is run. + <para>The <buildtarget>build</buildtarget> target is run. This is responsible for descending into the port's private - working directory (<makevar>WRKSRC</makevar>) and building + working directory (<varname>WRKSRC</varname>) and building it.</para> </step> <step> - <para>The <maketarget>stage</maketarget> target is run. This + <para>The <buildtarget>stage</buildtarget> target is run. This puts the final set of built files into a temporary directory - (<makevar>STAGEDIR</makevar>, see <xref - linkend="staging"/>). The hierarchy of this directory + (<varname>STAGEDIR</varname>, see <xref linkend="staging"/>). The hierarchy of this directory mirrors that of the system on which the package will be installed.</para> </step> <step> - <para>The <maketarget>install</maketarget> target is run. + <para>The <buildtarget>install</buildtarget> target is run. This copies the files listed in the port's pkg-plist to the host system.</para> </step> @@ -605,19 +599,19 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>The above are the default actions. In addition, you can define targets - <maketarget>pre-<replaceable>something</replaceable></maketarget> + <buildtarget>pre-<replaceable>something</replaceable></buildtarget> or - <maketarget>post-<replaceable>something</replaceable></maketarget>, + <buildtarget>post-<replaceable>something</replaceable></buildtarget>, or put scripts with those names, in the <filename>scripts</filename> subdirectory, and they will be run before or after the default actions are done.</para> <para>For example, if you have a - <maketarget>post-extract</maketarget> target defined in your + <buildtarget>post-extract</buildtarget> target defined in your <filename>Makefile</filename>, and a file <filename>pre-build</filename> in the <filename>scripts</filename> subdirectory, the - <maketarget>post-extract</maketarget> target will be called + <buildtarget>post-extract</buildtarget> target will be called after the regular extraction actions, and the <filename>pre-build</filename> script will be executed before the default build rules are done. It is recommended that you @@ -627,46 +621,46 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>The default actions are done by the <filename>bsd.port.mk</filename> targets - <maketarget>do-<replaceable>something</replaceable></maketarget>. + <buildtarget>do-<replaceable>something</replaceable></buildtarget>. For example, the commands to extract a port are in the target - <maketarget>do-extract</maketarget>. If you are not happy + <buildtarget>do-extract</buildtarget>. If you are not happy with the default target, you can fix it by redefining the - <maketarget>do-<replaceable>something</replaceable></maketarget> + <buildtarget>do-<replaceable>something</replaceable></buildtarget> target in your <filename>Makefile</filename>.</para> <note> <para>The <quote>main</quote> targets (e.g., - <maketarget>extract</maketarget>, - <maketarget>configure</maketarget>, etc.) do nothing more + <buildtarget>extract</buildtarget>, + <buildtarget>configure</buildtarget>, etc.) do nothing more than make sure all the stages up to that one are completed and call the real targets or scripts, and they are not intended to be changed. If you want to fix the extraction, - fix <maketarget>do-extract</maketarget>, but never ever - change the way <maketarget>extract</maketarget> + fix <buildtarget>do-extract</buildtarget>, but never ever + change the way <buildtarget>extract</buildtarget> operates! Additionally, the target - <maketarget>post-deinstall</maketarget> is invalid and + <buildtarget>post-deinstall</buildtarget> is invalid and is not run by the ports infrastructure.</para> </note> <para>Now that you understand what goes on when the user types - <command>make <maketarget>install</maketarget></command>, let + <command>make install</command>, let us go through the recommended steps to create the perfect port.</para> </sect1> - <sect1 id="slow-sources"> + <sect1 xml:id="slow-sources"> <title>Getting the Original Sources</title> <para>Get the original sources (normally) as a compressed tarball - (<filename><replaceable>foo</replaceable>.tar.gz</filename> or - <filename><replaceable>foo</replaceable>.tar.bz2</filename>) - and copy it into <makevar>DISTDIR</makevar>. Always use + (<filename>foo.tar.gz</filename> or + <filename>foo.tar.bz2</filename>) + and copy it into <varname>DISTDIR</varname>. Always use <emphasis>mainstream</emphasis> sources when and where you can.</para> <para>You will need to set the variable - <makevar>MASTER_SITES</makevar> to reflect where the original + <varname>MASTER_SITES</varname> to reflect where the original tarball resides. You will find convenient shorthand definitions for most mainstream sites in <filename>bsd.sites.mk</filename>. Please use these @@ -684,20 +678,20 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <para>If you cannot find somewhere convenient and reliable to put the distfile we can <quote>house</quote> it ourselves on - <hostid>ftp.FreeBSD.org</hostid>; however, this is the + <systemitem>ftp.FreeBSD.org</systemitem>; however, this is the least-preferred solution. The distfile must be placed into <filename>~/public_distfiles/</filename> of someone's - <hostid>freefall</hostid> account. Ask the person who commits + <systemitem>freefall</systemitem> account. Ask the person who commits your port to do this. This person will also set - <makevar>MASTER_SITES</makevar> to - <makevar>MASTER_SITE_LOCAL</makevar> and - <makevar>MASTER_SITE_SUBDIR</makevar> to their - <hostid>freefall</hostid> username.</para> + <varname>MASTER_SITES</varname> to + <varname>MASTER_SITE_LOCAL</varname> and + <varname>MASTER_SITE_SUBDIR</varname> to their + <systemitem>freefall</systemitem> username.</para> <para>If your port's distfile changes all the time without any kind of version update by the author, consider putting the distfile on your home page and listing it as the first - <makevar>MASTER_SITES</makevar>. If you can, try to talk the + <varname>MASTER_SITES</varname>. If you can, try to talk the port author out of doing this; it really does help to establish some kind of source code control. Hosting your own version will prevent users from getting @@ -705,18 +699,18 @@ PLIST_DIRS= lib/X11/oneko</programlisting> reduce the workload of maintainers of our FTP site. Also, if there is only one master site for the port, it is recommended that you house a backup at your site and list it as the second - <makevar>MASTER_SITES</makevar>.</para> + <varname>MASTER_SITES</varname>.</para> <para>If your port requires some additional `patches' that are available on the Internet, fetch them too and put them in - <makevar>DISTDIR</makevar>. Do not worry if they come from a + <varname>DISTDIR</varname>. Do not worry if they come from a site other than where you got the main source tarball, we have a way to handle these situations (see the description of <link linkend="porting-patchfiles">PATCHFILES</link> below).</para> </sect1> - <sect1 id="slow-modifying"> + <sect1 xml:id="slow-modifying"> <title>Modifying the Port</title> <para>Unpack a copy of the tarball in a private directory and @@ -745,28 +739,28 @@ PLIST_DIRS= lib/X11/oneko</programlisting> </note> </sect1> - <sect1 id="slow-patch"> + <sect1 xml:id="slow-patch"> <title>Patching</title> <para>In the preparation of the port, files that have been added or changed can be picked up with a &man.diff.1; for later feeding to &man.patch.1;. Each patch you wish to apply should be saved into a file named - <filename>patch-<replaceable>*</replaceable></filename> where + <filename>patch-*</filename> where <replaceable>*</replaceable> indicates the pathname of the file that is patched, such as <filename>patch-Imakefile</filename> or <filename>patch-src-config.h</filename>. These files should - be stored in <makevar>PATCHDIR</makevar> (usually + be stored in <varname>PATCHDIR</varname> (usually <filename>files/</filename>, from where they will be automatically applied. All patches must be relative to - <makevar>WRKSRC</makevar> (generally the directory your port's + <varname>WRKSRC</varname> (generally the directory your port's tarball unpacks itself into, that being where the build is done). To make fixes and upgrades easier, you should avoid having more than one patch fix the same file (e.g., <filename>patch-file</filename> and <filename>patch-file2</filename> both changing - <filename><makevar>WRKSRC</makevar>/foobar.c</filename>). + <filename>WRKSRC/foobar.c</filename>). Note that if the path of a patched file contains an underscore (<literal>_</literal>) character, the patch needs to have two underscores instead in its name. For example, to patch a file @@ -817,7 +811,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> at all.</para> <para>If you had to delete a file, then you can do it in the - <maketarget>post-extract</maketarget> target rather than as + <buildtarget>post-extract</buildtarget> target rather than as part of the patch.</para> <para>Simple replacements can be performed directly from the @@ -840,7 +834,7 @@ PLIST_DIRS= lib/X11/oneko</programlisting> <programlisting>USE_DOS2UNIX= util.c util.h</programlisting> <para>If you want to convert a group of files across - subdirectories, <makevar>DOS2UNIX_REGEX</makevar> can be used. + subdirectories, <varname>DOS2UNIX_REGEX</varname> can be used. Its argument is a <command>find</command> compatible regular expression. More on the format is in &man.re.format.7;. This option is useful for converting all files of a given @@ -853,13 +847,12 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>If you want to create a patch file based off of an existing file, you can copy it with an <filename>.orig</filename> extension, and then modify the - original one. The <maketarget>makepatch</maketarget> target - will write out an appropriate patch file to the <filename - class="directory">files</filename> directory of the + original one. The <buildtarget>makepatch</buildtarget> target + will write out an appropriate patch file to the <filename>files</filename> directory of the port.</para> </sect1> - <sect1 id="slow-configure"> + <sect1 xml:id="slow-configure"> <title>Configuring</title> <para>Include any additional customization commands in your @@ -871,11 +864,11 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <filename>post-configure</filename>.</para> </sect1> - <sect1 id="slow-user-input"> + <sect1 xml:id="slow-user-input"> <title>Handling User Input</title> <para>If your port requires user input to build, configure, or - install, you must set <makevar>IS_INTERACTIVE</makevar> in + install, you must set <varname>IS_INTERACTIVE</varname> in your <filename>Makefile</filename>. This will allow <quote>overnight builds</quote> to skip your port if the user sets the variable <envar>BATCH</envar> in his environment (and @@ -886,13 +879,13 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>It is also recommended that if there are reasonable default answers to the questions, you check the - <makevar>PACKAGE_BUILDING</makevar> variable and turn off the + <varname>PACKAGE_BUILDING</varname> variable and turn off the interactive script when it is set. This will allow us to build the packages for CDROMs and FTP.</para> </sect1> </chapter> - <chapter id="makefile"> + <chapter xml:id="makefile"> <title>Configuring the Makefile</title> <para>Configuring the <filename>Makefile</filename> is pretty @@ -906,28 +899,28 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>Now, consider the following problems in sequence as you design your new <filename>Makefile</filename>:</para> - <sect1 id="makefile-source"> + <sect1 xml:id="makefile-source"> <title>The Original Source</title> - <para>Does it live in <makevar>DISTDIR</makevar> as a standard + <para>Does it live in <varname>DISTDIR</varname> as a standard <command>gzip</command>ped tarball named something like <filename>foozolix-1.2.tar.gz</filename>? If so, you can go on to the next step. If not, you should look at overriding any - of the <makevar>DISTVERSION</makevar>, - <makevar>DISTNAME</makevar>, <makevar>EXTRACT_CMD</makevar>, - <makevar>EXTRACT_BEFORE_ARGS</makevar>, - <makevar>EXTRACT_AFTER_ARGS</makevar>, - <makevar>EXTRACT_SUFX</makevar>, or - <makevar>DISTFILES</makevar> variables, depending on how alien + of the <varname>DISTVERSION</varname>, + <varname>DISTNAME</varname>, <varname>EXTRACT_CMD</varname>, + <varname>EXTRACT_BEFORE_ARGS</varname>, + <varname>EXTRACT_AFTER_ARGS</varname>, + <varname>EXTRACT_SUFX</varname>, or + <varname>DISTFILES</varname> variables, depending on how alien a format your port's distribution file is.</para> <para>In the worst case, you can simply create your own - <maketarget>do-extract</maketarget> target to override the + <buildtarget>do-extract</buildtarget> target to override the default, though this should be rarely, if ever, necessary.</para> </sect1> - <sect1 id="makefile-naming"> + <sect1 xml:id="makefile-naming"> <title>Naming</title> <para>The first part of the port's <filename>Makefile</filename> @@ -935,36 +928,36 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> in the correct category.</para> <sect2> - <title><makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar></title> + <title><varname>PORTNAME</varname> and + <varname>PORTVERSION</varname></title> - <para>You should set <makevar>PORTNAME</makevar> to the - base name of your port, and <makevar>PORTVERSION</makevar> + <para>You should set <varname>PORTNAME</varname> to the + base name of your port, and <varname>PORTVERSION</varname> to the version number of the port.</para> </sect2> - <sect2 id="makefile-naming-revepoch"> - <title><makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar></title> + <sect2 xml:id="makefile-naming-revepoch"> + <title><varname>PORTREVISION</varname> and + <varname>PORTEPOCH</varname></title> <sect3> - <title><makevar>PORTREVISION</makevar></title> + <title><varname>PORTREVISION</varname></title> - <para>The <makevar>PORTREVISION</makevar> variable is a + <para>The <varname>PORTREVISION</varname> variable is a monotonically increasing value which is reset to 0 with - every increase of <makevar>PORTVERSION</makevar> (i.e., + every increase of <varname>PORTVERSION</varname> (i.e., every time a new official vendor release is made), and appended to the package name if non-zero. Changes to - <makevar>PORTREVISION</makevar> are used by automated + <varname>PORTREVISION</varname> are used by automated tools (e.g., &man.pkg.version.1;) to highlight the fact that a new package is available.</para> - <para><makevar>PORTREVISION</makevar> should be increased + <para><varname>PORTREVISION</varname> should be increased each time a change is made to the port which significantly affects the content or structure of the derived package.</para> - <para>Examples of when <makevar>PORTREVISION</makevar> + <para>Examples of when <varname>PORTREVISION</varname> should be bumped:</para> <itemizedlist> @@ -1000,14 +993,14 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> significant functional differences, i.e., changes to the distfile requiring a correction to <filename>distinfo</filename> with no corresponding - change to <makevar>PORTVERSION</makevar>, where a + change to <varname>PORTVERSION</varname>, where a <command>diff -ru</command> of the old and new versions shows non-trivial changes to the code.</para> </listitem> </itemizedlist> <para>Examples of changes which do not require a - <makevar>PORTREVISION</makevar> bump:</para> + <varname>PORTREVISION</varname> bump:</para> <itemizedlist> <listitem> @@ -1017,7 +1010,7 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> </listitem> <listitem> - <para>Changes to <makevar>MASTER_SITES</makevar> or + <para>Changes to <varname>MASTER_SITES</varname> or other functional changes to the port which do not affect the resulting package.</para> </listitem> @@ -1034,10 +1027,10 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> compilable where it was previously failing (as long as the changes do not introduce any functional change on any other platforms on which the port did previously - build). Since <makevar>PORTREVISION</makevar> + build). Since <varname>PORTREVISION</varname> reflects the content of the package, if the package was not previously buildable then there is no need to - increase <makevar>PORTREVISION</makevar> to mark a + increase <varname>PORTREVISION</varname> to mark a change.</para> </listitem> </itemizedlist> @@ -1049,11 +1042,11 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> at all), and weigh that against that fact that it will cause everyone who regularly updates their ports tree to be compelled to update. If yes, the - <makevar>PORTREVISION</makevar> should be bumped.</para> + <varname>PORTREVISION</varname> should be bumped.</para> </sect3> <sect3> - <title><makevar>PORTEPOCH</makevar></title> + <title><varname>PORTEPOCH</varname></title> <para>From time to time a software vendor or FreeBSD porter will do something silly and release a version of their @@ -1071,13 +1064,13 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <command>pkg version -t</command>. For example:</para> <screen>&prompt.user; <userinput>pkg_version -t 0.031 0.29</userinput> -></screen> +></screen> <para>Or, for <application>pkgng</application> users:</para> <screen>&prompt.user; <userinput>pkg version -t 0.031 0.29</userinput> -></screen> +></screen> <para>The <literal>></literal> output indicates that version 0.031 is considered greater than version 0.29, @@ -1085,10 +1078,10 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> </tip> <para>In situations such as this, the - <makevar>PORTEPOCH</makevar> version should be increased. - If <makevar>PORTEPOCH</makevar> is nonzero it is appended + <varname>PORTEPOCH</varname> version should be increased. + If <varname>PORTEPOCH</varname> is nonzero it is appended to the package name as described in section 0 above. - <makevar>PORTEPOCH</makevar> must never be decreased or + <varname>PORTEPOCH</varname> must never be decreased or reset to zero, because that would cause comparison to a package from an earlier epoch to fail (i.e., the package would not be detected as out of date): the new version @@ -1099,15 +1092,15 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> greater than the implied suffix <literal>,0</literal> on the earlier package.</para> - <para>Dropping or resetting <makevar>PORTEPOCH</makevar> + <para>Dropping or resetting <varname>PORTEPOCH</varname> incorrectly leads to no end of grief; if you do not understand the above discussion, please keep after it until you do, or ask questions on the mailing lists.</para> - <para>It is expected that <makevar>PORTEPOCH</makevar> will + <para>It is expected that <varname>PORTEPOCH</varname> will not be used for the majority of ports, and that sensible - use of <makevar>PORTVERSION</makevar> can often preempt it + use of <varname>PORTVERSION</varname> can often preempt it becoming necessary if a future release of the software should change the version structure. However, care is needed by FreeBSD porters when a vendor release is made @@ -1120,14 +1113,14 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <para>For example, if a snapshot release is made on the date 20000917, and the previous version of the software was version 1.2, the snapshot release should be given a - <makevar>PORTVERSION</makevar> of 1.2.20000917 or similar, + <varname>PORTVERSION</varname> of 1.2.20000917 or similar, not 20000917, so that the succeeding release, say 1.3, is still a numerically greater value.</para> </sect3> <sect3> - <title>Example of <makevar>PORTREVISION</makevar> and - <makevar>PORTEPOCH</makevar> Usage</title> + <title>Example of <varname>PORTREVISION</varname> and + <varname>PORTEPOCH</varname> Usage</title> <para>The <literal>gtkmumble</literal> port, version <literal>0.10</literal>, is committed to the ports @@ -1136,18 +1129,18 @@ DOS2UNIX_REGEX= .*\.(c|cpp|h)</programlisting> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.10</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.10</literal>.</para> <para>A security hole is discovered which requires a local - FreeBSD patch. <makevar>PORTREVISION</makevar> is bumped + FreeBSD patch. <varname>PORTREVISION</varname> is bumped accordingly.</para> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.10 PORTREVISION= 1</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.10_1</literal></para> <para>A new version is released by the vendor, numbered @@ -1157,72 +1150,72 @@ PORTREVISION= 1</programlisting> <quote>what comes after 0.9</quote> - oops, too late now). Since the new minor version <literal>2</literal> is numerically less than the previous version - <literal>10</literal>, the <makevar>PORTEPOCH</makevar> + <literal>10</literal>, the <varname>PORTEPOCH</varname> must be bumped to manually force the new package to be detected as <quote>newer</quote>. Since it is a new vendor release of the code, - <makevar>PORTREVISION</makevar> is reset to 0 (or removed + <varname>PORTREVISION</varname> is reset to 0 (or removed from the <filename>Makefile</filename>).</para> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.2 PORTEPOCH= 1</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.2,1</literal></para> <para>The next release is 0.3. Since - <makevar>PORTEPOCH</makevar> never decreases, the version + <varname>PORTEPOCH</varname> never decreases, the version variables are now:</para> <programlisting>PORTNAME= gtkmumble PORTVERSION= 0.3 PORTEPOCH= 1</programlisting> - <para><makevar>PKGNAME</makevar> becomes + <para><varname>PKGNAME</varname> becomes <literal>gtkmumble-0.3,1</literal></para> <note> - <para>If <makevar>PORTEPOCH</makevar> were reset to + <para>If <varname>PORTEPOCH</varname> were reset to <literal>0</literal> with this upgrade, someone who had installed the <literal>gtkmumble-0.10_1</literal> package would not detect the <literal>gtkmumble-0.3</literal> package as newer, since <literal>3</literal> is still numerically less than <literal>10</literal>. Remember, this is the whole - point of <makevar>PORTEPOCH</makevar> in the first + point of <varname>PORTEPOCH</varname> in the first place.</para> </note> </sect3> </sect2> <sect2> - <title><makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar></title> - - <para>Two optional variables, <makevar>PKGNAMEPREFIX</makevar> - and <makevar>PKGNAMESUFFIX</makevar>, are combined with - <makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar> to form - <makevar>PKGNAME</makevar> as + <title><varname>PKGNAMEPREFIX</varname> and + <varname>PKGNAMESUFFIX</varname></title> + + <para>Two optional variables, <varname>PKGNAMEPREFIX</varname> + and <varname>PKGNAMESUFFIX</varname>, are combined with + <varname>PORTNAME</varname> and + <varname>PORTVERSION</varname> to form + <varname>PKGNAME</varname> as <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. Make sure this conforms to our <link linkend="porting-pkgname">guidelines for a good package name</link>. In particular, you are <emphasis>not</emphasis> allowed to use a hyphen - (<literal>-</literal>) in <makevar>PORTVERSION</makevar>. + (<literal>-</literal>) in <varname>PORTVERSION</varname>. Also, if the package name has the <replaceable>language-</replaceable> or the <replaceable>-compiled.specifics</replaceable> part (see - below), use <makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar>, respectively. Do not make - them part of <makevar>PORTNAME</makevar>.</para> + below), use <varname>PKGNAMEPREFIX</varname> and + <varname>PKGNAMESUFFIX</varname>, respectively. Do not make + them part of <varname>PORTNAME</varname>.</para> </sect2> <sect2> - <title><makevar>LATEST_LINK</makevar></title> + <title><varname>LATEST_LINK</varname></title> - <para><makevar>LATEST_LINK</makevar> is used during package + <para><varname>LATEST_LINK</varname> is used during package building to determine a shortened name to create links that can be used by <command>pkg_add -r</command>. This makes it possible to, for example, install the latest perl version by @@ -1234,16 +1227,16 @@ PORTEPOCH= 1</programlisting> present in the ports collection at the same time. Both the index build and the package build system need to be able to see them as different, independent ports, although they may - all have the same <makevar>PORTNAME</makevar>, - <makevar>PKGNAMEPREFIX</makevar>, and even - <makevar>PKGNAMESUFFIX</makevar>. In those cases, the - optional <makevar>LATEST_LINK</makevar> variable should be + all have the same <varname>PORTNAME</varname>, + <varname>PKGNAMEPREFIX</varname>, and even + <varname>PKGNAMESUFFIX</varname>. In those cases, the + optional <varname>LATEST_LINK</varname> variable should be set to a different value for all ports except the <quote>main</quote> one — see the <filename>lang/gcc46</filename> and <filename>lang/gcc</filename> ports, and the <filename>www/apache*</filename> family for examples of its - use. By setting <makevar>NO_LATEST_LINK</makevar>, no link + use. By setting <varname>NO_LATEST_LINK</varname>, no link will be generated, which may be an option for all but the <quote>main</quote> version. Note that how to choose a <quote>main</quote> version — @@ -1254,7 +1247,7 @@ PORTEPOCH= 1</programlisting> picked a <quote>main</quote> one.</para> </sect2> - <sect2 id="porting-pkgname"> + <sect2 xml:id="porting-pkgname"> <title>Package Naming Conventions</title> <para>The following are the conventions you should follow in @@ -1263,7 +1256,7 @@ PORTEPOCH= 1</programlisting> users are going to turn away if they hurt their eyes!</para> <para>The package name should look like - <filename><replaceable><optional>language<optional>_region</optional></optional>-name<optional><optional>-</optional>compiled.specifics</optional>-version.numbers</replaceable></filename>.</para> + <filename>language_region-name-compiled.specifics-version.numbers</filename>.</para> <para>The package name is defined as <literal>${PKGNAMEPREFIX}${PORTNAME}${PKGNAMESUFFIX}-${PORTVERSION}</literal>. @@ -1289,7 +1282,7 @@ PORTEPOCH= 1</programlisting> French.</para> <para>The <replaceable>language-</replaceable> part should - be set in the <makevar>PKGNAMEPREFIX</makevar> + be set in the <varname>PKGNAMEPREFIX</varname> variable.</para> </listitem> @@ -1309,27 +1302,26 @@ PORTEPOCH= 1</programlisting> <listitem> <para>Make sure that the port's name and version are clearly separated and placed into the - <makevar>PORTNAME</makevar> and - <makevar>PORTVERSION</makevar> variables. The only - reason for <makevar>PORTNAME</makevar> to contain a + <varname>PORTNAME</varname> and + <varname>PORTVERSION</varname> variables. The only + reason for <varname>PORTNAME</varname> to contain a version part is if the upstream distribution is really named that way, as in the <filename>textproc/libxml2</filename> or <filename>japanese/kinput2-freewnn</filename> ports. - Otherwise, the <makevar>PORTNAME</makevar> should not + Otherwise, the <varname>PORTNAME</varname> should not contain any version-specific information. It is quite normal for several ports to have the same - <makevar>PORTNAME</makevar>, as the + <varname>PORTNAME</varname>, as the <filename>www/apache*</filename> ports do; in that case, different versions (and different index entries) are - distinguished by the <makevar>PKGNAMEPREFIX</makevar>, - <makevar>PKGNAMESUFFIX</makevar>, and - <makevar>LATEST_LINK</makevar> values.</para> + distinguished by the <varname>PKGNAMEPREFIX</varname>, + <varname>PKGNAMESUFFIX</varname>, and + <varname>LATEST_LINK</varname> values.</para> </listitem> <listitem> - <para>If the port can be built with different <link - linkend="makefile-masterdir">hardcoded defaults</link> + <para>If the port can be built with different <link linkend="makefile-masterdir">hardcoded defaults</link> (usually part of the directory name in a family of ports), the <replaceable>-compiled.specifics</replaceable> part @@ -1339,7 +1331,7 @@ PORTEPOCH= 1</programlisting> <para>The <replaceable>-compiled.specifics</replaceable> part should be set in the - <makevar>PKGNAMESUFFIX</makevar> variable.</para> + <varname>PKGNAMESUFFIX</varname> variable.</para> </listitem> <listitem> @@ -1364,16 +1356,16 @@ PORTEPOCH= 1</programlisting> looking at the version string. In particular, make sure version number components are always delimited by a period, and if the date is part of the string, use the - <literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> + <literal>0.0.yyyy.mm.dd</literal> format, not - <literal><replaceable>dd</replaceable>.<replaceable>mm</replaceable>.<replaceable>yyyy</replaceable></literal> + <literal>dd.mm.yyyy</literal> or the non-Y2K compliant - <literal><replaceable>yy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal> + <literal>yy.mm.dd</literal> format. It is important to prefix the version with <literal>0.0.</literal> in case a release with an actual version number is made, which would of course be numerically less than - <literal><replaceable>yyyy</replaceable></literal>.</para> + <literal>yyyy</literal>.</para> </listitem> </orderedlist> @@ -1386,10 +1378,10 @@ PORTEPOCH= 1</programlisting> <thead> <row> <entry>Distribution Name</entry> - <entry><makevar>PKGNAMEPREFIX</makevar></entry> - <entry><makevar>PORTNAME</makevar></entry> - <entry><makevar>PKGNAMESUFFIX</makevar></entry> - <entry><makevar>PORTVERSION</makevar></entry> + <entry><varname>PKGNAMEPREFIX</varname></entry> + <entry><varname>PORTNAME</varname></entry> + <entry><varname>PKGNAMESUFFIX</varname></entry> + <entry><varname>PORTVERSION</varname></entry> <entry>Reason</entry> </row> </thead> @@ -1517,23 +1509,23 @@ PORTEPOCH= 1</programlisting> version string to <literal>1.0</literal> (like the <literal>piewm</literal> example above). Otherwise, ask the original author or use the date string - (<literal>0.0.<replaceable>yyyy</replaceable>.<replaceable>mm</replaceable>.<replaceable>dd</replaceable></literal>) + (<literal>0.0.yyyy.mm.dd</literal>) as the version.</para> </sect2> </sect1> - <sect1 id="makefile-categories"> + <sect1 xml:id="makefile-categories"> <title>Categorization</title> <sect2> - <title><makevar>CATEGORIES</makevar></title> + <title><varname>CATEGORIES</varname></title> <para>When a package is created, it is put under <filename>/usr/ports/packages/All</filename> and links are made from one or more subdirectories of <filename>/usr/ports/packages</filename>. The names of these subdirectories are specified by the variable - <makevar>CATEGORIES</makevar>. It is intended to make life + <varname>CATEGORIES</varname>. It is intended to make life easier for the user when he is wading through the pile of packages on the FTP site or the CDROM. Please take a look at the <link linkend="porting-categories">current list of @@ -1548,7 +1540,7 @@ PORTEPOCH= 1</programlisting> discussion about how to pick the right categories.</para> </sect2> - <sect2 id="porting-categories"> + <sect2 xml:id="porting-categories"> <title>Current List of Categories</title> <para>Here is the current list of port categories. Those @@ -1560,7 +1552,7 @@ PORTEPOCH= 1</programlisting> <note> <para>For non-virtual categories, you will find a one-line - description in the <makevar>COMMENT</makevar> in that + description in the <varname>COMMENT</varname> in that subdirectory's <filename>Makefile</filename>.</para> </note> @@ -1578,63 +1570,62 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>accessibility</filename></entry> <entry>Ports to help disabled users.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>afterstep*</filename></entry> - <entry>Ports to support the <ulink - url="http://www.afterstep.org">AfterStep</ulink> + <entry>Ports to support the <link xlink:href="http://www.afterstep.org">AfterStep</link> window manager.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>arabic</filename></entry> <entry>Arabic language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>archivers</filename></entry> <entry>Archiving tools.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>astro</filename></entry> <entry>Astronomical ports.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>audio</filename></entry> <entry>Sound support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>benchmarks</filename></entry> <entry>Benchmarking utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>biology</filename></entry> <entry>Biology-related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>cad</filename></entry> <entry>Computer aided design tools.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>chinese</filename></entry> <entry>Chinese language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1647,20 +1638,20 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>converters</filename></entry> <entry>Character code converters.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>databases</filename></entry> <entry>Databases.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>deskutils</filename></entry> <entry>Things that used to be on the desktop before computers were invented.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1675,13 +1666,13 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>dns</filename></entry> <entry>DNS-related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>docs*</filename></entry> <entry>Meta-ports for FreeBSD documentation.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1695,7 +1686,7 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>elisp*</filename></entry> <entry>Emacs-lisp ports.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1713,13 +1704,13 @@ PORTEPOCH= 1</programlisting> <entry><filename>finance</filename></entry> <entry>Monetary, financial and related applications.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>french</filename></entry> <entry>French language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1733,83 +1724,83 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>games</filename></entry> <entry>Games.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>geography*</filename></entry> <entry>Geography-related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>german</filename></entry> <entry>German language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>gnome*</filename></entry> <entry>Ports from the - <ulink url="http://www.gnome.org">GNOME</ulink> + <link xlink:href="http://www.gnome.org">GNOME</link> Project.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>gnustep*</filename></entry> <entry>Software related to the GNUstep desktop environment.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>graphics</filename></entry> <entry>Graphics utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>hamradio*</filename></entry> <entry>Software for amateur radio.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>haskell*</filename></entry> <entry>Software related to the Haskell language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>hebrew</filename></entry> <entry>Hebrew language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>hungarian</filename></entry> <entry>Hungarian language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>ipv6*</filename></entry> <entry>IPv6 related software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>irc</filename></entry> <entry>Internet Relay Chat utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>japanese</filename></entry> <entry>Japanese language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1826,59 +1817,59 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>kde*</filename></entry> <entry>Ports from the - <ulink url="http://www.kde.org">KDE</ulink> + <link xlink:href="http://www.kde.org">KDE</link> Project.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>kld*</filename></entry> <entry>Kernel loadable modules.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>korean</filename></entry> <entry>Korean language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>lang</filename></entry> <entry>Programming languages.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>linux*</filename></entry> <entry>Linux applications and support utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>lisp*</filename></entry> <entry>Software related to the Lisp language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>mail</filename></entry> <entry>Mail software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>math</filename></entry> <entry>Numerical computation software and other utilities for mathematics.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>mbone*</filename></entry> <entry>MBone applications.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1893,59 +1884,58 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>multimedia</filename></entry> <entry>Multimedia software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net</filename></entry> <entry>Miscellaneous networking software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net-im</filename></entry> <entry>Instant messaging software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net-mgmt</filename></entry> <entry>Networking management software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>net-p2p</filename></entry> <entry>Peer to peer network applications.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>news</filename></entry> <entry>USENET news software.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>palm</filename></entry> - <entry>Software support for the <ulink - url="http://www.palm.com/">Palm™</ulink> + <entry>Software support for the <link xlink:href="http://www.palm.com/">Palm™</link> series.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>parallel*</filename></entry> <entry>Applications dealing with parallelism in computing.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>pear*</filename></entry> <entry>Ports related to the Pear PHP framework.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1953,20 +1943,19 @@ PORTEPOCH= 1</programlisting> <entry>Ports that require <application>Perl</application> version 5 to run.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>plan9*</filename></entry> - <entry>Various programs from <ulink - url="http://www.cs.bell-labs.com/plan9dist/">Plan9</ulink>.</entry> - <entry></entry> + <entry>Various programs from <link xlink:href="http://www.cs.bell-labs.com/plan9dist/">Plan9</link>.</entry> + <entry/> </row> <row> <entry><filename>polish</filename></entry> <entry>Polish language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1978,7 +1967,7 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>portuguese</filename></entry> <entry>Portuguese language support.</entry> - <entry></entry> + <entry/> </row> <row> @@ -1990,39 +1979,36 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>python*</filename></entry> - <entry>Software related to the <ulink - url="http://www.python.org/">Python</ulink> + <entry>Software related to the <link xlink:href="http://www.python.org/">Python</link> language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>ruby*</filename></entry> - <entry>Software related to the <ulink - url="http://www.ruby-lang.org/">Ruby</ulink> + <entry>Software related to the <link xlink:href="http://www.ruby-lang.org/">Ruby</link> language.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>rubygems*</filename></entry> - <entry>Ports of <ulink - url="http://www.rubygems.org/">RubyGems</ulink> + <entry>Ports of <link xlink:href="http://www.rubygems.org/">RubyGems</link> packages.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>russian</filename></entry> <entry>Russian language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>scheme*</filename></entry> <entry>Software related to the Scheme language.</entry> - <entry></entry> + <entry/> </row> <row> @@ -2031,37 +2017,37 @@ PORTEPOCH= 1</programlisting> categories such as <filename>astro</filename>, <filename>biology</filename> and <filename>math</filename>.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>security</filename></entry> <entry>Security utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>shells</filename></entry> <entry>Command line shells.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>spanish*</filename></entry> <entry>Spanish language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>sysutils</filename></entry> <entry>System utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>tcl*</filename></entry> <entry>Ports that use Tcl to run.</entry> - <entry></entry> + <entry/> </row> <row> @@ -2074,26 +2060,26 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>tk*</filename></entry> <entry>Ports that use Tk to run.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>ukrainian</filename></entry> <entry>Ukrainian language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>vietnamese</filename></entry> <entry>Vietnamese language support.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>windowmaker*</filename></entry> <entry>Ports to support the WindowMaker window manager.</entry> - <entry></entry> + <entry/> </row> <row> @@ -2116,71 +2102,71 @@ PORTEPOCH= 1</programlisting> <row> <entry><filename>x11-clocks</filename></entry> <entry>X11 clocks.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-drivers</filename></entry> <entry>X11 drivers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-fm</filename></entry> <entry>X11 file managers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-fonts</filename></entry> <entry>X11 fonts and font utilities.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-servers</filename></entry> <entry>X11 servers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-themes</filename></entry> <entry>X11 themes.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-toolkits</filename></entry> <entry>X11 toolkits.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>x11-wm</filename></entry> <entry>X11 window managers.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>xfce*</filename></entry> <entry>Ports related to the - <ulink url="http://www.xfce.org/">Xfce</ulink> + <link xlink:href="http://www.xfce.org/">Xfce</link> desktop environment.</entry> - <entry></entry> + <entry/> </row> <row> <entry><filename>zope*</filename></entry> - <entry><ulink url="http://www.zope.org/">Zope</ulink> + <entry><link xlink:href="http://www.zope.org/">Zope</link> support.</entry> - <entry></entry> + <entry/> </row> </tbody> </tgroup> </informaltable> </sect2> - <sect2 id="choosing-categories"> + <sect2 xml:id="choosing-categories"> <title>Choosing the Right Category</title> <para>As many of the categories overlap, you often have to @@ -2201,7 +2187,7 @@ PORTEPOCH= 1</programlisting> <listitem> <para>Language specific categories always come first. For example, if your port installs Japanese X11 fonts, then - your <makevar>CATEGORIES</makevar> line would read + your <varname>CATEGORIES</varname> line would read <filename>japanese x11-fonts</filename>.</para> </listitem> @@ -2239,14 +2225,14 @@ PORTEPOCH= 1</programlisting> <listitem> <para>Ports which install loadable kernel modules should have the virtual category <filename>kld</filename> in - their <makevar>CATEGORIES</makevar> line.</para> + their <varname>CATEGORIES</varname> line.</para> </listitem> <listitem> <para><filename>misc</filename> should not appear with any other non-virtual category. If you have <literal>misc</literal> with something else in your - <makevar>CATEGORIES</makevar> line, that means you can + <varname>CATEGORIES</varname> line, that means you can safely delete <literal>misc</literal> and just put the port in that other subdirectory!</para> </listitem> @@ -2267,7 +2253,7 @@ PORTEPOCH= 1</programlisting> repository.</para> </sect2> - <sect2 id="proposing-categories"> + <sect2 xml:id="proposing-categories"> <title>Proposing a New Category</title> <para>As the Ports Collection has grown over time, various new @@ -2288,8 +2274,8 @@ PORTEPOCH= 1</programlisting> human languages), or preferably both.</para> <para>The rationale for this is that such a change creates a - <ulink url="&url.articles.committers-guide;/#ports"> fair - amount of work</ulink> for both the committers and also + <link xlink:href="&url.articles.committers-guide;/#ports"> fair + amount of work</link> for both the committers and also for all users who track changes to the Ports Collection. In addition, proposed category changes just naturally seem to attract controversy. (Perhaps this is because there is no @@ -2361,9 +2347,8 @@ PORTEPOCH= 1</programlisting> <step> <para>If that PR is approved, a committer will need to - follow the rest of the procedure that is <ulink - url="&url.articles.committers-guide;/article.html#PORTS"> - outlined in the Committer's Guide</ulink>.</para> + follow the rest of the procedure that is <link xlink:href="&url.articles.committers-guide;/article.html#PORTS"> + outlined in the Committer's Guide</link>.</para> </step> </procedure> @@ -2371,11 +2356,11 @@ PORTEPOCH= 1</programlisting> the above but much less involved, since no ports will actually have to move. In this case, the only patches to include in the PR would be those to add the new category to - the <makevar>CATEGORIES</makevar> of the affected + the <varname>CATEGORIES</varname> of the affected ports.</para> </sect2> - <sect2 id="proposing-reorg"> + <sect2 xml:id="proposing-reorg"> <title>Proposing Reorganizing All the Categories</title> <para>Occasionally someone proposes reorganizing the @@ -2391,7 +2376,7 @@ PORTEPOCH= 1</programlisting> </sect2> </sect1> - <sect1 id="makefile-distfiles"> + <sect1 xml:id="makefile-distfiles"> <title>The Distribution Files</title> <para>The second part of the <filename>Makefile</filename> @@ -2399,27 +2384,27 @@ PORTEPOCH= 1</programlisting> the port, and where they can be downloaded from.</para> <sect2> - <title><makevar>DISTVERSION/DISTNAME</makevar></title> + <title><varname>DISTVERSION/DISTNAME</varname></title> - <para><makevar>DISTNAME</makevar> is the name of the port as + <para><varname>DISTNAME</varname> is the name of the port as called by the authors of the software. - <makevar>DISTNAME</makevar> defaults to + <varname>DISTNAME</varname> defaults to <literal>${PORTNAME}-${PORTVERSION}</literal>, so override - it only if necessary. <makevar>DISTNAME</makevar> is only + it only if necessary. <varname>DISTNAME</varname> is only used in two places. First, the distribution file list - (<makevar>DISTFILES</makevar>) defaults to - <makevar>${DISTNAME}</makevar><makevar>${EXTRACT_SUFX}</makevar>. + (<varname>DISTFILES</varname>) defaults to + <varname>${DISTNAME}</varname><varname>${EXTRACT_SUFX}</varname>. Second, the distribution file is expected to extract into a - subdirectory named <makevar>WRKSRC</makevar>, which defaults + subdirectory named <varname>WRKSRC</varname>, which defaults to - <filename>work/<makevar>${DISTNAME}</makevar></filename>.</para> + <filename>work/${DISTNAME}</filename>.</para> <para>Some vendor's distribution names which do not fit into the <literal>${PORTNAME}-${PORTVERSION}</literal>-scheme can be handled automatically by setting - <makevar>DISTVERSION</makevar>. - <makevar>PORTVERSION</makevar> and - <makevar>DISTNAME</makevar> will be derived automatically, + <varname>DISTVERSION</varname>. + <varname>PORTVERSION</varname> and + <varname>DISTNAME</varname> will be derived automatically, but can of course be overridden. The following table lists some examples:</para> @@ -2427,8 +2412,8 @@ PORTEPOCH= 1</programlisting> <tgroup cols="2"> <thead> <row> - <entry><makevar>DISTVERSION</makevar></entry> - <entry><makevar>PORTVERSION</makevar></entry> + <entry><varname>DISTVERSION</varname></entry> + <entry><varname>PORTVERSION</varname></entry> </row> </thead> @@ -2457,33 +2442,33 @@ PORTEPOCH= 1</programlisting> </informaltable> <note> - <para><makevar>PKGNAMEPREFIX</makevar> and - <makevar>PKGNAMESUFFIX</makevar> do not affect - <makevar>DISTNAME</makevar>. Also note that if - <makevar>WRKSRC</makevar> is equal to - <filename>work/<makevar>${PORTNAME}-${PORTVERSION}</makevar></filename> + <para><varname>PKGNAMEPREFIX</varname> and + <varname>PKGNAMESUFFIX</varname> do not affect + <varname>DISTNAME</varname>. Also note that if + <varname>WRKSRC</varname> is equal to + <filename>work/${PORTNAME}-${PORTVERSION}</filename> while the original source archive is named something other than - <makevar>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</makevar>, - you should probably leave <makevar>DISTNAME</makevar> + <varname>${PORTNAME}-${PORTVERSION}${EXTRACT_SUFX}</varname>, + you should probably leave <varname>DISTNAME</varname> alone— you are better off defining - <makevar>DISTFILES</makevar> than having to set both - <makevar>DISTNAME</makevar> and <makevar>WRKSRC</makevar> - (and possibly <makevar>EXTRACT_SUFX</makevar>).</para> + <varname>DISTFILES</varname> than having to set both + <varname>DISTNAME</varname> and <varname>WRKSRC</varname> + (and possibly <varname>EXTRACT_SUFX</varname>).</para> </note> </sect2> <sect2> - <title><makevar>MASTER_SITES</makevar></title> + <title><varname>MASTER_SITES</varname></title> <para>Record the directory part of the FTP/HTTP-URL pointing - at the original tarball in <makevar>MASTER_SITES</makevar>. + at the original tarball in <varname>MASTER_SITES</varname>. Do not forget the trailing slash (<filename>/</filename>)!</para> <para>The <command>make</command> macros will try to use this specification for grabbing the distribution file with - <makevar>FETCH</makevar> if they cannot find it already on + <varname>FETCH</varname> if they cannot find it already on the system.</para> <para>It is recommended that you put multiple sites on this @@ -2496,12 +2481,12 @@ PORTEPOCH= 1</programlisting> <para>If the original tarball is part of one of the popular archives such as SourceForge, GNU, or Perl CPAN, you may be able refer to those sites in an easy compact form using - <makevar>MASTER_SITE_<replaceable>*</replaceable></makevar> - (e.g., <makevar>MASTER_SITE_SOURCEFORGE</makevar>, - <makevar>MASTER_SITE_GNU</makevar> and - <makevar>MASTER_SITE_PERL_CPAN</makevar>). Simply set - <makevar>MASTER_SITES</makevar> to one of these variables - and <makevar>MASTER_SITE_SUBDIR</makevar> to the path within + <varname>MASTER_SITE_<replaceable>*</replaceable></varname> + (e.g., <varname>MASTER_SITE_SOURCEFORGE</varname>, + <varname>MASTER_SITE_GNU</varname> and + <varname>MASTER_SITE_PERL_CPAN</varname>). Simply set + <varname>MASTER_SITES</varname> to one of these variables + and <varname>MASTER_SITE_SUBDIR</varname> to the path within the archive. Here is an example:</para> <programlisting>MASTER_SITES= ${MASTER_SITE_GNU} @@ -2534,7 +2519,7 @@ MASTER_SITE_SUBDIR= make</programlisting> MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> <table frame="none"> - <title>Popular Magic <makevar>MASTER_SITES</makevar> + <title>Popular Magic <varname>MASTER_SITES</varname> Macros</title> <tgroup cols="2"> @@ -2547,68 +2532,68 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> <tbody> <row> - <entry><makevar>APACHE_JAKARTA</makevar></entry> - <entry><makevar>/dist/jakarta/${PORTNAME:S,-,,/,}/source</makevar></entry> + <entry><varname>APACHE_JAKARTA</varname></entry> + <entry><varname>/dist/jakarta/${PORTNAME:S,-,,/,}/source</varname></entry> </row> <row> - <entry><makevar>BERLIOS</makevar></entry> - <entry><makevar>/${PORTNAME:L}</makevar></entry> + <entry><varname>BERLIOS</varname></entry> + <entry><varname>/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>CHEESESHOP</makevar></entry> - <entry><makevar>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</makevar></entry> + <entry><varname>CHEESESHOP</varname></entry> + <entry><varname>/packages/source/source/${DISTNAME:C/(.).*/\1/}/${DISTNAME:C/(.*)-[0-9].*/\1/}</varname></entry> </row> <row> - <entry><makevar>DEBIAN</makevar></entry> - <entry><makevar>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</makevar></entry> + <entry><varname>DEBIAN</varname></entry> + <entry><varname>/debian/pool/main/${PORTNAME:C/^((lib)?.).*$/\1/}/${PORTNAME}</varname></entry> </row> <row> - <entry><makevar>GCC</makevar></entry> - <entry><makevar>/pub/gcc/releases/${DISTNAME}</makevar></entry> + <entry><varname>GCC</varname></entry> + <entry><varname>/pub/gcc/releases/${DISTNAME}</varname></entry> </row> <row> - <entry><makevar>GNOME</makevar></entry> - <entry><makevar>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</makevar></entry> + <entry><varname>GNOME</varname></entry> + <entry><varname>/pub/GNOME/sources/${PORTNAME}/${PORTVERSION:C/^([0-9]+\.[0-9]+).*/\1/}</varname></entry> </row> <row> - <entry><makevar>GNU</makevar></entry> - <entry><makevar>/gnu/${PORTNAME}</makevar></entry> + <entry><varname>GNU</varname></entry> + <entry><varname>/gnu/${PORTNAME}</varname></entry> </row> <row> - <entry><makevar>MOZDEV</makevar></entry> - <entry><makevar>/pub/mozdev/${PORTNAME:L}</makevar></entry> + <entry><varname>MOZDEV</varname></entry> + <entry><varname>/pub/mozdev/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>PERL_CPAN</makevar></entry> - <entry><makevar>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</makevar></entry> + <entry><varname>PERL_CPAN</varname></entry> + <entry><varname>/pub/CPAN/modules/by-module/${PORTNAME:C/-.*//}</varname></entry> </row> <row> - <entry><makevar>PYTHON</makevar></entry> - <entry><makevar>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</makevar></entry> + <entry><varname>PYTHON</varname></entry> + <entry><varname>/ftp/python/${PYTHON_PORTVERSION:C/rc[0-9]//}</varname></entry> </row> <row> - <entry><makevar>RUBYFORGE</makevar></entry> - <entry><makevar>/${PORTNAME:L}</makevar></entry> + <entry><varname>RUBYFORGE</varname></entry> + <entry><varname>/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>SAVANNAH</makevar></entry> - <entry><makevar>/${PORTNAME:L}</makevar></entry> + <entry><varname>SAVANNAH</varname></entry> + <entry><varname>/${PORTNAME:L}</varname></entry> </row> <row> - <entry><makevar>SF</makevar></entry> - <entry><makevar>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</makevar></entry> + <entry><varname>SF</varname></entry> + <entry><varname>/project/${PORTNAME:L}/${PORTNAME:L}/${PORTVERSION}</varname></entry> </row> </tbody> </tgroup> @@ -2616,11 +2601,11 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> </sect2> <sect2> - <title><makevar>EXTRACT_SUFX</makevar></title> + <title><varname>EXTRACT_SUFX</varname></title> <para>If you have one distribution file, and it uses an odd suffix to indicate the compression mechanism, set - <makevar>EXTRACT_SUFX</makevar>.</para> + <varname>EXTRACT_SUFX</varname>.</para> <para>For example, if the distribution file was named <filename>foo.tgz</filename> instead of the more normal @@ -2629,24 +2614,24 @@ MASTER_SITE_SUBDIR= stardict/WyabdcRealPeopleTTS/${PORTVERSION}</programlisting> <programlisting>DISTNAME= foo EXTRACT_SUFX= .tgz</programlisting> - <para>The <makevar>USE_BZIP2</makevar>, - <makevar>USE_XZ</makevar> and - <makevar>USE_ZIP</makevar> variables automatically set - <makevar>EXTRACT_SUFX</makevar> to + <para>The <varname>USE_BZIP2</varname>, + <varname>USE_XZ</varname> and + <varname>USE_ZIP</varname> variables automatically set + <varname>EXTRACT_SUFX</varname> to <literal>.tar.bz2</literal>, <literal>.tar.xz</literal> or <literal>.zip</literal> as necessary. If neither of - these are set then <makevar>EXTRACT_SUFX</makevar> + these are set then <varname>EXTRACT_SUFX</varname> defaults to <literal>.tar.gz</literal>.</para> <note> <para>You never need to set both - <makevar>EXTRACT_SUFX</makevar> and - <makevar>DISTFILES</makevar>.</para> + <varname>EXTRACT_SUFX</varname> and + <varname>DISTFILES</varname>.</para> </note> </sect2> <sect2> - <title><makevar>DISTFILES</makevar></title> + <title><varname>DISTFILES</varname></title> <para>Sometimes the names of the files to be downloaded have no resemblance to the name of the port. For example, it @@ -2655,49 +2640,49 @@ EXTRACT_SUFX= .tgz</programlisting> be in several different archives, all of which must be downloaded.</para> - <para>If this is the case, set <makevar>DISTFILES</makevar> to + <para>If this is the case, set <varname>DISTFILES</varname> to be a space separated list of all the files that must be downloaded.</para> <programlisting>DISTFILES= source1.tar.gz source2.tar.gz</programlisting> - <para>If not explicitly set, <makevar>DISTFILES</makevar> + <para>If not explicitly set, <varname>DISTFILES</varname> defaults to <literal>${DISTNAME}${EXTRACT_SUFX}</literal>.</para> </sect2> <sect2> - <title><makevar>EXTRACT_ONLY</makevar></title> + <title><varname>EXTRACT_ONLY</varname></title> - <para>If only some of the <makevar>DISTFILES</makevar> must be + <para>If only some of the <varname>DISTFILES</varname> must be extracted—for example, one of them is the source code, while another is an uncompressed document—list the filenames that must be extracted in - <makevar>EXTRACT_ONLY</makevar>.</para> + <varname>EXTRACT_ONLY</varname>.</para> <programlisting>DISTFILES= source.tar.gz manual.html EXTRACT_ONLY= source.tar.gz</programlisting> <para>If <emphasis>none</emphasis> of the - <makevar>DISTFILES</makevar> should be uncompressed then set - <makevar>EXTRACT_ONLY</makevar> to the empty string.</para> + <varname>DISTFILES</varname> should be uncompressed then set + <varname>EXTRACT_ONLY</varname> to the empty string.</para> <programlisting>EXTRACT_ONLY=</programlisting> </sect2> - <sect2 id="porting-patchfiles"> - <title><makevar>PATCHFILES</makevar></title> + <sect2 xml:id="porting-patchfiles"> + <title><varname>PATCHFILES</varname></title> <para>If your port requires some additional patches that are - available by FTP or HTTP, set <makevar>PATCHFILES</makevar> - to the names of the files and <makevar>PATCH_SITES</makevar> + available by FTP or HTTP, set <varname>PATCHFILES</varname> + to the names of the files and <varname>PATCH_SITES</varname> to the URL of the directory that contains them (the format - is the same as <makevar>MASTER_SITES</makevar>).</para> + is the same as <varname>MASTER_SITES</varname>).</para> <para>If the patch is not relative to the top of the source - tree (i.e., <makevar>WRKSRC</makevar>) because it contains + tree (i.e., <varname>WRKSRC</varname>) because it contains some extra pathnames, set - <makevar>PATCH_DIST_STRIP</makevar> accordingly. For + <varname>PATCH_DIST_STRIP</varname> accordingly. For instance, if all the pathnames in the patch have an extra <literal>foozolix-1.0/</literal> in front of the filenames, then set <literal>PATCH_DIST_STRIP=-p1</literal>.</para> @@ -2708,15 +2693,15 @@ EXTRACT_ONLY= source.tar.gz</programlisting> <para>If the patch is distributed with some other files, such as documentation, in a <command>gzip</command>ped tarball, - you cannot just use <makevar>PATCHFILES</makevar>. If that + you cannot just use <varname>PATCHFILES</varname>. If that is the case, add the name and the location of the patch - tarball to <makevar>DISTFILES</makevar> and - <makevar>MASTER_SITES</makevar>. Then, use the - <makevar>EXTRA_PATCHES</makevar> variable to point to those + tarball to <varname>DISTFILES</varname> and + <varname>MASTER_SITES</varname>. Then, use the + <varname>EXTRA_PATCHES</varname> variable to point to those files and <filename>bsd.port.mk</filename> will automatically apply them for you. In particular, do <emphasis>not</emphasis> copy patch files into the - <makevar>PATCHDIR</makevar> directory—that directory + <varname>PATCHDIR</varname> directory—that directory may not be writable.</para> <note> @@ -2727,11 +2712,11 @@ EXTRACT_ONLY= source.tar.gz</programlisting> latter, take extra care not to overwrite something that already exists in that directory. Also, do not forget to add a command to remove the copied patch in the - <maketarget>pre-clean</maketarget> target.</para> + <buildtarget>pre-clean</buildtarget> target.</para> </note> </sect2> - <sect2 id="porting-master-sites-n"> + <sect2 xml:id="porting-master-sites-n"> <title>Multiple Distribution Files or Patches from Different Sites and Subdirectories (<literal>MASTER_SITES:n</literal>)</title> @@ -2746,8 +2731,8 @@ EXTRACT_ONLY= source.tar.gz</programlisting> mechanism as <literal>MASTER_SITES:n</literal>.</para> <para>A little background first. OpenBSD has a neat feature - inside the <makevar>DISTFILES</makevar> and - <makevar>PATCHFILES</makevar> variables which allows files + inside the <varname>DISTFILES</varname> and + <varname>PATCHFILES</varname> variables which allows files and patches to be postfixed with <literal>:n</literal> identifiers. Here, <literal>n</literal> can be both <literal>[0-9]</literal> and denote a group designation. @@ -2757,26 +2742,26 @@ EXTRACT_ONLY= source.tar.gz</programlisting> <para>In OpenBSD, distribution file <filename>alpha</filename> will be associated with variable - <makevar>MASTER_SITES0</makevar> instead of our common - <makevar>MASTER_SITES</makevar> and + <varname>MASTER_SITES0</varname> instead of our common + <varname>MASTER_SITES</varname> and <filename>beta</filename> with - <makevar>MASTER_SITES1</makevar>.</para> + <varname>MASTER_SITES1</varname>.</para> <para>This is a very interesting feature which can decrease that endless search for the correct download site.</para> - <para>Just picture 2 files in <makevar>DISTFILES</makevar> and - 20 sites in <makevar>MASTER_SITES</makevar>, the sites slow + <para>Just picture 2 files in <varname>DISTFILES</varname> and + 20 sites in <varname>MASTER_SITES</varname>, the sites slow as hell where <filename>beta</filename> is carried by all - sites in <makevar>MASTER_SITES</makevar>, and + sites in <varname>MASTER_SITES</varname>, and <filename>alpha</filename> can only be found in the 20th site. It would be such a waste to check all of them if the maintainer knew this beforehand, would it not? Not a good start for that lovely weekend!</para> <para>Now that you have the idea, just imagine more - <makevar>DISTFILES</makevar> and more - <makevar>MASTER_SITES</makevar>. Surely our + <varname>DISTFILES</varname> and more + <varname>MASTER_SITES</varname>. Surely our <quote>distfiles survey meister</quote> would appreciate the relief to network strain that this would bring.</para> @@ -2807,9 +2792,9 @@ EXTRACT_ONLY= source.tar.gz</programlisting> sites.</para> <para>To support this, each entry in - <makevar>DISTFILES</makevar> may be followed by a colon + <varname>DISTFILES</varname> may be followed by a colon and a <quote>tag name</quote>. Each site listed in - <makevar>MASTER_SITES</makevar> is then followed by a + <varname>MASTER_SITES</varname> is then followed by a colon, and the tag that indicates which distribution files should be downloaded from this site.</para> @@ -2818,11 +2803,9 @@ EXTRACT_ONLY= source.tar.gz</programlisting> and <filename>source2.tar.gz</filename>, which must be downloaded from two different sites. The port's <filename>Makefile</filename> would include lines like - <xref - linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> + <xref linkend="ports-master-sites-n-example-simple-use-one-file-per-site"/>.</para> - <example - id="ports-master-sites-n-example-simple-use-one-file-per-site"> + <example xml:id="ports-master-sites-n-example-simple-use-one-file-per-site"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with One File Per Site</title> @@ -2836,13 +2819,11 @@ DISTFILES= source1.tar.gz:source1 \ Continuing the previous example, suppose that there was a third distfile, <filename>source3.tar.gz</filename>, that should be downloaded from - <hostid>ftp.example2.com</hostid>. The + <systemitem>ftp.example2.com</systemitem>. The <filename>Makefile</filename> would then be written like - <xref - linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> + <xref linkend="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"/>.</para> - <example - id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> + <example xml:id="ports-master-sites-n-example-simple-use-more-than-one-file-per-site"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with More Than One File Per Site</title> @@ -2866,7 +2847,7 @@ DISTFILES= source1.tar.gz:source1 \ <orderedlist> <listitem> <para>Elements can be postfixed with - <literal>:<replaceable>n</replaceable></literal> where + <literal>:n</literal> where <replaceable>n</replaceable> is <literal>[^:,]+</literal>, i.e., <replaceable>n</replaceable> could conceptually be any @@ -2882,11 +2863,9 @@ DISTFILES= source1.tar.gz:source1 \ postfixing purposes since they yield special meaning: <literal>default</literal>, <literal>all</literal> and <literal>ALL</literal> (they are used internally in - item <xref - linkend="porting-master-sites-n-what-changes-in-port-targets"/>). + item <xref linkend="porting-master-sites-n-what-changes-in-port-targets"/>). Furthermore, <literal>DEFAULT</literal> is a special - purpose word (check item <xref - linkend="porting-master-sites-n-DEFAULT-group"/>).</para> + purpose word (check item <xref linkend="porting-master-sites-n-DEFAULT-group"/>).</para> </listitem> <listitem> @@ -2896,15 +2875,14 @@ DISTFILES= source1.tar.gz:source1 \ <literal>m</literal> and so forth.</para> </listitem> - <listitem id="porting-master-sites-n-DEFAULT-group"> + <listitem xml:id="porting-master-sites-n-DEFAULT-group"> <para>Elements without a postfix are groupless, i.e., they all belong to the special group <literal>DEFAULT</literal>. If you postfix any elements with <literal>DEFAULT</literal>, you are just being redundant unless you want to have an element belonging to both <literal>DEFAULT</literal> and other - groups at the same time (check item <xref - linkend="porting-master-sites-n-comma-operator"/>).</para> + groups at the same time (check item <xref linkend="porting-master-sites-n-comma-operator"/>).</para> <para>The following examples are equivalent but the first one is preferred:</para> @@ -2922,7 +2900,7 @@ DISTFILES= source1.tar.gz:source1 \ will be simply that, repeated elements.</para> </listitem> - <listitem id="porting-master-sites-n-comma-operator"> + <listitem xml:id="porting-master-sites-n-comma-operator"> <para>When you want an element to belong to several groups at the same time, you can use the comma operator (<literal>,</literal>).</para> @@ -2948,32 +2926,32 @@ DISTFILES= source1.tar.gz:source1 \ <listitem> <para>All sites within a given group are sorted - according to <makevar>MASTER_SORT_AWK</makevar>. All - groups within <makevar>MASTER_SITES</makevar> and - <makevar>PATCH_SITES</makevar> are sorted as + according to <varname>MASTER_SORT_AWK</varname>. All + groups within <varname>MASTER_SITES</varname> and + <varname>PATCH_SITES</varname> are sorted as well.</para> </listitem> - <listitem id="porting-master-sites-n-group-semantics"> + <listitem xml:id="porting-master-sites-n-group-semantics"> <para>Group semantics can be used in any of the - following variables <makevar>MASTER_SITES</makevar>, - <makevar>PATCH_SITES</makevar>, - <makevar>MASTER_SITE_SUBDIR</makevar>, - <makevar>PATCH_SITE_SUBDIR</makevar>, - <makevar>DISTFILES</makevar>, and - <makevar>PATCHFILES</makevar> according to the + following variables <varname>MASTER_SITES</varname>, + <varname>PATCH_SITES</varname>, + <varname>MASTER_SITE_SUBDIR</varname>, + <varname>PATCH_SITE_SUBDIR</varname>, + <varname>DISTFILES</varname>, and + <varname>PATCHFILES</varname> according to the following syntax:</para> <orderedlist> <listitem> - <para>All <makevar>MASTER_SITES</makevar>, - <makevar>PATCH_SITES</makevar>, - <makevar>MASTER_SITE_SUBDIR</makevar> and - <makevar>PATCH_SITE_SUBDIR</makevar> elements must + <para>All <varname>MASTER_SITES</varname>, + <varname>PATCH_SITES</varname>, + <varname>MASTER_SITE_SUBDIR</varname> and + <varname>PATCH_SITE_SUBDIR</varname> elements must be terminated with the forward slash <literal>/</literal> character. If any elements belong to any groups, the group postfix - <literal>:<replaceable>n</replaceable></literal> + <literal>:n</literal> must come right after the terminator <literal>/</literal>. The <literal>MASTER_SITES:n</literal> mechanism relies @@ -2985,24 +2963,21 @@ DISTFILES= source1.tar.gz:source1 \ <literal>n</literal>. For compatibility purposes, since the <literal>/</literal> terminator was not required before in both - <makevar>MASTER_SITE_SUBDIR</makevar> and - <makevar>PATCH_SITE_SUBDIR</makevar> elements, if + <varname>MASTER_SITE_SUBDIR</varname> and + <varname>PATCH_SITE_SUBDIR</varname> elements, if the postfix immediate preceding character is not a <literal>/</literal> then <literal>:n</literal> will be considered a valid part of the element instead of a group postfix even if an element is postfixed with <literal>:n</literal>. See both - <xref - linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> - and <xref - linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + <xref linkend="ports-master-sites-n-example-detailed-use-master-site-subdir"/> + and <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> - <example - id="ports-master-sites-n-example-detailed-use-master-site-subdir"> + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-subdir"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> in - <makevar>MASTER_SITE_SUBDIR</makevar></title> + <varname>MASTER_SITE_SUBDIR</varname></title> <programlisting>MASTER_SITE_SUBDIR= old:n new/:NEW</programlisting> @@ -3020,8 +2995,7 @@ DISTFILES= source1.tar.gz:source1 \ </itemizedlist> </example> - <example - id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> + <example xml:id="ports-master-sites-n-example-detailed-use-complete-example-master-sites"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> with Comma Operator, Multiple Files, Multiple Sites and @@ -3052,7 +3026,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3076,7 +3050,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3089,7 +3063,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3113,7 +3087,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3124,7 +3098,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3132,7 +3106,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3143,7 +3117,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3167,7 +3141,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3178,11 +3152,11 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3193,7 +3167,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <itemizedlist> <listitem> - <para><makevar>MASTER_SITE_OVERRIDE</makevar></para> + <para><varname>MASTER_SITE_OVERRIDE</varname></para> </listitem> <listitem> @@ -3201,7 +3175,7 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ </listitem> <listitem> - <para><makevar>MASTER_SITE_BACKUP</makevar></para> + <para><varname>MASTER_SITE_BACKUP</varname></para> </listitem> </itemizedlist> </listitem> @@ -3214,16 +3188,14 @@ MASTER_SITE_SUBDIR= directory-trial:1 directory-n/:groupn \ <listitem> <para>How do I group one of the special variables from <filename>bsd.sites.mk</filename>, e.g., - <makevar>MASTER_SITE_SOURCEFORGE</makevar>?</para> + <varname>MASTER_SITE_SOURCEFORGE</varname>?</para> - <para>See <xref - linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> + <para>See <xref linkend="ports-master-sites-n-example-detailed-use-master-site-sourceforge"/>.</para> - <example - id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> + <example xml:id="ports-master-sites-n-example-detailed-use-master-site-sourceforge"> <title>Detailed Use of <literal>MASTER_SITES:n</literal> with - <makevar>MASTER_SITE_SOURCEFORGE</makevar></title> + <varname>MASTER_SITE_SOURCEFORGE</varname></title> <programlisting>MASTER_SITES= http://site1/ ${MASTER_SITE_SOURCEFORGE:S/$/:sourceforge,TEST/} DISTFILES= something.tar.gz:sourceforge</programlisting> @@ -3231,24 +3203,22 @@ DISTFILES= something.tar.gz:sourceforge</programlisting> <para><filename>something.tar.gz</filename> will be fetched from all sites within - <makevar>MASTER_SITE_SOURCEFORGE</makevar>.</para> + <varname>MASTER_SITE_SOURCEFORGE</varname>.</para> </listitem> <listitem> - <para>How do I use this with <makevar>PATCH*</makevar> + <para>How do I use this with <varname>PATCH*</varname> variables?</para> <para>All examples were done with - <makevar>MASTER*</makevar> variables but they work - exactly the same for <makevar>PATCH*</makevar> ones as - can be seen in <xref - linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> + <varname>MASTER*</varname> variables but they work + exactly the same for <varname>PATCH*</varname> ones as + can be seen in <xref linkend="ports-master-sites-n-example-detailed-use-patch-sites"/>.</para> - <example - id="ports-master-sites-n-example-detailed-use-patch-sites"> + <example xml:id="ports-master-sites-n-example-detailed-use-patch-sites"> <title>Simplified Use of <literal>MASTER_SITES:n</literal> with - <makevar>PATCH_SITES</makevar></title> + <varname>PATCH_SITES</varname></title> <programlisting>PATCH_SITES= http://site1/ http://site2/:test PATCHFILES= patch1:test</programlisting> @@ -3265,66 +3235,62 @@ PATCHFILES= patch1:test</programlisting> <para>All current ports remain the same. The <literal>MASTER_SITES:n</literal> feature code is only activated if there are elements postfixed with - <literal>:<replaceable>n</replaceable></literal> like + <literal>:n</literal> like elements according to the aforementioned syntax rules, - especially as shown in item <xref - linkend="porting-master-sites-n-group-semantics"/>.</para> + especially as shown in item <xref linkend="porting-master-sites-n-group-semantics"/>.</para> </listitem> - <listitem - id="porting-master-sites-n-what-changes-in-port-targets"> + <listitem xml:id="porting-master-sites-n-what-changes-in-port-targets"> <para>The port targets remain the same: - <maketarget>checksum</maketarget>, - <maketarget>makesum</maketarget>, - <maketarget>patch</maketarget>, - <maketarget>configure</maketarget>, - <maketarget>build</maketarget>, etc. With the obvious - exceptions of <maketarget>do-fetch</maketarget>, - <maketarget>fetch-list</maketarget>, - <maketarget>master-sites</maketarget> and - <maketarget>patch-sites</maketarget>.</para> + <buildtarget>checksum</buildtarget>, + <buildtarget>makesum</buildtarget>, + <buildtarget>patch</buildtarget>, + <buildtarget>configure</buildtarget>, + <buildtarget>build</buildtarget>, etc. With the obvious + exceptions of <buildtarget>do-fetch</buildtarget>, + <buildtarget>fetch-list</buildtarget>, + <buildtarget>master-sites</buildtarget> and + <buildtarget>patch-sites</buildtarget>.</para> <itemizedlist> <listitem> - <para><maketarget>do-fetch</maketarget>: deploys the + <para><buildtarget>do-fetch</buildtarget>: deploys the new grouping postfixed - <makevar>DISTFILES</makevar> and - <makevar>PATCHFILES</makevar> with their matching + <varname>DISTFILES</varname> and + <varname>PATCHFILES</varname> with their matching group elements within both - <makevar>MASTER_SITES</makevar> and - <makevar>PATCH_SITES</makevar> which use matching + <varname>MASTER_SITES</varname> and + <varname>PATCH_SITES</varname> which use matching group elements within both - <makevar>MASTER_SITE_SUBDIR</makevar> and - <makevar>PATCH_SITE_SUBDIR</makevar>. Check <xref - linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> + <varname>MASTER_SITE_SUBDIR</varname> and + <varname>PATCH_SITE_SUBDIR</varname>. Check <xref linkend="ports-master-sites-n-example-detailed-use-complete-example-master-sites"/>.</para> </listitem> <listitem> - <para><maketarget>fetch-list</maketarget>: works - like old <maketarget>fetch-list</maketarget> with + <para><buildtarget>fetch-list</buildtarget>: works + like old <buildtarget>fetch-list</buildtarget> with the exception that it groups just like - <maketarget>do-fetch</maketarget>.</para> + <buildtarget>do-fetch</buildtarget>.</para> </listitem> <listitem> - <para><maketarget>master-sites</maketarget> and - <maketarget>patch-sites</maketarget>: + <para><buildtarget>master-sites</buildtarget> and + <buildtarget>patch-sites</buildtarget>: (incompatible with older versions) only return the elements of group <literal>DEFAULT</literal>; in fact, they execute targets - <maketarget>master-sites-default</maketarget> and - <maketarget>patch-sites-default</maketarget> + <buildtarget>master-sites-default</buildtarget> and + <buildtarget>patch-sites-default</buildtarget> respectively.</para> <para>Furthermore, using target either - <maketarget>master-sites-all</maketarget> or - <maketarget>patch-sites-all</maketarget> is + <buildtarget>master-sites-all</buildtarget> or + <buildtarget>patch-sites-all</buildtarget> is preferred to directly checking either - <maketarget>MASTER_SITES</maketarget> or - <maketarget>PATCH_SITES</maketarget>. Also, + <buildtarget>MASTER_SITES</buildtarget> or + <buildtarget>PATCH_SITES</buildtarget>. Also, directly checking is not guaranteed to work in any - future versions. Check item <xref - linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> + future versions. Check item <xref linkend="porting-master-sites-n-new-port-targets-master-sites-all"/> for more information on these new port targets.</para> </listitem> @@ -3337,41 +3303,40 @@ PATCHFILES= patch1:test</programlisting> <orderedlist> <listitem> <para>There are - <maketarget>master-sites-<replaceable>n</replaceable></maketarget> + <buildtarget>master-sites-<replaceable>n</replaceable></buildtarget> and - <maketarget>patch-sites-<replaceable>n</replaceable></maketarget> + <buildtarget>patch-sites-<replaceable>n</replaceable></buildtarget> targets which will list the elements of the respective group <replaceable>n</replaceable> - within <makevar>MASTER_SITES</makevar> and - <makevar>PATCH_SITES</makevar> respectively. For + within <varname>MASTER_SITES</varname> and + <varname>PATCH_SITES</varname> respectively. For instance, both - <maketarget>master-sites-DEFAULT</maketarget> and - <maketarget>patch-sites-DEFAULT</maketarget> will + <buildtarget>master-sites-DEFAULT</buildtarget> and + <buildtarget>patch-sites-DEFAULT</buildtarget> will return the elements of group <literal>DEFAULT</literal>, - <maketarget>master-sites-test</maketarget> and - <maketarget>patch-sites-test</maketarget> of group + <buildtarget>master-sites-test</buildtarget> and + <buildtarget>patch-sites-test</buildtarget> of group <literal>test</literal>, and thereon.</para> </listitem> - <listitem - id="porting-master-sites-n-new-port-targets-master-sites-all"> + <listitem xml:id="porting-master-sites-n-new-port-targets-master-sites-all"> <para>There are new targets - <maketarget>master-sites-all</maketarget> and - <maketarget>patch-sites-all</maketarget> which do + <buildtarget>master-sites-all</buildtarget> and + <buildtarget>patch-sites-all</buildtarget> which do the work of the old - <maketarget>master-sites</maketarget> and - <maketarget>patch-sites</maketarget> ones. They + <buildtarget>master-sites</buildtarget> and + <buildtarget>patch-sites</buildtarget> ones. They return the elements of all groups as if they all belonged to the same group with the caveat that it lists as many - <makevar>MASTER_SITE_BACKUP</makevar> and - <makevar>MASTER_SITE_OVERRIDE</makevar> as there + <varname>MASTER_SITE_BACKUP</varname> and + <varname>MASTER_SITE_OVERRIDE</varname> as there are groups defined within either - <makevar>DISTFILES</makevar> or - <makevar>PATCHFILES</makevar>; respectively for - <maketarget>master-sites-all</maketarget> and - <maketarget>patch-sites-all</maketarget>.</para> + <varname>DISTFILES</varname> or + <varname>PATCHFILES</varname>; respectively for + <buildtarget>master-sites-all</buildtarget> and + <buildtarget>patch-sites-all</buildtarget>.</para> </listitem> </orderedlist> </listitem> @@ -3380,53 +3345,52 @@ PATCHFILES= patch1:test</programlisting> </sect2> <sect2> - <title><makevar>DIST_SUBDIR</makevar></title> + <title><varname>DIST_SUBDIR</varname></title> <para>Do not let your port clutter <filename>/usr/ports/distfiles</filename>. If your port requires a lot of files to be fetched, or contains a file that has a name that might conflict with other ports (e.g., <filename>Makefile</filename>), set - <makevar>DIST_SUBDIR</makevar> to the name of the port + <varname>DIST_SUBDIR</varname> to the name of the port (<literal>${PORTNAME}</literal> or <literal>${PKGNAMEPREFIX}${PORTNAME}</literal> should work - fine). This will change <makevar>DISTDIR</makevar> from the + fine). This will change <varname>DISTDIR</varname> from the default <filename>/usr/ports/distfiles</filename> to - <filename>/usr/ports/distfiles/<makevar>DIST_SUBDIR</makevar></filename>, + <filename>/usr/ports/distfiles/DIST_SUBDIR</filename>, and in effect puts everything that is required for your port into that subdirectory.</para> <para>It will also look at the subdirectory with the same name on the backup master site at <filename>ftp.FreeBSD.org</filename>. (Setting - <makevar>DISTDIR</makevar> explicitly in your - <makevar>Makefile</makevar> will not accomplish this, so - please use <makevar>DIST_SUBDIR</makevar>.)</para> + <varname>DISTDIR</varname> explicitly in your + <varname>Makefile</varname> will not accomplish this, so + please use <varname>DIST_SUBDIR</varname>.)</para> <note> <para>This does not affect the - <makevar>MASTER_SITES</makevar> you define in your + <varname>MASTER_SITES</varname> you define in your <filename>Makefile</filename>.</para> </note> </sect2> <sect2> - <title><makevar>ALWAYS_KEEP_DISTFILES</makevar></title> + <title><varname>ALWAYS_KEEP_DISTFILES</varname></title> <para>If your port uses binary distfiles and has a license that requires that the source code is provided with packages distributed in binary form, e.g., GPL, - <makevar>ALWAYS_KEEP_DISTFILES</makevar> will instruct the + <varname>ALWAYS_KEEP_DISTFILES</varname> will instruct the &os; build cluster to keep a copy of the files specified in - <makevar>DISTFILES</makevar>. Users of these ports will + <varname>DISTFILES</varname>. Users of these ports will generally not need these files, so it is a good idea to only - add the source distfiles to <makevar>DISTFILES</makevar> - when <makevar>PACKAGE_BUILDING</makevar> is defined.</para> + add the source distfiles to <varname>DISTFILES</varname> + when <varname>PACKAGE_BUILDING</varname> is defined.</para> - <example - id="ports-master-sites-n-example-always-keep-distfiles"> + <example xml:id="ports-master-sites-n-example-always-keep-distfiles"> <title>Use of - <makevar>ALWAYS_KEEP_DISTFILES</makevar></title> + <varname>ALWAYS_KEEP_DISTFILES</varname></title> <programlisting>.if defined(PACKAGE_BUILDING) DISTFILES+= <replaceable>foo.tar.gz</replaceable> @@ -3434,23 +3398,23 @@ ALWAYS_KEEP_DISTFILES= yes .endif</programlisting> </example> - <para>When adding extra files to <makevar>DISTFILES</makevar>, + <para>When adding extra files to <varname>DISTFILES</varname>, make sure you also add them to <filename>distinfo</filename>. Also, the additional files - will normally be extracted into <makevar>WRKDIR</makevar> as + will normally be extracted into <varname>WRKDIR</varname> as well, which for some ports may lead to undesirable side effects and require special handling.</para> </sect2> </sect1> - <sect1 id="makefile-maintainer"> - <title><makevar>MAINTAINER</makevar></title> + <sect1 xml:id="makefile-maintainer"> + <title><varname>MAINTAINER</varname></title> <para>Set your mail-address here. Please. <!-- smiley --><emphasis>:-)</emphasis></para> <para>Note that only a single address without the comment part - is allowed as a <makevar>MAINTAINER</makevar> value. The + is allowed as a <varname>MAINTAINER</varname> value. The format used should be <literal>user@hostname.domain</literal>. Please do not include any descriptive text such as your real name in this entry—that merely confuses @@ -3459,9 +3423,8 @@ ALWAYS_KEEP_DISTFILES= yes <para>The maintainer is responsible for keeping the port up to date, and ensuring the port works correctly. For a detailed description of the responsibilities of a port - maintainer, refer to the <ulink - url="&url.articles.contributing-ports;/maintain-port.html">The - challenge for port maintainers</ulink> section.</para> + maintainer, refer to the <link xlink:href="&url.articles.contributing-ports;/maintain-port.html">The + challenge for port maintainers</link> section.</para> <para>Changes to the port will be sent to the maintainer of a port for review and approval before being committed. If the @@ -3489,8 +3452,8 @@ ALWAYS_KEEP_DISTFILES= yes maintainership for security reasons.</para> </sect1> - <sect1 id="makefile-comment"> - <title><makevar>COMMENT</makevar></title> + <sect1 xml:id="makefile-comment"> + <title><varname>COMMENT</varname></title> <para>This is a one-line description of the port. Please respect the following rules:</para> @@ -3542,20 +3505,20 @@ ALWAYS_KEEP_DISTFILES= yes <filename>Makefile</filename>.</para> </sect1> - <sect1 id="makefile-portscout"> - <title><makevar>PORTSCOUT</makevar></title> + <sect1 xml:id="makefile-portscout"> + <title><varname>PORTSCOUT</varname></title> <para><application>Portscout</application> is an automated distfile check utility for the &os; Ports Collection, described in detail in <xref linkend="distfile-survey"/>.</para> - <para>The <makevar>PORTSCOUT</makevar> variable defines + <para>The <varname>PORTSCOUT</varname> variable defines special conditions within which the <application>Portscout</application> distfile scanner should be restricted.</para> - <para>Situations where the <makevar>PORTSCOUT</makevar> + <para>Situations where the <varname>PORTSCOUT</varname> variable should be set include:</para> <itemizedlist> @@ -3584,7 +3547,7 @@ ALWAYS_KEEP_DISTFILES= yes <para>When URLs listing the available versions differ from the download URLs. For example, to limit distfile version checks to the download page for the - <filename role="package">databases/pgtune</filename> + <package>databases/pgtune</package> port, add:</para> <programlisting>PORTSCOUT= site:http://pgfoundry.org/frs/?group_id=1000416</programlisting> @@ -3592,7 +3555,7 @@ ALWAYS_KEEP_DISTFILES= yes </itemizedlist> </sect1> - <sect1 id="makefile-depend"> + <sect1 xml:id="makefile-depend"> <title>Dependencies</title> <para>Many ports depend on other ports. This is a very @@ -3606,7 +3569,7 @@ ALWAYS_KEEP_DISTFILES= yes behavior of dependencies.</para> <sect2> - <title><makevar>LIB_DEPENDS</makevar></title> + <title><varname>LIB_DEPENDS</varname></title> <para>This variable specifies the shared libraries this port depends on. It is a list of @@ -3624,19 +3587,19 @@ ALWAYS_KEEP_DISTFILES= yes it is not found.</para> <para>The dependency is checked twice, once from within the - <maketarget>extract</maketarget> target and then from within - the <maketarget>install</maketarget> target. Also, the name + <buildtarget>extract</buildtarget> target and then from within + the <buildtarget>install</buildtarget> target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system.</para> </sect2> <sect2> - <title><makevar>RUN_DEPENDS</makevar></title> + <title><varname>RUN_DEPENDS</varname></title> <para>This variable specifies executables or files this port depends on during run-time. It is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples where <replaceable>path</replaceable> is the name of the executable or file, <replaceable>dir</replaceable> is the directory in which to find it in case it is not @@ -3679,16 +3642,16 @@ ALWAYS_KEEP_DISTFILES= yes </note> <para>The dependency is checked from within the - <maketarget>install</maketarget> target. Also, the name of + <buildtarget>install</buildtarget> target. Also, the name of the dependency is put into the package so that &man.pkg.add.1; will automatically install it if it is not on the user's system. The <replaceable>target</replaceable> part can be omitted if it is the same as - <makevar>DEPENDS_TARGET</makevar>.</para> + <varname>DEPENDS_TARGET</varname>.</para> <para>A quite common situation is when - <makevar>RUN_DEPENDS</makevar> is literally the same as - <makevar>BUILD_DEPENDS</makevar>, especially if ported + <varname>RUN_DEPENDS</varname> is literally the same as + <varname>BUILD_DEPENDS</varname>, especially if ported software is written in a scripted language or if it requires the same build and run-time environment. In this case, it is both tempting and intuitive to directly @@ -3698,18 +3661,18 @@ ALWAYS_KEEP_DISTFILES= yes <para>However, such assignment can pollute run-time dependencies with entries not defined in the port's original - <makevar>BUILD_DEPENDS</makevar>. This happens because of + <varname>BUILD_DEPENDS</varname>. This happens because of &man.make.1;'s lazy evaluation of variable assignment. Consider a <filename>Makefile</filename> with - <makevar>USE_<replaceable>*</replaceable></makevar> + <varname>USE_<replaceable>*</replaceable></varname> variables, which are processed by <filename>ports/Mk/bsd.*.mk</filename> to augment initial build dependencies. For example, <literal>USES= gmake</literal> adds - <filename role="package">devel/gmake</filename> to - <makevar>BUILD_DEPENDS</makevar>. To prevent such + <package>devel/gmake</package> to + <varname>BUILD_DEPENDS</varname>. To prevent such additional dependencies from polluting - <makevar>RUN_DEPENDS</makevar>, take care to assign with + <varname>RUN_DEPENDS</varname>, take care to assign with expansion, i.e., expand the value before assigning it to the variable:</para> @@ -3717,12 +3680,12 @@ ALWAYS_KEEP_DISTFILES= yes </sect2> <sect2> - <title><makevar>BUILD_DEPENDS</makevar></title> + <title><varname>BUILD_DEPENDS</varname></title> <para>This variable specifies executables or files this port - requires to build. Like <makevar>RUN_DEPENDS</makevar>, it + requires to build. Like <varname>RUN_DEPENDS</varname>, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>BUILD_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> @@ -3736,18 +3699,18 @@ ALWAYS_KEEP_DISTFILES= yes <note> <para><quote>build</quote> here means everything from extraction to compilation. The dependency is checked from - within the <maketarget>extract</maketarget> target. The + within the <buildtarget>extract</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if - it is the same as <makevar>DEPENDS_TARGET</makevar></para> + it is the same as <varname>DEPENDS_TARGET</varname></para> </note> </sect2> <sect2> - <title><makevar>FETCH_DEPENDS</makevar></title> + <title><varname>FETCH_DEPENDS</varname></title> <para>This variable specifies executables or files this port requires to fetch. Like the previous two, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>FETCH_DEPENDS= ncftp2:${PORTSDIR}/net/ncftp2</programlisting> @@ -3758,17 +3721,17 @@ ALWAYS_KEEP_DISTFILES= yes tree to build and install it if it is not found.</para> <para>The dependency is checked from within the - <maketarget>fetch</maketarget> target. The + <buildtarget>fetch</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if it - is the same as <makevar>DEPENDS_TARGET</makevar>.</para> + is the same as <varname>DEPENDS_TARGET</varname>.</para> </sect2> <sect2> - <title><makevar>EXTRACT_DEPENDS</makevar></title> + <title><varname>EXTRACT_DEPENDS</varname></title> <para>This variable specifies executables or files this port requires for extraction. Like the previous, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>EXTRACT_DEPENDS= unzip:${PORTSDIR}/archivers/unzip</programlisting> @@ -3780,25 +3743,25 @@ ALWAYS_KEEP_DISTFILES= yes found.</para> <para>The dependency is checked from within the - <maketarget>extract</maketarget> target. The + <buildtarget>extract</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if it - is the same as <makevar>DEPENDS_TARGET</makevar>.</para> + is the same as <varname>DEPENDS_TARGET</varname>.</para> <note> <para>Use this variable only if the extraction does not already work (the default assumes <command>gzip</command>) and cannot be made to work using - <makevar>USE_ZIP</makevar> or <makevar>USE_BZIP2</makevar> + <varname>USE_ZIP</varname> or <varname>USE_BZIP2</varname> described in <xref linkend="use-vars"/>.</para> </note> </sect2> <sect2> - <title><makevar>PATCH_DEPENDS</makevar></title> + <title><varname>PATCH_DEPENDS</varname></title> <para>This variable specifies executables or files this port requires to patch. Like the previous, it is a list of - <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional><replaceable>:target</replaceable></optional> + <replaceable>path</replaceable>:<replaceable>dir</replaceable><optional>:target</optional> tuples. For example,</para> <programlisting>PATCH_DEPENDS= ${NONEXISTENT}:${PORTSDIR}/java/jfc:extract</programlisting> @@ -3807,13 +3770,13 @@ ALWAYS_KEEP_DISTFILES= yes subdirectory of your ports tree to extract it.</para> <para>The dependency is checked from within the - <maketarget>patch</maketarget> target. The + <buildtarget>patch</buildtarget> target. The <replaceable>target</replaceable> part can be omitted if it - is the same as <makevar>DEPENDS_TARGET</makevar>.</para> + is the same as <varname>DEPENDS_TARGET</varname>.</para> </sect2> - <sect2 id="uses"> - <title><makevar>USES</makevar></title> + <sect2 xml:id="uses"> + <title><varname>USES</varname></title> <para>There several parameters exist for defining different kind of features and dependencies that the port in question @@ -3822,33 +3785,32 @@ ALWAYS_KEEP_DISTFILES= yes <programlisting>USES= feature[:arguments]</programlisting> - <para>For the complete list of such values, please see <xref - linkend="uses-values"/>.</para> + <para>For the complete list of such values, please see <xref linkend="uses-values"/>.</para> <warning> - <para><makevar>USES</makevar> cannot be assigned after + <para><varname>USES</varname> cannot be assigned after inclusion of <filename>bsd.port.pre.mk</filename>.</para> </warning> </sect2> - <sect2 id="use-vars"> - <title><makevar>USE_<replaceable>*</replaceable></makevar></title> + <sect2 xml:id="use-vars"> + <title><varname>USE_<replaceable>*</replaceable></varname></title> <para>Several variables exist to define common dependencies shared by many ports. Their use is optional, but helps to reduce the verbosity of the port <filename>Makefile</filename>s. Each of them is styled as - <makevar>USE_<replaceable>*</replaceable></makevar>. + <varname>USE_<replaceable>*</replaceable></varname>. These variables may be used only in the port <filename>Makefile</filename>s and <filename>ports/Mk/bsd.*.mk</filename>. They are not meant for user-settable options — use - <makevar>PORT_OPTIONS</makevar> for that purpose.</para> + <varname>PORT_OPTIONS</varname> for that purpose.</para> <note> <para>It is <emphasis>always</emphasis> incorrect to set any - <makevar>USE_<replaceable>*</replaceable></makevar> in + <varname>USE_<replaceable>*</replaceable></varname> in <filename>/etc/make.conf</filename>. For instance, setting</para> @@ -3861,7 +3823,7 @@ ALWAYS_KEEP_DISTFILES= yes <table frame="none"> <title>The - <makevar>USE_<replaceable>*</replaceable></makevar> + <varname>USE_<replaceable>*</replaceable></varname> Variables</title> <tgroup cols="2"> @@ -3874,19 +3836,19 @@ ALWAYS_KEEP_DISTFILES= yes <tbody> <row> - <entry><makevar>USE_BZIP2</makevar></entry> + <entry><varname>USE_BZIP2</varname></entry> <entry>The port's tarballs are compressed with <command>bzip2</command>.</entry> </row> <row> - <entry><makevar>USE_ZIP</makevar></entry> + <entry><varname>USE_ZIP</varname></entry> <entry>The port's tarballs are compressed with <command>zip</command>.</entry> </row> <row> - <entry><makevar>USE_GCC</makevar></entry> + <entry><varname>USE_GCC</varname></entry> <entry>The port requires GCC (<command>gcc</command> or <command>g++</command>) to build. Some ports need any GCC version, some require modern, recent @@ -3903,8 +3865,8 @@ ALWAYS_KEEP_DISTFILES= yes <literal>4.6+</literal>. The GCC from the base system is used when it satisfies the requested version, otherwise an appropriate compiler in built - from the port, and the <makevar>CC</makevar> and - <makevar>CXX</makevar> variables are adjusted + from the port, and the <varname>CC</varname> and + <varname>CXX</varname> variables are adjusted accordingly.</entry> </row> </tbody> @@ -3941,11 +3903,11 @@ ALWAYS_KEEP_DISTFILES= yes <title>Minimal Version of a Dependency</title> <para>A minimal version of a dependency can be specified in - any <makevar>*_DEPENDS</makevar> variable except - <makevar>LIB_DEPENDS</makevar> using the following + any <varname>*_DEPENDS</varname> variable except + <varname>LIB_DEPENDS</varname> using the following syntax:</para> - <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting> + <programlisting>p5-Spiffy>=0.26:${PORTSDIR}/devel/p5-Spiffy</programlisting> <para>The first field contains a dependent package name, which must match the entry in the package database, a comparison @@ -3958,26 +3920,26 @@ ALWAYS_KEEP_DISTFILES= yes <para>As mentioned above, the default target to call when a dependency is required is - <maketarget>DEPENDS_TARGET</maketarget>. It defaults to + <buildtarget>DEPENDS_TARGET</buildtarget>. It defaults to <literal>install</literal>. This is a user variable; it is never defined in a port's <filename>Makefile</filename>. If your port needs a special way to handle a dependency, use the <literal>:target</literal> part of the - <makevar>*_DEPENDS</makevar> variables instead of redefining - <makevar>DEPENDS_TARGET</makevar>.</para> + <varname>*_DEPENDS</varname> variables instead of redefining + <varname>DEPENDS_TARGET</varname>.</para> <para>When you type <command>make clean</command>, its dependencies are automatically cleaned too. If you do not wish this to happen, define the variable - <makevar>NOCLEANDEPENDS</makevar> in your environment. This + <varname>NOCLEANDEPENDS</varname> in your environment. This may be particularly desirable if the port has something that takes a long time to rebuild in its dependency list, such as KDE, GNOME or Mozilla.</para> <para>To depend on another port unconditionally, use the - variable <makevar>${NONEXISTENT}</makevar> as the first - field of <makevar>BUILD_DEPENDS</makevar> or - <makevar>RUN_DEPENDS</makevar>. Use this only when you need + variable <varname>${NONEXISTENT}</varname> as the first + field of <varname>BUILD_DEPENDS</varname> or + <varname>RUN_DEPENDS</varname>. Use this only when you need to get the source of the other port. You can often save compilation time by specifying the target too. For instance</para> @@ -4012,8 +3974,7 @@ ALWAYS_KEEP_DISTFILES= yes <title>Problems Caused by Automatic Dependencies</title> <para>Dependencies must be declared either explicitly or by - using the <link - linkend="makefile-options">OPTIONS framework</link>. + using the <link linkend="makefile-options">OPTIONS framework</link>. Using other methods like automatic detection complicates indexing, which causes problems for port and package management.</para> @@ -4059,45 +4020,45 @@ LIB_DEPENDS= bar:${PORTSDIR}/foo/bar packages.</para> </sect2> - <sect2 id="use-want"> - <title><makevar>USE_</makevar> and - <makevar>WANT_</makevar></title> + <sect2 xml:id="use-want"> + <title><varname>USE_</varname> and + <varname>WANT_</varname></title> - <para><makevar>USE_</makevar> variables are set by the port + <para><varname>USE_</varname> variables are set by the port maintainer to define software on which this port depends. A port that needs Firefox would set</para> <programlisting>USE_FIREFOX= yes</programlisting> - <para>Some <makevar>USE_</makevar> variables can accept + <para>Some <varname>USE_</varname> variables can accept version numbers or other parameters. For example, a port that requires Apache 2.2 would set</para> <programlisting>USE_APACHE= 22</programlisting> <para>For more control over dependencies in some cases, - <makevar>WANT_</makevar> variables are available to more + <varname>WANT_</varname> variables are available to more precisely specify what is needed. For example, consider the - <filename role="package">mail/squirrelmail</filename> port. + <package>mail/squirrelmail</package> port. This port needs some PHP modules, which are listed in the - <makevar>USE_PHP</makevar> variable:</para> + <varname>USE_PHP</varname> variable:</para> <programlisting>USE_PHP= session mhash gettext mbstring pcre openssl xml</programlisting> <para>Those modules may be available in CLI or web versions, so the web version is selected with a - <makevar>WANT_</makevar> variable:</para> + <varname>WANT_</varname> variable:</para> <programlisting>WANT_PHP_WEB= yes</programlisting> - <para>Available <makevar>USE_</makevar> and - <makevar>WANT_</makevar> variables are defined in the files + <para>Available <varname>USE_</varname> and + <varname>WANT_</varname> variables are defined in the files in <filename>/usr/ports/Mk</filename>.</para> </sect2> </sect1> - <sect1 id="makefile-masterdir"> - <title><makevar>MASTERDIR</makevar></title> + <sect1 xml:id="makefile-masterdir"> + <title><varname>MASTERDIR</varname></title> <para>If your port needs to build slightly different versions of packages by having a variable (for instance, resolution, or @@ -4107,10 +4068,9 @@ LIB_DEPENDS= bar:${PORTSDIR}/foo/bar you only need a very short <filename>Makefile</filename> in all but one of the directories if you use variables cleverly. In the sole <filename>Makefile</filename>, you can use - <makevar>MASTERDIR</makevar> to specify the directory where + <varname>MASTERDIR</varname> to specify the directory where the rest of the files are. Also, use a variable as part of - <link - linkend="porting-pkgname"><makevar>PKGNAMESUFFIX</makevar></link> + <link linkend="porting-pkgname"><varname>PKGNAMESUFFIX</varname></link> so the packages will have different names.</para> <para>This will be best demonstrated by an example. This is @@ -4130,7 +4090,7 @@ RESOLUTION?= 300 @${FALSE} .endif</programlisting> - <para><filename role="package">japanese/xdvi300</filename> also + <para><package>japanese/xdvi300</package> also has all the regular patches, package files, etc. If you type <command>make</command> there, it will take the default value for the resolution (300) and build the port normally.</para> @@ -4146,10 +4106,10 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <para>(<filename>xdvi240/Makefile</filename> and <filename>xdvi400/Makefile</filename> are similar). The - <makevar>MASTERDIR</makevar> definition tells + <varname>MASTERDIR</varname> definition tells <filename>bsd.port.mk</filename> that the regular set of - subdirectories like <makevar>FILESDIR</makevar> and - <makevar>SCRIPTDIR</makevar> are to be found under + subdirectories like <varname>FILESDIR</varname> and + <varname>SCRIPTDIR</varname> are to be found under <filename>xdvi300</filename>. The <literal>RESOLUTION=118</literal> line will override the <literal>RESOLUTION=300</literal> line in @@ -4157,35 +4117,35 @@ MASTERDIR= ${.CURDIR}/../xdvi300 built with resolution set to 118.</para> </sect1> - <sect1 id="makefile-manpages"> + <sect1 xml:id="makefile-manpages"> <title>Man Pages</title> <para>If your port anchors its man tree somewhere other than - <makevar>PREFIX</makevar>, you can use - <makevar>MANDIRS</makevar> to specify those directories. Note + <varname>PREFIX</varname>, you can use + <varname>MANDIRS</varname> to specify those directories. Note that the files corresponding to manual pages should be placed in <filename>pkg-plist</filename> along with the rest of the files. - The purpose of <makevar>MANDIRS</makevar> is to enable automatic + The purpose of <varname>MANDIRS</varname> is to enable automatic compression of manual pages, therefore the file names should be suffixed with <filename>.gz</filename>.</para> </sect1> - <sect1 id="makefile-info"> + <sect1 xml:id="makefile-info"> <title>Info Files</title> <para>If your package needs to install GNU info files, they - should be listed in the <makevar>INFO</makevar> variable + should be listed in the <varname>INFO</varname> variable (without the trailing <literal>.info</literal>), one entry per document. These files are assumed to be installed to - <filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar></filename>. - You can change <makevar>INFO_PATH</makevar> if your package + <filename>PREFIX/INFO_PATH</filename>. + You can change <varname>INFO_PATH</varname> if your package uses a different location. However, this is not recommended. These entries contain just the path relative to - <filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar></filename>. - For example, <filename role="package">lang/gcc34</filename> + <filename>PREFIX/INFO_PATH</filename>. + For example, <package>lang/gcc34</package> installs info files to - <filename><makevar>PREFIX</makevar>/<makevar>INFO_PATH</makevar>/gcc34</filename>, - and <makevar>INFO</makevar> will be something like + <filename>PREFIX/INFO_PATH/gcc34</filename>, + and <varname>INFO</varname> will be something like this:</para> <programlisting>INFO= gcc34/cpp gcc34/cppinternals gcc34/g77 ...</programlisting> @@ -4196,7 +4156,7 @@ MASTERDIR= ${.CURDIR}/../xdvi300 registration.</para> </sect1> - <sect1 id="makefile-options"> + <sect1 xml:id="makefile-options"> <title>Makefile Options</title> <para>Many applications can be built with optional or differing @@ -4212,26 +4172,25 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <title>Knobs</title> <sect3> - <title><makevar>WITH_<replaceable>*</replaceable></makevar> + <title><varname>WITH_<replaceable>*</replaceable></varname> and - <makevar>WITHOUT_<replaceable>*</replaceable></makevar></title> + <varname>WITHOUT_<replaceable>*</replaceable></varname></title> <para>These variables are designed to be set by the system administrator. There are many that are standardized in - the <ulink - url="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></ulink> + the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>ports/KNOBS</filename></link> file.</para> <para>When creating a port, do not make knob names specific to a given application. For example in Avahi port, use - <makevar>WITHOUT_MDNS</makevar> instead of - <makevar>WITHOUT_AVAHI_MDNS</makevar>.</para> + <varname>WITHOUT_MDNS</varname> instead of + <varname>WITHOUT_AVAHI_MDNS</varname>.</para> <note> <para>You should not assume that a - <makevar>WITH_<replaceable>*</replaceable></makevar> + <varname>WITH_<replaceable>*</replaceable></varname> necessarily has a corresponding - <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + <varname>WITHOUT_<replaceable>*</replaceable></varname> variable and vice versa. In general, the default is simply assumed.</para> </note> @@ -4245,8 +4204,8 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <table frame="none"> <title>Common - <makevar>WITH_<replaceable>*</replaceable></makevar> and - <makevar>WITHOUT_<replaceable>*</replaceable></makevar> + <varname>WITH_<replaceable>*</replaceable></varname> and + <varname>WITHOUT_<replaceable>*</replaceable></varname> Variables</title> <tgroup cols="2"> @@ -4259,16 +4218,15 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <tbody> <row> - <entry><makevar>WITH_OPENSSL_BASE</makevar></entry> + <entry><varname>WITH_OPENSSL_BASE</varname></entry> <entry>Use the version of OpenSSL in the base system.</entry> </row> <row> - <entry><makevar>WITH_OPENSSL_PORT</makevar></entry> + <entry><varname>WITH_OPENSSL_PORT</varname></entry> <entry>Installs the version of OpenSSL from - <filename - role="package">security/openssl</filename>, even + <package>security/openssl</package>, even if the base is up to date.</entry> </row> </tbody> @@ -4282,45 +4240,44 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <para>Porters should use like-named knobs, both for the benefit of end-users and to help keep the number of knob names down. A list of popular knob names can be - found in the <ulink - url="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></ulink> + found in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/KNOBS?view=markup"><filename>KNOBS</filename></link> file.</para> <para>Knob names should reflect what the knob is and does. When a port has a lib-prefix in the - <makevar>PORTNAME</makevar> the lib-prefix should be + <varname>PORTNAME</varname> the lib-prefix should be dropped in knob naming.</para> </sect3> </sect2> <sect2> - <title><makevar>OPTIONS</makevar></title> + <title><varname>OPTIONS</varname></title> <sect3> <title>Background</title> - <para>The <makevar>OPTIONS_*</makevar> variables give the + <para>The <varname>OPTIONS_*</varname> variables give the user installing the port a dialog showing the available options, and then saves those options to - <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>. + <filename>/var/db/ports/${UNIQUENAME}/options</filename>. The next time the port is built, the options are reused.</para> <para>When the user runs <command>make config</command> (or runs <command>make build</command> for the first time), the framework checks for - <filename>/var/db/ports/<makevar>${UNIQUENAME}</makevar>/options</filename>. + <filename>/var/db/ports/${UNIQUENAME}/options</filename>. If that file does not exist, the values of - <makevar>OPTIONS_*</makevar> are used, and a dialog box is + <varname>OPTIONS_*</varname> are used, and a dialog box is displayed where the options can be enabled or disabled. Then the <filename>options</filename> file is saved and the configured variables are used when building the port.</para> <para>If a new version of the port adds new - <makevar>OPTIONS</makevar>, the dialog will be presented + <varname>OPTIONS</varname>, the dialog will be presented to the user with the saved values of old - <makevar>OPTIONS</makevar> prefilled.</para> + <varname>OPTIONS</varname> prefilled.</para> <para><command>make showconfig</command> shows the saved configuration. Use <command>make rmconfig</command> @@ -4330,13 +4287,13 @@ MASTERDIR= ${.CURDIR}/../xdvi300 <sect3> <title>Syntax</title> - <para><makevar>OPTIONS_DEFINE</makevar> contains a list of - <makevar>OPTIONS</makevar> to be used. These are + <para><varname>OPTIONS_DEFINE</varname> contains a list of + <varname>OPTIONS</varname> to be used. These are independent of each other and are not grouped:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT2</programlisting> - <para>Once defined, <makevar>OPTIONS</makevar> are + <para>Once defined, <varname>OPTIONS</varname> are described (optional, but strongly recommended):</para> <programlisting>OPT1_DESC= Describe OPT1 @@ -4349,7 +4306,7 @@ OPT6_DESC= Describe OPT6</programlisting> <tip> <para><filename>ports/Mk/bsd.options.desc.mk</filename> has descriptions for many common - <makevar>OPTIONS</makevar>; there is usually no need + <varname>OPTIONS</varname>; there is usually no need to override these.</para> </tip> @@ -4366,21 +4323,21 @@ OPT6_DESC= Describe OPT6</programlisting> much more helpful.</para> </tip> - <para><makevar>OPTIONS</makevar> can be grouped as radio + <para><varname>OPTIONS</varname> can be grouped as radio choices, where only one choice from each group is allowed:</para> <programlisting>OPTIONS_SINGLE= SG1 OPTIONS_SINGLE_SG1= OPT3 OPT4</programlisting> - <para><makevar>OPTIONS</makevar> can be grouped as radio + <para><varname>OPTIONS</varname> can be grouped as radio choices, where none or only one choice from each group is allowed:</para> <programlisting>OPTIONS_RADIO= RG1 OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting> - <para><makevar>OPTIONS</makevar> can also be grouped as + <para><varname>OPTIONS</varname> can also be grouped as <quote>multiple-choice</quote> lists, where <emphasis>at least one</emphasis> option must be enabled:</para> @@ -4388,23 +4345,23 @@ OPTIONS_RADIO_RG1= OPT7 OPT8</programlisting> <programlisting>OPTIONS_MULTI= MG1 OPTIONS_MULTI_MG1= OPT5 OPT6</programlisting> - <para><makevar>OPTIONS</makevar> can also be grouped as + <para><varname>OPTIONS</varname> can also be grouped as <quote>multiple-choice</quote> lists, where none or any option can be enabled:</para> <programlisting>OPTIONS_GROUP= GG1 OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting> - <para><makevar>OPTIONS</makevar> are unset by default, + <para><varname>OPTIONS</varname> are unset by default, unless they are listed in - <makevar>OPTIONS_DEFAULT</makevar>:</para> + <varname>OPTIONS_DEFAULT</varname>:</para> <programlisting>OPTIONS_DEFAULT= OPT1 OPT3 OPT6</programlisting> - <para><makevar>OPTIONS</makevar> definitions must appear + <para><varname>OPTIONS</varname> definitions must appear before the inclusion of <filename>bsd.port.options.mk</filename>. The - <makevar>PORT_OPTIONS</makevar> variable can only be + <varname>PORT_OPTIONS</varname> variable can only be tested after the inclusion of <filename>bsd.port.options.mk</filename>. Inclusion of <filename>bsd.port.pre.mk</filename> can be used instead, @@ -4413,10 +4370,10 @@ OPTIONS_GROUP_GG1= OPT9 OPT10</programlisting> But be aware that some variables will not work as expected after the inclusion of <filename>bsd.port.pre.mk</filename>, typically some - <makevar>USE_*</makevar> flags.</para> + <varname>USE_*</varname> flags.</para> - <example id="ports-options-simple-use"> - <title>Simple Use of <makevar>OPTIONS</makevar></title> + <example xml:id="ports-options-simple-use"> + <title>Simple Use of <varname>OPTIONS</varname></title> <programlisting>OPTIONS_DEFINE= FOO BAR FOO_DESC= Enable option foo @@ -4439,17 +4396,17 @@ RUN_DEPENDS+= bar:${PORTSDIR}/bar/bar .include <bsd.port.mk></programlisting> </example> - <example id ="ports-options-check-unset"> + <example xml:id="ports-options-check-unset"> <title>Check for Unset Port - <makevar>OPTIONS</makevar></title> + <varname>OPTIONS</varname></title> <programlisting>.if ! ${PORT_OPTIONS:MEXAMPLES} CONFIGURE_ARGS+=--without-examples .endif</programlisting> </example> - <example id="ports-options-practical-use"> - <title>Practical Use of <makevar>OPTIONS</makevar></title> + <example xml:id="ports-options-practical-use"> + <title>Practical Use of <varname>OPTIONS</varname></title> <programlisting>OPTIONS_DEFINE= EXAMPLES @@ -4521,9 +4478,9 @@ CONFIGURE_ARGS+= --without-examples <note> <para>There is no need to add these to - <makevar>OPTIONS_DEFAULT</makevar>. To have them show + <varname>OPTIONS_DEFAULT</varname>. To have them show up in the options selection dialog, however, they must - be added to <makevar>OPTIONS_DEFINE</makevar>.</para> + be added to <varname>OPTIONS_DEFINE</varname>.</para> </note> </sect3> </sect2> @@ -4536,7 +4493,7 @@ CONFIGURE_ARGS+= --without-examples Explicitly disable optional features you do not wish to be used by passing respective <literal>--without-xxx</literal> or <literal>--disable-xxx</literal> in - <makevar>CONFIGURE_ARGS</makevar>.</para> + <varname>CONFIGURE_ARGS</varname>.</para> <example> <title>Wrong Handling of an Option</title> @@ -4592,10 +4549,10 @@ CONFIGURE_ARGS+= --disable-foo <para>There are some macros to help simplify conditional values which differ based on the options set.</para> - <para>If <makevar>OPTIONS_SUB</makevar> is set to + <para>If <varname>OPTIONS_SUB</varname> is set to <literal>yes</literal> then each of the options added - to <makevar>OPTIONS_DEFINE</makevar> will be added to - <makevar>PLIST_SUB</makevar>, for example:</para> + to <varname>OPTIONS_DEFINE</varname> will be added to + <varname>PLIST_SUB</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPTIONS_SUB= yes</programlisting> @@ -4612,11 +4569,11 @@ PLIST_SUB+= OPT1="" PLIST_SUB+= OPT1="@comment " .endif</programlisting> - <para>If <makevar>X_CONFIGURE_ENABLE</makevar> is set then + <para>If <varname>X_CONFIGURE_ENABLE</varname> is set then <literal>--enable-${X_CONFIGURE_ENABLE}</literal> or <literal>--disable-${X_CONFIGURE_ENABLE}</literal> will be - added to <makevar>CONFIGURE_ARGS</makevar> depending on the - value of the option<makevar>X</makevar>, for example:</para> + added to <varname>CONFIGURE_ARGS</varname> depending on the + value of the option<varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT1_CONFIGURE_ENABLE= test</programlisting> @@ -4633,11 +4590,11 @@ CONFIGURE_ARGS+= --enable-test CONFIGURE_ARGS+= --disable-test .endif</programlisting> - <para>If <makevar>X_CONFIGURE_WITH</makevar> is set then + <para>If <varname>X_CONFIGURE_WITH</varname> is set then <literal>--with-${X_CONFIGURE_WITH}</literal> or <literal>--without-${X_CONFIGURE_WITH}</literal> will - be added to <makevar>CONFIGURE_ARGS</makevar> depending - on the status of the option <makevar>X</makevar>, + be added to <varname>CONFIGURE_ARGS</varname> depending + on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4655,9 +4612,9 @@ CONFIGURE_ARGS+= --with-test CONFIGURE_ARGS+= --without-test .endif</programlisting> - <para>If <makevar>X_CONFIGURE_ON</makevar> is set then its - value will be appended to <makevar>CONFIGURE_ARGS</makevar> - depending on the status of the option <makevar>X</makevar>, + <para>If <varname>X_CONFIGURE_ON</varname> is set then its + value will be appended to <varname>CONFIGURE_ARGS</varname> + depending on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4673,9 +4630,9 @@ OPT1_CONFIGURE_ON= --add-test</programlisting> CONFIGURE_ARGS+= --add-test .endif</programlisting> - <para>If <makevar>X_CONFIGURE_OFF</makevar> is set then its - value will be appended to <makevar>CONFIGURE_ARGS</makevar> - depending on the status of the option <makevar>X</makevar>, + <para>If <varname>X_CONFIGURE_OFF</varname> is set then its + value will be appended to <varname>CONFIGURE_ARGS</varname> + depending on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4689,9 +4646,9 @@ OPT1_CONFIGURE_OFF= --no-test</programlisting> CONFIGURE_ARGS+= --no-test .endif</programlisting> - <para>If <makevar>X_CMAKE_ON</makevar> is set then its value - will be appended to <makevar>CMAKE_ARGS</makevar> depending - on the status of the option <makevar>X</makevar>, for + <para>If <varname>X_CMAKE_ON</varname> is set then its value + will be appended to <varname>CMAKE_ARGS</varname> depending + on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4707,9 +4664,9 @@ OPT1_CMAKE_ON= -DTEST:BOOL=true</programlisting> CMAKE_ARGS+= -DTEST:BOOL=true .endif</programlisting> - <para>If <makevar>X_CMAKE_OFF</makevar> is set then its value - will be appended to <makevar>CMAKE_ARGS</makevar> depending - on the status of the option <makevar>X</makevar>, for + <para>If <varname>X_CMAKE_OFF</varname> is set then its value + will be appended to <varname>CMAKE_ARGS</varname> depending + on the status of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 @@ -4729,82 +4686,82 @@ CMAKE_ARGS+= -DTEST:BOOL=false <itemizedlist> <listitem> - <para><makevar>ALL_TARGET</makevar></para> + <para><varname>ALL_TARGET</varname></para> </listitem> <listitem> - <para><makevar>CATEGORIES</makevar></para> + <para><varname>CATEGORIES</varname></para> </listitem> <listitem> - <para><makevar>CFLAGS</makevar></para> + <para><varname>CFLAGS</varname></para> </listitem> <listitem> - <para><makevar>CPPFLAGS</makevar></para> + <para><varname>CPPFLAGS</varname></para> </listitem> <listitem> - <para><makevar>CXXFLAGS</makevar></para> + <para><varname>CXXFLAGS</varname></para> </listitem> <listitem> - <para><makevar>CONFIGURE_ENV</makevar></para> + <para><varname>CONFIGURE_ENV</varname></para> </listitem> <listitem> - <para><makevar>DISTFILES</makevar></para> + <para><varname>DISTFILES</varname></para> </listitem> <listitem> - <para><makevar>EXTRA_PATCHES</makevar></para> + <para><varname>EXTRA_PATCHES</varname></para> </listitem> <listitem> - <para><makevar>INSTALL_TARGET</makevar></para> + <para><varname>INSTALL_TARGET</varname></para> </listitem> <listitem> - <para><makevar>LDFLAGS</makevar></para> + <para><varname>LDFLAGS</varname></para> </listitem> <listitem> - <para><makevar>MAKE_ARGS</makevar></para> + <para><varname>MAKE_ARGS</varname></para> </listitem> <listitem> - <para><makevar>MAKE_ENV</makevar></para> + <para><varname>MAKE_ENV</varname></para> </listitem> <listitem> - <para><makevar>PATCH_SITES</makevar></para> + <para><varname>PATCH_SITES</varname></para> </listitem> <listitem> - <para><makevar>PATCHFILES</makevar></para> + <para><varname>PATCHFILES</varname></para> </listitem> <listitem> - <para><makevar>PLIST_FILES</makevar></para> + <para><varname>PLIST_FILES</varname></para> </listitem> <listitem> - <para><makevar>PLIST_DIRS</makevar></para> + <para><varname>PLIST_DIRS</varname></para> </listitem> <listitem> - <para><makevar>PLIST_DIRSTRY</makevar></para> + <para><varname>PLIST_DIRSTRY</varname></para> </listitem> <listitem> - <para><makevar>USES</makevar></para> + <para><varname>USES</varname></para> </listitem> </itemizedlist> - <para>If <makevar>X_ABOVEVARIABLE</makevar> is defined then + <para>If <varname>X_ABOVEVARIABLE</varname> is defined then its value will be appended to - <makevar>ABOVEVARIABLE</makevar> depending on the status of - the option <makevar>X</makevar>, for example:</para> + <varname>ABOVEVARIABLE</varname> depending on the status of + the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT1_USES= gmake @@ -4825,38 +4782,38 @@ CFLAGS+= -DTEST <itemizedlist> <listitem> - <para><makevar>PKG_DEPENDS</makevar></para> + <para><varname>PKG_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>EXTRACT_DEPENDS</makevar></para> + <para><varname>EXTRACT_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>PATCH_DEPENDS</makevar></para> + <para><varname>PATCH_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>FETCH_DEPENDS</makevar></para> + <para><varname>FETCH_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>BUILD_DEPENDS</makevar></para> + <para><varname>BUILD_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>LIB_DEPENDS</makevar></para> + <para><varname>LIB_DEPENDS</varname></para> </listitem> <listitem> - <para><makevar>RUN_DEPENDS</makevar></para> + <para><varname>RUN_DEPENDS</varname></para> </listitem> </itemizedlist> - <para>If <makevar>X_ABOVEVARIABLE</makevar> is defined then + <para>If <varname>X_ABOVEVARIABLE</varname> is defined then its value will be appended to - <makevar>ABOVEVARIABLE</makevar> depending on the status - of the option <makevar>X</makevar>, for example:</para> + <varname>ABOVEVARIABLE</varname> depending on the status + of the option <varname>X</varname>, for example:</para> <programlisting>OPTIONS_DEFINE= OPT1 OPT1_LIB_DEPENDS= liba.so:${PORTSDIR}/devel/a</programlisting> @@ -4873,12 +4830,12 @@ LIB_DEPENDS+= liba.so:${PORTSDIR}/devel/a </sect2> </sect1> - <sect1 id="makefile-wrkdir"> + <sect1 xml:id="makefile-wrkdir"> <title>Specifying the Working Directory</title> <para>Each port is extracted in to a working directory, which must be writable. The ports system defaults to having the - <makevar>DISTFILES</makevar> unpack in to a directory called + <varname>DISTFILES</varname> unpack in to a directory called <literal>${DISTNAME}</literal>. In other words, if you have set:</para> @@ -4893,7 +4850,7 @@ PORTVERSION= 1.0</programlisting> is not the case.</para> <sect2> - <title><makevar>WRKSRC</makevar></title> + <title><varname>WRKSRC</varname></title> <para>The variable lists the name of the directory that is created when the application's distfiles are extracted. If @@ -4909,59 +4866,59 @@ PORTVERSION= 1.0</programlisting> </sect2> <sect2> - <title><makevar>NO_WRKSUBDIR</makevar></title> + <title><varname>NO_WRKSUBDIR</varname></title> <para>If the port does not extract in to a subdirectory at all - then you should set <makevar>NO_WRKSUBDIR</makevar> to + then you should set <varname>NO_WRKSUBDIR</varname> to indicate that.</para> <programlisting>NO_WRKSUBDIR= yes</programlisting> </sect2> </sect1> - <sect1 id="conflicts"> + <sect1 xml:id="conflicts"> <title>Conflict Handling</title> <para>There are three different variables to register a conflict - between packages and ports: <makevar>CONFLICTS</makevar>, - <makevar>CONFLICTS_INSTALL</makevar> and - <makevar>CONFLICTS_BUILD</makevar>.</para> + between packages and ports: <varname>CONFLICTS</varname>, + <varname>CONFLICTS_INSTALL</varname> and + <varname>CONFLICTS_BUILD</varname>.</para> <note> <para>The conflict variables automatically set the variable - <makevar>IGNORE</makevar>, which is more fully documented + <varname>IGNORE</varname>, which is more fully documented in <xref linkend="dads-noinstall"/>.</para> </note> <para>When removing one of several conflicting ports, it is - advisable to retain the <makevar>CONFLICTS</makevar> entries + advisable to retain the <varname>CONFLICTS</varname> entries in those other ports for a few months to cater for users who only update once in a while.</para> <sect2> - <title><makevar>CONFLICTS_INSTALL</makevar></title> + <title><varname>CONFLICTS_INSTALL</varname></title> <para>If your package cannot coexist with other packages (because of file conflicts, runtime incompatibilities, etc.), list the other package names in the - <makevar>CONFLICTS_INSTALL</makevar> variable. You can use + <varname>CONFLICTS_INSTALL</varname> variable. You can use shell globs like <literal>*</literal> and <literal>?</literal> here. Package names should be enumerated the same way they appear in <filename>/var/db/pkg</filename>. Please make sure that - <makevar>CONFLICTS_INSTALL</makevar> does not match this + <varname>CONFLICTS_INSTALL</varname> does not match this port's package itself. Otherwise enforcing its installation - with <makevar>FORCE_PKG_REGISTER</makevar> will no longer + with <varname>FORCE_PKG_REGISTER</varname> will no longer work. The CONFLICTS_INSTALL check is done after the build stage and prior to the install stage.</para> </sect2> <sect2> - <title><makevar>CONFLICTS_BUILD</makevar></title> + <title><varname>CONFLICTS_BUILD</varname></title> <para>If your port cannot be built if a certain port is already installed, list the other port names in the - <makevar>CONFLICTS_BUILD</makevar> variable. You can use + <varname>CONFLICTS_BUILD</varname> variable. You can use shell globs like <literal>*</literal> and <literal>?</literal> here. Package names should be enumerated the same way they appear in @@ -4971,37 +4928,37 @@ PORTVERSION= 1.0</programlisting> </sect2> <sect2> - <title><makevar>CONFLICTS</makevar></title> + <title><varname>CONFLICTS</varname></title> <para>If your port cannot be built if a certain port is already installed and the resulting package cannot coexist with the other package, list the other package name in the - <makevar>CONFLICTS</makevar> variable. You can use shell + <varname>CONFLICTS</varname> variable. You can use shell globs like <literal>*</literal> and <literal>?</literal> here. Packages names should be enumerated the same way they appear in <filename>/var/db/pkg</filename>. Please make - sure that <makevar>CONFLICTS_INSTALL</makevar> does not + sure that <varname>CONFLICTS_INSTALL</varname> does not match this port's package itself. Otherwise enforcing its - installation with <makevar>FORCE_PKG_REGISTER</makevar> will + installation with <varname>FORCE_PKG_REGISTER</varname> will no longer work. The CONFLICTS check is done prior to the build stage and prior to the install stage.</para> </sect2> </sect1> - <sect1 id="install"> + <sect1 xml:id="install"> <title>Installing Files</title> - <sect2 id="install-macros"> - <title><makevar>INSTALL_*</makevar> Macros</title> + <sect2 xml:id="install-macros"> + <title><varname>INSTALL_*</varname> Macros</title> <para>Use the macros provided in <filename>bsd.port.mk</filename> to ensure correct modes of - files in the port's <maketarget>*-install</maketarget> targets. + files in the port's <buildtarget>*-install</buildtarget> targets. Set ownership directly in <filename>pkg-plist</filename> with the corresponding entries, such as <literal>@owner - <replaceable>owner</replaceable></literal> and <literal>@group - <replaceable>group</replaceable></literal>. These + owner</literal> and <literal>@group + group</literal>. These operators work until being overridden, or until the end of <filename>pkg-plist</filename>, so do not forget to reset them after they are no longer needed. The default @@ -5010,35 +4967,35 @@ PORTVERSION= 1.0</programlisting> <itemizedlist> <listitem> - <para><makevar>INSTALL_PROGRAM</makevar> is a command to + <para><varname>INSTALL_PROGRAM</varname> is a command to install binary executables.</para> </listitem> <listitem> - <para><makevar>INSTALL_SCRIPT</makevar> is a command to + <para><varname>INSTALL_SCRIPT</varname> is a command to install executable scripts.</para> </listitem> <listitem> - <para><makevar>INSTALL_LIB</makevar> is a command to + <para><varname>INSTALL_LIB</varname> is a command to install shared libraries.</para> </listitem> <listitem> - <para><makevar>INSTALL_KLD</makevar> is a command to + <para><varname>INSTALL_KLD</varname> is a command to install kernel loadable modules. Some architectures do not like having the modules stripped, so use this command instead of - <makevar>INSTALL_PROGRAM</makevar>.</para> + <varname>INSTALL_PROGRAM</varname>.</para> </listitem> <listitem> - <para><makevar>INSTALL_DATA</makevar> is a command to + <para><varname>INSTALL_DATA</varname> is a command to install sharable data.</para> </listitem> <listitem> - <para><makevar>INSTALL_MAN</makevar> is a command to + <para><varname>INSTALL_MAN</varname> is a command to install manpages and other documentation (it does not compress anything).</para> </listitem> @@ -5048,22 +5005,22 @@ PORTVERSION= 1.0</programlisting> command with all the appropriate flags.</para> </sect2> - <sect2 id="install-strip"> + <sect2 xml:id="install-strip"> <title>Stripping Binaries and Shared Libraries</title> <para>Do not strip binaries manually unless you have to. All binaries should be stripped, but the - <makevar>INSTALL_PROGRAM</makevar> macro will install and + <varname>INSTALL_PROGRAM</varname> macro will install and strip a binary at the same time (see the next section). The - <makevar>INSTALL_LIB</makevar> macro does the same thing to + <varname>INSTALL_LIB</varname> macro does the same thing to shared libraries.</para> <para>If you need to strip a file, but wish to use neither - <makevar>INSTALL_PROGRAM</makevar> nor - <makevar>INSTALL_LIB</makevar> macros, - <makevar>${STRIP_CMD}</makevar> will strip your program or + <varname>INSTALL_PROGRAM</varname> nor + <varname>INSTALL_LIB</varname> macros, + <varname>${STRIP_CMD}</varname> will strip your program or shared library. This is typically done within the - <maketarget>post-install</maketarget> target. For + <buildtarget>post-install</buildtarget> target. For example:</para> <programlisting>post-install: @@ -5076,30 +5033,30 @@ PORTVERSION= 1.0</programlisting> stripped program; it will instead exit cleanly.</para> </sect2> - <sect2 id="install-copytree"> + <sect2 xml:id="install-copytree"> <title>Installing a Whole Tree of Files</title> <para>Sometimes, a large number of files must be installed while preserving their hierarchical organization. For example, copying over a whole directory tree from - <makevar>WRKSRC</makevar> to a target directory under - <makevar>PREFIX</makevar>. Note that - <makevar>PREFIX</makevar>, <makevar>EXAMPLESDIR</makevar>, - <makevar>DATADIR</makevar>, and other path varialbes must always be - prepended with <makevar>STAGEDIR</makevar> to respect + <varname>WRKSRC</varname> to a target directory under + <varname>PREFIX</varname>. Note that + <varname>PREFIX</varname>, <varname>EXAMPLESDIR</varname>, + <varname>DATADIR</varname>, and other path varialbes must always be + prepended with <varname>STAGEDIR</varname> to respect staging (see <xref linkend="staging"/>).</para> <para>Two macros exist for this situation. The advantage of using these macros instead of <command>cp</command> is that they guarantee proper file ownership and permissions on target files. The first macro, - <makevar>COPYTREE_BIN</makevar>, will set all the installed + <varname>COPYTREE_BIN</varname>, will set all the installed files to be executable, thus being suitable for installing - into <filename><makevar>PREFIX</makevar>/bin</filename>. - The second macro, <makevar>COPYTREE_SHARE</makevar>, does + into <filename>PREFIX/bin</filename>. + The second macro, <varname>COPYTREE_SHARE</varname>, does not set executable permissions on files, and is therefore suitable for installing files under - <filename><makevar>PREFIX</makevar>/share</filename> + <filename>PREFIX/share</filename> target.</para> <programlisting>post-install: @@ -5117,11 +5074,11 @@ PORTVERSION= 1.0</programlisting> <para>And this example will install the data of summer months to the <filename>summer</filename> subdirectory of a - <filename><makevar>DATADIR</makevar></filename>.</para> + <filename>DATADIR</filename>.</para> <para>Additional <command>find</command> arguments can be passed via the third argument to the - <makevar>COPYTREE_*</makevar> macros. For example, to + <varname>COPYTREE_*</varname> macros. For example, to install all files from the first example except Makefiles, one can use the following command.</para> @@ -5133,34 +5090,33 @@ PORTVERSION= 1.0</programlisting> <para>These macros do not add the installed files to <filename>pkg-plist</filename>. They must be added manually. For optional documentation - (<makevar>PORTDOCS</makevar>, see <xref - linkend="install-documentation"/>) and examples - (<makevar>PORTEXAMPLES</makevar>), the + (<varname>PORTDOCS</varname>, see <xref linkend="install-documentation"/>) and examples + (<varname>PORTEXAMPLES</varname>), the <literal>%%PORTDOCS%%</literal> or <literal>%%PORTEXAMPLES%%</literal> prefixes must be prepended in <filename>pkg-plist</filename>.</para> </sect2> - <sect2 id="install-documentation"> + <sect2 xml:id="install-documentation"> <title>Install Additional Documentation</title> <para>If your software has some documentation other than the standard man and info pages that you think is useful for the user, install it under - <filename><makevar>PREFIX</makevar>/share/doc</filename>. + <filename>PREFIX/share/doc</filename>. This can be done, like the previous item, in the - <maketarget>post-install</maketarget> target.</para> + <buildtarget>post-install</buildtarget> target.</para> <para>Create a new directory for your port. The directory name should reflect what the port is. This usually means - <makevar>PORTNAME</makevar>. However, if you think the user + <varname>PORTNAME</varname>. However, if you think the user might want different versions of the port to be installed at the same time, you can use the whole - <makevar>PKGNAME</makevar>.</para> + <varname>PKGNAME</varname>.</para> <para>Since only the files listed in <filename>pkg-plist</filename> are installed, it is safe to - always install documentation to <makevar>STAGEDIR</makevar> + always install documentation to <varname>STAGEDIR</varname> (see <xref linkend="staging"/>). Hence <literal>.if</literal> blocks are only needed when the installed files are large enough to cause significant I/O overhead.</para> @@ -5175,53 +5131,53 @@ PORTVERSION= 1.0</programlisting> <itemizedlist> <listitem> - <para><makevar>DATADIR</makevar> gets expanded to - <filename><makevar>PREFIX</makevar>/share/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DATADIR</varname> gets expanded to + <filename>PREFIX/share/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>DATADIR_REL</makevar> gets expanded to - <filename>share/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DATADIR_REL</varname> gets expanded to + <filename>share/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>DOCSDIR</makevar> gets expanded to - <filename><makevar>PREFIX</makevar>/share/doc/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DOCSDIR</varname> gets expanded to + <filename>PREFIX/share/doc/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>DOCSDIR_REL</makevar> gets expanded to - <filename>share/doc/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>DOCSDIR_REL</varname> gets expanded to + <filename>share/doc/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>EXAMPLESDIR</makevar> gets expanded to - <filename><makevar>PREFIX</makevar>/share/examples/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>EXAMPLESDIR</varname> gets expanded to + <filename>PREFIX/share/examples/PORTNAME</filename>.</para> </listitem> <listitem> - <para><makevar>EXAMPLESDIR_REL</makevar> gets expanded to - <filename>share/examples/<makevar>PORTNAME</makevar></filename>.</para> + <para><varname>EXAMPLESDIR_REL</varname> gets expanded to + <filename>share/examples/PORTNAME</filename>.</para> </listitem> </itemizedlist> <note> <para>The <literal>DOCS</literal> option only controls additional documentation installed in - <makevar>DOCSDIR</makevar>. It does not apply to standard + <varname>DOCSDIR</varname>. It does not apply to standard man pages and info pages. Things installed in - <makevar>DATADIR</makevar> and - <makevar>EXAMPLESDIR</makevar> are controlled by + <varname>DATADIR</varname> and + <varname>EXAMPLESDIR</varname> are controlled by <literal>DATA</literal> and <literal>EXAMPLES</literal> options, respectively.</para> </note> <para>These variables are exported to - <makevar>PLIST_SUB</makevar>. Their values will appear + <varname>PLIST_SUB</varname>. Their values will appear there as pathnames relative to - <filename><makevar>PREFIX</makevar></filename> if possible. + <filename>PREFIX</filename> if possible. That is, - <filename>share/doc/<makevar>PORTNAME</makevar></filename> + <filename>share/doc/PORTNAME</filename> will be substituted for <literal>%%DOCSDIR%%</literal> in the packing list by default, and so on. (See more on <filename>pkg-plist</filename> substitution @@ -5238,31 +5194,31 @@ PORTVERSION= 1.0</programlisting> <para>As an alternative to enumerating the documentation files in <filename>pkg-plist</filename>, a port can set the - variable <makevar>PORTDOCS</makevar> to a list of file names + variable <varname>PORTDOCS</varname> to a list of file names and shell glob patterns to add to the final packing list. - The names will be relative to <makevar>DOCSDIR</makevar>. - Therefore, a port that utilizes <makevar>PORTDOCS</makevar> + The names will be relative to <varname>DOCSDIR</varname>. + Therefore, a port that utilizes <varname>PORTDOCS</varname> and uses a non-default location for its documentation should - set <makevar>DOCSDIR</makevar> accordingly. If a directory - is listed in <makevar>PORTDOCS</makevar> or matched by a + set <varname>DOCSDIR</varname> accordingly. If a directory + is listed in <varname>PORTDOCS</varname> or matched by a glob pattern from this variable, the entire subtree of contained files and directories will be registered in the final packing list. If the <literal>DOCS</literal> option has been unset then files and directories listed in - <makevar>PORTDOCS</makevar> would not be installed or added + <varname>PORTDOCS</varname> would not be installed or added to port packing list. Installing the documentation at - <makevar>PORTDOCS</makevar> as shown above remains up to the + <varname>PORTDOCS</varname> as shown above remains up to the port itself. A typical example of utilizing - <makevar>PORTDOCS</makevar> looks as follows:</para> + <varname>PORTDOCS</varname> looks as follows:</para> <programlisting>PORTDOCS= README.* ChangeLog docs/*</programlisting> <note> - <para>The equivalents of <makevar>PORTDOCS</makevar> for - files installed under <makevar>DATADIR</makevar> and - <makevar>EXAMPLESDIR</makevar> are - <makevar>PORTDATA</makevar> and - <makevar>PORTEXAMPLES</makevar>, respectively.</para> + <para>The equivalents of <varname>PORTDOCS</varname> for + files installed under <varname>DATADIR</varname> and + <varname>EXAMPLESDIR</varname> are + <varname>PORTDATA</varname> and + <varname>PORTEXAMPLES</varname>, respectively.</para> <para>You can also use the <filename>pkg-message</filename> file to display messages upon installation. See @@ -5273,11 +5229,11 @@ PORTVERSION= 1.0</programlisting> </note> </sect2> - <sect2 id="install-subdirs"> - <title>Subdirectories Under <makevar>PREFIX</makevar></title> + <sect2 xml:id="install-subdirs"> + <title>Subdirectories Under <varname>PREFIX</varname></title> <para>Try to let the port put things in the right - subdirectories of <makevar>PREFIX</makevar>. Some ports + subdirectories of <varname>PREFIX</varname>. Some ports lump everything and put it in the subdirectory with the port's name, which is incorrect. Also, many ports put everything except binaries, header files and manual pages in @@ -5293,39 +5249,38 @@ PORTVERSION= 1.0</programlisting> <filename>/usr</filename> pretty much apply to <filename>/usr/local</filename> too. The exception are ports dealing with USENET <quote>news</quote>. They may use - <filename><makevar>PREFIX</makevar>/news</filename> as a + <filename>PREFIX/news</filename> as a destination for their files.</para> </sect2> </sect1> </chapter> - <chapter id="special"> + <chapter xml:id="special"> <title>Special Considerations</title> <para>There are some more things you have to take into account when you create a port. This section explains the most common of those.</para> - <sect1 id="staging"> + <sect1 xml:id="staging"> <title>Staging</title> <para><filename>bsd.port.mk</filename> expects ports to work with a <quote>stage directory</quote>. This means that a port should not install files directly to the regular destination directories (that is, under - <makevar>PREFIX</makevar>, for example) but instead into a + <varname>PREFIX</varname>, for example) but instead into a separate directory from which the package is then built. In many cases, this does not require root privileges, making it possible to build packages as an unprivileged user. With staging, the port is built and installed into the stage - directory, <makevar>STAGEDIR</makevar>. A package is created + directory, <varname>STAGEDIR</varname>. A package is created from the stage directory and then installed on the system. Automake tools refer to - this concept as <makevar>DESTDIR</makevar>, but in &os;, - <makevar>DESTDIR</makevar> has a different meaning (see <xref - linkend="porting-prefix"/>).</para> + this concept as <varname>DESTDIR</varname>, but in &os;, + <varname>DESTDIR</varname> has a different meaning (see <xref linkend="porting-prefix"/>).</para> <para>When a port still requires system-wide privileges in order - to run the <maketarget>package</maketarget> target, this + to run the <buildtarget>package</buildtarget> target, this line must be added to the <filename>Makefile</filename>:</para> @@ -5341,19 +5296,19 @@ PORTVERSION= 1.0</programlisting> <programlisting>NO_MTREE= yes</programlisting> <para>Staging is enabled by prepending the - <makevar>STAGEDIR</makevar> variable to paths used in - the <maketarget>pre-install</maketarget>, - <maketarget>do-install</maketarget>, and - <maketarget>post-install</maketarget> targets (see the examples + <varname>STAGEDIR</varname> variable to paths used in + the <buildtarget>pre-install</buildtarget>, + <buildtarget>do-install</buildtarget>, and + <buildtarget>post-install</buildtarget> targets (see the examples through the book). Typically, this includes - <makevar>PREFIX</makevar>, <makevar>ETCDIR</makevar>, - <makevar>DATADIR</makevar>, <makevar>EXAMPLESDIR</makevar>, - <makevar>MANPREFIX</makevar>, <makevar>DOCSDIR</makevar>, and so on. + <varname>PREFIX</varname>, <varname>ETCDIR</varname>, + <varname>DATADIR</varname>, <varname>EXAMPLESDIR</varname>, + <varname>MANPREFIX</varname>, <varname>DOCSDIR</varname>, and so on. Directories should be created as part of the - <maketarget>post-install</maketarget> target. Avoid using + <buildtarget>post-install</buildtarget> target. Avoid using absolute paths whenever possible.</para> - <para>When creating a symlink, <makevar>STAGEDIR</makevar> should + <para>When creating a symlink, <varname>STAGEDIR</varname> should be prepended to the target path only. For example:</para> <programlisting>${LN} -sf libfoo.so.42 ${STAGEDIR}${PREFIX}/lib/libfoo.so</programlisting> @@ -5366,10 +5321,9 @@ PORTVERSION= 1.0</programlisting> Relative paths are less fragile, and often much shorter.</para> <para>Ports that install kernel modules must prepend the - <makevar>STAGEDIR</makevar> variable to - their default destination, <filename - class="directory">/boot/modules</filename>. Then the - <maketarget>pre-install</maketarget> target can be used to handle + <varname>STAGEDIR</varname> variable to + their default destination, <filename>/boot/modules</filename>. Then the + <buildtarget>pre-install</buildtarget> target can be used to handle the creation of this directory:</para> <programlisting>pre-install: @@ -5377,8 +5331,8 @@ PORTVERSION= 1.0</programlisting> <para>&man.kldxref.8; should not be run when installing to the temporary staging directory. To prevent this, define - the<makevar>NO_XREF</makevar> variable and add it - to <makevar>MAKE_ENV</makevar> in the port's + the<varname>NO_XREF</varname> variable and add it + to <varname>MAKE_ENV</varname> in the port's <filename>Makefile</filename>:</para> <programlisting>MAKE_ENV+= KMODDIR=/boot/modules NO_XREF=yes</programlisting> @@ -5391,16 +5345,16 @@ PORTVERSION= 1.0</programlisting> @exec kldxref /boot/modules</programlisting> </sect1> - <sect1 id="porting-shlibs"> + <sect1 xml:id="porting-shlibs"> <title>Shared Libraries</title> <para>If your port installs one or more shared libraries, define - a <makevar>USE_LDCONFIG</makevar> make variable, which will + a <varname>USE_LDCONFIG</varname> make variable, which will instruct a <filename>bsd.port.mk</filename> to run <literal>${LDCONFIG} -m</literal> on the directory where the new library is installed (usually - <filename><makevar>PREFIX</makevar>/lib</filename>) during - <maketarget>post-install</maketarget> target to register it + <filename>PREFIX/lib</filename>) during + <buildtarget>post-install</buildtarget> target to register it into the shared library cache. This variable, when defined, will also facilitate addition of an appropriate <literal>@exec /sbin/ldconfig -m</literal> and @@ -5413,11 +5367,11 @@ PORTVERSION= 1.0</programlisting> <programlisting>USE_LDCONFIG= yes</programlisting> <para>If you need, you can override the default directory by - setting the <makevar>USE_LDCONFIG</makevar> value to a list of + setting the <varname>USE_LDCONFIG</varname> value to a list of directories into which shared libraries are to be installed. For example if your port installs shared libraries into - <filename><makevar>PREFIX</makevar>/lib/foo</filename> and - <filename><makevar>PREFIX</makevar>/lib/bar</filename> + <filename>PREFIX/lib/foo</filename> and + <filename>PREFIX/lib/bar</filename> directories you could use the following in your <filename>Makefile</filename>:</para> @@ -5426,14 +5380,14 @@ PORTVERSION= 1.0</programlisting> <para>Please double-check, often this is not necessary at all or can be avoided through <literal>-rpath</literal> or setting <envar>LD_RUN_PATH</envar> during linking (see - <filename role="package">lang/moscow_ml</filename> for an + <package>lang/moscow_ml</package> for an example), or through a shell-wrapper which sets - <makevar>LD_LIBRARY_PATH</makevar> before invoking the binary, - like <filename role="package">www/seamonkey</filename> + <varname>LD_LIBRARY_PATH</varname> before invoking the binary, + like <package>www/seamonkey</package> does.</para> <para>When installing 32-bit libraries on 64-bit system, use - <makevar>USE_LDCONFIG32</makevar> instead.</para> + <varname>USE_LDCONFIG32</varname> instead.</para> <para>Try to keep shared library version numbers in the <filename>libfoo.so.0</filename> format. Our runtime linker @@ -5442,11 +5396,11 @@ PORTVERSION= 1.0</programlisting> <para>When the major library version number increments in the update to the new port version, all other ports that link to the affected library should have their - <makevar>PORTREVISION</makevar> incremented, to force + <varname>PORTREVISION</varname> incremented, to force recompilation with the new library version.</para> </sect1> - <sect1 id="porting-restrictions"> + <sect1 xml:id="porting-restrictions"> <title>Ports with Distribution Restrictions</title> <para>Licenses vary, and some of them place restrictions on how @@ -5466,7 +5420,7 @@ PORTVERSION= 1.0</programlisting> following sections can be set.</para> <sect2> - <title><makevar>NO_PACKAGE</makevar></title> + <title><varname>NO_PACKAGE</varname></title> <para>This variable indicates that we may not generate a binary package of the application. For instance, the @@ -5474,39 +5428,39 @@ PORTVERSION= 1.0</programlisting> prohibit distribution of packages created from patched sources.</para> - <para>However, the port's <makevar>DISTFILES</makevar> may be + <para>However, the port's <varname>DISTFILES</varname> may be freely mirrored on FTP/HTTP. They may also be distributed on a CD-ROM (or similar media) unless - <makevar>NO_CDROM</makevar> is set as well.</para> + <varname>NO_CDROM</varname> is set as well.</para> - <para><makevar>NO_PACKAGE</makevar> should also be used if the + <para><varname>NO_PACKAGE</varname> should also be used if the binary package is not generally useful, and the application should always be compiled from the source code. For example, if the application has configuration information that is site specific hard coded in to it at compile time, - set <makevar>NO_PACKAGE</makevar>.</para> + set <varname>NO_PACKAGE</varname>.</para> - <para><makevar>NO_PACKAGE</makevar> should be set to a string + <para><varname>NO_PACKAGE</varname> should be set to a string describing the reason why the package should not be generated.</para> </sect2> <sect2> - <title><makevar>NO_CDROM</makevar></title> + <title><varname>NO_CDROM</varname></title> <para>This variable alone indicates that, although we are allowed to generate binary packages, we may put neither - those packages nor the port's <makevar>DISTFILES</makevar> + those packages nor the port's <varname>DISTFILES</varname> onto a CD-ROM (or similar media) for resale. However, the - binary packages and the port's <makevar>DISTFILES</makevar> + binary packages and the port's <varname>DISTFILES</varname> will still be available via FTP/HTTP.</para> <para> If this variable is set along with - <makevar>NO_PACKAGE</makevar>, then only the port's - <makevar>DISTFILES</makevar> will be available, and only via + <varname>NO_PACKAGE</varname>, then only the port's + <varname>DISTFILES</varname> will be available, and only via FTP/HTTP.</para> - <para><makevar>NO_CDROM</makevar> should be set to a string + <para><varname>NO_CDROM</varname> should be set to a string describing the reason why the port cannot be redistributed on CD-ROM. For instance, this should be used if the port's license is for <quote>non-commercial</quote> use @@ -5514,45 +5468,45 @@ PORTVERSION= 1.0</programlisting> </sect2> <sect2> - <title><makevar>NOFETCHFILES</makevar></title> + <title><varname>NOFETCHFILES</varname></title> - <para>Files defined in the <makevar>NOFETCHFILES</makevar> + <para>Files defined in the <varname>NOFETCHFILES</varname> variable are not fetchable from any of the - <makevar>MASTER_SITES</makevar>. An example of such a file + <varname>MASTER_SITES</varname>. An example of such a file is when the file is supplied on CD-ROM by the vendor.</para> <para>Tools which check for the availability of these files - on the <makevar>MASTER_SITES</makevar> should ignore these + on the <varname>MASTER_SITES</varname> should ignore these files and not report about them.</para> </sect2> <sect2> - <title><makevar>RESTRICTED</makevar></title> + <title><varname>RESTRICTED</varname></title> <para>Set this variable alone if the application's license permits neither mirroring the application's - <makevar>DISTFILES</makevar> nor distributing the binary + <varname>DISTFILES</varname> nor distributing the binary package in any way.</para> - <para><makevar>NO_CDROM</makevar> or - <makevar>NO_PACKAGE</makevar> should not be set along with - <makevar>RESTRICTED</makevar> since the latter variable + <para><varname>NO_CDROM</varname> or + <varname>NO_PACKAGE</varname> should not be set along with + <varname>RESTRICTED</varname> since the latter variable implies the former ones.</para> - <para><makevar>RESTRICTED</makevar> should be set to a string + <para><varname>RESTRICTED</varname> should be set to a string describing the reason why the port cannot be redistributed. Typically, this indicates that the port contains proprietary software and that the user will need to manually download - the <makevar>DISTFILES</makevar>, possibly after registering + the <varname>DISTFILES</varname>, possibly after registering for the software or agreeing to accept the terms of an <acronym>EULA</acronym>.</para> </sect2> <sect2> - <title><makevar>RESTRICTED_FILES</makevar></title> + <title><varname>RESTRICTED_FILES</varname></title> - <para>When <makevar>RESTRICTED</makevar> or - <makevar>NO_CDROM</makevar> is set, this variable defaults + <para>When <varname>RESTRICTED</varname> or + <varname>NO_CDROM</varname> is set, this variable defaults to <literal>${DISTFILES} ${PATCHFILES}</literal>, otherwise it is empty. If only some of the distribution files are restricted, then set this variable to list them.</para> @@ -5581,10 +5535,10 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep </sect2> </sect1> - <sect1 id="building"> + <sect1 xml:id="building"> <title>Building Mechanisms</title> - <sect2 id="parallel-builds"> + <sect2 xml:id="parallel-builds"> <title>Building Ports in Parallel</title> <para>The &os; ports framework supports parallel building @@ -5593,7 +5547,7 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep their available <acronym>CPU</acronym> power, allowing port builds to be faster and more effective.</para> - <para>This is achieved by passing <makevar>-jX</makevar> flag + <para>This is achieved by passing <varname>-jX</varname> flag to &man.make.1; running on vendor code. Unfortunately, not all ports handle parallel building well. Therefore it is required to explicitly enable this feature by adding @@ -5603,15 +5557,15 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <para>Another option for controlling this feature from the maintainer's point of view is the - <makevar>MAKE_JOBS_UNSAFE=yes</makevar> variable. It is + <varname>MAKE_JOBS_UNSAFE=yes</varname> variable. It is used when a port is known to be broken with - <makevar>-jX</makevar> and a user forces the use of multi + <varname>-jX</varname> and a user forces the use of multi processor compilations for all ports in <filename>/etc/make.conf</filename> with the <literal>FORCE_MAKE_JOBS=yes</literal> variable.</para> </sect2> - <sect2 id="using-make"> + <sect2 xml:id="using-make"> <title><command>make</command>, <command>gmake</command>, and <command>imake</command></title> @@ -5632,13 +5586,13 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <tbody> <row> - <entry><makevar>USES= gmake</makevar></entry> + <entry><varname>USES= gmake</varname></entry> <entry>The port requires <command>gmake</command> to build.</entry> </row> <row> - <entry><makevar>GMAKE</makevar></entry> + <entry><varname>GMAKE</varname></entry> <entry>The full path for <command>gmake</command> if it is not in the <envar>PATH</envar>.</entry> </row> @@ -5656,18 +5610,18 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep flag is a problem for your port, set <literal>XMKMF=xmkmf</literal>. If the port uses <application>imake</application> but does not understand the - <maketarget>install.man</maketarget> target, + <buildtarget>install.man</buildtarget> target, <literal>NO_INSTALL_MANPAGES=yes</literal> should be set.</para> <para>If your port's source <filename>Makefile</filename> has - something else than <maketarget>all</maketarget> as the main - build target, set <makevar>ALL_TARGET</makevar> accordingly. - Same goes for <maketarget>install</maketarget> and - <makevar>INSTALL_TARGET</makevar>.</para> + something else than <buildtarget>all</buildtarget> as the main + build target, set <varname>ALL_TARGET</varname> accordingly. + Same goes for <buildtarget>install</buildtarget> and + <varname>INSTALL_TARGET</varname>.</para> </sect2> - <sect2 id="using-configure"> + <sect2 xml:id="using-configure"> <title><command>configure</command> Script</title> <para>If your port uses the <command>configure</command> @@ -5679,9 +5633,9 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep --infodir=${PREFIX}/${INFO_PATH} --mandir=${MANPREFIX}/man --build=${CONFIGURE_TARGET}</literal>), set those - extra arguments in <makevar>CONFIGURE_ARGS</makevar>. Extra + extra arguments in <varname>CONFIGURE_ARGS</varname>. Extra environment variables can be passed using - <makevar>CONFIGURE_ENV</makevar> variable.</para> + <varname>CONFIGURE_ENV</varname> variable.</para> <table frame="none"> <title>Variables for Ports That Use @@ -5697,32 +5651,32 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <tbody> <row> - <entry><makevar>GNU_CONFIGURE</makevar></entry> + <entry><varname>GNU_CONFIGURE</varname></entry> <entry>The port uses <command>configure</command> script to prepare build.</entry> </row> <row> - <entry><makevar>HAS_CONFIGURE</makevar></entry> - <entry>Same as <makevar>GNU_CONFIGURE</makevar>, + <entry><varname>HAS_CONFIGURE</varname></entry> + <entry>Same as <varname>GNU_CONFIGURE</varname>, except default configure target is not added to - <makevar>CONFIGURE_ARGS</makevar>.</entry> + <varname>CONFIGURE_ARGS</varname>.</entry> </row> <row> - <entry><makevar>CONFIGURE_ARGS</makevar></entry> + <entry><varname>CONFIGURE_ARGS</varname></entry> <entry>Additional arguments passed to <command>configure</command> script.</entry> </row> <row> - <entry><makevar>CONFIGURE_ENV</makevar></entry> + <entry><varname>CONFIGURE_ENV</varname></entry> <entry>Additional environment variables to be set for <command>configure</command> script run.</entry> </row> <row> - <entry><makevar>CONFIGURE_TARGET</makevar></entry> + <entry><varname>CONFIGURE_TARGET</varname></entry> <entry>Override default configure target. Default value is <literal>${MACHINE_ARCH}-portbld-freebsd${OSREL}</literal>.</entry> @@ -5732,7 +5686,7 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep </table> </sect2> - <sect2 id="using-cmake"> + <sect2 xml:id="using-cmake"> <title>Using <command>cmake</command></title> <para>For ports that use <application>CMake</application>, @@ -5754,30 +5708,30 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <tbody> <row> - <entry><makevar>CMAKE_ARGS</makevar></entry> + <entry><varname>CMAKE_ARGS</varname></entry> <entry>Port specific <application>CMake</application> flags to be passed to the <command>cmake</command> binary.</entry> </row> <row> - <entry><makevar>CMAKE_BUILD_TYPE</makevar></entry> + <entry><varname>CMAKE_BUILD_TYPE</varname></entry> <entry>Type of build (<application>CMake</application> predefined build profiles). Default is <literal>Release</literal>, or <literal>Debug</literal> if - <makevar>WITH_DEBUG</makevar> is set.</entry> + <varname>WITH_DEBUG</varname> is set.</entry> </row> <row> - <entry><makevar>CMAKE_ENV</makevar></entry> + <entry><varname>CMAKE_ENV</varname></entry> <entry>Environment variables to be set for <command>cmake</command> binary. Default is <literal>${CONFIGURE_ENV}</literal>.</entry> </row> <row> - <entry><makevar>CMAKE_SOURCE_PATH</makevar></entry> + <entry><varname>CMAKE_SOURCE_PATH</varname></entry> <entry>Path to the source directory. Default is <literal>${WRKSRC}</literal>.</entry> </row> @@ -5793,19 +5747,19 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep <literal>Release</literal> profiles respect system <literal>*FLAGS</literal>, <literal>RelWithDebInfo</literal> and <literal>MinSizeRel</literal> will set - <makevar>CFLAGS</makevar> to <literal>-O2 -g</literal> and + <varname>CFLAGS</varname> to <literal>-O2 -g</literal> and <literal>-Os -DNDEBUG</literal> correspondingly. The - lower-cased value of <makevar>CMAKE_BUILD_TYPE</makevar> is - exported to the <makevar>PLIST_SUB</makevar> and should be + lower-cased value of <varname>CMAKE_BUILD_TYPE</varname> is + exported to the <varname>PLIST_SUB</varname> and should be used if port installs <literal>*.cmake</literal> files depending on the build type (see - <filename role="package">deskutils/strigi</filename> for an + <package>deskutils/strigi</package> for an example). Please note that some projects may define their own build profiles and/or force particular build type by setting <literal>CMAKE_BUILD_TYPE</literal> in <filename>CMakeLists.txt </filename> files. In order to make a port for such a project respect - <makevar>CFLAGS</makevar> and <makevar>WITH_DEBUG</makevar>, + <varname>CFLAGS</varname> and <varname>WITH_DEBUG</varname>, the <literal>CMAKE_BUILD_TYPE</literal> definitions must be removed from those files.</para> @@ -5813,20 +5767,20 @@ IGNORE= may not be redistributed because of licensing reasons. Please visit <rep support an out-of-source method of building. The out-of-source build for a port can be requested by using the <literal>:outsource</literal> suffix. When enabled, - <makevar>CONFIGURE_WRKSRC</makevar>, - <makevar>BUILD_WRKSRC</makevar> and - <makevar>INSTALL_WRKSRC</makevar> will be set to + <varname>CONFIGURE_WRKSRC</varname>, + <varname>BUILD_WRKSRC</varname> and + <varname>INSTALL_WRKSRC</varname> will be set to <literal>${WRKDIR}/.build</literal> and this directory will be used to keep all files generated during configuration and build stages, leaving the source directory intact.</para> - <example id="using-cmake-example"> + <example xml:id="using-cmake-example"> <title><literal>USES= cmake</literal> Example</title> <para>The following snippet demonstrates the use of <application>CMake</application> for a port. - <makevar>CMAKE_SOURCE_PATH</makevar> is not usually + <varname>CMAKE_SOURCE_PATH</varname> is not usually required, but can be set when the sources are not located in the top directory, or if only a subset of the project is intended to be built by the port.</para> @@ -5836,7 +5790,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> </example> </sect2> - <sect2 id="using-scons"> + <sect2 xml:id="using-scons"> <title>Using <command>scons</command></title> <para>If your port uses <application>SCons</application>, @@ -5856,27 +5810,27 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <tbody> <row> - <entry><makevar>SCONS_ARGS</makevar></entry> + <entry><varname>SCONS_ARGS</varname></entry> <entry>Port specific SCons flags passed to the SCons environment.</entry> </row> <row> - <entry><makevar>SCONS_BUILDENV</makevar></entry> + <entry><varname>SCONS_BUILDENV</varname></entry> <entry>Variables to be set in system environment.</entry> </row> <row> - <entry><makevar>SCONS_ENV</makevar></entry> + <entry><varname>SCONS_ENV</varname></entry> <entry>Variables to be set in SCons environment.</entry> </row> <row> - <entry><makevar>SCONS_TARGET</makevar></entry> + <entry><varname>SCONS_TARGET</varname></entry> <entry>Last argument passed to SCons, similar to - <makevar>MAKE_TARGET</makevar>.</entry> + <varname>MAKE_TARGET</varname>.</entry> </row> </tbody> </tgroup> @@ -5884,8 +5838,8 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <para>To make third party <filename>SConstruct</filename> respect everything that is passed to SCons in - <makevar>SCONS_ENV</makevar> (that is, most importantly, - <makevar>CC/CXX/CFLAGS/CXXFLAGS</makevar>), patch the + <varname>SCONS_ENV</varname> (that is, most importantly, + <varname>CC/CXX/CFLAGS/CXXFLAGS</varname>), patch the <filename>SConstruct</filename> so build <literal>Environment</literal> is constructed like this:</para> @@ -5898,10 +5852,10 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> </sect2> </sect1> - <sect1 id="using-autotools"> + <sect1 xml:id="using-autotools"> <title>Using GNU Autotools</title> - <sect2 id="using-autotools-introduction"> + <sect2 xml:id="using-autotools-introduction"> <title>Introduction</title> <para>The various GNU autotools provide an abstraction @@ -5938,7 +5892,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <literal>devel/autotools</literal> port.</para> </sect2> - <sect2 id="using-libtool"> + <sect2 xml:id="using-libtool"> <title><command>libtool</command></title> <para>Shared libraries using the GNU building framework @@ -5953,11 +5907,11 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= libtool:<replaceable>version</replaceable>[:env]</programlisting> <para>With no additional operations, - <literal>libtool:<replaceable>version</replaceable></literal> + <literal>libtool:version</literal> tells the building framework to patch the configure script with the system-installed copy of <command>libtool</command>. The - <makevar>GNU_CONFIGURE</makevar> is implied. Further, a + <varname>GNU_CONFIGURE</varname> is implied. Further, a number of make and shell variables will be assigned for onward use by the port. See <filename>bsd.autotools.mk</filename> for details.</para> @@ -5965,15 +5919,15 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <para>With the <literal>:env</literal> operation, only the environment will be set up.</para> - <para>Finally, <makevar>LIBTOOLFLAGS</makevar> and - <makevar>LIBTOOLFILES</makevar> can be optionally set to + <para>Finally, <varname>LIBTOOLFLAGS</varname> and + <varname>LIBTOOLFILES</varname> can be optionally set to override the most likely arguments to, and files patched by, <command>libtool</command>. Most ports are unlikely to need this. See <filename>bsd.autotools.mk</filename> for further details.</para> </sect2> - <sect2 id="using-libltdl"> + <sect2 xml:id="using-libltdl"> <title><command>libltdl</command></title> <para>Some ports make use of the <command>libltdl</command> @@ -5986,15 +5940,15 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= libltdl:<replaceable>version</replaceable></programlisting> <para>Currently, all this does is to bring in a - <makevar>LIB_DEPENDS</makevar> on the appropriate + <varname>LIB_DEPENDS</varname> on the appropriate <command>libltdl</command> port, and is provided as a convenience function to help eliminate any dependencies on the autotools ports outside of the - <makevar>USE_AUTOTOOLS</makevar> framework. There are no + <varname>USE_AUTOTOOLS</varname> framework. There are no optional operations for this tool.</para> </sect2> - <sect2 id="using-autoconf"> + <sect2 xml:id="using-autoconf"> <title><command>autoconf</command> and <command>autoheader</command></title> @@ -6013,7 +5967,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= autoheader:<replaceable>version</replaceable></programlisting> <para>which also implies the use of - <literal>autoconf:<replaceable>version</replaceable></literal>.</para> + <literal>autoconf:version</literal>.</para> <para>Similarly to <command>libtool</command>, the inclusion of the optional <literal>:env</literal> operation simply @@ -6022,14 +5976,14 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> out.</para> <para>The additional optional variables - <makevar>AUTOCONF_ARGS</makevar> and - <makevar>AUTOHEADER_ARGS</makevar> can be overridden by the + <varname>AUTOCONF_ARGS</varname> and + <varname>AUTOHEADER_ARGS</varname> can be overridden by the port <filename>Makefile</filename> if specifically requested. As with the <command>libtool</command> equivalents, most ports are unlikely to need this.</para> </sect2> - <sect2 id="using-automake"> + <sect2 xml:id="using-automake"> <title><command>automake</command> and <command>aclocal</command></title> @@ -6060,7 +6014,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <programlisting>USE_AUTOTOOLS= aclocal:<replaceable>version</replaceable></programlisting> <para>which also implies the use of - <literal>automake:<replaceable>version</replaceable></literal>.</para> + <literal>automake:version</literal>.</para> <para>Similarly to <command>libtool</command> and <command>autoconf</command>, the inclusion of the optional @@ -6072,14 +6026,14 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <command>autoheader</command>, both <command>automake</command> and <command>aclocal</command> have optional argument variables, - <makevar>AUTOMAKE_ARGS</makevar> and - <makevar>ACLOCAL_ARGS</makevar> respectively, which may be + <varname>AUTOMAKE_ARGS</varname> and + <varname>ACLOCAL_ARGS</varname> respectively, which may be overridden by the port <filename>Makefile</filename> if required.</para> </sect2> </sect1> - <sect1 id="using-gettext"> + <sect1 xml:id="using-gettext"> <title>Using GNU <literal>gettext</literal></title> <sect2> @@ -6088,7 +6042,7 @@ CMAKE_SOURCE_PATH= ${WRKSRC}/subproject</programlisting> <para>If your port requires <literal>gettext</literal>, set <literal>USES= gettext</literal>, and your port will inherit a dependency on - <filename role="package">devel/gettext</filename>. Other + <package>devel/gettext</package>. Other values for <literal>gettext</literal> usage are listed in <xref linkend="uses-values"/>.</para> @@ -6121,7 +6075,7 @@ GNU_CONFIGURE= yes</programlisting> through passing <option>--disable-nls</option> to <command>configure</command>. In that case, your port should use <literal>gettext</literal> conditionally, - depending on the status of the <makevar>NLS</makevar> + depending on the status of the <varname>NLS</varname> option. For ports of low to medium complexity, you can rely on the following idiom:</para> @@ -6172,37 +6126,36 @@ PLIST_SUB+= NLS="@comment " <para>There is a point to note about installing message catalog files. The target directories for them, which reside under - <filename><makevar>LOCALBASE</makevar>/share/locale</filename>, + <filename>LOCALBASE/share/locale</filename>, should rarely be created and removed by a port. The most popular languages have their respective directories listed in - <filename><makevar>PORTSDIR</makevar>/Templates/BSD.local.dist</filename>. + <filename>PORTSDIR/Templates/BSD.local.dist</filename>. The directories for many other languages are governed by the - <filename role="package">devel/gettext</filename> port. + <package>devel/gettext</package> port. Consult its <filename>pkg-plist</filename> and see whether the port is going to install a message catalog file for a unique language.</para> </sect2> </sect1> - <sect1 id="using-perl"> + <sect1 xml:id="using-perl"> <title>Using <application>Perl</application></title> - <para>If <makevar>MASTER_SITES</makevar> is set to - <makevar>MASTER_SITE_PERL_CPAN</makevar>, then the preferred - value of <makevar>MASTER_SITE_SUBDIR</makevar> is the + <para>If <varname>MASTER_SITES</varname> is set to + <varname>MASTER_SITE_PERL_CPAN</varname>, then the preferred + value of <varname>MASTER_SITE_SUBDIR</varname> is the top-level hierarchy name. For example, the recommended value for <literal>p5-Module-Name</literal> is <literal>Module</literal>. The top-level hierarchy can be - examined at <ulink - url="http://cpan.org/modules/by-module/">cpan.org</ulink>. + examined at <link xlink:href="http://cpan.org/modules/by-module/">cpan.org</link>. This keeps the port working when the author of the module changes.</para> <para>The exception to this rule is when the relevant directory does not exist or the distfile does not exist in that directory. In such case, using author's id as - <makevar>MASTER_SITE_SUBDIR</makevar> is allowed.</para> + <varname>MASTER_SITE_SUBDIR</varname> is allowed.</para> <para>All of the tunable knobs below accept either <literal>YES</literal> or a version string like @@ -6230,25 +6183,25 @@ PLIST_SUB+= NLS="@comment " <tbody> <row> - <entry><makevar>USE_PERL5</makevar></entry> + <entry><varname>USE_PERL5</varname></entry> <entry>The port uses Perl 5 to build and run.</entry> </row> <row> - <entry><makevar>USE_PERL5_BUILD</makevar></entry> + <entry><varname>USE_PERL5_BUILD</varname></entry> <entry>The port uses Perl 5 to build.</entry> </row> <row> - <entry><makevar>USE_PERL5_RUN</makevar></entry> + <entry><varname>USE_PERL5_RUN</varname></entry> <entry>The port uses Perl 5 to run.</entry> </row> <row> - <entry><makevar>PERL</makevar></entry> + <entry><varname>PERL</varname></entry> <entry>The full path of the Perl 5 interpreter, either in the system or installed from a port, but without the version number. Use this if you need to @@ -6257,15 +6210,15 @@ PLIST_SUB+= NLS="@comment " </row> <row> - <entry><makevar>PERL_CONFIGURE</makevar></entry> + <entry><varname>PERL_CONFIGURE</varname></entry> <entry>Configure using Perl's MakeMaker. It implies - <makevar>USE_PERL5</makevar>.</entry> + <varname>USE_PERL5</varname>.</entry> </row> <row> - <entry><makevar>PERL_MODBUILD</makevar></entry> + <entry><varname>PERL_MODBUILD</varname></entry> <entry>Configure, build and install using Module::Build. - It implies <makevar>PERL_CONFIGURE</makevar>.</entry> + It implies <varname>PERL_CONFIGURE</varname>.</entry> </row> </tbody> </tgroup> @@ -6280,36 +6233,36 @@ PLIST_SUB+= NLS="@comment " <tbody> <row> - <entry><makevar>PERL_VERSION</makevar></entry> + <entry><varname>PERL_VERSION</varname></entry> <entry>The full version of Perl installed (e.g., <literal>5.8.9</literal>).</entry> </row> <row> - <entry><makevar>PERL_LEVEL</makevar></entry> + <entry><varname>PERL_LEVEL</varname></entry> <entry>The installed Perl version as an integer of the form <literal>MNNNPP</literal> (e.g., <literal>500809</literal>).</entry> </row> <row> - <entry><makevar>PERL_ARCH</makevar></entry> + <entry><varname>PERL_ARCH</varname></entry> <entry>Where Perl stores architecture dependent libraries. Defaults to <literal>${ARCH}-freebsd</literal>.</entry> </row> <row> - <entry><makevar>PERL_PORT</makevar></entry> + <entry><varname>PERL_PORT</varname></entry> <entry>Name of the Perl port that is installed (e.g., <literal>perl5</literal>).</entry> </row> <row> - <entry><makevar>SITE_PERL</makevar></entry> + <entry><varname>SITE_PERL</varname></entry> <entry>Directory name where site specific Perl packages go. This value is - added to <makevar>PLIST_SUB</makevar>.</entry> + added to <varname>PLIST_SUB</varname>.</entry> </row> </tbody> </tgroup> @@ -6317,7 +6270,7 @@ PLIST_SUB+= NLS="@comment " <note> <para>Ports of Perl modules which do not have an official - website should link to <hostid>cpan.org</hostid> in the WWW + website should link to <systemitem>cpan.org</systemitem> in the WWW line of <filename>pkg-descr</filename>. The preferred URL form is <literal>http://search.cpan.org/dist/Module-Name/</literal> @@ -6334,14 +6287,14 @@ PLIST_SUB+= NLS="@comment " is shown in the example below.</para> </note> - <example id="use-perl-dependency-example"> + <example xml:id="use-perl-dependency-example"> <title>Perl Dependency Example</title> <programlisting>p5-IO-Tee>=0.64:${PORTSDIR}/devel/p5-IO-Tee</programlisting> </example> <para>For Perl ports that install manual pages, the macro - <makevar>PERL5_MAN<replaceable>x</replaceable></makevar> (where + <varname>PERL5_MAN<replaceable>x</replaceable></varname> (where <replaceable>x</replaceable> ranges from <literal>1</literal> to <literal>9</literal>) can be used inside <filename>pkg-plist</filename>. For example,</para> @@ -6353,15 +6306,15 @@ PLIST_SUB+= NLS="@comment " <programlisting>%%PERL5_MAN3%%/AnyEvent::I3.3.gz</programlisting> </sect1> - <sect1 id="using-x11"> + <sect1 xml:id="using-x11"> <title>Using X11</title> - <sect2 id="x11-variables"> + <sect2 xml:id="x11-variables"> <title>X.Org Components</title> <para>The X11 implementation available in The Ports Collection is X.Org. If your application depends on X components, set - <makevar>USE_XORG</makevar> to the list of required + <varname>USE_XORG</varname> to the list of required components. Available components, at the time of writing, are:</para> @@ -6385,14 +6338,14 @@ PLIST_SUB+= NLS="@comment " <para>The Mesa Project is an effort to provide free OpenGL implementation. You can specify a dependency on various - components of this project with <makevar>USE_GL</makevar> + components of this project with <varname>USE_GL</varname> variable. Valid options are: <literal>glut, glu, glw, glew, gl</literal> and <literal>linux</literal>. For backwards compatibility, the value of <literal>yes</literal> maps to <literal>glu</literal>.</para> - <example id="use-xorg-example"> + <example xml:id="use-xorg-example"> <title>USE_XORG Example</title> <programlisting>USE_XORG= xrender xft xkbfile xt xaw @@ -6405,12 +6358,12 @@ USE_GL= glu</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>USES= imake</makevar></entry> + <entry><varname>USES= imake</varname></entry> <entry>The port uses <command>imake</command>.</entry> </row> <row> - <entry><makevar>XMKMF</makevar></entry> + <entry><varname>XMKMF</varname></entry> <entry>Set to the path of <command>xmkmf</command> if not in the <envar>PATH</envar>. Defaults to <literal>xmkmf -a</literal>.</entry> @@ -6419,7 +6372,7 @@ USE_GL= glu</programlisting> </tgroup> </table> - <example id="using-x11-vars"> + <example xml:id="using-x11-vars"> <title>Using X11-Related Variables</title> <programlisting># Use some X11 libraries @@ -6427,20 +6380,20 @@ USE_XORG= x11 xpm</programlisting> </example> </sect2> - <sect2 id="x11-motif"> + <sect2 xml:id="x11-motif"> <title>Ports That Require Motif</title> <para>If your port requires a Motif library, define - <makevar>USES= motif</makevar> in the + <varname>USES= motif</varname> in the <filename>Makefile</filename>. Default Motif implementation is - <filename role="package">x11-toolkits/open-motif</filename>. + <package>x11-toolkits/open-motif</package>. Users can choose - <filename role="package">x11-toolkits/lesstif</filename> - instead by setting <makevar>WANT_LESSTIF</makevar> + <package>x11-toolkits/lesstif</package> + instead by setting <varname>WANT_LESSTIF</varname> variable.</para> - <para>The <makevar>MOTIFLIB</makevar> variable will be set by + <para>The <varname>MOTIFLIB</varname> variable will be set by <filename>bsd.port.mk</filename> to reference the appropriate Motif library. Please patch the source of your port to use <literal>${MOTIFLIB}</literal> wherever @@ -6467,7 +6420,7 @@ USE_XORG= x11 xpm</programlisting> </listitem> </itemizedlist> - <para>Note that <makevar>MOTIFLIB</makevar> (usually) expands + <para>Note that <varname>MOTIFLIB</varname> (usually) expands to <literal>-L/usr/local/lib -lXm</literal> or <literal>/usr/local/lib/libXm.a</literal>, so there is no need to add <literal>-L</literal> or <literal>-l</literal> @@ -6479,7 +6432,7 @@ USE_XORG= x11 xpm</programlisting> <para>If your port installs fonts for the X Window System, put them in - <filename><makevar>LOCALBASE</makevar>/lib/X11/fonts/local</filename>.</para> + <filename>LOCALBASE/lib/X11/fonts/local</filename>.</para> </sect2> <sect2> @@ -6495,12 +6448,11 @@ USE_XORG= x11 xpm</programlisting> <programlisting>USES= display</programlisting> </sect2> - <sect2 id="desktop-entries"> + <sect2 xml:id="desktop-entries"> <title>Desktop Entries</title> - <para>Desktop entries (<ulink - url="http://standards.freedesktop.org/desktop-entry-spec/latest/">a - Freedesktop standard</ulink>) provide a way to + <para>Desktop entries (<link xlink:href="http://standards.freedesktop.org/desktop-entry-spec/latest/">a + Freedesktop standard</link>) provide a way to automatically adjust desktop features when a new program is installed, without requiring user intervention. For example, newly-installed programs automatically appear in @@ -6522,32 +6474,31 @@ USE_XORG= x11 xpm</programlisting> <filename>*.desktop</filename> files should include those files in <filename>pkg-plist</filename> and install them in the - <filename><makevar>$LOCALBASE</makevar>/share/applications</filename> - directory. The <link - linkend="install-macros"><makevar>INSTALL_DATA</makevar> + <filename>$LOCALBASE/share/applications</filename> + directory. The <link linkend="install-macros"><varname>INSTALL_DATA</varname> macro</link> is useful for installing these files.</para> </sect3> - <sect3 id="updating-desktop-database"> + <sect3 xml:id="updating-desktop-database"> <title>Updating Desktop Database</title> <para>If a port has a MimeType entry in its - <filename><replaceable>portname</replaceable>.desktop</filename>, + <filename>portname.desktop</filename>, the desktop database must be updated after install and - deinstall. To do this, define <makevar>USES</makevar>= + deinstall. To do this, define <varname>USES</varname>= desktop-file-utils.</para> </sect3> - <sect3 id="desktop-entries-macro"> + <sect3 xml:id="desktop-entries-macro"> <title>Creating Desktop Entries with the - <makevar>DESKTOP_ENTRIES</makevar> Macro</title> + <varname>DESKTOP_ENTRIES</varname> Macro</title> <para>Desktop entries can be easily created for applications - by using the <makevar>DESKTOP_ENTRIES</makevar> variable. + by using the <varname>DESKTOP_ENTRIES</varname> variable. A file named - <filename><replaceable>name</replaceable>.desktop</filename> + <filename>name.desktop</filename> will be created, installed, and added to the <filename>pkg-plist</filename> automatically. Syntax is:</para> @@ -6555,9 +6506,8 @@ USE_XORG= x11 xpm</programlisting> <programlisting>DESKTOP_ENTRIES= "NAME" "COMMENT" "ICON" "COMMAND" "CATEGORY" StartupNotify</programlisting> <para>The list of possible categories is available on the - <ulink - url="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop - website</ulink>. <makevar>StartupNotify</makevar> + <link xlink:href="http://standards.freedesktop.org/menu-spec/latest/apa.html">Freedesktop + website</link>. <varname>StartupNotify</varname> indicates whether the application is compatible with <emphasis>startup notifications</emphasis>. These are typically a graphic indicator like a clock that appear at @@ -6567,7 +6517,7 @@ USE_XORG= x11 xpm</programlisting> after it has started. Programs that are not compatible with startup notifications would never clear the indicator (potentially confusing and infuriating the user), and - should have <makevar>StartupNotify</makevar> set to + should have <varname>StartupNotify</varname> set to <literal>false</literal> so the indicator is not shown at all.</para> @@ -6582,21 +6532,20 @@ USE_XORG= x11 xpm</programlisting> </sect2> </sect1> - <sect1 id="using-gnome"> + <sect1 xml:id="using-gnome"> <title>Using GNOME</title> <para>The FreeBSD/GNOME project uses its own set of variables to define which GNOME components a particular port uses. A - <ulink - url="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive - list of these variables</ulink> exists within the + <link xlink:href="http://www.FreeBSD.org/gnome/docs/porting.html">comprehensive + list of these variables</link> exists within the FreeBSD/GNOME project's homepage.</para> </sect1> - <sect1 id="using-qt"> + <sect1 xml:id="using-qt"> <title>Using Qt</title> - <sect2 id="qt-common"> + <sect2 xml:id="qt-common"> <title>Ports That Require Qt</title> <table frame="none"> @@ -6605,7 +6554,7 @@ USE_XORG= x11 xpm</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_QT_VER</makevar></entry> + <entry><varname>USE_QT_VER</varname></entry> <entry>The port uses the Qt toolkit. The only possible value is <literal>3</literal>. Appropriate parameters are passed to @@ -6614,7 +6563,7 @@ USE_XORG= x11 xpm</programlisting> </row> <row> - <entry><makevar>USE_QT4</makevar></entry> + <entry><varname>USE_QT4</varname></entry> <entry>Specify tool and library dependencies for ports that use Qt 4. See <link linkend="qt4-components">Qt 4 component @@ -6622,41 +6571,41 @@ USE_XORG= x11 xpm</programlisting> </row> <row> - <entry><makevar>QT_PREFIX</makevar></entry> + <entry><varname>QT_PREFIX</varname></entry> <entry>Set to the path where Qt installed to (read-only variable).</entry> </row> <row> - <entry><makevar>MOC</makevar></entry> + <entry><varname>MOC</varname></entry> <entry>Set to the path of <command>moc</command> (read-only variable). Default set according to - <makevar>USE_QT_VER</makevar> value.</entry> + <varname>USE_QT_VER</varname> value.</entry> </row> <row> - <entry><makevar>QTCPPFLAGS</makevar></entry> + <entry><varname>QTCPPFLAGS</varname></entry> <entry>Additional compiler flags passed via - <makevar>CONFIGURE_ENV</makevar> for Qt toolkit. + <varname>CONFIGURE_ENV</varname> for Qt toolkit. Default set according to - <makevar>USE_QT_VER</makevar>.</entry> + <varname>USE_QT_VER</varname>.</entry> </row> <row> - <entry><makevar>QTCFGLIBS</makevar></entry> + <entry><varname>QTCFGLIBS</varname></entry> <entry>Additional libraries for linking passed via - <makevar>CONFIGURE_ENV</makevar> for Qt toolkit. + <varname>CONFIGURE_ENV</varname> for Qt toolkit. Default set according to - <makevar>USE_QT_VER</makevar>.</entry> + <varname>USE_QT_VER</varname>.</entry> </row> <row> - <entry><makevar>QTNONSTANDARD</makevar></entry> + <entry><varname>QTNONSTANDARD</varname></entry> <entry>Suppress modification of - <makevar>CONFIGURE_ENV</makevar>, - <makevar>CONFIGURE_ARGS</makevar>, - <makevar>CPPFLAGS</makevar> and - <makevar>MAKE_ENV</makevar>.</entry> + <varname>CONFIGURE_ENV</varname>, + <varname>CONFIGURE_ARGS</varname>, + <varname>CPPFLAGS</varname> and + <varname>MAKE_ENV</varname>.</entry> </row> </tbody> </tgroup> @@ -6669,44 +6618,44 @@ USE_XORG= x11 xpm</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>UIC</makevar></entry> + <entry><varname>UIC</varname></entry> <entry>Set to the path of <command>uic</command> (read-only variable).</entry> </row> <row> - <entry><makevar>QMAKE</makevar></entry> + <entry><varname>QMAKE</varname></entry> <entry>Set to the path of <command>qmake</command> (read-only variable).</entry> </row> <row> - <entry><makevar>QMAKESPEC</makevar></entry> + <entry><varname>QMAKESPEC</varname></entry> <entry>Set to the path of configuration file for <command>qmake</command> (read-only variable).</entry> </row> <row> - <entry><makevar>QMAKEFLAGS</makevar></entry> + <entry><varname>QMAKEFLAGS</varname></entry> <entry>Additional flags for <command>qmake</command>.</entry> </row> <row> - <entry><makevar>QT_INCDIR</makevar></entry> + <entry><varname>QT_INCDIR</varname></entry> <entry>Set to Qt 4 include directories (read-only variable).</entry> </row> <row> - <entry><makevar>QT_LIBDIR</makevar></entry> + <entry><varname>QT_LIBDIR</varname></entry> <entry>Set to Qt 4 libraries path (read-only variable).</entry> </row> <row> - <entry><makevar>QT_PLUGINDIR</makevar></entry> + <entry><varname>QT_PLUGINDIR</varname></entry> <entry>Set to Qt 4 plugins path (read-only variable).</entry> </row> @@ -6714,7 +6663,7 @@ USE_XORG= x11 xpm</programlisting> </tgroup> </table> - <para>When <makevar>USE_QT_VER</makevar> is set to + <para>When <varname>USE_QT_VER</varname> is set to <literal>3</literal>, some useful settings are passed to the <command>configure</command> script:</para> @@ -6726,7 +6675,7 @@ CONFIGURE_ENV+= MOC="${MOC}" LIBS="${QTCFGLIBS}" \ QTDIR="${QT_PREFIX}" KDEDIR="${KDE_PREFIX}" CPPFLAGS+= ${QTCPPFLAGS}</programlisting> - <para>If <makevar>USE_QT4</makevar> is set, the following + <para>If <varname>USE_QT4</varname> is set, the following settings are deployed:</para> <programlisting>CONFIGURE_ARGS+= --with-qt-includes=${QT_INCDIR} \ @@ -6742,11 +6691,11 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ QT_PLUGINDIR_REL=${QT_PLUGINDIR_REL}</programlisting> </sect2> - <sect2 id="qt4-components"> + <sect2 xml:id="qt4-components"> <title>Component Selection (Qt 4.x Only)</title> <para>Individual Qt 4 tool and library dependencies must be - specified in the <makevar>USE_QT4</makevar> variable. Every + specified in the <varname>USE_QT4</varname> variable. Every component can be suffixed by either <literal>_build</literal> or <literal>_run</literal>, the suffix indicating whether the component should be depended @@ -6758,7 +6707,7 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ should be specified with the <literal>_run</literal> suffix. The most commonly used components are listed below (all available components are listed in - <makevar>_USE_QT4_ALL</makevar> in + <varname>_USE_QT4_ALL</varname> in <filename>/usr/ports/Mk/bsd.qt.mk</filename>):</para> <table frame="none"> @@ -6894,7 +6843,7 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ </tgroup> </table> - <example id="qt4-components-example"> + <example xml:id="qt4-components-example"> <title>Selecting Qt 4 Components</title> <para>In this example, the ported application uses the Qt 4 @@ -6913,7 +6862,7 @@ PLIST_SUB+= QT_INCDIR_REL=${QT_INCDIR_REL} \ </example> </sect2> - <sect2 id="qt-additional"> + <sect2 xml:id="qt-additional"> <title>Additional Considerations</title> <para>If the application does not provide a @@ -6929,12 +6878,12 @@ do-configure: <para>Note the similarity to the <command>qmake</command> line from the provided <filename>BUILD.sh</filename> script. - Passing <makevar>CONFIGURE_ENV</makevar> ensures + Passing <varname>CONFIGURE_ENV</varname> ensures <command>qmake</command> will see the - <makevar>QMAKESPEC</makevar> variable, without which it + <varname>QMAKESPEC</varname> variable, without which it cannot work. <command>qmake</command> generates standard Makefiles, so it is not necessary to write our own - <maketarget>build</maketarget> target.</para> + <buildtarget>build</buildtarget> target.</para> <para>Qt applications often are written to be cross-platform and often X11/Unix is not the platform they are developed @@ -6960,7 +6909,7 @@ do-configure: Sometimes data such as icons or .desktop files are by default installed into directories which are not scanned by XDG-compatible applications. - <filename role="package">editors/texmaker</filename> is + <package>editors/texmaker</package> is an example for this - look at <filename>patch-texmaker.pro</filename> in the <filename>files</filename> directory of that port for a @@ -6971,14 +6920,14 @@ do-configure: </sect2> </sect1> - <sect1 id="using-kde"> + <sect1 xml:id="using-kde"> <title>Using KDE</title> - <sect2 id="kde4-variables"> + <sect2 xml:id="kde4-variables"> <title>KDE 4 Variable Definitions</title> <para>If your application depends on KDE 4.x, set - <makevar>USE_KDE4</makevar> to the list of required + <varname>USE_KDE4</varname> to the list of required components. <literal>_build</literal> and <literal>_run</literal> suffixes can be used to force components dependency type (e.g., @@ -7128,7 +7077,7 @@ do-configure: </row> <row> - <entry>smokekde<literal></literal></entry> + <entry>smokekde<literal/></entry> <entry>KDE SMOKE libraries</entry> </row> </tbody> @@ -7136,32 +7085,32 @@ do-configure: </table> <para>KDE 4.x ports are installed into - <makevar>KDE4_PREFIX</makevar>, which is + <varname>KDE4_PREFIX</varname>, which is <filename>/usr/local/kde4</filename> currently. This is achieved by specifying the <literal>kdeprefix</literal> component, which overrides the default - <makevar>PREFIX</makevar>. The ports however respect any - <makevar>PREFIX</makevar> set via <envar>MAKEFLAGS</envar> + <varname>PREFIX</varname>. The ports however respect any + <varname>PREFIX</varname> set via <envar>MAKEFLAGS</envar> environment variable and/or <command>make</command> arguments.</para> - <example id="kde4-components-example"> - <title><makevar>USE_KDE4</makevar> Example</title> + <example xml:id="kde4-components-example"> + <title><varname>USE_KDE4</varname> Example</title> <para>This is a simple example for a KDE 4 port. <literal>USES= cmake:outsource</literal> instructs the port to utilize <application>CMake</application>, a configuration tool widely used by KDE 4 projects (see <xref linkend="using-cmake"/> for detailed usage). - <makevar>USE_KDE4</makevar> brings dependency on KDE + <varname>USE_KDE4</varname> brings dependency on KDE libraries and makes port using <command>automoc4</command> at build stage. Required KDE components and other dependencies can be determined through configure log. - <makevar>USE_KDE4</makevar> does not imply - <makevar>USE_QT4</makevar>. If a port requires some + <varname>USE_KDE4</varname> does not imply + <varname>USE_QT4</varname>. If a port requires some Qt 4 components, they should be specified in - <makevar>USE_QT4</makevar>.</para> + <varname>USE_QT4</varname>.</para> <programlisting>USES= cmake:outsource USE_KDE4= kdelibs kdeprefix automoc4 @@ -7170,22 +7119,22 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </sect2> </sect1> - <sect1 id="using-java"> + <sect1 xml:id="using-java"> <title>Using Java</title> - <sect2 id="java-variables"> + <sect2 xml:id="java-variables"> <title>Variable Definitions</title> <para>If your port needs a Java™ Development Kit (JDK™) to either build, run or even extract the distfile, then it should define - <makevar>USE_JAVA</makevar>.</para> + <varname>USE_JAVA</varname>.</para> <para>There are several JDKs in the ports collection, from various vendors, and in several versions. If your port must use one of these versions, you can define which one. The most current version, and &os; default is - <filename role="package">java/openjdk6</filename>.</para> + <package>java/openjdk6</package>.</para> <table frame="none"> <title>Variables Which May be Set by Ports That Use @@ -7201,13 +7150,13 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>USE_JAVA</makevar></entry> + <entry><varname>USE_JAVA</varname></entry> <entry>Should be defined for the remaining variables to have any effect.</entry> </row> <row> - <entry><makevar>JAVA_VERSION</makevar></entry> + <entry><varname>JAVA_VERSION</varname></entry> <entry>List of space-separated suitable Java versions for the port. An optional <literal>"+"</literal> allows you to specify a range of versions (allowed @@ -7216,14 +7165,14 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>JAVA_OS</makevar></entry> + <entry><varname>JAVA_OS</varname></entry> <entry>List of space-separated suitable JDK port operating systems for the port (allowed values: <literal>native linux</literal>).</entry> </row> <row> - <entry><makevar>JAVA_VENDOR</makevar></entry> + <entry><varname>JAVA_VENDOR</varname></entry> <entry>List of space-separated suitable JDK port vendors for the port (allowed values: <literal>freebsd bsdjava sun @@ -7231,21 +7180,21 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>JAVA_BUILD</makevar></entry> + <entry><varname>JAVA_BUILD</varname></entry> <entry>When set, it means that the selected JDK port should be added to the build dependencies of the port.</entry> </row> <row> - <entry><makevar>JAVA_RUN</makevar></entry> + <entry><varname>JAVA_RUN</varname></entry> <entry>When set, it means that the selected JDK port should be added to the run dependencies of the port.</entry> </row> <row> - <entry><makevar>JAVA_EXTRACT</makevar></entry> + <entry><varname>JAVA_EXTRACT</varname></entry> <entry>When set, it means that the selected JDK port should be added to the extract dependencies of the port.</entry> @@ -7255,7 +7204,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </table> <para>Below is the list of all settings a port will receive - after setting <makevar>USE_JAVA</makevar>:</para> + after setting <varname>USE_JAVA</varname>:</para> <table frame="none"> <title>Variables Provided to Ports That Use Java</title> @@ -7270,60 +7219,60 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>JAVA_PORT</makevar></entry> + <entry><varname>JAVA_PORT</varname></entry> <entry>The name of the JDK port (e.g., <literal>'java/openjdk6'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_VERSION</makevar></entry> + <entry><varname>JAVA_PORT_VERSION</varname></entry> <entry>The full version of the JDK port (e.g., <literal>'1.6.0'</literal>). If you only need the first two digits of this version number, use - <makevar>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</makevar>.</entry> + <varname>${JAVA_PORT_VERSION:C/^([0-9])\.([0-9])(.*)$/\1.\2/}</varname>.</entry> </row> <row> - <entry><makevar>JAVA_PORT_OS</makevar></entry> + <entry><varname>JAVA_PORT_OS</varname></entry> <entry>The operating system used by the JDK port (e.g., <literal>'native'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_VENDOR</makevar></entry> + <entry><varname>JAVA_PORT_VENDOR</varname></entry> <entry>The vendor of the JDK port (e.g., <literal>'openjdk'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_OS_DESCRIPTION</makevar></entry> + <entry><varname>JAVA_PORT_OS_DESCRIPTION</varname></entry> <entry>Description of the operating system used by the JDK port (e.g., <literal>'Native'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_PORT_VENDOR_DESCRIPTION</makevar></entry> + <entry><varname>JAVA_PORT_VENDOR_DESCRIPTION</varname></entry> <entry>Description of the vendor of the JDK port (e.g., <literal>'OpenJDK BSD Porting Team'</literal>).</entry> </row> <row> - <entry><makevar>JAVA_HOME</makevar></entry> + <entry><varname>JAVA_HOME</varname></entry> <entry>Path to the installation directory of the JDK (e.g., <filename>'/usr/local/openjdk6'</filename>).</entry> </row> <row> - <entry><makevar>JAVAC</makevar></entry> + <entry><varname>JAVAC</varname></entry> <entry>Path to the Java compiler to use (e.g., <filename>'/usr/local/openjdk6/bin/javac'</filename>).</entry> </row> <row> - <entry><makevar>JAR</makevar></entry> + <entry><varname>JAR</varname></entry> <entry>Path to the <command>jar</command> tool to use (e.g., <filename>'/usr/local/openjdk6/bin/jar'</filename> @@ -7332,81 +7281,81 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>APPLETVIEWER</makevar></entry> + <entry><varname>APPLETVIEWER</varname></entry> <entry>Path to the <command>appletviewer</command> utility (e.g., <filename>'/usr/local/openjdk6/bin/appletviewer'</filename>).</entry> </row> <row> - <entry><makevar>JAVA</makevar></entry> + <entry><varname>JAVA</varname></entry> <entry>Path to the <command>java</command> executable. Use this for executing Java programs (e.g., <filename>'/usr/local/openjdk6/bin/java'</filename>).</entry> </row> <row> - <entry><makevar>JAVADOC</makevar></entry> + <entry><varname>JAVADOC</varname></entry> <entry>Path to the <command>javadoc</command> utility program.</entry> </row> <row> - <entry><makevar>JAVAH</makevar></entry> + <entry><varname>JAVAH</varname></entry> <entry>Path to the <command>javah</command> program.</entry> </row> <row> - <entry><makevar>JAVAP</makevar></entry> + <entry><varname>JAVAP</varname></entry> <entry>Path to the <command>javap</command> program.</entry> </row> <row> - <entry><makevar>JAVA_KEYTOOL</makevar></entry> + <entry><varname>JAVA_KEYTOOL</varname></entry> <entry>Path to the <command>keytool</command> utility program.</entry> </row> <row> - <entry><makevar>JAVA_N2A</makevar></entry> + <entry><varname>JAVA_N2A</varname></entry> <entry>Path to the <command>native2ascii</command> tool.</entry> </row> <row> - <entry><makevar>JAVA_POLICYTOOL</makevar></entry> + <entry><varname>JAVA_POLICYTOOL</varname></entry> <entry>Path to the <command>policytool</command> program.</entry> </row> <row> - <entry><makevar>JAVA_SERIALVER</makevar></entry> + <entry><varname>JAVA_SERIALVER</varname></entry> <entry>Path to the <command>serialver</command> utility program.</entry> </row> <row> - <entry><makevar>RMIC</makevar></entry> + <entry><varname>RMIC</varname></entry> <entry>Path to the RMI stub/skeleton generator, <command>rmic</command>.</entry> </row> <row> - <entry><makevar>RMIREGISTRY</makevar></entry> + <entry><varname>RMIREGISTRY</varname></entry> <entry>Path to the RMI registry program, <command>rmiregistry</command>.</entry> </row> <row> - <entry><makevar>RMID</makevar></entry> + <entry><varname>RMID</varname></entry> <entry>Path to the RMI daemon program <command>rmid</command>.</entry> </row> <row> - <entry><makevar>JAVA_CLASSES</makevar></entry> + <entry><varname>JAVA_CLASSES</varname></entry> <entry>Path to the archive that contains the JDK class files, <filename>${JAVA_HOME}/jre/lib/rt.jar</filename>.</entry> @@ -7435,21 +7384,21 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>JAVASHAREDIR</makevar></entry> + <entry><varname>JAVASHAREDIR</varname></entry> <entry>The base directory for everything related to Java. Default: <filename>${PREFIX}/share/java</filename>.</entry> </row> <row> - <entry><makevar>JAVAJARDIR</makevar></entry> + <entry><varname>JAVAJARDIR</varname></entry> <entry>The directory where JAR files should be installed. Default: <filename>${JAVASHAREDIR}/classes</filename>.</entry> </row> <row> - <entry><makevar>JAVALIBDIR</makevar></entry> + <entry><varname>JAVALIBDIR</varname></entry> <entry>The directory where JAR files installed by other ports are located. Default: <filename>${LOCALBASE}/share/java/classes</filename>.</entry> @@ -7459,26 +7408,26 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </table> <para>The related entries are defined in both - <makevar>PLIST_SUB</makevar> (documented in + <varname>PLIST_SUB</varname> (documented in <xref linkend="plist-sub"/>) and - <makevar>SUB_LIST</makevar>.</para> + <varname>SUB_LIST</varname>.</para> </sect2> - <sect2 id="java-building-with-ant"> + <sect2 xml:id="java-building-with-ant"> <title>Building with Ant</title> <para>When the port is to be built using Apache Ant, it has to - define <makevar>USE_ANT</makevar>. Ant is thus considered + define <varname>USE_ANT</varname>. Ant is thus considered to be the sub-make command. When no <literal>do-build</literal> target is defined by the port, a default one will be set that simply runs Ant according to - <makevar>MAKE_ENV</makevar>, <makevar>MAKE_ARGS</makevar> - and <makevar>ALL_TARGET</makevar>. This is similar to the - <makevar>USES= gmake</makevar> mechanism, which is + <varname>MAKE_ENV</varname>, <varname>MAKE_ARGS</varname> + and <varname>ALL_TARGET</varname>. This is similar to the + <varname>USES= gmake</varname> mechanism, which is documented in <xref linkend="building"/>.</para> </sect2> - <sect2 id="java-best-practices"> + <sect2 xml:id="java-best-practices"> <title>Best Practices</title> <para>When porting a Java library, your port should install @@ -7514,18 +7463,18 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> particular JDK, it is therefore a complex task to specify the packing list (<filename>pkg-plist</filename>). This is one reason why porters are strongly encouraged to use the - <makevar>PORTDOCS</makevar> macro. Moreover, even if you + <varname>PORTDOCS</varname> macro. Moreover, even if you can predict the set of files that will be generated by <command>javadoc</command>, the size of the resulting <filename>pkg-plist</filename> advocates for the use of - <makevar>PORTDOCS</makevar>.</para> + <varname>PORTDOCS</varname>.</para> - <para>The default value for <makevar>DATADIR</makevar> is + <para>The default value for <varname>DATADIR</varname> is <filename>${PREFIX}/share/${PORTNAME}</filename>. It is a - good idea to override <makevar>DATADIR</makevar> to + good idea to override <varname>DATADIR</varname> to <filename>${JAVASHAREDIR}/${PORTNAME}</filename> for Java - ports. Indeed, <makevar>DATADIR</makevar> is automatically - added to <makevar>PLIST_SUB</makevar> (documented in + ports. Indeed, <varname>DATADIR</varname> is automatically + added to <varname>PLIST_SUB</varname> (documented in <xref linkend="plist-sub"/>) so you may use <literal>%%DATADIR%%</literal> directly in <filename>pkg-plist</filename>.</para> @@ -7534,16 +7483,15 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> directly installing them from a binary distribution, there is no defined policy at the time of writing. However, people from the - <ulink url="http://www.freebsd.org/java/">&os; Java - Project</ulink> encourage porters to have their ports + <link xlink:href="http://www.freebsd.org/java/">&os; Java + Project</link> encourage porters to have their ports built from source whenever it is a trivial task.</para> <para>All the features that have been presented in this section are implemented in <filename>bsd.java.mk</filename>. If you ever think that your port needs more sophisticated - Java support, please first have a look at the <ulink - url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk - SVN log</ulink> as it usually takes some time + Java support, please first have a look at the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.java.mk?view=markup">bsd.java.mk + SVN log</link> as it usually takes some time to document the latest features. Then, if you think the support you are lacking would be beneficial to many other Java ports, feel free to discuss it on the &a.java;.</para> @@ -7557,15 +7505,15 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <filename>bsd.java.mk</filename>.</para> <para>Similarly, there is a defined policy regarding the - <makevar>CATEGORIES</makevar> of a Java port, which is + <varname>CATEGORIES</varname> of a Java port, which is detailed in <xref linkend="makefile-categories"/>.</para> </sect2> </sect1> - <sect1 id="using-php"> + <sect1 xml:id="using-php"> <title>Web Applications, Apache and PHP</title> - <sect2 id="using-apache"> + <sect2 xml:id="using-apache"> <title>Apache</title> <table frame="none"> @@ -7575,7 +7523,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>USE_APACHE</makevar></entry> + <entry><varname>USE_APACHE</varname></entry> <entry>The port requires Apache. Possible values: <literal>yes</literal> (gets any version), <literal>22</literal>, <literal>24</literal>, @@ -7583,24 +7531,23 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> etc. The default APACHE version is <literal>22</literal>. More details are available in <filename>ports/Mk/bsd.apache.mk</filename> and - at <ulink - url="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</ulink>.</entry> + at <link xlink:href="http://wiki.freebsd.org/Apache/">wiki.freebsd.org/Apache/</link>.</entry> </row> <row> - <entry><makevar>APXS</makevar></entry> + <entry><varname>APXS</varname></entry> <entry>Full path to the <command>apxs</command> binary. Can be overridden in your port.</entry> </row> <row> - <entry><makevar>HTTPD</makevar></entry> + <entry><varname>HTTPD</varname></entry> <entry>Full path to the <command>httpd</command> binary. Can be overridden in your port.</entry> </row> <row> - <entry><makevar>APACHE_VERSION</makevar></entry> + <entry><varname>APACHE_VERSION</varname></entry> <entry>The version of present Apache installation (read-only variable). This variable is only available after inclusion of @@ -7610,21 +7557,21 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>APACHEMODDIR</makevar></entry> + <entry><varname>APACHEMODDIR</varname></entry> <entry>Directory for Apache modules. This variable is automatically expanded in <filename>pkg-plist</filename>.</entry> </row> <row> - <entry><makevar>APACHEINCLUDEDIR</makevar></entry> + <entry><varname>APACHEINCLUDEDIR</varname></entry> <entry>Directory for Apache headers. This variable is automatically expanded in <filename>pkg-plist</filename>.</entry> </row> <row> - <entry><makevar>APACHEETCDIR</makevar></entry> + <entry><varname>APACHEETCDIR</varname></entry> <entry>Directory for Apache configuration files. This variable is automatically expanded in <filename>pkg-plist</filename>.</entry> @@ -7640,46 +7587,46 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tbody> <row> - <entry><makevar>MODULENAME</makevar></entry> + <entry><varname>MODULENAME</varname></entry> <entry>Name of the module. Default value is - <makevar>PORTNAME</makevar>. Example: + <varname>PORTNAME</varname>. Example: <literal>mod_hello</literal></entry> </row> <row> - <entry><makevar>SHORTMODNAME</makevar></entry> + <entry><varname>SHORTMODNAME</varname></entry> <entry>Short name of the module. Automatically - derived from <makevar>MODULENAME</makevar>, but can + derived from <varname>MODULENAME</varname>, but can be overridden. Example: <literal>hello</literal></entry> </row> <row> - <entry><makevar>AP_FAST_BUILD</makevar></entry> + <entry><varname>AP_FAST_BUILD</varname></entry> <entry>Use <command>apxs</command> to compile and install the module.</entry> </row> <row> - <entry><makevar>AP_GENPLIST</makevar></entry> + <entry><varname>AP_GENPLIST</varname></entry> <entry>Also automatically creates a <filename>pkg-plist</filename>.</entry> </row> <row> - <entry><makevar>AP_INC</makevar></entry> + <entry><varname>AP_INC</varname></entry> <entry>Adds a directory to a header search path during compilation.</entry> </row> <row> - <entry><makevar>AP_LIB</makevar></entry> + <entry><varname>AP_LIB</varname></entry> <entry>Adds a directory to a library search path during compilation.</entry> </row> <row> - <entry><makevar>AP_EXTRAS</makevar></entry> + <entry><varname>AP_EXTRAS</varname></entry> <entry>Additional flags to pass to <command>apxs</command>.</entry> </row> @@ -7688,20 +7635,20 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </table> </sect2> - <sect2 id="web-apps"> + <sect2 xml:id="web-apps"> <title>Web Applications</title> <para>Web applications should be installed into - <filename><makevar>PREFIX</makevar>/www/<replaceable>appname</replaceable></filename>. + <filename>PREFIX/www/appname</filename>. For your convenience, this path is available both in <filename>Makefile</filename> and in - <filename>pkg-plist</filename> as <makevar>WWWDIR</makevar>, - and the path relative to <makevar>PREFIX</makevar> is + <filename>pkg-plist</filename> as <varname>WWWDIR</varname>, + and the path relative to <varname>PREFIX</varname> is available in <filename>Makefile</filename> as - <makevar>WWWDIR_REL</makevar>.</para> + <varname>WWWDIR_REL</varname>.</para> <para>The user and group of web server process are available - as <makevar>WWWOWN</makevar> and <makevar>WWWGRP</makevar>, + as <varname>WWWOWN</varname> and <varname>WWWGRP</varname>, in case you need to change the ownership of some files. The default values of both are <literal>www</literal>. If you want different values for your port, use @@ -7713,7 +7660,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> app on different web server than Apache.</para> </sect2> - <sect2 id="php-variables"> + <sect2 xml:id="php-variables"> <title>PHP</title> <table frame="none"> @@ -7722,7 +7669,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_PHP</makevar></entry> + <entry><varname>USE_PHP</varname></entry> <entry>The port requires PHP. The value <literal>yes</literal> adds a dependency on PHP. The list of required PHP extensions can be specified @@ -7731,7 +7678,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>DEFAULT_PHP_VER</makevar></entry> + <entry><varname>DEFAULT_PHP_VER</varname></entry> <entry>Selects which major version of PHP will be installed as a dependency when no PHP is installed yet. Default is <literal>5</literal>. Possible @@ -7740,53 +7687,53 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> </row> <row> - <entry><makevar>IGNORE_WITH_PHP</makevar></entry> + <entry><varname>IGNORE_WITH_PHP</varname></entry> <entry>The port does not work with PHP of the given version. Possible values: <literal>4</literal>, <literal>5</literal></entry> </row> <row> - <entry><makevar>USE_PHPIZE</makevar></entry> + <entry><varname>USE_PHPIZE</varname></entry> <entry>The port will be built as a PHP extension.</entry> </row> <row> - <entry><makevar>USE_PHPEXT</makevar></entry> + <entry><varname>USE_PHPEXT</varname></entry> <entry>The port will be treated as a PHP extension, including installation and registration in the extension registry.</entry> </row> <row> - <entry><makevar>USE_PHP_BUILD</makevar></entry> + <entry><varname>USE_PHP_BUILD</varname></entry> <entry>Set PHP as a build dependency.</entry> </row> <row> - <entry><makevar>WANT_PHP_CLI</makevar></entry> + <entry><varname>WANT_PHP_CLI</varname></entry> <entry>Want the CLI (command line) version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_CGI</makevar></entry> + <entry><varname>WANT_PHP_CGI</varname></entry> <entry>Want the CGI version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_MOD</makevar></entry> + <entry><varname>WANT_PHP_MOD</varname></entry> <entry>Want the Apache module version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_SCR</makevar></entry> + <entry><varname>WANT_PHP_SCR</varname></entry> <entry>Want the CLI or the CGI version of PHP.</entry> </row> <row> - <entry><makevar>WANT_PHP_WEB</makevar></entry> + <entry><varname>WANT_PHP_WEB</varname></entry> <entry>Want the Apache module or the CGI version of PHP.</entry> </row> @@ -7800,10 +7747,10 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> <para>Porting PEAR modules is a very simple process.</para> - <para>Use the variables <makevar>FILES</makevar>, - <makevar>TESTS</makevar>, <makevar>DATA</makevar>, - <makevar>SQLS</makevar>, <makevar>SCRIPTFILES</makevar>, - <makevar>DOCS</makevar> and <makevar>EXAMPLES</makevar> to + <para>Use the variables <varname>FILES</varname>, + <varname>TESTS</varname>, <varname>DATA</varname>, + <varname>SQLS</varname>, <varname>SCRIPTFILES</varname>, + <varname>DOCS</varname> and <varname>EXAMPLES</varname> to list the files you want to install. All listed files will be automatically installed into the appropriate locations and added to <filename>pkg-plist</filename>.</para> @@ -7813,7 +7760,7 @@ USE_QT4= moc_build qmake_build rcc_build uic_build</programlisting> on the last line of the <filename>Makefile</filename>.</para> - <example id="pear-makefile"> + <example xml:id="pear-makefile"> <title>Example Makefile for PEAR Class</title> <programlisting>PORTNAME= Date @@ -7844,19 +7791,19 @@ _DOCSDIR= . </sect2> </sect1> - <sect1 id="using-python"> + <sect1 xml:id="using-python"> <title>Using Python</title> <para>The Ports Collection supports parallel installation of multiple Python versions. Ports should make sure to use a correct <command>python</command> interpreter, according to - the user-settable <makevar>PYTHON_VERSION</makevar> variable. + the user-settable <varname>PYTHON_VERSION</varname> variable. Most prominently, this means replacing the path to <command>python</command> executable in scripts with the value - of <makevar>PYTHON_CMD</makevar> variable.</para> + of <varname>PYTHON_CMD</varname> variable.</para> <para>Ports that install files under - <makevar>PYTHON_SITELIBDIR</makevar> should use the + <varname>PYTHON_SITELIBDIR</varname> should use the <literal>pyXY-</literal> package name prefix, so their package name embeds the version of Python they are installed into.</para> @@ -7869,7 +7816,7 @@ _DOCSDIR= . <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_PYTHON</makevar></entry> + <entry><varname>USE_PYTHON</varname></entry> <entry>The port needs Python. Minimal required version can be specified with values such as <literal>2.6+</literal>. Version ranges can also be @@ -7878,35 +7825,35 @@ _DOCSDIR= . </row> <row> - <entry><makevar>USE_PYDISTUTILS</makevar></entry> + <entry><varname>USE_PYDISTUTILS</varname></entry> <entry>Use Python distutils for configuring, compiling and installing. This is required when the port comes with <filename>setup.py</filename>. This overrides - the <maketarget>do-build</maketarget> and - <maketarget>do-install</maketarget> targets and may - also override <maketarget>do-configure</maketarget> if - <makevar>GNU_CONFIGURE</makevar> is not + the <buildtarget>do-build</buildtarget> and + <buildtarget>do-install</buildtarget> targets and may + also override <buildtarget>do-configure</buildtarget> if + <varname>GNU_CONFIGURE</varname> is not defined.</entry> </row> <row> - <entry><makevar>PYTHON_PKGNAMEPREFIX</makevar></entry> - <entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to + <entry><varname>PYTHON_PKGNAMEPREFIX</varname></entry> + <entry>Used as a <varname>PKGNAMEPREFIX</varname> to distinguish packages for different Python versions. Example: <literal>py24-</literal></entry> </row> <row> - <entry><makevar>PYTHON_SITELIBDIR</makevar></entry> + <entry><varname>PYTHON_SITELIBDIR</varname></entry> <entry>Location of the site-packages tree, that contains installation path of Python (usually - <makevar>LOCALBASE</makevar>). The - <makevar>PYTHON_SITELIBDIR</makevar> variable can be + <varname>LOCALBASE</varname>). The + <varname>PYTHON_SITELIBDIR</varname> variable can be very useful when installing Python modules.</entry> </row> <row> - <entry><makevar>PYTHONPREFIX_SITELIBDIR</makevar></entry> + <entry><varname>PYTHONPREFIX_SITELIBDIR</varname></entry> <entry>The PREFIX-clean variant of PYTHON_SITELIBDIR. Always use <literal>%%PYTHON_SITELIBDIR%%</literal> in <filename>pkg-plist</filename> when possible. The @@ -7916,32 +7863,32 @@ _DOCSDIR= . </row> <row> - <entry><makevar>PYTHON_CMD</makevar></entry> + <entry><varname>PYTHON_CMD</varname></entry> <entry>Python interpreter command line, including version number.</entry> </row> <row> - <entry><makevar>PYNUMERIC</makevar></entry> + <entry><varname>PYNUMERIC</varname></entry> <entry>Dependency line for numeric extension.</entry> </row> <row> - <entry><makevar>PYNUMPY</makevar></entry> + <entry><varname>PYNUMPY</varname></entry> <entry>Dependency line for the new numeric extension, numpy. (PYNUMERIC is deprecated by upstream vendor).</entry> </row> <row> - <entry><makevar>PYXML</makevar></entry> + <entry><varname>PYXML</varname></entry> <entry>Dependency line for XML extension (not needed for Python 2.0 and higher as it is also in base distribution).</entry> </row> <row> - <entry><makevar>USE_TWISTED</makevar></entry> + <entry><varname>USE_TWISTED</varname></entry> <entry>Add dependency on twistedCore. The list of required components can be specified as a value of this variable. Example: @@ -7949,10 +7896,10 @@ _DOCSDIR= . </row> <row> - <entry><makevar>USE_ZOPE</makevar></entry> + <entry><varname>USE_ZOPE</varname></entry> <entry>Add dependency on Zope, a web application platform. Change Python dependency to Python 2.7. - Set <makevar>ZOPEBASEDIR</makevar> containing a + Set <varname>ZOPEBASEDIR</varname> containing a directory with Zope installation.</entry> </row> </tbody> @@ -7963,12 +7910,12 @@ _DOCSDIR= . <filename>/usr/ports/Mk/bsd.python.mk</filename>.</para> <para>Some Python applications claim to have - <makevar>DESTDIR</makevar> support (which would be required for + <varname>DESTDIR</varname> support (which would be required for staging) but it is broken (Mailman up to 2.1.16, for instance). This can be worked around by recompiling the scripts. This can - be done, for example, in the <maketarget>post-build</maketarget> + be done, for example, in the <buildtarget>post-build</buildtarget> target. Assuming the Python scripts are supposed to reside in - <makevar>PYTHONPREFIX_SITELIBDIR</makevar> after + <varname>PYTHONPREFIX_SITELIBDIR</varname> after installation, this solution can be applied:</para> <programlisting>(cd ${STAGEDIR}${PREFIX} \ @@ -7978,29 +7925,29 @@ _DOCSDIR= . <para>This recompiles the sources with a path relative to the stage directory, and prepends the value of - <makevar>PREFIX</makevar> to the file name recorded in the + <varname>PREFIX</varname> to the file name recorded in the byte-compiled output file by <literal>-d</literal>. <literal>-f</literal> is required to force recompilation, and the <literal>:S;${PREFIX}/;;</literal> strips prefixes from - the value of the <makevar>PYTHONPREFIX_SITELIBDIR</makevar> + the value of the <varname>PYTHONPREFIX_SITELIBDIR</varname> variable to make it relative to - <makevar>PREFIX</makevar>.</para> + <varname>PREFIX</varname>.</para> <para>Python 2.7 or newer is required for this. It does not work with Python 2.6.</para> </sect1> - <sect1 id="using-tcl"> + <sect1 xml:id="using-tcl"> <title>Using <application>Tcl/Tk</application></title> <para>The Ports Collection supports parallel installation of multiple <application>Tcl/Tk</application> versions. Ports should try to support at least the default <application>Tcl/Tk</application> version and higher with the - <makevar>USE_TCL</makevar> and <makevar>USE_TK</makevar> + <varname>USE_TCL</varname> and <varname>USE_TK</varname> variables. It is possible to specify the desired version of <command>tcl</command> with the - <makevar>WITH_TCL_VER</makevar> variable.</para> + <varname>WITH_TCL_VER</varname> variable.</para> <table frame="none"> <title>The Most Useful Variables for Ports That Use @@ -8009,23 +7956,23 @@ _DOCSDIR= . <tgroup cols="2"> <tbody> <row> - <entry><makevar>USE_TCL</makevar></entry> + <entry><varname>USE_TCL</varname></entry> <entry>The port depends on the <application>Tcl</application> library (not the shell). Minimal required version can be specified with values such as 84+. Individual unsupported versions can be specified with the - <makevar>INVALID_TCL_VER</makevar> variable.</entry> + <varname>INVALID_TCL_VER</varname> variable.</entry> </row> <row> - <entry><makevar>USE_TCL_BUILD</makevar></entry> + <entry><varname>USE_TCL_BUILD</varname></entry> <entry>The port needs <application>Tcl</application> only during the build time.</entry> </row> <row> - <entry><makevar>USE_TCL_WRAPPER</makevar></entry> + <entry><varname>USE_TCL_WRAPPER</varname></entry> <entry>Ports that require the <application>Tcl</application> shell and do not require a specific <literal>tclsh</literal> version @@ -8036,48 +7983,48 @@ _DOCSDIR= . </row> <row> - <entry><makevar>WITH_TCL_VER</makevar></entry> + <entry><varname>WITH_TCL_VER</varname></entry> <entry>User-defined variable that sets the desired <application>Tcl</application> version.</entry> </row> <row> - <entry><makevar><replaceable>UNIQUENAME</replaceable>_WITH_TCL_VER</makevar></entry> - <entry>Like <makevar>WITH_TCL_VER</makevar>, but + <entry><varname><replaceable>UNIQUENAME</replaceable>_WITH_TCL_VER</varname></entry> + <entry>Like <varname>WITH_TCL_VER</varname>, but per-port.</entry> </row> <row> - <entry><makevar>USE_TCL_THREADS</makevar></entry> + <entry><varname>USE_TCL_THREADS</varname></entry> <entry>Require a threaded build of <application>Tcl/Tk</application>.</entry> </row> <row> - <entry><makevar>USE_TK</makevar></entry> + <entry><varname>USE_TK</varname></entry> <entry>The port depends on the <application>Tk</application> library (not the wish - shell). Implies <makevar>USE_TCL</makevar> with the + shell). Implies <varname>USE_TCL</varname> with the same value. For more information see the description - of <makevar>USE_TCL</makevar> variable.</entry> + of <varname>USE_TCL</varname> variable.</entry> </row> <row> - <entry><makevar>USE_TK_BUILD</makevar></entry> - <entry>Analog to the <makevar>USE_TCL_BUILD</makevar> + <entry><varname>USE_TK_BUILD</varname></entry> + <entry>Analog to the <varname>USE_TCL_BUILD</varname> variable.</entry> </row> <row> - <entry><makevar>USE_TK_WRAPPER</makevar></entry> - <entry>Analog to the <makevar>USE_TCL_WRAPPER</makevar> + <entry><varname>USE_TK_WRAPPER</varname></entry> + <entry>Analog to the <varname>USE_TCL_WRAPPER</varname> variable.</entry> </row> <row> - <entry><makevar>WITH_TK_VER</makevar></entry> - <entry>Analog to the <makevar>WITH_TCL_VER</makevar> - variable and implies <makevar>WITH_TCL_VER</makevar> + <entry><varname>WITH_TK_VER</varname></entry> + <entry>Analog to the <varname>WITH_TCL_VER</varname> + variable and implies <varname>WITH_TCL_VER</varname> of the same value.</entry> </row> </tbody> @@ -8088,13 +8035,13 @@ _DOCSDIR= . <filename>/usr/ports/Mk/bsd.tcl.mk</filename>.</para> </sect1> - <sect1 id="using-emacs"> + <sect1 xml:id="using-emacs"> <title>Using Emacs</title> <para>This section is yet to be written.</para> </sect1> - <sect1 id="using-ruby"> + <sect1 xml:id="using-ruby"> <title>Using Ruby</title> <table frame="none"> @@ -8109,24 +8056,24 @@ _DOCSDIR= . </thead> <tbody> <row> - <entry><makevar>USE_RUBY</makevar></entry> + <entry><varname>USE_RUBY</varname></entry> <entry>The port requires Ruby.</entry> </row> <row> - <entry><makevar>USE_RUBY_EXTCONF</makevar></entry> + <entry><varname>USE_RUBY_EXTCONF</varname></entry> <entry>The port uses <filename>extconf.rb</filename> to configure.</entry> </row> <row> - <entry><makevar>USE_RUBY_SETUP</makevar></entry> + <entry><varname>USE_RUBY_SETUP</varname></entry> <entry>The port uses <filename>setup.rb</filename> to configure.</entry> </row> <row> - <entry><makevar>RUBY_SETUP</makevar></entry> + <entry><varname>RUBY_SETUP</varname></entry> <entry>Set to the alternative name of <filename>setup.rb</filename>. Common value is <filename>install.rb</filename>.</entry> @@ -8157,42 +8104,42 @@ _DOCSDIR= . <tbody> <row> - <entry><makevar>RUBY_PKGNAMEPREFIX</makevar></entry> - <entry>Used as a <makevar>PKGNAMEPREFIX</makevar> to + <entry><varname>RUBY_PKGNAMEPREFIX</varname></entry> + <entry>Used as a <varname>PKGNAMEPREFIX</varname> to distinguish packages for different Ruby versions.</entry> <entry><literal>ruby18-</literal></entry> </row> <row> - <entry><makevar>RUBY_VERSION</makevar></entry> + <entry><varname>RUBY_VERSION</varname></entry> <entry>Full version of Ruby in the form of <literal>x.y.z</literal>.</entry> <entry><literal>1.8.2</literal></entry> </row> <row> - <entry><makevar>RUBY_SITELIBDIR</makevar></entry> + <entry><varname>RUBY_SITELIBDIR</varname></entry> <entry>Architecture independent libraries installation path.</entry> <entry><literal>/usr/local/lib/ruby/site_ruby/1.8</literal></entry> </row> <row> - <entry><makevar>RUBY_SITEARCHLIBDIR</makevar></entry> + <entry><varname>RUBY_SITEARCHLIBDIR</varname></entry> <entry>Architecture dependent libraries installation path.</entry> <entry><literal>/usr/local/lib/ruby/site_ruby/1.8/amd64-freebsd6</literal></entry> </row> <row> - <entry><makevar>RUBY_MODDOCDIR</makevar></entry> + <entry><varname>RUBY_MODDOCDIR</varname></entry> <entry>Module documentation installation path.</entry> <entry><literal>/usr/local/share/doc/ruby18/patsy</literal></entry> </row> <row> - <entry><makevar>RUBY_MODEXAMPLESDIR</makevar></entry> + <entry><varname>RUBY_MODEXAMPLESDIR</varname></entry> <entry>Module examples installation path.</entry> <entry><literal>/usr/local/share/examples/ruby18/patsy</literal></entry> </row> @@ -8205,106 +8152,95 @@ _DOCSDIR= . </sect1> - <sect1 id="using-sdl"> + <sect1 xml:id="using-sdl"> <title>Using SDL</title> - <para>The <makevar>USE_SDL</makevar> variable is used to + <para>The <varname>USE_SDL</varname> variable is used to autoconfigure the dependencies for ports which use an SDL based library like - <filename role="package">devel/sdl12</filename> and <filename - role="package">x11-toolkits/sdl_gui</filename>.</para> + <package>devel/sdl12</package> and <package>x11-toolkits/sdl_gui</package>.</para> <para>The following SDL libraries are recognized at the moment:</para> <itemizedlist> <listitem> - <para>sdl: <filename - role="package">devel/sdl12</filename></para> + <para>sdl: <package>devel/sdl12</package></para> </listitem> <listitem> - <para>gfx: <filename - role="package">graphics/sdl_gfx</filename></para> + <para>gfx: <package>graphics/sdl_gfx</package></para> </listitem> <listitem> - <para>gui: <filename - role="package">x11-toolkits/sdl_gui</filename></para> + <para>gui: <package>x11-toolkits/sdl_gui</package></para> </listitem> <listitem> - <para>image: <filename - role="package">graphics/sdl_image</filename></para> + <para>image: <package>graphics/sdl_image</package></para> </listitem> <listitem> - <para>ldbad: <filename - role="package">devel/sdl_ldbad</filename></para> + <para>ldbad: <package>devel/sdl_ldbad</package></para> </listitem> <listitem> - <para>mixer: <filename - role="package">audio/sdl_mixer</filename></para> + <para>mixer: <package>audio/sdl_mixer</package></para> </listitem> <listitem> - <para>mm: <filename - role="package">devel/sdlmm</filename></para> + <para>mm: <package>devel/sdlmm</package></para> </listitem> <listitem> - <para>net: <filename - role="package">net/sdl_net</filename></para> + <para>net: <package>net/sdl_net</package></para> </listitem> <listitem> - <para>sound: <filename - role="package">audio/sdl_sound</filename></para> + <para>sound: <package>audio/sdl_sound</package></para> </listitem> <listitem> - <para>ttf: <filename - role="package">graphics/sdl_ttf</filename></para> + <para>ttf: <package>graphics/sdl_ttf</package></para> </listitem> </itemizedlist> <para>Therefore, if a port has a dependency on - <filename role="package">net/sdl_net</filename> and - <filename role="package">audio/sdl_mixer</filename>, + <package>net/sdl_net</package> and + <package>audio/sdl_mixer</package>, the syntax will be:</para> <programlisting>USE_SDL= net mixer</programlisting> <para>The dependency - <filename role="package">devel/sdl12</filename>, which is - required by <filename role="package">net/sdl_net</filename> - and <filename role="package">audio/sdl_mixer</filename>, is + <package>devel/sdl12</package>, which is + required by <package>net/sdl_net</package> + and <package>audio/sdl_mixer</package>, is automatically added as well.</para> - <para>If you use <makevar>USE_SDL</makevar>, it will + <para>If you use <varname>USE_SDL</varname>, it will automatically:</para> <itemizedlist> <listitem> <para>Add a dependency on <application>sdl12-config</application> to - <makevar>BUILD_DEPENDS</makevar></para> + <varname>BUILD_DEPENDS</varname></para> </listitem> <listitem> - <para>Add the variable <makevar>SDL_CONFIG</makevar> to - <makevar>CONFIGURE_ENV</makevar></para> + <para>Add the variable <varname>SDL_CONFIG</varname> to + <varname>CONFIGURE_ENV</varname></para> </listitem> <listitem> <para>Add the dependencies of the selected libraries to the - <makevar>LIB_DEPENDS</makevar></para> + <varname>LIB_DEPENDS</varname></para> </listitem> </itemizedlist> <para>To check whether an SDL library is available, you can do - it with the <makevar>WANT_SDL</makevar> variable:</para> + it with the <varname>WANT_SDL</varname> variable:</para> <programlisting>WANT_SDL= yes @@ -8317,14 +8253,14 @@ USE_SDL+= mixer .include <bsd.port.post.mk></programlisting> </sect1> - <sect1 id="using-wx"> + <sect1 xml:id="using-wx"> <title>Using <application>wxWidgets</application></title> <para>This section describes the status of the <application>wxWidgets</application> libraries in the ports tree and its integration with the ports system.</para> - <sect2 id="wx-introduction"> + <sect2 xml:id="wx-introduction"> <title>Introduction</title> <para>There are many versions of the @@ -8346,7 +8282,7 @@ USE_SDL+= mixer have to be patched.</para> </sect2> - <sect2 id="wx-version"> + <sect2 xml:id="wx-version"> <title>Version Selection</title> <para>To make your port use a specific version of @@ -8354,7 +8290,7 @@ USE_SDL+= mixer available for defining (if only one is defined the other will be set to a default value):</para> - <table id="wx-ver-sel-table" frame="none"> + <table xml:id="wx-ver-sel-table" frame="none"> <title>Variables to Select <application>wxWidgets</application> Versions</title> @@ -8369,13 +8305,13 @@ USE_SDL+= mixer <tbody> <row> - <entry><makevar>USE_WX</makevar></entry> + <entry><varname>USE_WX</varname></entry> <entry>List of versions the port can use</entry> <entry>All available versions</entry> </row> <row> - <entry><makevar>USE_WX_NOT</makevar></entry> + <entry><varname>USE_WX_NOT</varname></entry> <entry>List of versions the port can not use</entry> <entry>None</entry> </row> @@ -8402,20 +8338,17 @@ USE_SDL+= mixer <tbody> <row> <entry><literal>2.4</literal></entry> - <entry><filename - role="package">x11-toolkits/wxgtk24</filename></entry> + <entry><package>x11-toolkits/wxgtk24</package></entry> </row> <row> <entry><literal>2.6</literal></entry> - <entry><filename - role="package">x11-toolkits/wxgtk26</filename></entry> + <entry><package>x11-toolkits/wxgtk26</package></entry> </row> <row> <entry><literal>2.8</literal></entry> - <entry><filename - role="package">x11-toolkits/wxgtk28</filename></entry> + <entry><package>x11-toolkits/wxgtk28</package></entry> </row> </tbody> </tgroup> @@ -8426,8 +8359,7 @@ USE_SDL+= mixer come in Unicode version and are installed by a slave port named like the normal one plus a <literal>-unicode</literal> suffix, but this can be - handled with variables (see <xref - linkend="wx-unicode"/>).</para> + handled with variables (see <xref linkend="wx-unicode"/>).</para> </note> <para>The variables in <xref linkend="wx-ver-sel-table"/> can @@ -8489,12 +8421,12 @@ USE_SDL+= mixer <tbody> <row> - <entry><makevar>WANT_WX_VER</makevar></entry> + <entry><varname>WANT_WX_VER</varname></entry> <entry>the port</entry> </row> <row> - <entry><makevar>WITH_WX_VER</makevar></entry> + <entry><varname>WITH_WX_VER</varname></entry> <entry>the user</entry> </row> </tbody> @@ -8502,13 +8434,13 @@ USE_SDL+= mixer </table> </sect2> - <sect2 id="wx-components"> + <sect2 xml:id="wx-components"> <title>Component Selection</title> <para>There are other applications that, while not being <application>wxWidgets</application> libraries, are related to them. These applications can be specified in the - <makevar>WX_COMPS</makevar> variable. The following + <varname>WX_COMPS</varname> variable. The following components are available:</para> <table frame="none"> @@ -8581,19 +8513,19 @@ USE_SDL+= mixer <row> <entry><literal>build</literal></entry> <entry>Component is required for building, equivalent - to <makevar>BUILD_DEPENDS</makevar></entry> + to <varname>BUILD_DEPENDS</varname></entry> </row> <row> <entry><literal>run</literal></entry> <entry>Component is required for running, equivalent - to <makevar>RUN_DEPENDS</makevar></entry> + to <varname>RUN_DEPENDS</varname></entry> </row> <row> <entry><literal>lib</literal></entry> <entry>Component is required for building and running, - equivalent to <makevar>LIB_DEPENDS</makevar></entry> + equivalent to <varname>LIB_DEPENDS</varname></entry> </row> </tbody> </tgroup> @@ -8602,7 +8534,7 @@ USE_SDL+= mixer <para>The default values for the components are detailed in the following table:</para> - <table id="wx-def-dep-types" frame="none"> + <table xml:id="wx-def-dep-types" frame="none"> <title>Default <application>wxWidgets</application> Dependency Types</title> @@ -8643,7 +8575,7 @@ USE_SDL+= mixer </tgroup> </table> - <example id="wx-components-example"> + <example xml:id="wx-components-example"> <title>Selecting <application>wxWidgets</application> Components</title> @@ -8657,7 +8589,7 @@ WX_COMPS= wx contrib</programlisting> </example> </sect2> - <sect2 id="wx-unicode"> + <sect2 xml:id="wx-unicode"> <title>Unicode</title> <para>The <application>wxWidgets</application> library @@ -8665,7 +8597,7 @@ WX_COMPS= wx contrib</programlisting> the ports tree both versions are available and can be selected with the following variables:</para> - <table id="wx-unicode-var-table" frame="none"> + <table xml:id="wx-unicode-var-table" frame="none"> <title>Variables to Select Unicode in <application>wxWidgets</application> Versions</title> @@ -8681,29 +8613,29 @@ WX_COMPS= wx contrib</programlisting> <tbody> <row> - <entry><makevar>WX_UNICODE</makevar></entry> + <entry><varname>WX_UNICODE</varname></entry> <entry>The port works <emphasis>only</emphasis> with the Unicode version</entry> <entry>the port</entry> </row> <row> - <entry><makevar>WANT_UNICODE</makevar></entry> + <entry><varname>WANT_UNICODE</varname></entry> <entry>The port works with both versions but prefers the Unicode one</entry> <entry>the port</entry> </row> <row> - <entry><makevar>WITH_UNICODE</makevar></entry> + <entry><varname>WITH_UNICODE</varname></entry> <entry>The port will use the Unicode version</entry> <entry>the user</entry> </row> <row> - <entry><makevar>WITHOUT_UNICODE</makevar></entry> + <entry><varname>WITHOUT_UNICODE</varname></entry> <entry>The port will use the normal version if - supported (when <makevar>WX_UNICODE</makevar> is not + supported (when <varname>WX_UNICODE</varname> is not defined)</entry> <entry>the user</entry> </row> @@ -8712,23 +8644,23 @@ WX_COMPS= wx contrib</programlisting> </table> <warning> - <para>Do not use <makevar>WX_UNICODE</makevar> for ports + <para>Do not use <varname>WX_UNICODE</varname> for ports that can use both Unicode and normal versions. If you want the port to use Unicode by default define - <makevar>WANT_UNICODE</makevar> instead.</para> + <varname>WANT_UNICODE</varname> instead.</para> </warning> </sect2> - <sect2 id="wx-version-detection"> + <sect2 xml:id="wx-version-detection"> <title>Detecting Installed Versions</title> <para>To detect an installed version you have to define - <makevar>WANT_WX</makevar>. If you do not set it to a + <varname>WANT_WX</varname>. If you do not set it to a specific version then the components will have a version - suffix. The <makevar>HAVE_WX</makevar> variable will be + suffix. The <varname>HAVE_WX</varname> variable will be filled after detection.</para> - <example id="wx-ver-det-example"> + <example xml:id="wx-ver-det-example"> <title>Detecting Installed <application>wxWidgets</application> Versions and Components</title> @@ -8765,7 +8697,7 @@ CONFIGURE_ARGS+= --enable-wxpython </example> </sect2> - <sect2 id="wx-defined-variables"> + <sect2 xml:id="wx-defined-variables"> <title>Defined Variables</title> <para>The following variables are available in the port (after @@ -8786,7 +8718,7 @@ CONFIGURE_ARGS+= --enable-wxpython <tbody> <row> - <entry><makevar>WX_CONFIG</makevar></entry> + <entry><varname>WX_CONFIG</varname></entry> <entry>The path to the <application>wxWidgets</application> <command>wx-config</command> script (with different @@ -8794,7 +8726,7 @@ CONFIGURE_ARGS+= --enable-wxpython </row> <row> - <entry><makevar>WXRC_CMD</makevar></entry> + <entry><varname>WXRC_CMD</varname></entry> <entry>The path to the <application>wxWidgets</application> <command>wxrc</command> program (with different @@ -8802,14 +8734,14 @@ CONFIGURE_ARGS+= --enable-wxpython </row> <row> - <entry><makevar>WX_VERSION</makevar></entry> + <entry><varname>WX_VERSION</varname></entry> <entry>The <application>wxWidgets</application> version that is going to be used (e.g., <literal>2.6</literal>)</entry> </row> <row> - <entry><makevar>WX_UNICODE</makevar></entry> + <entry><varname>WX_UNICODE</varname></entry> <entry>If not defined but Unicode is going to be used then it will be defined</entry> </row> @@ -8818,16 +8750,16 @@ CONFIGURE_ARGS+= --enable-wxpython </table> </sect2> - <sect2 id="wx-premk"> + <sect2 xml:id="wx-premk"> <title>Processing in <filename>bsd.port.pre.mk</filename></title> <para>If you need to use the variables for running commands right after including <filename>bsd.port.pre.mk</filename> - you need to define <makevar>WX_PREMK</makevar>.</para> + you need to define <varname>WX_PREMK</varname>.</para> <important> - <para>If you define <makevar>WX_PREMK</makevar>, then the + <para>If you define <varname>WX_PREMK</varname>, then the version, dependencies, components and defined variables will not change if you modify the <application>wxWidgets</application> port variables @@ -8835,12 +8767,12 @@ CONFIGURE_ARGS+= --enable-wxpython <filename>bsd.port.pre.mk</filename>.</para> </important> - <example id="wx-premk-example"> + <example xml:id="wx-premk-example"> <title>Using <application>wxWidgets</application> Variables in Commands</title> <para>The following fragment illustrates the use of - <makevar>WX_PREMK</makevar> by running the + <varname>WX_PREMK</varname> by running the <command>wx-config</command> script to obtain the full version string, assign it to a variable and pass it to the program.</para> @@ -8860,11 +8792,11 @@ PLIST_SUB+= VERSION="${VER_STR}" <note> <para>The <application>wxWidgets</application> variables can be safely used in commands when they are inside targets - without the need of <makevar>WX_PREMK</makevar>.</para> + without the need of <varname>WX_PREMK</varname>.</para> </note> </sect2> - <sect2 id="wx-additional-config-args"> + <sect2 xml:id="wx-additional-config-args"> <title>Additional <command>configure</command> Arguments</title> @@ -8872,12 +8804,12 @@ PLIST_SUB+= VERSION="${VER_STR}" find <application>wxWidgets</application> with just the <literal>WX_CONFIG</literal> environment variable set, requiring additional arguments. The - <makevar>WX_CONF_ARGS</makevar> variable can be used for + <varname>WX_CONF_ARGS</varname> variable can be used for provide them.</para> <table frame="none"> <title>Legal Values for - <makevar>WX_CONF_ARGS</makevar></title> + <varname>WX_CONF_ARGS</varname></title> <tgroup cols="2"> <thead> @@ -8904,14 +8836,14 @@ PLIST_SUB+= VERSION="${VER_STR}" </sect2> </sect1> - <sect1 id="using-lua"> + <sect1 xml:id="using-lua"> <title>Using <application>Lua</application></title> <para>This section describes the status of the <application>Lua</application> libraries in the ports tree and its integration with the ports system.</para> - <sect2 id="lua-introduction"> + <sect2 xml:id="lua-introduction"> <title>Introduction</title> <para>There are many versions of the @@ -8927,7 +8859,7 @@ PLIST_SUB+= VERSION="${VER_STR}" compiler and linker.</para> </sect2> - <sect2 id="lua-version"> + <sect2 xml:id="lua-version"> <title>Version Selection</title> <para>To make your port use a specific version of @@ -8935,7 +8867,7 @@ PLIST_SUB+= VERSION="${VER_STR}" available for defining (if only one is defined the other will be set to a default value):</para> - <table id="lua-ver-sel-table" frame="none"> + <table xml:id="lua-ver-sel-table" frame="none"> <title>Variables to Select <application>Lua</application> Versions</title> @@ -8950,13 +8882,13 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> - <entry><makevar>USE_LUA</makevar></entry> + <entry><varname>USE_LUA</varname></entry> <entry>List of versions the port can use</entry> <entry>All available versions</entry> </row> <row> - <entry><makevar>USE_LUA_NOT</makevar></entry> + <entry><varname>USE_LUA_NOT</varname></entry> <entry>List of versions the port can not use</entry> <entry>None</entry> </row> @@ -8983,20 +8915,17 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> <entry><literal>4.0</literal></entry> - <entry><filename - role="package">lang/lua4</filename></entry> + <entry><package>lang/lua4</package></entry> </row> <row> <entry><literal>5.0</literal></entry> - <entry><filename - role="package">lang/lua50</filename></entry> + <entry><package>lang/lua50</package></entry> </row> <row> <entry><literal>5.1</literal></entry> - <entry><filename - role="package">lang/lua</filename></entry> + <entry><package>lang/lua</package></entry> </row> </tbody> </tgroup> @@ -9061,19 +8990,19 @@ PLIST_SUB+= VERSION="${VER_STR}" <tbody> <row> - <entry><makevar>WANT_LUA_VER</makevar></entry> + <entry><varname>WANT_LUA_VER</varname></entry> <entry>the port</entry> </row> <row> - <entry><makevar>WITH_LUA_VER</makevar></entry> + <entry><varname>WITH_LUA_VER</varname></entry> <entry>the user</entry> </row> </tbody> </tgroup> </table> - <example id="lua-version-example"> + <example xml:id="lua-version-example"> <title>Selecting the <application>Lua</application> Version</title> @@ -9081,20 +9010,20 @@ PLIST_SUB+= VERSION="${VER_STR}" <application>Lua</application> version <literal>5.0</literal> or <literal>5.1</literal>, and uses <literal>5.0</literal> by default. It can be overridden - by the user with <makevar>WITH_LUA_VER</makevar>.</para> + by the user with <varname>WITH_LUA_VER</varname>.</para> <programlisting>USE_LUA= 5.0-5.1 WANT_LUA_VER= 5.0</programlisting> </example> </sect2> - <sect2 id="lua-components"> + <sect2 xml:id="lua-components"> <title>Component Selection</title> <para>There are other applications that, while not being <application>Lua</application> libraries, are related to them. These applications can be specified in the - <makevar>LUA_COMPS</makevar> variable. The following + <varname>LUA_COMPS</varname> variable. The following components are available:</para> <table frame="none"> @@ -9160,19 +9089,19 @@ WANT_LUA_VER= 5.0</programlisting> <row> <entry><literal>build</literal></entry> <entry>Component is required for building, equivalent - to <makevar>BUILD_DEPENDS</makevar></entry> + to <varname>BUILD_DEPENDS</varname></entry> </row> <row> <entry><literal>run</literal></entry> <entry>Component is required for running, equivalent - to <makevar>RUN_DEPENDS</makevar></entry> + to <varname>RUN_DEPENDS</varname></entry> </row> <row> <entry><literal>lib</literal></entry> <entry>Component is required for building and running, - equivalent to <makevar>LIB_DEPENDS</makevar></entry> + equivalent to <varname>LIB_DEPENDS</varname></entry> </row> </tbody> </tgroup> @@ -9181,7 +9110,7 @@ WANT_LUA_VER= 5.0</programlisting> <para>The default values for the components are detailed in the following table:</para> - <table id="lua-def-dep-types" frame="none"> + <table xml:id="lua-def-dep-types" frame="none"> <title>Default <application>Lua</application> Dependency Types</title> @@ -9215,7 +9144,7 @@ WANT_LUA_VER= 5.0</programlisting> </tgroup> </table> - <example id="lua-components-example"> + <example xml:id="lua-components-example"> <title>Selecting <application>Lua</application> Components</title> @@ -9229,16 +9158,16 @@ LUA_COMPS= lua ruby</programlisting> </example> </sect2> - <sect2 id="lua-version-detection"> + <sect2 xml:id="lua-version-detection"> <title>Detecting Installed Versions</title> <para>To detect an installed version you have to define - <makevar>WANT_LUA</makevar>. If you do not set it to a + <varname>WANT_LUA</varname>. If you do not set it to a specific version then the components will have a version - suffix. The <makevar>HAVE_LUA</makevar> variable will be + suffix. The <varname>HAVE_LUA</varname> variable will be filled after detection.</para> - <example id="lua-ver-det-example"> + <example xml:id="lua-ver-det-example"> <title>Detecting Installed <application>Lua</application> Versions and Components</title> @@ -9274,7 +9203,7 @@ CONFIGURE_ARGS+= --enable-tolua </example> </sect2> - <sect2 id="lua-defined-variables"> + <sect2 xml:id="lua-defined-variables"> <title>Defined Variables</title> <para>The following variables are available in the port (after @@ -9295,34 +9224,34 @@ CONFIGURE_ARGS+= --enable-tolua <tbody> <row> - <entry><makevar>LUA_VER</makevar></entry> + <entry><varname>LUA_VER</varname></entry> <entry>The <application>Lua</application> version that is going to be used (e.g., <literal>5.1</literal>)</entry> </row> <row> - <entry><makevar>LUA_VER_SH</makevar></entry> + <entry><varname>LUA_VER_SH</varname></entry> <entry>The <application>Lua</application> shared library major version (e.g., <literal>1</literal>)</entry> </row> <row> - <entry><makevar>LUA_VER_STR</makevar></entry> + <entry><varname>LUA_VER_STR</varname></entry> <entry>The <application>Lua</application> version without the dots (e.g., <literal>51</literal>)</entry> </row> <row> - <entry><makevar>LUA_PREFIX</makevar></entry> + <entry><varname>LUA_PREFIX</varname></entry> <entry>The prefix where <application>Lua</application> (and components) is installed</entry> </row> <row> - <entry><makevar>LUA_SUBDIR</makevar></entry> + <entry><varname>LUA_SUBDIR</varname></entry> <entry>The directory under <filename>${PREFIX}/bin</filename>, <filename>${PREFIX}/share</filename> and @@ -9331,7 +9260,7 @@ CONFIGURE_ARGS+= --enable-tolua </row> <row> - <entry><makevar>LUA_INCDIR</makevar></entry> + <entry><varname>LUA_INCDIR</varname></entry> <entry>The directory where <application>Lua</application> and <application>tolua</application> header files are @@ -9339,7 +9268,7 @@ CONFIGURE_ARGS+= --enable-tolua </row> <row> - <entry><makevar>LUA_LIBDIR</makevar></entry> + <entry><varname>LUA_LIBDIR</varname></entry> <entry>The directory where <application>Lua</application> and <application>tolua</application> libraries are @@ -9347,39 +9276,39 @@ CONFIGURE_ARGS+= --enable-tolua </row> <row> - <entry><makevar>LUA_MODLIBDIR</makevar></entry> + <entry><varname>LUA_MODLIBDIR</varname></entry> <entry>The directory where <application>Lua</application> module libraries (<filename>.so</filename>) are installed</entry> </row> <row> - <entry><makevar>LUA_MODSHAREDIR</makevar></entry> + <entry><varname>LUA_MODSHAREDIR</varname></entry> <entry>The directory where <application>Lua</application> modules (<filename>.lua</filename>) are installed</entry> </row> <row> - <entry><makevar>LUA_PKGNAMEPREFIX</makevar></entry> + <entry><varname>LUA_PKGNAMEPREFIX</varname></entry> <entry>The package name prefix used by <application>Lua</application> modules</entry> </row> <row> - <entry><makevar>LUA_CMD</makevar></entry> + <entry><varname>LUA_CMD</varname></entry> <entry>The path to the <application>Lua</application> interpreter</entry> </row> <row> - <entry><makevar>LUAC_CMD</makevar></entry> + <entry><varname>LUAC_CMD</varname></entry> <entry>The path to the <application>Lua</application> compiler</entry> </row> <row> - <entry><makevar>TOLUA_CMD</makevar></entry> + <entry><varname>TOLUA_CMD</varname></entry> <entry>The path to the <application>tolua</application> program</entry> </row> @@ -9387,7 +9316,7 @@ CONFIGURE_ARGS+= --enable-tolua </tgroup> </table> - <example id="lua-variables-example"> + <example xml:id="lua-variables-example"> <title>Telling the Port Where to Find <application>Lua</application></title> @@ -9402,16 +9331,16 @@ CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"</programlist </example> </sect2> - <sect2 id="lua-premk"> + <sect2 xml:id="lua-premk"> <title>Processing in <filename>bsd.port.pre.mk</filename></title> <para>If you need to use the variables for running commands right after including <filename>bsd.port.pre.mk</filename> - you need to define <makevar>LUA_PREMK</makevar>.</para> + you need to define <varname>LUA_PREMK</varname>.</para> <important> - <para>If you define <makevar>LUA_PREMK</makevar>, then the + <para>If you define <varname>LUA_PREMK</varname>, then the version, dependencies, components and defined variables will not change if you modify the <application>Lua</application> port variables @@ -9419,12 +9348,12 @@ CONFIGURE_ENV= CPPFLAGS="-I${LUA_INCDIR}" LDFLAGS="-L${LUA_LIBDIR}"</programlist <filename>bsd.port.pre.mk</filename>.</para> </important> - <example id="lua-premk-example"> + <example xml:id="lua-premk-example"> <title>Using <application>Lua</application> Variables in Commands</title> <para>The following fragment illustrates the use of - <makevar>LUA_PREMK</makevar> by running the + <varname>LUA_PREMK</varname> by running the <application>Lua</application> interpreter to obtain the full version string, assign it to a variable and pass it to the program.</para> @@ -9444,27 +9373,27 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" <note> <para>The <application>Lua</application> variables can be safely used in commands when they are inside targets - without the need of <makevar>LUA_PREMK</makevar>.</para> + without the need of <varname>LUA_PREMK</varname>.</para> </note> </sect2> </sect1> - <sect1 id="using-iconv"> + <sect1 xml:id="using-iconv"> <title>Using <command>iconv</command></title> - <para>After 2013-10-08 (<svnref>254273</svnref>), &os; + <para>After 2013-10-08 (<revnumber>254273</revnumber>), &os; 10-CURRENT and newer versions have a native <command>iconv</command> in the operating system. On earlier versions, - <filename role="package">converters/libiconv</filename> was + <package>converters/libiconv</package> was used as a dependency.</para> <para>For software that needs <command>iconv</command>, define <literal>USES=iconv</literal>. &os; versions before - 10-CURRENT on 2013-08-13 (<svnref>254273</svnref>) do not have + 10-CURRENT on 2013-08-13 (<revnumber>254273</revnumber>) do not have a native <command>iconv</command>. On these earlier versions, a dependency on - <filename role="package">converters/libiconv</filename> will + <package>converters/libiconv</package> will be added automatically.</para> <para>When a port defines <literal>USES=iconv</literal>, these @@ -9477,25 +9406,24 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" <entry>Variable name</entry> <entry>Purpose</entry> <entry>Value before &os; 10-CURRENT - <svnref>254273</svnref> (2013-08-13)</entry> + <revnumber>254273</revnumber> (2013-08-13)</entry> <entry>Value after &os; 10-CURRENT - <svnref>254273</svnref> (2013-08-13)</entry> + <revnumber>254273</revnumber> (2013-08-13)</entry> </row> </thead> <tbody> <row> - <entry><makevar>ICONV_CMD</makevar></entry> + <entry><varname>ICONV_CMD</varname></entry> <entry>Directory where the <command>iconv</command> binary resides</entry> <entry><literal>${LOCALBASE}/bin/iconv</literal></entry> - <entry><filename - class="directory">/usr/bin/iconv</filename></entry> + <entry><filename>/usr/bin/iconv</filename></entry> </row> <row> - <entry><makevar>ICONV_LIB</makevar></entry> + <entry><varname>ICONV_LIB</varname></entry> <entry><command>ld</command> argument to link to <filename>libiconv</filename> (if needed)</entry> <entry><literal>-liconv</literal></entry> @@ -9503,17 +9431,16 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" </row> <row> - <entry><makevar>ICONV_PREFIX</makevar></entry> + <entry><varname>ICONV_PREFIX</varname></entry> <entry>Directory where the <command>iconv</command> implementation resides (useful for configure scripts)</entry> <entry><literal>${LOCALBASE}</literal></entry> - <entry><filename - class="directory">/usr</filename></entry> + <entry><filename>/usr</filename></entry> </row> <row> - <entry><makevar>ICONV_CONFIGURE_ARG</makevar></entry> + <entry><varname>ICONV_CONFIGURE_ARG</varname></entry> <entry>Preconstructed configure argument for configure scripts</entry> <entry><literal>--with-libiconv-prefix=${LOCALBASE}</literal></entry> @@ -9521,7 +9448,7 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" </row> <row> - <entry><makevar>ICONV_CONFIGURE_BASE</makevar></entry> + <entry><varname>ICONV_CONFIGURE_BASE</varname></entry> <entry>Preconstructed configure argument for configure scripts</entry> <entry><literal>--with-libiconv=${LOCALBASE}</literal></entry> @@ -9533,17 +9460,17 @@ CFLAGS+= -DLUA_VERSION_STRING="${VER_STR}" <para>These two examples automatically populate the variables with the correct value for systems using - <filename role="package">converters/libiconv</filename> or the + <package>converters/libiconv</package> or the native <command>iconv</command> respectively:</para> - <example id="iconv-simple-use"> + <example xml:id="iconv-simple-use"> <title>Simple <command>iconv</command> Usage</title> <programlisting>USES= iconv LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}</programlisting> </example> - <example id="iconv-configure-use"> + <example xml:id="iconv-configure-use"> <title><command>iconv</command> Usage with <command>configure</command></title> @@ -9551,7 +9478,7 @@ LDFLAGS+= -L${LOCALBASE}/lib ${ICONV_LIB}</programlisting> CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting> </example> - <para>As shown above, <makevar>ICONV_LIB</makevar> is empty when + <para>As shown above, <varname>ICONV_LIB</varname> is empty when a native <command>iconv</command> is present. This can be used to detect the native <command>iconv</command> and respond appropriately.</para> @@ -9561,7 +9488,7 @@ CONFIGURE_ARGS+=${ICONV_CONFIGURE_ARG}</programlisting> configure script. This approach can be used to solve that problem:</para> - <example id="iconv-reinplace"> + <example xml:id="iconv-reinplace"> <title>Fixing Hardcoded <literal>-liconv</literal></title> <programlisting>USES= iconv @@ -9574,9 +9501,9 @@ post-patch: perform operations depending on whether there is a native <command>iconv</command>. <filename>bsd.port.pre.mk</filename> must be included before - testing the value of <makevar>ICONV_LIB</makevar>:</para> + testing the value of <varname>ICONV_LIB</varname>:</para> - <example id="iconv-conditional"> + <example xml:id="iconv-conditional"> <title>Checking for Native <command>iconv</command> Availability</title> @@ -9594,63 +9521,53 @@ post-patch: </example> </sect1> - <sect1 id="using-xfce"> + <sect1 xml:id="using-xfce"> <title>Using Xfce</title> - <para>The <makevar>USE_XFCE</makevar> variable is used to + <para>The <varname>USE_XFCE</varname> variable is used to autoconfigure the dependencies for ports which use an Xfce based library or application like - <filename role="package">x11-toolkits/libxfce4gui</filename> - and <filename - role="package">x11-wm/xfce4-panel</filename>.</para> + <package>x11-toolkits/libxfce4gui</package> + and <package>x11-wm/xfce4-panel</package>.</para> <para>The following Xfce libraries and applications are recognized at the moment:</para> <itemizedlist> <listitem> - <para>libexo: <filename - role="package">x11/libexo</filename></para> + <para>libexo: <package>x11/libexo</package></para> </listitem> <listitem> - <para>libgui: <filename - role="package">x11-toolkits/libxfce4gui</filename></para> + <para>libgui: <package>x11-toolkits/libxfce4gui</package></para> </listitem> <listitem> - <para>libutil: <filename - role="package">x11/libxfce4util</filename></para> + <para>libutil: <package>x11/libxfce4util</package></para> </listitem> <listitem> - <para>libmcs: <filename - role="package">x11/libxfce4mcs</filename></para> + <para>libmcs: <package>x11/libxfce4mcs</package></para> </listitem> <listitem> - <para>mcsmanager: <filename - role="package">sysutils/xfce4-mcs-manager</filename></para> + <para>mcsmanager: <package>sysutils/xfce4-mcs-manager</package></para> </listitem> <listitem> - <para>panel: <filename - role="package">x11-wm/xfce4-panel</filename></para> + <para>panel: <package>x11-wm/xfce4-panel</package></para> </listitem> <listitem> - <para>thunar: <filename - role="package">x11-fm/thunar</filename></para> + <para>thunar: <package>x11-fm/thunar</package></para> </listitem> <listitem> - <para>wm: <filename - role="package">x11-wm/xfce4-wm</filename></para> + <para>wm: <package>x11-wm/xfce4-wm</package></para> </listitem> <listitem> - <para>xfdev: <filename - role="package">dev/xfce4-dev-tools</filename></para> + <para>xfdev: <package>dev/xfce4-dev-tools</package></para> </listitem> </itemizedlist> @@ -9659,25 +9576,25 @@ post-patch: <itemizedlist> <listitem> <para>configenv: Use this if your port requires a special - modified <makevar>CONFIGURE_ENV</makevar> to find its + modified <varname>CONFIGURE_ENV</varname> to find its required libraries.</para> <programlisting>-I${LOCALBASE}/include -L${LOCALBASE}/lib</programlisting> <para>gets added to CPPFLAGS to - <makevar>CONFIGURE_ENV</makevar>.</para> + <varname>CONFIGURE_ENV</varname>.</para> </listitem> </itemizedlist> <para>Therefore, if a port has a dependency on - <filename role="package">sysutils/xfce4-mcs-manager</filename> + <package>sysutils/xfce4-mcs-manager</package> and requires the special CPPFLAGS in its configure environment, the syntax will be:</para> <programlisting>USE_XFCE= mcsmanager configenv</programlisting> </sect1> - <sect1 id="using-mozilla"> + <sect1 xml:id="using-mozilla"> <title>Using Mozilla</title> <table frame="none"> @@ -9687,7 +9604,7 @@ post-patch: <tbody> <row> - <entry><makevar>USE_GECKO</makevar></entry> + <entry><varname>USE_GECKO</varname></entry> <entry>Gecko backend the port can handle. Possible values: <literal>libxul</literal> (<filename>libxul.so</filename>), @@ -9697,7 +9614,7 @@ post-patch: </row> <row> - <entry><makevar>USE_FIREFOX</makevar></entry> + <entry><varname>USE_FIREFOX</varname></entry> <entry>The port requires Firefox as a runtime dependency. Possible values: <literal>yes</literal> (get default version), <literal>40</literal>, @@ -9707,7 +9624,7 @@ post-patch: </row> <row> - <entry><makevar>USE_FIREFOX_BUILD</makevar></entry> + <entry><varname>USE_FIREFOX_BUILD</varname></entry> <entry>The port requires Firefox as a buildtime dependency. Possible values: see USE_FIREFOX. This automatically sets USE_FIREFOX and assigns the same @@ -9715,7 +9632,7 @@ post-patch: </row> <row> - <entry><makevar>USE_SEAMONKEY</makevar></entry> + <entry><varname>USE_SEAMONKEY</varname></entry> <entry>The port requires SeaMonkey as a runtime dependency. Possible values: <literal>yes</literal> (get default version), <literal>20</literal>, @@ -9725,7 +9642,7 @@ post-patch: </row> <row> - <entry><makevar>USE_SEAMONKEY_BUILD</makevar></entry> + <entry><varname>USE_SEAMONKEY_BUILD</varname></entry> <entry>The port requires SeaMonkey as a buildtime dependency. Possible values: see USE_SEAMONKEY. This automatically sets USE_SEAMONKEY and assigns the same @@ -9733,7 +9650,7 @@ post-patch: </row> <row> - <entry><makevar>USE_THUNDERBIRD</makevar></entry> + <entry><varname>USE_THUNDERBIRD</varname></entry> <entry>The port requires Thunderbird as a runtime dependency. Possible values: <literal>yes</literal> (get default version), <literal>31</literal>, @@ -9743,7 +9660,7 @@ post-patch: </row> <row> - <entry><makevar>USE_THUNDERBIRD_BUILD</makevar></entry> + <entry><varname>USE_THUNDERBIRD_BUILD</varname></entry> <entry>The port requires Thunderbird as a buildtime dependency. Possible values: see USE_THUNDERBIRD. This automatically sets USE_THUNDERBIRD and assigns @@ -9757,7 +9674,7 @@ post-patch: <filename>/usr/ports/Mk/bsd.gecko.mk</filename>.</para> </sect1> - <sect1 id="using-databases"> + <sect1 xml:id="using-databases"> <title>Using Databases</title> <table frame="none"> @@ -9773,48 +9690,46 @@ post-patch: <tbody> <row> - <entry><makevar>USE_BDB</makevar></entry> + <entry><varname>USE_BDB</varname></entry> <entry>If variable is set to <literal>yes</literal>, add dependency on - <filename role="package">databases/db41</filename> + <package>databases/db41</package> port. The variable may also be set to values: 40, 41, 42, 43, 44, 46, 47, 48, or 51. You can declare a range of acceptable values, - <makevar>USE_BDB</makevar>=42+ will find the highest + <varname>USE_BDB</varname>=42+ will find the highest installed version, and fall back to 42 if nothing else is installed.</entry> </row> <row> - <entry><makevar>USE_MYSQL</makevar></entry> + <entry><varname>USE_MYSQL</varname></entry> <entry>If variable is set to <literal>yes</literal>, add - dependency on <filename - role="package">databases/mysql55-client</filename> + dependency on <package>databases/mysql55-client</package> port. An associated variable, - <makevar>WANT_MYSQL_VER</makevar>, may be set to + <varname>WANT_MYSQL_VER</varname>, may be set to values such as 323, 40, 41, 50, 51, 52, 55, or 60.</entry> </row> <row> - <entry><makevar>USE_PGSQL</makevar></entry> + <entry><varname>USE_PGSQL</varname></entry> <entry>If set to <literal>yes</literal>, add dependency - on <filename - role="package">databases/postgresql90-client</filename> + on <package>databases/postgresql90-client</package> port. An associated variable, - <makevar>WANT_PGSQL_VER</makevar>, may be set to + <varname>WANT_PGSQL_VER</varname>, may be set to values such as 83, 84, 90, 91 or 92. You can declare a minimum or maximum value; - <makevar>WANT_PGSQL_VER</makevar>= + <varname>WANT_PGSQL_VER</varname>= <literal> 90+</literal> will cause the port to depend on a minimum version of 9.0.</entry> </row> <row> - <entry><makevar>USE_SQLITE</makevar></entry> + <entry><varname>USE_SQLITE</varname></entry> <entry>If variable is set to <literal>yes</literal>, add dependency on - <filename role="package">databases/sqlite3</filename> + <package>databases/sqlite3</package> port. The variable may also be set to values: 3, 2.</entry> </row> @@ -9822,11 +9737,10 @@ post-patch: </tgroup> </table> - <para>More details are available in <ulink - url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup">bsd.database.mk</ulink>.</para> + <para>More details are available in <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.database.mk?view=markup">bsd.database.mk</link>.</para> </sect1> - <sect1 id="rc-scripts"> + <sect1 xml:id="rc-scripts"> <title>Starting and Stopping Services (<literal>rc</literal> Scripts)</title> @@ -9834,12 +9748,11 @@ post-patch: services on system startup, and to give administrators a standard way of stopping, starting and restarting the service. Ports integrate into the system <filename>rc.d</filename> - framework. Details on its usage can be found in <ulink - url="&url.books.handbook;/configtuning-rcd.html">the rc.d - Handbook chapter</ulink>. Detailed explanation of available + framework. Details on its usage can be found in <link xlink:href="&url.books.handbook;/configtuning-rcd.html">the rc.d + Handbook chapter</link>. Detailed explanation of available commands is provided in &man.rc.8; and &man.rc.subr.8;. - Finally, there is <ulink url="&url.articles.rc-scripting;">an - article</ulink> on practical aspects of + Finally, there is <link xlink:href="&url.articles.rc-scripting;">an + article</link> on practical aspects of <filename>rc.d</filename> scripting.</para> <para>One or more <filename>rc.d</filename> scripts can be @@ -9849,18 +9762,18 @@ post-patch: <para>Scripts must be placed in the <filename>files</filename> subdirectory and a <literal>.in</literal> suffix must be added - to their filename. Standard <makevar>SUB_LIST</makevar> + to their filename. Standard <varname>SUB_LIST</varname> expansions will be used for this file. Use of the <literal>%%PREFIX%%</literal> and <literal>%%LOCALBASE%%</literal> expansions is strongly - encouraged as well. More on <makevar>SUB_LIST</makevar> in + encouraged as well. More on <varname>SUB_LIST</varname> in <link linkend="using-sub-files">the relevant section</link>.</para> <para>Prior to &os; 6.1-RELEASE, integration with &man.rcorder.8; is available by using - <makevar>USE_RCORDER</makevar> instead of - <makevar>USE_RC_SUBR</makevar>. However, use of this method + <varname>USE_RCORDER</varname> instead of + <varname>USE_RC_SUBR</varname>. However, use of this method is not necessary unless the port has an option to install itself in the base, or the service needs to run prior to the <filename>FILESYSTEMS</filename> <filename>rc.d</filename> @@ -10015,7 +9928,7 @@ run_rc_command "$1"</programlisting> <varname>command_interpreter</varname> is set appropriately. Otherwise,</para> - <screen>&prompt.root; <userinput>service <replaceable>name</replaceable> stop</userinput></screen> + <screen>&prompt.root; <userinput>service name stop</userinput></screen> <para>will probably not work properly. See &man.service.8; for more information.</para> @@ -10098,7 +10011,7 @@ run_rc_command "$1"</programlisting> </sect2> </sect1> - <sect1 id="users-and-groups"> + <sect1 xml:id="users-and-groups"> <title>Adding Users and Groups</title> <para>Some ports require a certain user to be on the installed @@ -10112,8 +10025,8 @@ run_rc_command "$1"</programlisting> require a new user or group to be created for your port.</para> - <para>Then you can use <makevar>USERS</makevar> and - <makevar>GROUPS</makevar> variables in your + <para>Then you can use <varname>USERS</varname> and + <varname>GROUPS</varname> variables in your <filename>Makefile</filename>, and the user will be automatically created when installing the port.</para> @@ -10125,7 +10038,7 @@ GROUPS= pulse pulse-access pulse-rt</programlisting> <filename>ports/GIDs</filename>.</para> </sect1> - <sect1 id="requiring-kernel-sources"> + <sect1 xml:id="requiring-kernel-sources"> <title>Ports That Rely on Kernel Sources</title> <para>Some ports (such as kernel loadable modules) need the @@ -10139,10 +10052,10 @@ IGNORE= requires kernel sources to be installed </sect1> </chapter> - <chapter id="plist"> + <chapter xml:id="plist"> <title>Advanced <filename>pkg-plist</filename> Practices</title> - <sect1 id="plist-sub"> + <sect1 xml:id="plist-sub"> <title>Changing <filename>pkg-plist</filename> Based on Make Variables</title> @@ -10160,16 +10073,16 @@ IGNORE= requires kernel sources to be installed and <literal>%%PERL_VER%%</literal> is the full version number of <command>perl</command> (e.g., <literal>5.8.9</literal>). Several other - <literal>%%<replaceable>VARS</replaceable>%%</literal> related + <literal>%%VARS%%</literal> related to port's documentation files are described in <link linkend="install-documentation">the relevant section</link>.</para> <para>If you need to make other substitutions, you can set the - <makevar>PLIST_SUB</makevar> variable with a list of - <literal><replaceable>VAR</replaceable>=<replaceable>VALUE</replaceable></literal> + <varname>PLIST_SUB</varname> variable with a list of + <literal>VAR=VALUE</literal> pairs and instances of - <literal>%%<replaceable>VAR</replaceable>%%</literal> will be + <literal>%%VAR%%</literal> will be substituted with <replaceable>VALUE</replaceable> in the <filename>pkg-plist</filename>.</para> @@ -10191,7 +10104,7 @@ PLIST_SUB= OCTAVE_VERSION=${OCTAVE_VERSION}</programlisting> set in the port, the usual way of handling it is prefixing the <filename>pkg-plist</filename> lines with a <literal>%%TAG%%</literal> and adding that - <literal>TAG</literal> to the <makevar>PLIST_SUB</makevar> + <literal>TAG</literal> to the <varname>PLIST_SUB</varname> variable inside the <filename>Makefile</filename> with a special value of <literal>@comment</literal>, which makes package tools to ignore the line:</para> @@ -10208,47 +10121,47 @@ PLIST_SUB+= X11="@comment " <para>This substitution will be - done between the <maketarget>pre-install</maketarget> and - <maketarget>do-install</maketarget> targets, by reading from - <filename><makevar>PLIST</makevar></filename> and writing to - <filename><makevar>TMPPLIST</makevar></filename> (default: - <filename><makevar>WRKDIR</makevar>/.PLIST.mktmp</filename>). + done between the <buildtarget>pre-install</buildtarget> and + <buildtarget>do-install</buildtarget> targets, by reading from + <filename>PLIST</filename> and writing to + <filename>TMPPLIST</filename> (default: + <filename>WRKDIR/.PLIST.mktmp</filename>). So if your port builds - <filename><makevar>PLIST</makevar></filename> on the fly, do - so in or before <maketarget>pre-install</maketarget>. Also, + <filename>PLIST</filename> on the fly, do + so in or before <buildtarget>pre-install</buildtarget>. Also, if your port needs to edit the resulting file, do so in - <maketarget>post-install</maketarget> to a file named - <filename><makevar>TMPPLIST</makevar></filename>.</para> + <buildtarget>post-install</buildtarget> to a file named + <filename>TMPPLIST</filename>.</para> <para>Another way of modifying a port's packing list is based - on setting the variables <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar>. The value of each variable + on setting the variables <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname>. The value of each variable is regarded as a list of pathnames to write to - <filename><makevar>TMPPLIST</makevar></filename> along with - <filename><makevar>PLIST</makevar></filename> contents. Names - listed in <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar> are subject to - <literal>%%<replaceable>VAR</replaceable>%%</literal> + <filename>TMPPLIST</filename> along with + <filename>PLIST</filename> contents. Names + listed in <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname> are subject to + <literal>%%VAR%%</literal> substitution as described above. Except for that, names from - <makevar>PLIST_FILES</makevar> will appear in the final + <varname>PLIST_FILES</varname> will appear in the final packing list unchanged, while <literal>@dirrm</literal> and <literal>@dirrmtry</literal> will - be prepended to names from <makevar>PLIST_DIRS</makevar> - and <makevar>PLIST_DIRSTRY</makevar>, respectively. To - take effect, <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar> must be set before - <filename><makevar>TMPPLIST</makevar></filename> is written, - i.e., in <maketarget>pre-install</maketarget> or + be prepended to names from <varname>PLIST_DIRS</varname> + and <varname>PLIST_DIRSTRY</varname>, respectively. To + take effect, <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname> must be set before + <filename>TMPPLIST</filename> is written, + i.e., in <buildtarget>pre-install</buildtarget> or earlier.</para> </sect1> - <sect1 id="plist-cleaning"> + <sect1 xml:id="plist-cleaning"> <title>Empty Directories</title> - <sect2 id="plist-dir-cleaning"> + <sect2 xml:id="plist-dir-cleaning"> <title>Cleaning Up Empty Directories</title> <para>Do make your ports remove empty directories when they @@ -10275,12 +10188,12 @@ lib/X11/oneko/sounds/cat.au <para>This will neither print any error messages nor cause &man.pkg.delete.1; to exit abnormally even if - <filename><makevar>${PREFIX}</makevar>/share/doc/gimp</filename> + <filename>${PREFIX}/share/doc/gimp</filename> is not empty due to other ports installing some files in there.</para> </sect2> - <sect2 id="plist-dir-empty"> + <sect2 xml:id="plist-dir-empty"> <title>Creating Empty Directories</title> <para>Empty directories created during port installation need @@ -10296,18 +10209,18 @@ lib/X11/oneko/sounds/cat.au </sect2> </sect1> - <sect1 id="plist-config"> + <sect1 xml:id="plist-config"> <title>Configuration Files</title> <para>If your port installs configuration files to - <filename><makevar>PREFIX</makevar>/etc</filename> (or + <filename>PREFIX/etc</filename> (or elsewhere) do <emphasis>not</emphasis> simply list them in the <filename>pkg-plist</filename>. That will cause &man.pkg.delete.1; to remove the files carefully edited by the user, and a re-installation will wipe them out.</para> <para>Instead, install sample file(s) with a - <filename><replaceable>filename</replaceable>.sample</filename> + <filename>filename.sample</filename> suffix. Then copy the sample file to the real configuration file name, if it does not already exist. On deinstall delete the configuration file, but only if it is identical @@ -10359,7 +10272,7 @@ etc/orbit.conf.sample will work.</para> </sect1> - <sect1 id="plist-dynamic"> + <sect1 xml:id="plist-dynamic"> <title>Dynamic Versus Static Package List</title> <para>A <emphasis>static package list</emphasis> is a package @@ -10367,9 +10280,9 @@ etc/orbit.conf.sample <filename>pkg-plist</filename> file (with or without variable substitution), or embedded into the <filename>Makefile</filename> via - <makevar>PLIST_FILES</makevar>, - <makevar>PLIST_DIRS</makevar>, and - <makevar>PLIST_DIRSTRY</makevar>. Even if the contents are + <varname>PLIST_FILES</varname>, + <varname>PLIST_DIRS</varname>, and + <varname>PLIST_DIRSTRY</varname>. Even if the contents are auto-generated by a tool or a target in the Makefile <emphasis>before</emphasis> the inclusion into the Ports Collection by a committer, this is still considered a static @@ -10395,23 +10308,23 @@ etc/orbit.conf.sample which generate docs with <application>Javadoc</application>).</para> - <para>Note that the <maketarget>makeplist</maketarget> target can + <para>Note that the <buildtarget>makeplist</buildtarget> target can be used for ports that support staging to display the package list.</para> </sect1> - <sect1 id="plist-autoplist"> + <sect1 xml:id="plist-autoplist"> <title>Automated Package List Creation</title> <para>First, make sure your port is almost complete, with only <filename>pkg-plist</filename> missing. You may then run - <command>make <maketarget>makeplist</maketarget></command> to + <command>make makeplist</command> to generate a <filename>pkg-plist</filename> automatically. This file must be double checked for correctness.</para> <para>User configuration files should be removed, or installed as - <filename><replaceable>filename</replaceable>.sample</filename>. + <filename>filename.sample</filename>. The <filename>info/dir</filename> file should not be listed and appropriate <filename>install-info</filename> lines should be added as noted in the @@ -10441,22 +10354,22 @@ etc/orbit.conf.sample <para>Another tool that might be used to create an initial <filename>pkg-plist</filename> is - <filename role="package">ports-mgmt/genplist</filename>. As + <package>ports-mgmt/genplist</package>. As with any automated tool, the resulting <filename>pkg-plist</filename> should be checked and manually edited as needed.</para> </sect1> </chapter> - <chapter id="pkg-files"> - <title>The <filename>pkg-<replaceable>*</replaceable></filename> + <chapter xml:id="pkg-files"> + <title>The <filename>pkg-*</filename> Files</title> <para>There are some tricks we have not mentioned yet about the - <filename>pkg-<replaceable>*</replaceable></filename> files + <filename>pkg-*</filename> files that come in handy sometimes.</para> - <sect1 id="porting-message"> + <sect1 xml:id="porting-message"> <title><filename>pkg-message</filename></title> <para>If you need to display a message to the installer, you may @@ -10466,10 +10379,10 @@ etc/orbit.conf.sample licensing information.</para> <para>When some lines about the build-time knobs or warnings - have to be displayed, use <makevar>ECHO_MSG</makevar>. The + have to be displayed, use <varname>ECHO_MSG</varname>. The <filename>pkg-message</filename> file is only for post-installation steps. Likewise, the distinction between - <makevar>ECHO_MSG</makevar> and <makevar>ECHO_CMD</makevar> + <varname>ECHO_MSG</varname> and <varname>ECHO_CMD</varname> should be kept in mind. The former is for printing informational text to the screen, while the latter is for command pipelining:</para> @@ -10487,7 +10400,7 @@ etc/orbit.conf.sample </note> </sect1> - <sect1 id="pkg-install"> + <sect1 xml:id="pkg-install"> <title><filename>pkg-install</filename></title> <para>If your port needs to execute commands when the binary @@ -10515,7 +10428,7 @@ etc/orbit.conf.sample </note> </sect1> - <sect1 id="pkg-deinstall"> + <sect1 xml:id="pkg-deinstall"> <title><filename>pkg-deinstall</filename></title> <para>This script executes when a package is removed.</para> @@ -10527,27 +10440,27 @@ etc/orbit.conf.sample POST-DEINSTALL</literal>.</para> </sect1> - <sect1 id="pkg-names"> - <title id="porting-pkgfiles">Changing the Names of - <filename>pkg-<replaceable>*</replaceable></filename> + <sect1 xml:id="pkg-names"> + <title xml:id="porting-pkgfiles">Changing the Names of + <filename>pkg-*</filename> Files</title> <para>All the names of - <filename>pkg-<replaceable>*</replaceable></filename> files + <filename>pkg-*</filename> files are defined using variables so you can change them in your <filename>Makefile</filename> if need be. This is especially useful when you are sharing the same - <filename>pkg-<replaceable>*</replaceable></filename> files + <filename>pkg-*</filename> files among several ports or have to write to one of the above files (see <link linkend="porting-wrkdir">writing to places other - than <makevar>WRKDIR</makevar></link> for why it is a bad + than <varname>WRKDIR</varname></link> for why it is a bad idea to write directly into the - <filename>pkg-<replaceable>*</replaceable></filename> + <filename>pkg-*</filename> subdirectory).</para> <para>Here is a list of variable names and their default values. - (<makevar>PKGDIR</makevar> defaults to - <makevar>${MASTERDIR}</makevar>.)</para> + (<varname>PKGDIR</varname> defaults to + <varname>${MASTERDIR}</varname>.)</para> <informaltable frame="none" pgwide="0"> <tgroup cols="2"> @@ -10560,27 +10473,27 @@ etc/orbit.conf.sample <tbody> <row> - <entry><makevar>DESCR</makevar></entry> + <entry><varname>DESCR</varname></entry> <entry><literal>${PKGDIR}/pkg-descr</literal></entry> </row> <row> - <entry><makevar>PLIST</makevar></entry> + <entry><varname>PLIST</varname></entry> <entry><literal>${PKGDIR}/pkg-plist</literal></entry> </row> <row> - <entry><makevar>PKGINSTALL</makevar></entry> + <entry><varname>PKGINSTALL</varname></entry> <entry><literal>${PKGDIR}/pkg-install</literal></entry> </row> <row> - <entry><makevar>PKGDEINSTALL</makevar></entry> + <entry><varname>PKGDEINSTALL</varname></entry> <entry><literal>${PKGDIR}/pkg-deinstall</literal></entry> </row> <row> - <entry><makevar>PKGMESSAGE</makevar></entry> + <entry><varname>PKGMESSAGE</varname></entry> <entry><literal>${PKGDIR}/pkg-message</literal></entry> </row> </tbody> @@ -10588,32 +10501,32 @@ etc/orbit.conf.sample </informaltable> <para>Please change these variables rather than overriding - <makevar>PKG_ARGS</makevar>. If you change - <makevar>PKG_ARGS</makevar>, those files will not correctly be + <varname>PKG_ARGS</varname>. If you change + <varname>PKG_ARGS</varname>, those files will not correctly be installed in <filename>/var/db/pkg</filename> upon install from a port.</para> </sect1> - <sect1 id="using-sub-files"> - <title>Making Use of <makevar>SUB_FILES</makevar> and - <makevar>SUB_LIST</makevar></title> + <sect1 xml:id="using-sub-files"> + <title>Making Use of <varname>SUB_FILES</varname> and + <varname>SUB_LIST</varname></title> - <para>The <makevar>SUB_FILES</makevar> and - <makevar>SUB_LIST</makevar> variables are useful for dynamic + <para>The <varname>SUB_FILES</varname> and + <varname>SUB_LIST</varname> variables are useful for dynamic values in port files, such as the installation - <makevar>PREFIX</makevar> in + <varname>PREFIX</varname> in <filename>pkg-message</filename>.</para> - <para>The <makevar>SUB_FILES</makevar> variable specifies a list + <para>The <varname>SUB_FILES</varname> variable specifies a list of files to be automatically modified. Each <replaceable>file</replaceable> in the - <makevar>SUB_FILES</makevar> list must have a corresponding - <filename><replaceable>file</replaceable>.in</filename> - present in <makevar>FILESDIR</makevar>. A modified version - will be created in <makevar>WRKDIR</makevar>. Files defined - as a value of <makevar>USE_RC_SUBR</makevar> (or the - deprecated <makevar>USE_RCORDER</makevar>) are automatically - added to the <makevar>SUB_FILES</makevar>. For the files + <varname>SUB_FILES</varname> list must have a corresponding + <filename>file.in</filename> + present in <varname>FILESDIR</varname>. A modified version + will be created in <varname>WRKDIR</varname>. Files defined + as a value of <varname>USE_RC_SUBR</varname> (or the + deprecated <varname>USE_RCORDER</varname>) are automatically + added to the <varname>SUB_FILES</varname>. For the files <filename>pkg-message</filename>, <filename>pkg-install</filename>, and @@ -10622,15 +10535,15 @@ etc/orbit.conf.sample variable is automatically set to point to the processed version.</para> - <para>The <makevar>SUB_LIST</makevar> variable is a list of + <para>The <varname>SUB_LIST</varname> variable is a list of <literal>VAR=VALUE</literal> pairs. For each pair <literal>%%VAR%%</literal> will get replaced with <literal>VALUE</literal> in each file listed in - <makevar>SUB_FILES</makevar>. Several common pairs are - automatically defined: <makevar>PREFIX</makevar>, - <makevar>LOCALBASE</makevar>, <makevar>DATADIR</makevar>, - <makevar>DOCSDIR</makevar>, <makevar>EXAMPLESDIR</makevar>, - <makevar>WWWDIR</makevar>, and <makevar>ETCDIR</makevar>. + <varname>SUB_FILES</varname>. Several common pairs are + automatically defined: <varname>PREFIX</varname>, + <varname>LOCALBASE</varname>, <varname>DATADIR</varname>, + <varname>DOCSDIR</varname>, <varname>EXAMPLESDIR</varname>, + <varname>WWWDIR</varname>, and <varname>ETCDIR</varname>. Any line beginning with <literal>@comment</literal> will be deleted from resulting files after a variable substitution.</para> @@ -10644,7 +10557,7 @@ SUB_LIST= ARCH=${ARCH}</programlisting> <para>Note that for this example, the <filename>pkg-message.in</filename> file must exist in - <makevar>FILESDIR</makevar>.</para> + <varname>FILESDIR</varname>.</para> <para>Example of a good <filename>pkg-message.in</filename>:</para> @@ -10655,10 +10568,10 @@ as .putsy.conf and edit it.</programlisting> </sect1> </chapter> - <chapter id="testing"> + <chapter xml:id="testing"> <title>Testing Your Port</title> - <sect1 id="make-describe"> + <sect1 xml:id="make-describe"> <title>Running <command>make describe</command></title> <para>Several of the &os; port maintenance tools, such as @@ -10693,11 +10606,10 @@ as .putsy.conf and edit it.</programlisting> automatically.</para> </sect1> - <sect1 id="testing-portlint"> + <sect1 xml:id="testing-portlint"> <title>Portlint</title> - <para>Do check your work with <link - linkend="porting-portlint"><command>portlint</command></link> + <para>Do check your work with <link linkend="porting-portlint"><command>portlint</command></link> before you submit or commit it. <command>portlint</command> warns you about many common errors, both functional and stylistic. For a new (or repocopied) port, @@ -10713,19 +10625,18 @@ as .putsy.conf and edit it.</programlisting> doubt, the best thing to do is ask on &a.ports;.</para> </sect1> - <sect1 id="testing-porttools"> + <sect1 xml:id="testing-porttools"> <title>Port Tools</title> <para>The - <filename role="package">ports-mgmt/porttools</filename> + <package>ports-mgmt/porttools</package> program is part of the Ports Collection.</para> <para><command>port</command> is the front-end script, which can help you simplify the testing job. Whenever you want to test a new port or update an existing one, you can use <command>port test</command> to test your port, including the - <link - linkend="testing-portlint"><command>portlint</command></link> + <link linkend="testing-portlint"><command>portlint</command></link> checking. This command also detects and lists any files that are not listed in <filename>pkg-plist</filename>. See the following example:</para> @@ -10733,33 +10644,33 @@ as .putsy.conf and edit it.</programlisting> <screen>&prompt.root; <userinput>port test /usr/ports/net/csup</userinput></screen> </sect1> - <sect1 id="porting-prefix"> - <title><makevar>PREFIX</makevar> and - <makevar>DESTDIR</makevar></title> + <sect1 xml:id="porting-prefix"> + <title><varname>PREFIX</varname> and + <varname>DESTDIR</varname></title> - <para><makevar>PREFIX</makevar> determines where the port will + <para><varname>PREFIX</varname> determines where the port will be installed. It defaults to <filename>/usr/local</filename>, but can be set by the user to a custom path like <filename>/opt</filename>. Your port must respect the value of this variable.</para> - <para><makevar>DESTDIR</makevar>, if set by the user, determines + <para><varname>DESTDIR</varname>, if set by the user, determines the complete alternative environment, usually a jail or an installed system mounted somewhere other than <filename>/</filename>. A port will actually install into - <filename><makevar>DESTDIR</makevar>/<makevar>PREFIX</makevar></filename>, + <filename>DESTDIR/PREFIX</filename>, and register with the package database in - <filename><makevar>DESTDIR</makevar>/var/db/pkg</filename>. - As <makevar>DESTDIR</makevar> is handled automatically by the + <filename>DESTDIR/var/db/pkg</filename>. + As <varname>DESTDIR</varname> is handled automatically by the ports infrastructure with &man.chroot.8;, you do not need any modifications or any extra care to write - <makevar>DESTDIR</makevar>-compliant ports.</para> + <varname>DESTDIR</varname>-compliant ports.</para> - <para>The value of <makevar>PREFIX</makevar> will be set to - <makevar>LOCALBASE</makevar> (defaulting to + <para>The value of <varname>PREFIX</varname> will be set to + <varname>LOCALBASE</varname> (defaulting to <filename>/usr/local</filename>). If - <makevar>USE_LINUX_PREFIX</makevar> is set, - <makevar>PREFIX</makevar> will be <makevar>LINUXBASE</makevar> + <varname>USE_LINUX_PREFIX</varname> is set, + <varname>PREFIX</varname> will be <varname>LINUXBASE</varname> (defaulting to <filename>/compat/linux</filename>).</para> <para>Avoiding hard-coded <filename>/usr/local</filename> paths @@ -10774,13 +10685,13 @@ as .putsy.conf and edit it.</programlisting> <para>Make sure your application is not installing things in <filename>/usr/local</filename> instead of - <makevar>PREFIX</makevar>. A quick test for such hard-coded + <varname>PREFIX</varname>. A quick test for such hard-coded paths is:</para> <screen>&prompt.root; <userinput>make clean; make package PREFIX=/var/tmp/`make -V PORTNAME`</userinput></screen> <para>If anything is installed outside of - <makevar>PREFIX</makevar>, the package creation process will + <varname>PREFIX</varname>, the package creation process will complain that it cannot find the files.</para> <para>In addition, it is worth checking the same with the @@ -10790,15 +10701,15 @@ as .putsy.conf and edit it.</programlisting> <para>These tests will not find hard-coded paths inside the port's files, nor will it verify that - <makevar>LOCALBASE</makevar> is being used to correctly refer + <varname>LOCALBASE</varname> is being used to correctly refer to files from other ports. The temporarily-installed port in <filename>/var/tmp/`make -V PORTNAME`</filename> should be tested for proper operation to make sure there are no problems with paths.</para> - <para><makevar>PREFIX</makevar> should not be set explicitly + <para><varname>PREFIX</varname> should not be set explicitly in a port's <filename>Makefile</filename>. Users installing - the port may have set <makevar>PREFIX</makevar> to a custom + the port may have set <varname>PREFIX</varname> to a custom location, and the port should respect that setting.</para> <para>Refer to programs and files from other ports with the @@ -10811,12 +10722,12 @@ as .putsy.conf and edit it.</programlisting> <programlisting>-DPAGER=\"${LOCALBASE}/bin/less\"</programlisting> - <para>The path with <makevar>LOCALBASE</makevar> is more likely + <para>The path with <varname>LOCALBASE</varname> is more likely to still work if the system administrator has moved the whole <filename>/usr/local</filename> tree somewhere else.</para> </sect1> - <sect1 id="testing-tinderbox"> + <sect1 xml:id="testing-tinderbox"> <title>Tinderbox</title> <para>If you are an avid ports contributor, you might want to @@ -10825,17 +10736,17 @@ as .putsy.conf and edit it.</programlisting> scripts used on <link linkend="build-cluster">Pointyhat</link>. You can install <application>Tinderbox</application> using - <filename role="package">ports-mgmt/tinderbox</filename> port. + <package>ports-mgmt/tinderbox</package> port. Be sure to read supplied documentation since the configuration is not trivial.</para> <para>Visit the - <ulink url="http://tinderbox.marcuscom.com/">Tinderbox - website</ulink> for more details.</para> + <link xlink:href="http://tinderbox.marcuscom.com/">Tinderbox + website</link> for more details.</para> </sect1> </chapter> - <chapter id="port-upgrading"> + <chapter xml:id="port-upgrading"> <title>Upgrading an Individual Port</title> <para>When you notice that a port is out of date compared to the @@ -10846,16 +10757,14 @@ as .putsy.conf and edit it.</programlisting> few ports, you will probably find it easier to use <application>Subversion</application> or &man.portsnap.8; to keep your whole ports - collection up-to-date, as described in the <ulink - url="&url.books.handbook;/ports-using.html">Handbook</ulink>. + collection up-to-date, as described in the <link xlink:href="&url.books.handbook;/ports-using.html">Handbook</link>. This will have the added benefit of tracking all the ports' dependencies.</para> <para>The next step is to see if there is an update already pending. To do this, you have two options. There is a - searchable interface to the <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">FreeBSD - Problem Report (PR) database</ulink> (also known as + searchable interface to the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">FreeBSD + Problem Report (PR) database</link> (also known as <literal>GNATS</literal>). Select <literal>ports</literal> in the dropdown, and enter the name of the port.</para> @@ -10865,9 +10774,8 @@ as .putsy.conf and edit it.</programlisting> <link linkend="portsmon">FreeBSD Ports Monitoring System</link> (also known as <literal>portsmon</literal>). This system attempts to classify port PRs by portname. To search for PRs - about a particular port, use the <ulink - url="http://portsmon.FreeBSD.org/portoverview.py">Overview of - One Port</ulink>.</para> + about a particular port, use the <link xlink:href="http://portsmon.FreeBSD.org/portoverview.py">Overview of + One Port</link>.</para> <para>If there is no pending PR, the next step is to send an email to the port's maintainer, as shown by @@ -10892,7 +10800,7 @@ as .putsy.conf and edit it.</programlisting> patch:</para> <informalexample> - <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen> + <screen>&prompt.user; <userinput>diff -u something.orig something > something.diff</userinput></screen> </informalexample> <para>Otherwise, you should either use the @@ -10923,9 +10831,8 @@ as .putsy.conf and edit it.</programlisting> maintainer. &os; has over 4000 ports without maintainers, and this is an area where more volunteers are always needed. (For a detailed description of the responsibilities of maintainers, - refer to the section in the <ulink - url="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER"> - Developer's Handbook</ulink>.)</para> + refer to the section in the <link xlink:href="&url.books.developers-handbook;/policies.html#POLICIES-MAINTAINER"> + Developer's Handbook</link>.)</para> <para>The best way to send us the diff is by including it via &man.send-pr.1; (category <literal>ports</literal>). If you are @@ -10941,8 +10848,8 @@ as .putsy.conf and edit it.</programlisting> otherwise, just include it in the PR as is.</para> <para>Before you &man.send-pr.1;, you should review the - <ulink url="&url.articles.problem-reports;/pr-writing.html"> - Writing the problem report</ulink> section in the Problem + <link xlink:href="&url.articles.problem-reports;/pr-writing.html"> + Writing the problem report</link> section in the Problem Reports article; it contains far more information about how to write useful problem reports.</para> @@ -10965,7 +10872,7 @@ as .putsy.conf and edit it.</programlisting> <para>Now that you have done all that, you will want to read about how to keep up-to-date in <xref linkend="keeping-up"/>.</para> - <sect1 id="svn-diff"> + <sect1 xml:id="svn-diff"> <title>Using <literal>SVN</literal> to Make Patches</title> <para>If you can, please submit a &man.svn.1; diff — they @@ -10976,8 +10883,8 @@ as .putsy.conf and edit it.</programlisting> started to work on it until you submit your changes, or if the committer asks you to fix something.</para> - <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co id="my-wrkdir"/> -&prompt.user; <userinput>svn co <replaceable>https://svn0.us-west.FreeBSD.org</replaceable>/ports/head/dns/pdnsd</userinput> <co id="svn-FreeBSD-org"/> + <screen>&prompt.user; <userinput>cd ~/my_wrkdir</userinput> <co xml:id="my-wrkdir"/> +&prompt.user; <userinput>svn co https://svn0.us-west.FreeBSD.org/ports/head/dns/pdnsd</userinput> <co xml:id="svn-FreeBSD-org"/> &prompt.user; <userinput>cd ~/my_wrkdir/pdnsd</userinput></screen> <calloutlist> @@ -10985,17 +10892,15 @@ as .putsy.conf and edit it.</programlisting> <para>This can be anywhere you want, of course; building ports is not limited to within - <filename class="directory">/usr/ports/</filename>.</para> + <filename>/usr/ports/</filename>.</para> </callout> <callout arearefs="svn-FreeBSD-org"> - <para><ulink - url="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</ulink> + <para><link xlink:href="https://svn0.us-west.FreeBSD.org/">svn0.us-west.FreeBSD.org</link> is a public <literal>SVN</literal> server. Select the closest mirror and verify the mirror server - certificate from the list of <ulink - url="&url.books.handbook;/svn-mirrors.html">Subversion - mirror sites</ulink>.</para> + certificate from the list of <link xlink:href="&url.books.handbook;/svn-mirrors.html">Subversion + mirror sites</link>.</para> </callout> </calloutlist> @@ -11011,7 +10916,7 @@ as .putsy.conf and edit it.</programlisting> <xref linkend="porting-portlint"/>.</para> <screen>&prompt.user; <userinput>svn status</userinput> -&prompt.user; <userinput>svn update</userinput> <co id="svn-update"/></screen> +&prompt.user; <userinput>svn update</userinput> <co xml:id="svn-update"/></screen> <calloutlist> <callout arearefs="svn-update"> @@ -11023,7 +10928,7 @@ as .putsy.conf and edit it.</programlisting> </callout> </calloutlist> - <table pgwide="1" frame="none" id="table-svn-up"> + <table pgwide="1" frame="none" xml:id="table-svn-up"> <title><literal>SVN</literal> Update File Prefixes</title> <tgroup cols="2"> @@ -11079,7 +10984,7 @@ as .putsy.conf and edit it.</programlisting> <xref linkend="port-upgrading"/>.</para> </sect1> - <sect1 id="moved-and-updating-files"> + <sect1 xml:id="moved-and-updating-files"> <title>The Files <filename>UPDATING</filename> and <filename>MOVED</filename></title> @@ -11122,10 +11027,10 @@ as .putsy.conf and edit it.</programlisting> </sect1> </chapter> - <chapter id="security"> + <chapter xml:id="security"> <title>Ports Security</title> - <sect1 id="security-intro"> + <sect1 xml:id="security-intro"> <title>Why Security is So Important</title> <para>Bugs are occasionally introduced to the software. @@ -11161,7 +11066,7 @@ as .putsy.conf and edit it.</programlisting> actions.</para> </sect1> - <sect1 id="security-fix"> + <sect1 xml:id="security-fix"> <title>Fixing Security Vulnerabilities</title> <para>While on the subject of ports and packages, a security @@ -11172,7 +11077,7 @@ as .putsy.conf and edit it.</programlisting> port promptly with respect to the author's fix. If the fix is delayed for some reason, you should either <link linkend="dads-noinstall">mark the port as - <makevar>FORBIDDEN</makevar></link> or introduce a patch file + <varname>FORBIDDEN</varname></link> or introduce a patch file of your own to the port. In the case of a vulnerable port, just fix the port as soon as possible. In either case, <link linkend="port-upgrading">the standard procedure for @@ -11191,21 +11096,21 @@ as .putsy.conf and edit it.</programlisting> on a regular basis will see they need to run an update. Besides, a new package will be built and distributed over FTP and WWW mirrors, replacing the vulnerable one. - <makevar>PORTREVISION</makevar> should be bumped unless - <makevar>PORTVERSION</makevar> has changed in the course + <varname>PORTREVISION</varname> should be bumped unless + <varname>PORTVERSION</varname> has changed in the course of correcting the vulnerability. That is you should - bump <makevar>PORTREVISION</makevar> if you have added a + bump <varname>PORTREVISION</varname> if you have added a patch file to the port, but you should not if you have updated the port to the latest software version and thus already - touched <makevar>PORTVERSION</makevar>. Please refer to the + touched <varname>PORTVERSION</varname>. Please refer to the <link linkend="makefile-naming-revepoch">corresponding section</link> for more information.</para> </sect1> - <sect1 id="security-notify"> + <sect1 xml:id="security-notify"> <title>Keeping the Community Informed</title> - <sect2 id="security-notify-vuxml-db"> + <sect2 xml:id="security-notify-vuxml-db"> <title>The VuXML Database</title> <para>A very important and urgent step to take as early after @@ -11226,8 +11131,8 @@ as .putsy.conf and edit it.</programlisting> a flood and losing the attention of the audience when it comes to really serious matters. Therefore security vulnerabilities found in ports are recorded in - <ulink url="http://vuxml.freebsd.org/">the FreeBSD VuXML - database</ulink>. The Security Officer Team members also + <link xlink:href="http://vuxml.freebsd.org/">the FreeBSD VuXML + database</link>. The Security Officer Team members also monitor it for issues requiring their intervention.</para> <para>If you have committer rights you can update the VuXML @@ -11237,14 +11142,14 @@ as .putsy.conf and edit it.</programlisting> you believe you have found an exceptionally severe vulnerability please do not hesitate to contact the Security Officer Team directly as described on the - <ulink url="http://www.freebsd.org/security/#how">FreeBSD - Security Information</ulink> page.</para> + <link xlink:href="http://www.freebsd.org/security/#how">FreeBSD + Security Information</link> page.</para> <para>The VuXML database is an XML document. Its source file <filename>vuln.xml</filename> is kept right inside the port - <filename role="package">security/vuxml</filename>. + <package>security/vuxml</package>. Therefore the file's full pathname will be - <filename><envar>PORTSDIR</envar>/security/vuxml/vuln.xml</filename>. + <filename>PORTSDIR/security/vuxml/vuln.xml</filename>. Each time you discover a security vulnerability in a port please add an entry for it to that file. Until you are familiar with VuXML, the best thing you can do is to find an @@ -11252,7 +11157,7 @@ as .putsy.conf and edit it.</programlisting> a template.</para> </sect2> - <sect2 id="security-notify-vuxml-intro"> + <sect2 xml:id="security-notify-vuxml-intro"> <title>A Short Introduction to VuXML</title> <para>The full-blown XML format is complex, and far beyond the @@ -11272,26 +11177,26 @@ as .putsy.conf and edit it.</programlisting> <para>Now consider a realistic VuXML entry:</para> - <programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co id="co-vx-vid"/> - <topic>Several vulnerabilities found in Foo</topic> <co id="co-vx-top"/> + <programlisting><vuln vid="f4bc80f4-da62-11d8-90ea-0004ac98a7b9"> <co xml:id="co-vx-vid"/> + <topic>Several vulnerabilities found in Foo</topic> <co xml:id="co-vx-top"/> <affects> <package> - <name>foo</name> <co id="co-vx-nam"/> + <name>foo</name> <co xml:id="co-vx-nam"/> <name>foo-devel</name> <name>ja-foo</name> - <range><ge>1.6</ge><lt>1.9</lt></range> <co id="co-vx-rng"/> + <range><ge>1.6</ge><lt>1.9</lt></range> <co xml:id="co-vx-rng"/> <range><ge>2.*</ge><lt>2.4_1</lt></range> <range><eq>3.0b1</eq></range> </package> <package> - <name>openfoo</name> <co id="co-vx-nm2"/> - <range><lt>1.10_7</lt></range> <co id="co-vx-epo"/> + <name>openfoo</name> <co xml:id="co-vx-nm2"/> + <range><lt>1.10_7</lt></range> <co xml:id="co-vx-epo"/> <range><ge>1.2,1</ge><lt>1.3_1,1</lt></range> </package> </affects> <description> <body xmlns="http://www.w3.org/1999/xhtml"> - <p>J. Random Hacker reports:</p> <co id="co-vx-bdy"/> + <p>J. Random Hacker reports:</p> <co xml:id="co-vx-bdy"/> <blockquote cite="http://j.r.hacker.com/advisories/1"> <p>Several issues in the Foo software may be exploited @@ -11301,23 +11206,23 @@ as .putsy.conf and edit it.</programlisting> </blockquote> </body> </description> - <references> <co id="co-vx-ref"/> - <freebsdsa>SA-10:75.foo</freebsdsa> <co id="co-vx-fsa"/> - <freebsdpr>ports/987654</freebsdpr> <co id="co-vx-fpr"/> - <cvename>CAN-2010-0201</cvename> <co id="co-vx-cve"/> + <references> <co xml:id="co-vx-ref"/> + <freebsdsa>SA-10:75.foo</freebsdsa> <co xml:id="co-vx-fsa"/> + <freebsdpr>ports/987654</freebsdpr> <co xml:id="co-vx-fpr"/> + <cvename>CAN-2010-0201</cvename> <co xml:id="co-vx-cve"/> <cvename>CAN-2010-0466</cvename> - <bid>96298</bid> <co id="co-vx-bid"/> - <certsa>CA-2010-99</certsa> <co id="co-vx-cts"/> - <certvu>740169</certvu> <co id="co-vx-ctv"/> - <uscertsa>SA10-99A</uscertsa> <co id="co-vx-ucs"/> - <uscertta>SA10-99A</uscertta> <co id="co-vx-uct"/> - <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <co id="co-vx-mls"/> - <url>http://j.r.hacker.com/advisories/1</url> <co id="co-vx-url"/> + <bid>96298</bid> <co xml:id="co-vx-bid"/> + <certsa>CA-2010-99</certsa> <co xml:id="co-vx-cts"/> + <certvu>740169</certvu> <co xml:id="co-vx-ctv"/> + <uscertsa>SA10-99A</uscertsa> <co xml:id="co-vx-ucs"/> + <uscertta>SA10-99A</uscertta> <co xml:id="co-vx-uct"/> + <mlist msgid="201075606@hacker.com">http://marc.theaimsgroup.com/?l=bugtraq&amp;m=203886607825605</mlist> <co xml:id="co-vx-mls"/> + <url>http://j.r.hacker.com/advisories/1</url> <co xml:id="co-vx-url"/> </references> <dates> - <discovery>2010-05-25</discovery> <co id="co-vx-dsc"/> - <entry>2010-07-13</entry> <co id="co-vx-ent"/> - <modified>2010-09-17</modified> <co id="co-vx-mod"/> + <discovery>2010-05-25</discovery> <co xml:id="co-vx-dsc"/> + <entry>2010-07-13</entry> <co xml:id="co-vx-ent"/> + <modified>2010-09-17</modified> <co xml:id="co-vx-mod"/> </dates> </vuln></programlisting> @@ -11427,12 +11332,12 @@ as .putsy.conf and edit it.</programlisting> <callout arearefs="co-vx-epo"> <para>The version ranges should allow for - <makevar>PORTEPOCH</makevar> and - <makevar>PORTREVISION</makevar> if applicable. Please + <varname>PORTEPOCH</varname> and + <varname>PORTREVISION</varname> if applicable. Please remember that according to the collation rules, a - version with a non-zero <makevar>PORTEPOCH</makevar> is + version with a non-zero <varname>PORTEPOCH</varname> is greater than any version without - <makevar>PORTEPOCH</makevar>, e.g., + <varname>PORTEPOCH</varname>, e.g., <literal>3.0,1</literal> is greater than <literal>3.1</literal> or even than <literal>8.9</literal>.</para> @@ -11454,50 +11359,47 @@ as .putsy.conf and edit it.</programlisting> </callout> <callout arearefs="co-vx-fsa"> - <para>This is a <ulink - url="http://www.freebsd.org/security/#adv">FreeBSD - security advisory</ulink>.</para> + <para>This is a <link xlink:href="http://www.freebsd.org/security/#adv">FreeBSD + security advisory</link>.</para> </callout> <callout arearefs="co-vx-fpr"> - <para>This is a <ulink - url="http://www.freebsd.org/support.html#gnats">FreeBSD - problem report</ulink>.</para> + <para>This is a <link xlink:href="http://www.freebsd.org/support.html#gnats">FreeBSD + problem report</link>.</para> </callout> <callout arearefs="co-vx-cve"> <para>This is a - <ulink url="http://www.cve.mitre.org/">MITRE - CVE</ulink> identifier.</para> + <link xlink:href="http://www.cve.mitre.org/">MITRE + CVE</link> identifier.</para> </callout> <callout arearefs="co-vx-bid"> - <para>This is a <ulink - url="http://www.securityfocus.com/bid">SecurityFocus - Bug ID</ulink>.</para> + <para>This is a <link xlink:href="http://www.securityfocus.com/bid">SecurityFocus + Bug ID</link>.</para> </callout> <callout arearefs="co-vx-cts"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> security advisory.</para> </callout> <callout arearefs="co-vx-ctv"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> vulnerability note.</para> </callout> <callout arearefs="co-vx-ucs"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> Cyber Security Alert.</para> </callout> <callout arearefs="co-vx-uct"> <para>This is a - <ulink url="http://www.cert.org/">US-CERT</ulink> + <link xlink:href="http://www.cert.org/">US-CERT</link> Technical Cyber Security Alert.</para> </callout> @@ -11533,7 +11435,7 @@ as .putsy.conf and edit it.</programlisting> </calloutlist> </sect2> - <sect2 id="security-notify-vuxml-testing"> + <sect2 xml:id="security-notify-vuxml-testing"> <title>Testing Your Changes to the VuXML Database</title> <para>Assume you just wrote or filled in an entry for a @@ -11542,24 +11444,24 @@ as .putsy.conf and edit it.</programlisting> <para>As a prerequisite, you need to <emphasis>install</emphasis> fresh versions of the ports - <filename role="package">ports-mgmt/portaudit</filename>, - <filename role="package">ports-mgmt/portaudit-db</filename>, + <package>ports-mgmt/portaudit</package>, + <package>ports-mgmt/portaudit-db</package>, and - <filename role="package">security/vuxml</filename>.</para> + <package>security/vuxml</package>.</para> <note> <para>To run <command>packaudit</command> you must have permission to write to its - <filename><makevar>DATABASEDIR</makevar></filename>, + <filename>DATABASEDIR</filename>, typically <filename>/var/db/portaudit</filename>.</para> <para>To use a different directory set the - <filename><makevar>DATABASEDIR</makevar></filename> + <filename>DATABASEDIR</filename> environment variable to a different location.</para> <para>If you are working in a directory other than <filename>${PORTSDIR}/security/vuxml</filename> set the - <filename><makevar>VUXMLDIR</makevar></filename> + <filename>VUXMLDIR</filename> environment variable to the directory where <filename>vuln.xml</filename> is located.</para> </note> @@ -11586,8 +11488,8 @@ as .putsy.conf and edit it.</programlisting> <note> <para>You will need at least one of the following packages installed: - <filename role="package">textproc/libxml2</filename>, - <filename role="package">textproc/jade</filename>.</para> + <package>textproc/libxml2</package>, + <package>textproc/jade</package>.</para> </note> <para>Now rebuild the <command>portaudit</command> database @@ -11599,7 +11501,7 @@ as .putsy.conf and edit it.</programlisting> section of your entry will match correct package(s), issue the following command:</para> - <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r <replaceable>uuid</replaceable></userinput></screen> + <screen>&prompt.user; <userinput>portaudit -f /usr/ports/INDEX -r uuid</userinput></screen> <note> <para>Please refer to &man.portaudit.1; for better @@ -11632,71 +11534,68 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 </sect1> </chapter> - <chapter id="porting-dads"> + <chapter xml:id="porting-dads"> <title>Dos and Don'ts</title> - <sect1 id="dads-intro"> + <sect1 xml:id="dads-intro"> <title>Introduction</title> <para>Here is a list of common dos and don'ts that you encounter during the porting process. You should check your own port - against this list, but you can also check ports in the <ulink - url="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR - database</ulink> that others have submitted. Submit any - comments on ports you check as described in <ulink - url="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug - Reports and General Commentary</ulink>. Checking ports in + against this list, but you can also check ports in the <link xlink:href="http://www.FreeBSD.org/cgi/query-pr-summary.cgi?query">PR + database</link> that others have submitted. Submit any + comments on ports you check as described in <link xlink:href="&url.articles.contributing;/contrib-how.html#CONTRIB-GENERAL">Bug + Reports and General Commentary</link>. Checking ports in the PR database will both make it faster for us to commit them, and prove that you know what you are doing.</para> </sect1> - <sect1 id="porting-wrkdir"> - <title><makevar>WRKDIR</makevar></title> + <sect1 xml:id="porting-wrkdir"> + <title><varname>WRKDIR</varname></title> <para>Do not write anything to files outside - <makevar>WRKDIR</makevar>. <makevar>WRKDIR</makevar> is the + <varname>WRKDIR</varname>. <varname>WRKDIR</varname> is the only place that is guaranteed to be writable during the port build (see - <ulink url="&url.books.handbook;/ports-using.html#PORTS-CD"> - installing ports from a CDROM</ulink> for an example of + <link xlink:href="&url.books.handbook;/ports-using.html#PORTS-CD"> + installing ports from a CDROM</link> for an example of building ports from a read-only tree). If you need to modify one of the - <filename>pkg-<replaceable>*</replaceable></filename> files, + <filename>pkg-*</filename> files, do so by <link linkend="porting-pkgfiles">redefining a variable</link>, not by writing over it.</para> </sect1> - <sect1 id="porting-wrkdirprefix"> - <title><makevar>WRKDIRPREFIX</makevar></title> + <sect1 xml:id="porting-wrkdirprefix"> + <title><varname>WRKDIRPREFIX</varname></title> <para>Make sure your port honors - <makevar>WRKDIRPREFIX</makevar>. Most ports do not have to + <varname>WRKDIRPREFIX</varname>. Most ports do not have to worry about this. In particular, if you are referring to a - <makevar>WRKDIR</makevar> of another port, note that the + <varname>WRKDIR</varname> of another port, note that the correct location is - <filename><makevar>WRKDIRPREFIX</makevar><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + <filename>WRKDIRPREFIXPORTSDIR/subdir/name/work</filename> not - <filename><makevar>PORTSDIR</makevar>/<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + <filename>PORTSDIR/subdir/name/work</filename> or - <filename><makevar>.CURDIR</makevar>/../../<replaceable>subdir</replaceable>/<replaceable>name</replaceable>/work</filename> + <filename>.CURDIR/../../subdir/name/work</filename> or some such.</para> - <para>Also, if you are defining <makevar>WRKDIR</makevar> + <para>Also, if you are defining <varname>WRKDIR</varname> yourself, make sure you prepend <literal>${WRKDIRPREFIX}${.CURDIR}</literal> in the front.</para> </sect1> - <sect1 id="porting-versions"> + <sect1 xml:id="porting-versions"> <title>Differentiating Operating Systems and OS Versions</title> <para>You may come across code that needs modifications or conditional compilation based upon what version of &os; Unix it is running under. The preferred way to tell &os; versions apart are the <literal>__FreeBSD_version</literal> and - <literal>__FreeBSD__</literal> macros defined in <ulink - url="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</ulink>. + <literal>__FreeBSD__</literal> macros defined in <link xlink:href="http://svnweb.freebsd.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>. If this file is not included add the code,</para> <programlisting>#include <sys/param.h></programlisting> @@ -11718,7 +11617,7 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 </para> </sect1> - <sect1 id="dads-after-port-mk"> + <sect1 xml:id="dads-after-port-mk"> <title>Writing Something After <filename>bsd.port.mk</filename></title> @@ -11756,43 +11655,41 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 <tbody> <row> - <entry><makevar>ARCH</makevar></entry> + <entry><varname>ARCH</varname></entry> <entry>The architecture as returned by <command>uname -m</command> (e.g., <literal>i386</literal>)</entry> </row> <row> - <entry><makevar>OPSYS</makevar></entry> + <entry><varname>OPSYS</varname></entry> <entry>The operating system type, as returned by <command>uname -s</command> (e.g., <literal>FreeBSD</literal>)</entry> </row> <row> - <entry><makevar>OSREL</makevar></entry> + <entry><varname>OSREL</varname></entry> <entry>The release version of the operating system (e.g., <literal>2.1.5</literal> or <literal>2.2.7</literal>)</entry> </row> <row> - <entry><makevar>OSVERSION</makevar></entry> + <entry><varname>OSVERSION</varname></entry> <entry>The numeric version of the operating system; the - same as <link - linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry> + same as <link linkend="freebsd-versions"><literal>__FreeBSD_version</literal></link>.</entry> </row> <row> - <entry><makevar>LOCALBASE</makevar></entry> + <entry><varname>LOCALBASE</varname></entry> <entry>The base of the <quote>local</quote> tree (e.g., <literal>/usr/local</literal>)</entry> </row> <row> - <entry><makevar>PREFIX</makevar></entry> - <entry>Where the port installs itself (see <link - linkend="porting-prefix">more on - <makevar>PREFIX</makevar></link>).</entry> + <entry><varname>PREFIX</varname></entry> + <entry>Where the port installs itself (see <link linkend="porting-prefix">more on + <varname>PREFIX</varname></link>).</entry> </row> </tbody> </tgroup> @@ -11800,7 +11697,7 @@ Reference: <http://www.freebsd.org/ports/portaudit/74a9541d-5d6c-11d8-80e3-00 <note> <para>If you have to define the variable - <makevar>MASTERDIR</makevar>, do so before including + <varname>MASTERDIR</varname>, do so before including <filename>bsd.port.pre.mk</filename>.</para> </note> @@ -11817,7 +11714,7 @@ BROKEN= perl is in system <!-- smiley -->:-).</para> </sect1> - <sect1 id="dads-sh-exec"> + <sect1 xml:id="dads-sh-exec"> <title>Use the <function>exec</function> Statement in Wrapper Scripts</title> @@ -11837,7 +11734,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> needlessly consumes system resources.</para> </sect1> - <sect1 id="dads-rational"> + <sect1 xml:id="dads-rational"> <title>Do Things Rationally</title> <para>The <filename>Makefile</filename> should do things simply @@ -11845,9 +11742,9 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> or more readable, then do so. Examples include using a make <literal>.if</literal> construct instead of a shell <literal>if</literal> construct, not redefining - <maketarget>do-extract</maketarget> if you can redefine - <makevar>EXTRACT*</makevar> instead, and using - <makevar>GNU_CONFIGURE</makevar> instead of + <buildtarget>do-extract</buildtarget> if you can redefine + <varname>EXTRACT*</varname> instead, and using + <varname>GNU_CONFIGURE</varname> instead of <literal>CONFIGURE_ARGS += --prefix=${PREFIX}</literal>.</para> @@ -11860,12 +11757,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> shorthand solution.</para> </sect1> - <sect1 id="dads-cc"> - <title>Respect Both <makevar>CC</makevar> and - <makevar>CXX</makevar></title> + <sect1 xml:id="dads-cc"> + <title>Respect Both <varname>CC</varname> and + <varname>CXX</varname></title> - <para>The port must respect both <makevar>CC</makevar> and - <makevar>CXX</makevar> variables. What we mean by this is + <para>The port must respect both <varname>CC</varname> and + <varname>CXX</varname> variables. What we mean by this is that the port must not set the values of these variables absolutely, overriding existing values; instead, it may append whatever values it needs to the existing values. This @@ -11878,22 +11775,22 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <filename>Makefile</filename>.</para> <para>An example of a <filename>Makefile</filename> respecting - both <makevar>CC</makevar> and <makevar>CXX</makevar> - variables follows. Note the <makevar>?=</makevar>:</para> + both <varname>CC</varname> and <varname>CXX</varname> + variables follows. Note the <varname>?=</varname>:</para> <programlisting>CC?= gcc</programlisting> <programlisting>CXX?= g++</programlisting> <para>Here is an example which respects neither - <makevar>CC</makevar> nor <makevar>CXX</makevar> + <varname>CC</varname> nor <varname>CXX</varname> variables:</para> <programlisting>CC= gcc</programlisting> <programlisting>CXX= g++</programlisting> - <para>Both <makevar>CC</makevar> and <makevar>CXX</makevar> + <para>Both <varname>CC</varname> and <varname>CXX</varname> variables can be defined on FreeBSD systems in <filename>/etc/make.conf</filename>. The first example defines a value if it was not previously set in @@ -11902,10 +11799,10 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> anything previously defined.</para> </sect1> - <sect1 id="dads-cflags"> - <title>Respect <makevar>CFLAGS</makevar></title> + <sect1 xml:id="dads-cflags"> + <title>Respect <varname>CFLAGS</varname></title> - <para>The port must respect the <makevar>CFLAGS</makevar> + <para>The port must respect the <varname>CFLAGS</varname> variable. What we mean by this is that the port must not set the value of this variable absolutely, overriding the existing value; instead, it may append whatever values it @@ -11917,26 +11814,26 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <filename>Makefile</filename>.</para> <para>An example of a <filename>Makefile</filename> respecting - the <makevar>CFLAGS</makevar> variable follows. Note the - <makevar>+=</makevar>:</para> + the <varname>CFLAGS</varname> variable follows. Note the + <varname>+=</varname>:</para> <programlisting>CFLAGS+= -Wall -Werror</programlisting> <para>Here is an example which does not respect the - <makevar>CFLAGS</makevar> variable:</para> + <varname>CFLAGS</varname> variable:</para> <programlisting>CFLAGS= -Wall -Werror</programlisting> - <para>The <makevar>CFLAGS</makevar> variable is defined on + <para>The <varname>CFLAGS</varname> variable is defined on FreeBSD systems in <filename>/etc/make.conf</filename>. The first example appends additional flags to the - <makevar>CFLAGS</makevar> variable, preserving any system-wide + <varname>CFLAGS</varname> variable, preserving any system-wide definitions. The second example clobbers anything previously defined.</para> <para>You should remove optimization flags from the third party <filename>Makefile</filename>s. System - <makevar>CFLAGS</makevar> contains system-wide optimization + <varname>CFLAGS</varname> contains system-wide optimization flags. An example from an unmodified <filename>Makefile</filename>:</para> @@ -11949,7 +11846,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <programlisting>CFLAGS+= -DHAVE_SOUND</programlisting> </sect1> - <sect1 id="dads-pthread"> + <sect1 xml:id="dads-pthread"> <title>Threading Libraries</title> <para>The threading library must be linked to the binaries using @@ -11961,14 +11858,14 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <para>If building the port errors out with <literal>unrecognized option '-pthread'</literal>, it may be desirable to use <command>cc</command> as linker by setting - <makevar>CONFIGURE_ENV</makevar> to + <varname>CONFIGURE_ENV</varname> to <literal>LD=${CC}</literal>. The <literal>-pthread</literal> option is not supported by <command>ld</command> directly.</para> </note> </sect1> - <sect1 id="dads-freedback"> + <sect1 xml:id="dads-freedback"> <title>Feedback</title> <para>Do send applicable changes/patches to the original @@ -11977,7 +11874,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> release.</para> </sect1> - <sect1 id="dads-readme"> + <sect1 xml:id="dads-readme"> <title><filename>README.html</filename></title> <para>Do not include the <filename>README.html</filename> file. @@ -11986,15 +11883,15 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <note> <para>If <command>make readme</command> fails, make sure that - the default value of <makevar>ECHO_MSG</makevar> has not + the default value of <varname>ECHO_MSG</varname> has not been modified by the port.</para> </note> </sect1> - <sect1 id="dads-noinstall"> + <sect1 xml:id="dads-noinstall"> <title>Marking a Port Not Installable with - <makevar>BROKEN</makevar>, <makevar>FORBIDDEN</makevar>, or - <makevar>IGNORE</makevar></title> + <varname>BROKEN</varname>, <varname>FORBIDDEN</varname>, or + <varname>IGNORE</varname></title> <para>In certain cases users should be prevented from installing a port. To tell a user that a port should not be installed, @@ -12010,12 +11907,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> cluster</link>, <link linkend="freshports">FreshPorts</link>, and <link linkend="portsmon">portsmon</link>.</para> - <sect2 id="dads-noinstall-variables"> + <sect2 xml:id="dads-noinstall-variables"> <title>Variables</title> <itemizedlist> <listitem> - <para><makevar>BROKEN</makevar> is reserved for ports that + <para><varname>BROKEN</varname> is reserved for ports that currently do not compile, install, or deinstall correctly. It should be used for ports where the problem is believed to be temporary.</para> @@ -12025,7 +11922,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> has been resolved. (However, in general, the cluster is run without this.)</para> - <para>For instance, use <makevar>BROKEN</makevar> when a + <para>For instance, use <varname>BROKEN</varname> when a port:</para> <itemizedlist> @@ -12053,12 +11950,12 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> </listitem> <listitem> - <para><makevar>FORBIDDEN</makevar> is used for ports that + <para><varname>FORBIDDEN</varname> is used for ports that contain a security vulnerability or induce grave concern regarding the security of a FreeBSD system with a given port installed (e.g., a reputably insecure program or a program that provides easily exploitable services). - Ports should be marked as <makevar>FORBIDDEN</makevar> + Ports should be marked as <varname>FORBIDDEN</varname> as soon as a particular piece of software has a vulnerability and there is no released upgrade. Ideally ports should be upgraded as soon as possible when a @@ -12068,18 +11965,18 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> noticeable time gap between disclosure of a vulnerability and an updated release of the vulnerable software. Do not mark a port - <makevar>FORBIDDEN</makevar> for any reason other than + <varname>FORBIDDEN</varname> for any reason other than security.</para> </listitem> <listitem> - <para><makevar>IGNORE</makevar> is reserved for ports that + <para><varname>IGNORE</varname> is reserved for ports that should not be built for some other reason. It should be used for ports where the problem is believed to be structural. The build cluster will not, under any circumstances, build ports marked as - <makevar>IGNORE</makevar>. For instance, use - <makevar>IGNORE</makevar> when a port:</para> + <varname>IGNORE</varname>. For instance, use + <varname>IGNORE</varname> when a port:</para> <itemizedlist> <listitem> @@ -12104,8 +12001,8 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> <listitem> <para>does not work with some other currently installed port (for instance, the port depends on - <filename role="package">www/apache20</filename> but - <filename role="package">www/apache22</filename> is + <package>www/apache20</package> but + <package>www/apache22</package> is installed)</para> </listitem> </itemizedlist> @@ -12115,47 +12012,47 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> installed port (for example, if they install a file in the same place that performs a different function), <link linkend="conflicts">use - <makevar>CONFLICTS</makevar> instead</link>. - <makevar>CONFLICTS</makevar> will set - <makevar>IGNORE</makevar> by itself.</para> + <varname>CONFLICTS</varname> instead</link>. + <varname>CONFLICTS</varname> will set + <varname>IGNORE</varname> by itself.</para> </note> </listitem> <listitem> - <para>If a port should be marked <makevar>IGNORE</makevar> + <para>If a port should be marked <varname>IGNORE</varname> only on certain architectures, there are two other convenience variables that will automatically set - <makevar>IGNORE</makevar> for you: - <makevar>ONLY_FOR_ARCHS</makevar> and - <makevar>NOT_FOR_ARCHS</makevar>. Examples:</para> + <varname>IGNORE</varname> for you: + <varname>ONLY_FOR_ARCHS</varname> and + <varname>NOT_FOR_ARCHS</varname>. Examples:</para> <programlisting>ONLY_FOR_ARCHS= i386 amd64</programlisting> <programlisting>NOT_FOR_ARCHS= ia64 sparc64</programlisting> - <para>A custom <makevar>IGNORE</makevar> message can be - set using <makevar>ONLY_FOR_ARCHS_REASON</makevar> and - <makevar>NOT_FOR_ARCHS_REASON</makevar>. Per + <para>A custom <varname>IGNORE</varname> message can be + set using <varname>ONLY_FOR_ARCHS_REASON</varname> and + <varname>NOT_FOR_ARCHS_REASON</varname>. Per architecture entries are possible with - <makevar>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></makevar> + <varname>ONLY_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname> and - <makevar>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></makevar>.</para> + <varname>NOT_FOR_ARCHS_REASON_<replaceable>ARCH</replaceable></varname>.</para> </listitem> <listitem> <para>If a port fetches i386 binaries and installs them, - <makevar>IA32_BINARY_PORT</makevar> should be set. If + <varname>IA32_BINARY_PORT</varname> should be set. If this variable is set, it will be checked whether the <filename>/usr/lib32</filename> directory is available for IA32 versions of libraries and whether the kernel has IA32 compatibility compiled in. If one of these two - dependencies is not satisfied, <makevar>IGNORE</makevar> + dependencies is not satisfied, <varname>IGNORE</varname> will be set automatically.</para> </listitem> </itemizedlist> </sect2> - <sect2 id="dads-noinstall-notes"> + <sect2 xml:id="dads-noinstall-notes"> <title>Implementation Notes</title> <para>The strings should not be quoted. @@ -12176,25 +12073,25 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> </sect2> </sect1> - <sect1 id="dads-deprecated"> + <sect1 xml:id="dads-deprecated"> <title>Marking a Port for Removal with - <makevar>DEPRECATED</makevar> or - <makevar>EXPIRATION_DATE</makevar></title> + <varname>DEPRECATED</varname> or + <varname>EXPIRATION_DATE</varname></title> - <para>Do remember that <makevar>BROKEN</makevar> and - <makevar>FORBIDDEN</makevar> are to be used as a temporary + <para>Do remember that <varname>BROKEN</varname> and + <varname>FORBIDDEN</varname> are to be used as a temporary resort if a port is not working. Permanently broken ports should be removed from the tree entirely.</para> <para>When it makes sense to do so, users can be warned about - a pending port removal with <makevar>DEPRECATED</makevar> - and <makevar>EXPIRATION_DATE</makevar>. The former is + a pending port removal with <varname>DEPRECATED</varname> + and <varname>EXPIRATION_DATE</varname>. The former is simply a string stating why the port is scheduled for removal; the latter is a string in ISO 8601 format (YYYY-MM-DD). Both will be shown to the user.</para> - <para>It is possible to set <makevar>DEPRECATED</makevar> - without an <makevar>EXPIRATION_DATE</makevar> (for instance, + <para>It is possible to set <varname>DEPRECATED</varname> + without an <varname>EXPIRATION_DATE</varname> (for instance, recommending a newer version of the port), but the converse does not make any sense.</para> @@ -12205,7 +12102,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> problems.</para> </sect1> - <sect1 id="dads-dot-error"> + <sect1 xml:id="dads-dot-error"> <title>Avoid Use of the <literal>.error</literal> Construct</title> @@ -12213,7 +12110,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> signal that the port can not be installed due to some external factor (for instance, the user has specified an illegal combination of build options) is to set a non-blank value to - <makevar>IGNORE</makevar>. This value will be formatted and + <varname>IGNORE</varname>. This value will be formatted and shown to the user by <command>make install</command>.</para> <para>It is a common mistake to use <literal>.error</literal> @@ -12225,7 +12122,7 @@ exec %%LOCALBASE%%/bin/java -jar %%DATADIR%%/foo.jar "$@"</programlisting> trivial commands such as <command>make maintainer</command> also fail in this scenario. This is not acceptable.</para> - <example id="dot-error-breaks-index"> + <example xml:id="dot-error-breaks-index"> <title>How to Avoid Using <literal>.error</literal></title> <para>Assume that someone has the line</para> @@ -12247,7 +12144,7 @@ IGNORE= POINTYHAT is not supported </example> </sect1> - <sect1 id="dads-sysctl"> + <sect1 xml:id="dads-sysctl"> <title>Usage of <filename>sysctl</filename></title> <para>The usage of <filename>sysctl</filename> is discouraged @@ -12257,12 +12154,12 @@ IGNORE= POINTYHAT is not supported further slowing down that process.</para> <para>Usage of &man.sysctl.8; should always be done with the - <makevar>SYSCTL</makevar> variable, as it contains the fully + <varname>SYSCTL</varname> variable, as it contains the fully qualified path and can be overridden, if one has such a special need.</para> </sect1> - <sect1 id="dads-rerolling-distfiles"> + <sect1 xml:id="dads-rerolling-distfiles"> <title>Rerolling Distfiles</title> <para>Sometimes the authors of software change the content of @@ -12284,7 +12181,7 @@ IGNORE= POINTYHAT is not supported and confirm the changes with them.</para> </sect1> - <sect1 id="dads-avoiding-linuxisms"> + <sect1 xml:id="dads-avoiding-linuxisms"> <title>Avoiding Linuxisms</title> <para>Do not use <filename>/proc</filename> if there are any @@ -12323,8 +12220,7 @@ IGNORE= POINTYHAT is not supported do a check for the behaviour in the configure stage, and stop if it is missing.</para> - <para>Check the <ulink - url="http://www.freebsd.org/cgi/man.cgi">man pages</ulink> + <para>Check the <link xlink:href="http://www.freebsd.org/cgi/man.cgi">man pages</link> to see if the function used is a <acronym>POSIX</acronym> interface (in the <quote>STANDARDS</quote> section of the man page).</para> @@ -12335,8 +12231,7 @@ IGNORE= POINTYHAT is not supported <acronym>POSIX</acronym> compliant shell.</para> <para>A list of common <application>bash</application>isms is - available <ulink - url="https://wiki.ubuntu.com/DashAsBinSh">here</ulink>.</para> + available <link xlink:href="https://wiki.ubuntu.com/DashAsBinSh">here</link>.</para> <para>Check that headers are included in the <acronym>POSIX</acronym> or man page recommended way, e.g., @@ -12348,7 +12243,7 @@ IGNORE= POINTYHAT is not supported variations thereof.</para> </sect1> - <sect1 id="dads-misc"> + <sect1 xml:id="dads-misc"> <title>Miscellanea</title> <para>The files <filename>pkg-descr</filename> and @@ -12364,7 +12259,7 @@ IGNORE= POINTYHAT is not supported </sect1> </chapter> - <chapter id="porting-samplem"> + <chapter xml:id="porting-samplem"> <title>A Sample <filename>Makefile</filename></title> <para>Here is a sample <filename>Makefile</filename> that you can @@ -12458,18 +12353,18 @@ pre-install: .include <bsd.port.mk></programlisting> </chapter> - <chapter id="keeping-up"> + <chapter xml:id="keeping-up"> <title>Keeping Up</title> <para>The &os; Ports Collection is constantly changing. Here is some information on how to keep up.</para> - <sect1 id="freshports"> + <sect1 xml:id="freshports"> <title>FreshPorts</title> <para>One of the easiest ways to learn about updates that have already been committed is by subscribing to - <ulink url="http://www.FreshPorts.org/">FreshPorts</ulink>. + <link xlink:href="http://www.FreshPorts.org/">FreshPorts</link>. You can select multiple ports to monitor. Maintainers are strongly encouraged to subscribe, because they will receive notification of not only their own changes, but also any @@ -12498,23 +12393,20 @@ pre-install: commits.</para> </sect1> - <sect1 id="svnweb"> + <sect1 xml:id="svnweb"> <title>The Web Interface to the Source Repository</title> <para>It is possible to browse the files in the source repository by using a web interface. Changes that affect the - entire port system are now documented in the <ulink - url="http://svnweb.FreeBSD.org/ports/head/CHANGES">CHANGES</ulink> + entire port system are now documented in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/CHANGES">CHANGES</link> file. Changes that affect individual ports - are now documented in the <ulink - url="http://svnweb.FreeBSD.org/ports/head/UPDATING">UPDATING</ulink> + are now documented in the <link xlink:href="http://svnweb.FreeBSD.org/ports/head/UPDATING">UPDATING</link> file. However, the definitive answer to - any question is undoubtedly to read the source code of <ulink - url="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk">bsd.port.mk</ulink>, + any question is undoubtedly to read the source code of <link xlink:href="http://svnweb.FreeBSD.org/ports/head/Mk/bsd.port.mk">bsd.port.mk</link>, and associated files.</para> </sect1> - <sect1 id="ports-mailling-list"> + <sect1 xml:id="ports-mailling-list"> <title>The &os; Ports Mailing List</title> <para>If you maintain ports, you should consider following the @@ -12527,34 +12419,34 @@ pre-install: discussion.</para> </sect1> - <sect1 id="build-cluster"> + <sect1 xml:id="build-cluster"> <title>The &os; Port Building Cluster on - <hostid role="hostname">pointyhat.FreeBSD.org</hostid></title> + <systemitem class="fqdomainname">pointyhat.FreeBSD.org</systemitem></title> <para>One of the least-publicized strengths of &os; is that an entire cluster of machines is dedicated to continually building the Ports Collection, for each of the major OS releases and for each Tier-1 architecture. You can find the results of these builds at - <ulink url="http://pointyhat.FreeBSD.org/">package building - logs and errors</ulink>.</para> + <link xlink:href="http://pointyhat.FreeBSD.org/">package building + logs and errors</link>.</para> <para>Individual ports are built unless they are specifically - marked with <makevar>IGNORE</makevar>. Ports that are - marked with <makevar>BROKEN</makevar> will still be attempted, + marked with <varname>IGNORE</varname>. Ports that are + marked with <varname>BROKEN</varname> will still be attempted, to see if the underlying problem has been resolved. (This - is done by passing <makevar>TRYBROKEN</makevar> to the + is done by passing <varname>TRYBROKEN</varname> to the port's <filename>Makefile</filename>.)</para> </sect1> - <sect1 id="distfile-survey"> + <sect1 xml:id="distfile-survey"> <title>Portscout: the &os; Ports Distfile Scanner</title> <para>The build cluster is dedicated to building the latest release of each port with distfiles that have already been fetched. However, as the Internet continually changes, distfiles can quickly go missing. - <ulink url="http://portscout.FreeBSD.org">Portscout</ulink>, + <link xlink:href="http://portscout.FreeBSD.org">Portscout</link>, the &os; Ports distfile scanner, attempts to query every download site for every port to find out if each distfile is still available. <application>Portscout</application> can @@ -12580,16 +12472,16 @@ pre-install: search for a specific port.</para> <para>Clicking on a port name in the list displays the - <ulink url="http://freshports.org">FreshPorts</ulink> port + <link xlink:href="http://freshports.org">FreshPorts</link> port information.</para> </sect1> - <sect1 id="portsmon"> + <sect1 xml:id="portsmon"> <title>The &os; Ports Monitoring System</title> <para>Another handy resource is the - <ulink url="http://portsmon.FreeBSD.org">FreeBSD Ports - Monitoring System</ulink> (also known as + <link xlink:href="http://portsmon.FreeBSD.org">FreeBSD Ports + Monitoring System</link> (also known as <literal>portsmon</literal>). This system comprises a database that processes information from several sources and allows it to be browsed via a web interface. Currently, the @@ -12599,9 +12491,8 @@ pre-install: distfile survey, as well as other sources.</para> <para>To get started, you can view all information about a - particular port by using the <ulink - url="http://portsmon.FreeBSD.org/portoverview.py">Overview - of One Port</ulink>.</para> + particular port by using the <link xlink:href="http://portsmon.FreeBSD.org/portoverview.py">Overview + of One Port</link>.</para> <para>As of this writing, this is the only resource available that maps GNATS PR entries to portnames. (PR submitters do @@ -12614,14 +12505,14 @@ pre-install: </sect1> </chapter> - <chapter id="appendices"> + <chapter xml:id="appendices"> <title>Appendices</title> - <sect1 id="uses-values"> - <title>Values of <makevar>USES</makevar></title> + <sect1 xml:id="uses-values"> + <title>Values of <varname>USES</varname></title> <table frame="none"> - <title>Values of <makevar>USES</makevar></title> + <title>Values of <varname>USES</varname></title> <tgroup cols="3"> <thead> @@ -12639,13 +12530,12 @@ pre-install: </table> </sect1> - <sect1 id="freebsd-versions"> + <sect1 xml:id="freebsd-versions"> <title><literal>__FreeBSD_version</literal> Values</title> <para>Here is a convenient list of <literal>__FreeBSD_version</literal> values as defined in - <ulink - url="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</ulink>:</para> + <link xlink:href="http://svnweb.FreeBSD.org/base/head/sys/sys/param.h?view=markup">sys/param.h</link>:</para> <table frame="none"> <title><literal>__FreeBSD_version</literal> Values</title> diff --git a/en_US.ISO8859-1/books/porters-handbook/uses.xml b/en_US.ISO8859-1/books/porters-handbook/uses.xml index 6592275cfc..7c3394bc59 100644 --- a/en_US.ISO8859-1/books/porters-handbook/uses.xml +++ b/en_US.ISO8859-1/books/porters-handbook/uses.xml @@ -21,7 +21,7 @@ <entry>(none)</entry> <entry>Depends on an <application>Ada</application>-capable - compiler, and sets <makevar>CC</makevar> accordingly.</entry> + compiler, and sets <varname>CC</varname> accordingly.</entry> </row> <row> @@ -43,10 +43,10 @@ <entry>Prevents the port from installing <filename>charset.alias</filename>. This should be installed only by <filename role="package">converters/libiconv</filename>. - <makevar>CHARSETFIX_MAKEFILEIN</makevar> can be set to a path - relative to <makevar>WRKSRC</makevar> if + <varname>CHARSETFIX_MAKEFILEIN</varname> can be set to a path + relative to <varname>WRKSRC</varname> if <filename>charset.alias</filename> is not installed by - <makevar>WRKSRC</makevar>/<filename>Makefile.in</filename>.</entry> + <varname>WRKSRC</varname>/<filename>Makefile.in</filename>.</entry> </row> <row> @@ -114,7 +114,7 @@ <filename role="package">converters/libiconv</filename> as a build-time and run-time dependency, or from the base system on 10-CURRENT after a native <command>iconv</command> was committed - in <svnref>254273</svnref>. By default, with no arguments or with + in <revnumber>254273</revnumber>. By default, with no arguments or with the <literal>lib</literal> argument, implies <command>iconv</command> with build-time and run-time dependencies, <literal>build</literal> implies a build-time @@ -137,13 +137,13 @@ <entry>Fills in the boilerplate for kernel module ports, currently: <itemizedlist> <listitem><para>Add <literal>kld</literal> to - <makevar>CATEGORIES</makevar>.</para></listitem> - <listitem><para>Set <makevar>SSP_UNSAFE</makevar>.</para></listitem> - <listitem><para>Set <makevar>IGNORE</makevar> if the kernel sources are - not found in <makevar>SRC_BASE</makevar>.</para></listitem> - <listitem><para>Define <makevar>KMODDIR</makevar> to <filename + <varname>CATEGORIES</varname>.</para></listitem> + <listitem><para>Set <varname>SSP_UNSAFE</varname>.</para></listitem> + <listitem><para>Set <varname>IGNORE</varname> if the kernel sources are + not found in <varname>SRC_BASE</varname>.</para></listitem> + <listitem><para>Define <varname>KMODDIR</varname> to <filename class="directory">/boot/modules</filename> by default, add it - to <makevar>PLIST_SUB</makevar> and <makevar>MAKE_ENV</makevar>, + to <varname>PLIST_SUB</varname> and <varname>MAKE_ENV</varname>, and create it upon installation.</para></listitem> <listitem><para>Handle cross-referencing kernel modules upon installation and deinstallation.</para></listitem> @@ -156,7 +156,7 @@ <entry>(none)</entry> <entry>Implies that the ports uses <filename role="package">devel/open-motif</filename> as a library - dependency. End users can set <makevar>WANT_LESSTIF</makevar> + dependency. End users can set <varname>WANT_LESSTIF</varname> for the dependency to be on <filename role="package">devel/lesstif</filename> instead of <filename role="package">devel/open-motif</filename>.</entry> @@ -225,7 +225,7 @@ <entry>(none), port</entry> <entry>Implies that the port uses <application>readline</application> as library dependency, and - sets <makevar>CPPFLAGS</makevar> and <makevar>LDFLAGS</makevar> as + sets <varname>CPPFLAGS</varname> and <varname>LDFLAGS</varname> as necessary.</entry> </row> @@ -250,16 +250,16 @@ <entry>A lot of software uses incorrect locations for script interpreters, most notably <filename>/usr/bin/perl</filename> and <filename>/bin/bash</filename>. This fixes shebang lines in - scripts listed in <makevar>SHEBANG_FILES</makevar>. Currently + scripts listed in <varname>SHEBANG_FILES</varname>. Currently <application>Perl</application>, <application>Python</application>, <application>Bash</application>, <application>Ruby</application>, and <application>PHP</application> are supported by default. To - support another interpreter, set <makevar>SHEBANG_LANG</makevar> + support another interpreter, set <varname>SHEBANG_LANG</varname> (for example - <literal><makevar>SHEBANG_LANG</makevar>=lua</literal>), then - <makevar>lua_OLD_CMD</makevar> and - <makevar>lua_CMD</makevar>.</entry> + <literal>SHEBANG_LANG=lua</literal>), then + <varname>lua_OLD_CMD</varname> and + <varname>lua_CMD</varname>.</entry> </row> <row> diff --git a/en_US.ISO8859-1/books/porters-handbook/versions.xml b/en_US.ISO8859-1/books/porters-handbook/versions.xml index 87d5e1765c..362d5bb76d 100644 --- a/en_US.ISO8859-1/books/porters-handbook/versions.xml +++ b/en_US.ISO8859-1/books/porters-handbook/versions.xml @@ -2812,7 +2812,7 @@ <entry>800005</entry> <entry>December 4, 2007</entry> <entry>8.0-CURRENT after changes to the jumbo frame - allocator (rev <svnref>174247</svnref>).</entry> + allocator (rev <revnumber>174247</revnumber>).</entry> </row> <row> @@ -3032,7 +3032,7 @@ <entry>8.0-CURRENT after added &man.write.2; support for &man.psm.4; in native operation level. Now arbitrary commands can be written to - <devicename>/dev/psm%d</devicename> and status can be + <filename>/dev/psm%d</filename> and status can be read back from it.</entry> </row> @@ -3811,7 +3811,7 @@ <entry>8.2-STABLE after introduction of the new extensible sysctl(3) interface NET_RT_IFLISTL to query address lists (rev - <svnref>231769</svnref>).</entry> + <revnumber>231769</revnumber>).</entry> </row> <row> @@ -4213,7 +4213,7 @@ it was never committed: <entry>9.0-STABLE after introduction of the new extensible sysctl(3) interface NET_RT_IFLISTL to query address lists (rev - <svnref>231768</svnref>).</entry> + <revnumber>231768</revnumber>).</entry> </row> <row> @@ -4221,7 +4221,7 @@ it was never committed: <entry>March 3, 2012</entry> <entry>9.0-STABLE after changes related to mounting of filesystem inside a jail (rev - <svnref>232728</svnref>).</entry> + <revnumber>232728</revnumber>).</entry> </row> <row> @@ -4230,7 +4230,7 @@ it was never committed: <entry>9.0-STABLE after introduction of new tcp(4) socket options: TCP_KEEPINIT, TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT (rev - <svnref>232945</svnref>).</entry> + <revnumber>232945</revnumber>).</entry> </row> <row> @@ -4239,7 +4239,7 @@ it was never committed: <entry>9.0-STABLE after introduction of the <function>quick_exit</function> function and related changes required for C++11 (rev - <svnref>235786</svnref>).</entry> + <revnumber>235786</revnumber>).</entry> </row> <row> @@ -4259,8 +4259,8 @@ it was never committed: <entry>901501</entry> <entry>November 11, 2012</entry> <entry>9.1-STABLE after LIST_PREV() added to queue.h - (rev <svnref>242893</svnref>) and KBI change in USB - serial devices (rev <svnref>240659</svnref>).</entry> + (rev <revnumber>242893</revnumber>) and KBI change in USB + serial devices (rev <revnumber>240659</revnumber>).</entry> </row> <row> @@ -4289,7 +4289,7 @@ it was never committed: <entry>901505</entry> <entry>June 13, 2013</entry> <entry>9.1-STABLE after fixes in ctfmerge bootstrapping - (rev <svnref>249243</svnref>).</entry> + (rev <revnumber>249243</revnumber>).</entry> </row> <row> @@ -4297,7 +4297,7 @@ it was never committed: <entry>August 3, 2013</entry> <entry><literal>releng/9.2</literal> branched from <literal>stable/9</literal> - (rev <svnref>253912</svnref>).</entry> + (rev <revnumber>253912</revnumber>).</entry> </row> <row> @@ -4305,7 +4305,7 @@ it was never committed: <entry>August 2, 2013</entry> <entry>9.2-STABLE after creation of <literal>releng/9.2</literal> branch - (rev <svnref>253913</svnref>).</entry> + (rev <revnumber>253913</revnumber>).</entry> </row> <row> @@ -4326,9 +4326,9 @@ it was never committed: <entry>December 12, 2011</entry> <entry>10-CURRENT after defining boolean true/false in sys/types.h, sizeof(bool) may have changed (rev - <svnref>228444</svnref>). 10-CURRENT after xlocale.h + <revnumber>228444</revnumber>). 10-CURRENT after xlocale.h was introduced (rev - <svnref>227753</svnref>).</entry> + <revnumber>227753</revnumber>).</entry> </row> <row> @@ -4336,9 +4336,9 @@ it was never committed: <entry>December 16, 2011</entry> <entry>10-CURRENT after major changes to carp(4), changing size of struct in_aliasreq, - struct in6_aliasreq (rev <svnref>228571</svnref>) + struct in6_aliasreq (rev <revnumber>228571</revnumber>) and straitening arguments check of SIOCAIFADDR (rev - <svnref>228574</svnref>).</entry> + <revnumber>228574</revnumber>).</entry> </row> <row> @@ -4346,7 +4346,7 @@ it was never committed: <entry>January 1, 2012</entry> <entry>10-CURRENT after the removal of skpc(9) and the addition of memcchr(9) (rev - <svnref>229200</svnref>).</entry> + <revnumber>229200</revnumber>).</entry> </row> <row> @@ -4355,7 +4355,7 @@ it was never committed: <entry>10-CURRENT after the removal of support for SIOCSIFADDR, SIOCSIFNETMASK, SIOCSIFBRDADDR, SIOCSIFDSTADDR ioctls (rev - <svnref>230207</svnref>).</entry> + <revnumber>230207</revnumber>).</entry> </row> <row> @@ -4363,7 +4363,7 @@ it was never committed: <entry>January 26, 2012</entry> <entry>10-CURRENT after introduction of read capacity data asynchronous notification in the cam(4) layer - (rev <svnref>230590</svnref>).</entry> + (rev <revnumber>230590</revnumber>).</entry> </row> <row> @@ -4372,7 +4372,7 @@ it was never committed: <entry>10-CURRENT after introduction of new tcp(4) socket options: TCP_KEEPINIT, TCP_KEEPIDLE, TCP_KEEPINTVL, and TCP_KEEPCNT (rev - <svnref>231025</svnref>).</entry> + <revnumber>231025</revnumber>).</entry> </row> <row> @@ -4381,84 +4381,84 @@ it was never committed: <entry>10-CURRENT after introduction of the new extensible sysctl(3) interface NET_RT_IFLISTL to query address lists (rev - <svnref>231505</svnref>).</entry> + <revnumber>231505</revnumber>).</entry> </row> <row> <entry>1000009</entry> <entry>February 25, 2012</entry> <entry>10-CURRENT after import of libarchive 3.0.3 - (rev <svnref>232153</svnref>).</entry> + (rev <revnumber>232153</revnumber>).</entry> </row> <row> <entry>1000010</entry> <entry>March 31, 2012</entry> <entry>10-CURRENT after xlocale cleanup (rev - <svnref>233757</svnref>).</entry> + <revnumber>233757</revnumber>).</entry> </row> <row> <entry>1000011</entry> <entry>April 16, 2012</entry> <entry>10-CURRENT import of LLVM/Clang 3.1 trunk r154661 - (rev <svnref>234353</svnref>).</entry> + (rev <revnumber>234353</revnumber>).</entry> </row> <row> <entry>1000012</entry> <entry>May 2, 2012</entry> <entry>10-CURRENT jemalloc import - (rev <svnref>234924</svnref>).</entry> + (rev <revnumber>234924</revnumber>).</entry> </row> <row> <entry>1000013</entry> <entry>May 22, 2012</entry> <entry>10-CURRENT after byacc import - (rev <svnref>235788</svnref>).</entry> + (rev <revnumber>235788</revnumber>).</entry> </row> <row> <entry>1000014</entry> <entry>June 27, 2012</entry> <entry>10-CURRENT after BSD sort becoming the default - sort (rev <svnref>237629</svnref>).</entry> + sort (rev <revnumber>237629</revnumber>).</entry> </row> <row> <entry>1000015</entry> <entry>July 12, 2012</entry> <entry>10-CURRENT after import of OpenSSL 1.0.1c - (rev <svnref>238405</svnref>).</entry> + (rev <revnumber>238405</revnumber>).</entry> </row> <row> <entry>(not changed)</entry> <entry>July 13, 2012</entry> <entry>10-CURRENT after the fix for LLVM/Clang 3.1 - regression (rev <svnref>238429</svnref>).</entry> + regression (rev <revnumber>238429</revnumber>).</entry> </row> <row> <entry>1000016</entry> <entry>August 8, 2012</entry> <entry>10-CURRENT after KBI change in &man.ucom.4; - (rev <svnref>239179</svnref>).</entry> + (rev <revnumber>239179</revnumber>).</entry> </row> <row> <entry>1000017</entry> <entry>August 8, 2012</entry> <entry>10-CURRENT after adding streams feature to the - USB stack (rev <svnref>239214</svnref>).</entry> + USB stack (rev <revnumber>239214</revnumber>).</entry> </row> <row> <entry>1000018</entry> <entry>September 8, 2012</entry> <entry>10-CURRENT after major rewrite of &man.pf.4; - (rev <svnref>240233</svnref>).</entry> + (rev <revnumber>240233</revnumber>).</entry> </row> <row> @@ -4466,7 +4466,7 @@ it was never committed: <entry>October 6, 2012</entry> <entry>10-CURRENT after &man.pfil.9; KBI/KPI changed to supply packets in net byte order to AF_INET - filter hooks (rev <svnref>241245</svnref>).</entry> + filter hooks (rev <revnumber>241245</revnumber>).</entry> </row> <row> @@ -4474,7 +4474,7 @@ it was never committed: <entry>October 16, 2012</entry> <entry>10-CURRENT after the network interface cloning KPI changed and struct if_clone becoming opaque (rev - <svnref>241610</svnref>).</entry> + <revnumber>241610</revnumber>).</entry> </row> <row> @@ -4483,8 +4483,8 @@ it was never committed: <entry>10-CURRENT after removal of support for non-MPSAFE filesystems and addition of support for FUSEFS (rev - <svnref>241519</svnref>, - <svnref>241897</svnref>).</entry> + <revnumber>241519</revnumber>, + <revnumber>241897</revnumber>).</entry> </row> <row> @@ -4492,7 +4492,7 @@ it was never committed: <entry>October 22, 2012</entry> <entry>10-CURRENT after the entire IPv4 stack switched to network byte order for IP packet header storage - (rev <svnref>241913</svnref>).</entry> + (rev <revnumber>241913</revnumber>).</entry> </row> <row> @@ -4502,7 +4502,7 @@ it was never committed: serial driver code, to temporarily store characters if the TTY buffer is full. Add flow stop and start signals when this happens (rev - <svnref>242619</svnref>).</entry> + <revnumber>242619</revnumber>).</entry> </row> <row> @@ -4510,7 +4510,7 @@ it was never committed: <entry>November 5, 2012</entry> <entry>10-CURRENT after clang was made the default compiler on i386 and amd64 - (rev <svnref>242624</svnref>).</entry> + (rev <revnumber>242624</revnumber>).</entry> </row> <row> @@ -4522,14 +4522,14 @@ it was never committed: the userland via sysctl or routing socket. This means the KAME-specific embedded scope id in sin6_addr.s6_addr[2] is always cleared in userland - application (rev <svnref>243443</svnref>).</entry> + application (rev <revnumber>243443</revnumber>).</entry> </row> <row> <entry>1000026</entry> <entry>January 11, 2013</entry> <entry>10-CURRENT after install gained the -N flag (rev - <svnref>245313</svnref>). May also be used to + <revnumber>245313</revnumber>). May also be used to indicate the presence of nmtree.</entry> </row> @@ -4537,7 +4537,7 @@ it was never committed: <entry>1000027</entry> <entry>January 29, 2013</entry> <entry>10-CURRENT after cat gained the -l flag (rev - <svnref>246083</svnref>).</entry> + <revnumber>246083</revnumber>).</entry> </row> <row> @@ -4545,7 +4545,7 @@ it was never committed: <entry>February 13, 2013</entry> <entry>10-CURRENT after USB moved to the driver structure requiring a rebuild of all USB modules (rev - <svnref>246759</svnref>).</entry> + <revnumber>246759</revnumber>).</entry> </row> <row> @@ -4553,7 +4553,7 @@ it was never committed: <entry>March 4, 2013</entry> <entry>10-CURRENT after the introduction of tickless callout facility which also changed the layout of - struct callout (rev <svnref>247777</svnref>).</entry> + struct callout (rev <revnumber>247777</revnumber>).</entry> </row> <row> @@ -4561,7 +4561,7 @@ it was never committed: <entry>March 12, 2013</entry> <entry>10-CURRENT after KPI breakage introduced in the VM subsystem to support read/write locking (rev - <svnref>248084</svnref>).</entry> + <revnumber>248084</revnumber>).</entry> </row> <row> @@ -4570,7 +4570,7 @@ it was never committed: <entry>10-CURRENT after the dst parameter of the ifnet <function>if_output</function> method was changed to take const qualifier (rev - <svnref>249925</svnref>).</entry> + <revnumber>249925</revnumber>).</entry> </row> <row> @@ -4578,16 +4578,16 @@ it was never committed: <entry>May 1, 2013</entry> <entry>10-CURRENT after the introduction of the <function>accept4</function> (rev - <svnref>250154</svnref>) and + <revnumber>250154</revnumber>) and <function>pipe2</function> (rev - <svnref>250159</svnref>) system calls.</entry> + <revnumber>250159</revnumber>) system calls.</entry> </row> <row> <entry>1000033</entry> <entry>May 21, 2013</entry> <entry>10-CURRENT after flex 2.5.37 import (rev - <svnref>250881</svnref>).</entry> + <revnumber>250881</revnumber>).</entry> </row> <row> @@ -4611,7 +4611,7 @@ it was never committed: <function>log10l</function>, <function>log1pl</function>, <function>expm1l</function> (rev - <svnref>251294</svnref>).</entry> + <revnumber>251294</revnumber>).</entry> </row> <row> @@ -4619,7 +4619,7 @@ it was never committed: <entry>June 8, 2013</entry> <entry>10-CURRENT after the introduction of the <function>aio_mlock</function> system call (rev - <svnref>251526</svnref>).</entry> + <revnumber>251526</revnumber>).</entry> </row> <row> @@ -4628,7 +4628,7 @@ it was never committed: <entry>10-CURRENT after the addition of a new function to the kernel GSSAPI module's function call interface (rev - <svnref>253049</svnref>).</entry> + <revnumber>253049</revnumber>).</entry> </row> <row> @@ -4653,7 +4653,7 @@ it was never committed: <literal>pimstat</literal>, <literal>rip6stat</literal>, <literal>udpstat</literal> (rev - <svnref>253081</svnref>).</entry> + <revnumber>253081</revnumber>).</entry> </row> <row> @@ -4662,7 +4662,7 @@ it was never committed: <entry>10-CURRENT after making <literal>ARM EABI</literal> the default ABI on arm, armeb, armv6, and armv6eb architectures - (rev <svnref>253396</svnref>).</entry> + (rev <revnumber>253396</revnumber>).</entry> </row> <row> @@ -4670,14 +4670,14 @@ it was never committed: <entry>July 22, 2013</entry> <entry>10-CURRENT after <literal>CAM</literal> and &man.mps.4; driver scanning changes - (rev <svnref>253549</svnref>).</entry> + (rev <revnumber>253549</revnumber>).</entry> </row> <row> <entry>1000040</entry> <entry>July 24, 2013</entry> <entry>10-CURRENT after addition of libusb - pkgconf files (rev <svnref>253638</svnref>).</entry> + pkgconf files (rev <revnumber>253638</revnumber>).</entry> </row> <row> @@ -4687,7 +4687,7 @@ it was never committed: <function>time_second</function> to <function>time_uptime</function> in <literal>PF_INET6</literal> - (rev <svnref>253970</svnref>).</entry> + (rev <revnumber>253970</revnumber>).</entry> </row> <row> @@ -4695,19 +4695,19 @@ it was never committed: <entry>August 9, 2013</entry> <entry>10-CURRENT after VM subsystem change to unify soft and hard busy mechanisms - (rev <svnref>254138</svnref>).</entry> + (rev <revnumber>254138</revnumber>).</entry> </row> <row> <entry>1000043</entry> <entry>August 13, 2013</entry> - <entry>10-CURRENT after <makevar>WITH_ICONV</makevar> is + <entry>10-CURRENT after <varname>WITH_ICONV</varname> is enabled by default. A new &man.src.conf.5; option, - <makevar>WITH_LIBICONV_COMPAT</makevar> (disabled by + <varname>WITH_LIBICONV_COMPAT</varname> (disabled by default) adds <function>libiconv_open</function> to provide compatibility with the <package>libiconv</package> port (rev - <svnref>254273</svnref>).</entry> + <revnumber>254273</revnumber>).</entry> </row> <row> @@ -4716,8 +4716,8 @@ it was never committed: <entry>10-CURRENT after <literal>libc.so</literal> conversion to an &man.ld.1; script (rev - <svnref>251668</svnref>, - <svnref>254358</svnref>).</entry> + <revnumber>251668</revnumber>, + <revnumber>254358</revnumber>).</entry> </row> <row> @@ -4727,7 +4727,7 @@ it was never committed: change by replacing the cdevsw flag <literal>D_UNMAPPED_IO</literal> with the struct cdev flag <literal>SI_UNMAPPED</literal> (rev - <svnref>254389</svnref>).</entry> + <revnumber>254389</revnumber>).</entry> </row> <row> @@ -4736,8 +4736,8 @@ it was never committed: <entry>10-CURRENT after addition of <literal>M_PROTO[9-12]</literal> and removal of <literal>M_FRAG|M_FIRSTFRAG|M_LASTFRAG</literal> - mbuf flags (rev <svnref>254524</svnref>, - <svnref>254526</svnref>).</entry> + mbuf flags (rev <revnumber>254524</revnumber>, + <revnumber>254526</revnumber>).</entry> </row> <row> @@ -4746,7 +4746,7 @@ it was never committed: <entry>10-CURRENT after &man.stat.2; update to allow storing some Windows/DOS and CIFS file attributes as &man.stat.2; flags (rev - <svnref>254627</svnref>).</entry> + <revnumber>254627</revnumber>).</entry> </row> <row> @@ -4754,7 +4754,7 @@ it was never committed: <entry>August 22, 2013</entry> <entry>10-CURRENT after modification of structure <literal>xsctp_inpcb</literal> - (rev <svnref>254672</svnref>).</entry> + (rev <revnumber>254672</revnumber>).</entry> </row> <row> @@ -4763,7 +4763,7 @@ it was never committed: <entry>10-CURRENT after &man.physio.9; support for devices that do not function properly with split I/O, such as &man.sa.4; (rev - <svnref>254760</svnref>).</entry> + <revnumber>254760</revnumber>).</entry> </row> <row> @@ -4771,17 +4771,17 @@ it was never committed: <entry>August 24, 2013</entry> <entry>10-CURRENT after modifications of structure <literal>mbuf</literal> - (rev <svnref>254780</svnref>, <svnref>254799</svnref>, - <svnref>254804</svnref>, <svnref>254807</svnref> - <svnref>254842</svnref>).</entry> + (rev <revnumber>254780</revnumber>, <revnumber>254799</revnumber>, + <revnumber>254804</revnumber>, <revnumber>254807</revnumber> + <revnumber>254842</revnumber>).</entry> </row> <row> <entry>1000051</entry> <entry>August 25, 2013</entry> <entry>10-CURRENT after Radeon KMS driver import - (rev <svnref>254885</svnref>, - <svnref>254887</svnref>).</entry> + (rev <revnumber>254885</revnumber>, + <revnumber>254887</revnumber>).</entry> </row> <row> @@ -4789,7 +4789,7 @@ it was never committed: <entry>September 3, 2013</entry> <entry>10-CURRENT after import of NetBSD <literal>libexecinfo</literal> is connected to the - build (rev <svnref>255180</svnref>).</entry> + build (rev <revnumber>255180</revnumber>).</entry> </row> <row> @@ -4797,7 +4797,7 @@ it was never committed: <entry>September 6, 2013</entry> <entry>10-CURRENT after API and ABI changes to the Capsicum framework (rev - <svnref>255305</svnref>).</entry> + <revnumber>255305</revnumber>).</entry> </row> <row> @@ -4805,7 +4805,7 @@ it was never committed: <entry>September 6, 2013</entry> <entry>10-CURRENT after <literal>gcc</literal> and <literal>libstdc++</literal> are no longer built by - default (rev <svnref>255321</svnref>).</entry> + default (rev <revnumber>255321</revnumber>).</entry> </row> <row> @@ -4813,19 +4813,19 @@ it was never committed: <entry>September 6, 2013</entry> <entry>10-CURRENT after addition of <literal>MMAP_32BIT</literal> &man.mmap.2; flag - (rev <svnref>255426</svnref>).</entry> + (rev <revnumber>255426</revnumber>).</entry> </row> <row> <entry>1000500</entry> <entry>October 10, 2013</entry> <entry>10-STABLE after branch from <literal>head/</literal> - (rev <svnref>256283</svnref>).</entry> + (rev <revnumber>256283</revnumber>).</entry> </row> <row> <entry>1100000</entry> <entry>October 10, 2013</entry> <entry>11.0-CURRENT. - (rev <svnref>256284</svnref>).</entry> + (rev <revnumber>256284</revnumber>).</entry> </row> diff --git a/en_US.ISO8859-1/share/xml/catalog b/en_US.ISO8859-1/share/xml/catalog deleted file mode 100644 index 2422c1740c..0000000000 --- a/en_US.ISO8859-1/share/xml/catalog +++ /dev/null @@ -1,2 +0,0 @@ -PUBLIC "-//FreeBSD//DOCUMENT DocBook Stylesheet//EN" - "freebsd.dsl" diff --git a/en_US.ISO8859-1/share/xml/entities.ent b/en_US.ISO8859-1/share/xml/entities.ent index e5a3813abe..ffd135e39a 100644 --- a/en_US.ISO8859-1/share/xml/entities.ent +++ b/en_US.ISO8859-1/share/xml/entities.ent @@ -6,9 +6,6 @@ <!ENTITY % freebsd PUBLIC "-//FreeBSD//ENTITIES DocBook Miscellaneous FreeBSD Entities//EN" "../../../share/xml/freebsd.ent"> %freebsd; -<!ENTITY % glossary PUBLIC "-//FreeBSD//ENTITIES DocBook Glossary Entities//EN" - "glossary.ent"> -%glossary; <!ENTITY % teams PUBLIC "-//FreeBSD//ENTITIES DocBook Team Entities//EN" "teams.ent"> %teams; diff --git a/en_US.ISO8859-1/share/xml/freebsd.dsl b/en_US.ISO8859-1/share/xml/freebsd.dsl deleted file mode 100644 index 30c745f542..0000000000 --- a/en_US.ISO8859-1/share/xml/freebsd.dsl +++ /dev/null @@ -1,14 +0,0 @@ -<!-- $FreeBSD$ --> - -<!DOCTYPE style-sheet PUBLIC "-//James Clark//DTD DSSSL Style Sheet//EN" [ -<!ENTITY freebsd.dsl PUBLIC "-//FreeBSD//DOCUMENT DocBook Language Neutral Stylesheet//EN" CDATA DSSSL> -]> - -<style-sheet> - <style-specification use="docbook"> - <style-specification-body> - </style-specification-body> - </style-specification> - - <external-specification id="docbook" document="freebsd.dsl"> -</style-sheet> diff --git a/en_US.ISO8859-1/share/xml/glossary.ent b/en_US.ISO8859-1/share/xml/glossary.ent index 4e2b6290b1..2e4d6ada14 100644 --- a/en_US.ISO8859-1/share/xml/glossary.ent +++ b/en_US.ISO8859-1/share/xml/glossary.ent @@ -31,9 +31,7 @@ the main text. --> - -<!ENTITY freebsd-glossary ' -<glossary status="draft" id="freebsd-glossary"> +<glossary xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" status="draft" xml:id="freebsd-glossary"> <title>&os; Glossary</title> <para>This glossary contains terms and acronyms used within the &os; community and documentation.</para> @@ -96,7 +94,7 @@ <glosssee otherterm="atm-glossary"/> </glossentry> - <glossentry id="aml-glossary"> + <glossentry xml:id="aml-glossary"> <glossterm><acronym>ACPI</acronym> Machine Language</glossterm> <acronym>AML</acronym> <glossdef> @@ -107,7 +105,7 @@ </glossdef> </glossentry> - <glossentry id="asl-glossary"> + <glossentry xml:id="asl-glossary"> <glossterm><acronym>ACPI</acronym> Source Language</glossterm> <acronym>ASL</acronym> <glossdef> @@ -115,7 +113,7 @@ </glossdef> </glossentry> - <glossentry id="acl-glossary"> + <glossentry xml:id="acl-glossary"> <glossterm>Access Control List</glossterm> <acronym>ACL</acronym> <glossdef> @@ -124,7 +122,7 @@ </glossdef> </glossentry> - <glossentry id="acpi-glossary"> + <glossentry xml:id="acpi-glossary"> <glossterm>Advanced Configuration and Power Interface</glossterm> <acronym>ACPI</acronym> <glossdef> @@ -139,7 +137,7 @@ </glossdef> </glossentry> - <glossentry id="api-glossary"> + <glossentry xml:id="api-glossary"> <glossterm>Application Programming Interface</glossterm> <acronym>API</acronym> <glossdef> @@ -150,7 +148,7 @@ </glossdef> </glossentry> - <glossentry id="apm-glossary"> + <glossentry xml:id="apm-glossary"> <glossterm>Advanced Power Management</glossterm> <acronym>APM</acronym> <glossdef> @@ -162,39 +160,39 @@ </glossdef> </glossentry> - <glossentry id="apic-glossary"> + <glossentry xml:id="apic-glossary"> <glossterm>Advanced Programmable Interrupt Controller</glossterm> <acronym>APIC</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ata-glossary"> + <glossentry xml:id="ata-glossary"> <glossterm>Advanced Technology Attachment</glossterm> <acronym>ATA</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="atm-glossary"> + <glossentry xml:id="atm-glossary"> <glossterm>Asynchronous Transfer Mode</glossterm> <acronym>ATM</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="apop-glossary"> + <glossentry xml:id="apop-glossary"> <glossterm>Authenticated Post Office Protocol</glossterm> <acronym>APOP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="amd-glossary"> + <glossentry xml:id="amd-glossary"> <glossterm>Automatic Mount Daemon</glossterm> <acronym>AMD</acronym> <glossdef> @@ -227,7 +225,7 @@ <glosssee otherterm="bsd-glossary"/> </glossentry> - <glossentry id="bar-glossary"> + <glossentry xml:id="bar-glossary"> <glossterm>Base Address Register</glossterm> <acronym>BAR</acronym> <glossdef> @@ -236,7 +234,7 @@ </glossdef> </glossentry> - <glossentry id="bios-glossary"> + <glossentry xml:id="bios-glossary"> <glossterm>Basic Input/Output System</glossterm> <acronym>BIOS</acronym> <glossdef> @@ -251,7 +249,7 @@ </glossdef> </glossentry> - <glossentry id="bind-glossary"> + <glossentry xml:id="bind-glossary"> <glossterm>Berkeley Internet Name Domain</glossterm> <acronym>BIND</acronym> <glossdef> @@ -259,26 +257,26 @@ </glossdef> </glossentry> - <glossentry id="bsd-glossary"> + <glossentry xml:id="bsd-glossary"> <glossterm>Berkeley Software Distribution</glossterm> <acronym>BSD</acronym> <glossdef> <para>This is the name that the Computer Systems Research Group - (CSRG) at <ulink url="http://www.berkeley.edu">The University - of California at Berkeley</ulink> + (CSRG) at <link xlink:href="http://www.berkeley.edu">The University + of California at Berkeley</link> gave to their improvements and modifications to AT&T's 32V &unix;. &os; is a descendant of the CSRG work.</para> </glossdef> </glossentry> - <glossentry id="bikeshed-glossary"> + <glossentry xml:id="bikeshed-glossary"> <glossterm>Bikeshed Building</glossterm> <glossdef subject="FreeBSD"> <para>A phenomenon whereby many people will give an opinion on an uncomplicated topic, whilst a complex topic receives little or no discussion. See the - <ulink url="&url.books.faq;/misc.html#BIKESHED-PAINTING">FAQ</ulink> for + <link xlink:href="&url.books.faq;/misc.html#BIKESHED-PAINTING">FAQ</link> for the origin of the term.</para> </glossdef> </glossentry> @@ -322,7 +320,7 @@ <glosssee otherterm="cvs-glossary"/> </glossentry> - <glossentry id="cd-glossary"> + <glossentry xml:id="cd-glossary"> <glossterm>Carrier Detect</glossterm> <acronym>CD</acronym> <glossdef> @@ -331,7 +329,7 @@ </glossdef> </glossentry> - <glossentry id="cpu-glossary"> + <glossentry xml:id="cpu-glossary"> <glossterm>Central Processing Unit</glossterm> <acronym>CPU</acronym> <glossdef> @@ -343,7 +341,7 @@ </glossdef> </glossentry> - <glossentry id="chap-glossary"> + <glossentry xml:id="chap-glossary"> <glossterm>Challenge Handshake Authentication Protocol</glossterm> <acronym>CHAP</acronym> <glossdef> @@ -352,15 +350,15 @@ </glossdef> </glossentry> - <glossentry id="clip-glossary"> + <glossentry xml:id="clip-glossary"> <glossterm>Classical <acronym>IP</acronym> over <acronym>ATM</acronym></glossterm> <acronym>CLIP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="cts-glossary"> + <glossentry xml:id="cts-glossary"> <glossterm>Clear To Send</glossterm> <acronym>CTS</acronym> <glossdef> @@ -370,15 +368,15 @@ </glossdef> </glossentry> - <glossentry id="coff-glossary"> + <glossentry xml:id="coff-glossary"> <glossterm>Common Object File Format</glossterm> <acronym>COFF</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="cvs-glossary"> + <glossentry xml:id="cvs-glossary"> <glossterm>Concurrent Versions System</glossterm> <acronym>CVS</acronym> <glossdef> @@ -439,15 +437,15 @@ <glosssee otherterm="dvmrp-glossary"/> </glossentry> - <glossentry id="dac-glossary"> + <glossentry xml:id="dac-glossary"> <glossterm>Discretionary Access Control</glossterm> <acronym>DAC</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="des-glossary"> + <glossentry xml:id="des-glossary"> <glossterm>Data Encryption Standard</glossterm> <acronym>DES</acronym> <glossdef> @@ -457,7 +455,7 @@ </glossdef> </glossentry> - <glossentry id="dsr-glossary"> + <glossentry xml:id="dsr-glossary"> <glossterm>Data Set Ready</glossterm> <acronym>DSR</acronym> <glossdef> @@ -468,7 +466,7 @@ </glossdef> </glossentry> - <glossentry id="dtr-glossary"> + <glossentry xml:id="dtr-glossary"> <glossterm>Data Terminal Ready</glossterm> <acronym>DTR</acronym> <glossdef> @@ -478,7 +476,7 @@ </glossdef> </glossentry> - <glossentry id="ddb-glossary"> + <glossentry xml:id="ddb-glossary"> <glossterm>Debugger</glossterm> <acronym>DDB</acronym> <glossdef> @@ -488,7 +486,7 @@ </glossdef> </glossentry> - <glossentry id="dsdt-glossary"> + <glossentry xml:id="dsdt-glossary"> <glossterm>Differentiated System Description Table</glossterm> <acronym>DSDT</acronym> <glossdef> @@ -497,15 +495,15 @@ </glossdef> </glossentry> - <glossentry id="dvmrp-glossary"> + <glossentry xml:id="dvmrp-glossary"> <glossterm>Distance-Vector Multicast Routing Protocol</glossterm> <acronym>DVMRP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="dns-glossary"> + <glossentry xml:id="dns-glossary"> <glossterm>Domain Name System</glossterm> <acronym>DNS</acronym> <glossdef> @@ -514,7 +512,7 @@ </glossdef> </glossentry> - <glossentry id="dhcp-glossary"> + <glossentry xml:id="dhcp-glossary"> <glossterm>Dynamic Host Configuration Protocol</glossterm> <acronym>DHCP</acronym> <glossdef> @@ -543,27 +541,27 @@ <glosssee otherterm="esp-glossary"/> </glossentry> - <glossentry id="esp-glossary"> + <glossentry xml:id="esp-glossary"> <glossterm>Encapsulated Security Payload</glossterm> <acronym>ESP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="elf-glossary"> + <glossentry xml:id="elf-glossary"> <glossterm>Executable and Linking Format</glossterm> <acronym>ELF</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ecoff-glossary"> + <glossentry xml:id="ecoff-glossary"> <glossterm>Extended <acronym>COFF</acronym></glossterm> <acronym>ECOFF</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> </glossdiv> @@ -591,23 +589,23 @@ <glosssee otherterm="ftp-glossary"/> </glossentry> - <glossentry id="fat-glossary"> + <glossentry xml:id="fat-glossary"> <glossterm>File Allocation Table</glossterm> <acronym>FAT</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="fat16-glossary"> + <glossentry xml:id="fat16-glossary"> <glossterm>File Allocation Table (16-bit)</glossterm> <acronym>FAT16</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ftp-glossary"> + <glossentry xml:id="ftp-glossary"> <glossterm>File Transfer Protocol</glossterm> <acronym>FTP</acronym> <glossdef> @@ -617,11 +615,11 @@ </glossdef> </glossentry> - <glossentry id="fadt-glossary"> + <glossentry xml:id="fadt-glossary"> <glossterm>Fixed <acronym>ACPI</acronym> Description Table</glossterm> <acronym>FADT</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> </glossdiv> @@ -634,7 +632,7 @@ <glosssee otherterm="gui-glossary"/> </glossentry> - <glossentry id="giant-glossary"> + <glossentry xml:id="giant-glossary"> <glossterm>Giant</glossterm> <glossdef subject="FreeBSD"> <para>The name of a mutual exclusion mechanism @@ -650,7 +648,7 @@ </glossdef> </glossentry> - <glossentry id="gui-glossary"> + <glossentry xml:id="gui-glossary"> <glossterm>Graphical User Interface</glossterm> <acronym>GUI</acronym> <glossdef> @@ -673,15 +671,15 @@ <glosssee otherterm="hup-glossary"/> </glossentry> - <glossentry id="hup-glossary"> + <glossentry xml:id="hup-glossary"> <glossterm>HangUp</glossterm> <acronym>HUP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="html-glossary"> + <glossentry xml:id="html-glossary"> <glossterm>HyperText Markup Language</glossterm> <acronym>HTML</acronym> <glossdef> @@ -738,15 +736,15 @@ <glosssee otherterm="isp-glossary"/> </glossentry> - <glossentry id="ipfw-glossary"> + <glossentry xml:id="ipfw-glossary"> <glossterm><acronym>IP</acronym> Firewall</glossterm> <acronym>IPFW</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ipv4-glossary"> + <glossentry xml:id="ipv4-glossary"> <glossterm><acronym>IP</acronym> Version 4</glossterm> <acronym>IPv4</acronym> <glossdef> @@ -757,7 +755,7 @@ </glossdef> </glossentry> - <glossentry id="ipv6-glossary"> + <glossentry xml:id="ipv6-glossary"> <glossterm><acronym>IP</acronym> Version 6</glossterm> <acronym>IPv6</acronym> <glossdef> @@ -767,15 +765,15 @@ </glossdef> </glossentry> - <glossentry id="io-glossary"> + <glossentry xml:id="io-glossary"> <glossterm>Input/Output</glossterm> <acronym>I/O</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="iasl-glossary"> + <glossentry xml:id="iasl-glossary"> <glossterm>Intel’s <acronym>ASL</acronym> compiler</glossterm> <acronym>IASL</acronym> <glossdef> @@ -784,7 +782,7 @@ </glossdef> </glossentry> - <glossentry id="imap-glossary"> + <glossentry xml:id="imap-glossary"> <glossterm>Internet Message Access Protocol</glossterm> <acronym>IMAP</acronym> <glossdef> @@ -795,15 +793,15 @@ </glossdef> </glossentry> - <glossentry id="ipp-glossary"> + <glossentry xml:id="ipp-glossary"> <glossterm>Internet Printing Protocol</glossterm> <acronym>IPP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ip-glossary"> + <glossentry xml:id="ip-glossary"> <glossterm>Internet Protocol</glossterm> <acronym>IP</acronym> <glossdef> @@ -812,12 +810,12 @@ Defense and an extremely important part of the <acronym>TCP/IP </acronym> stack. Without the Internet Protocol, the Internet would not have become what it is today. For more information, see - <ulink url="ftp://ftp.rfc-editor.org/in-notes/rfc791.txt"> - RFC 791</ulink>.</para> + <link xlink:href="ftp://ftp.rfc-editor.org/in-notes/rfc791.txt"> + RFC 791</link>.</para> </glossdef> </glossentry> - <glossentry id="isp-glossary"> + <glossentry xml:id="isp-glossary"> <glossterm>Internet Service Provider</glossterm> <acronym>ISP</acronym> <glossdef> @@ -829,12 +827,11 @@ <glossdiv> <title>K</title> - <glossentry id="kame-glossary"> + <glossentry xml:id="kame-glossary"> <glossterm>KAME</glossterm> <glossdef> <para>Japanese for <quote>turtle</quote>, the term KAME is used - in computing circles to refer to the <ulink - url="http://www.kame.net/">KAME Project</ulink>, who work on + in computing circles to refer to the <link xlink:href="http://www.kame.net/">KAME Project</link>, who work on an implementation of <acronym>IPv6</acronym>.</para> </glossdef> </glossentry> @@ -864,7 +861,7 @@ <glosssee otherterm="kbps-glossary"/> </glossentry> - <glossentry id="kld-glossary"> + <glossentry xml:id="kld-glossary"> <glossterm>Kernel &man.ld.1;</glossterm> <acronym>KLD</acronym> <glossdef> @@ -873,33 +870,32 @@ </glossdef> </glossentry> - <glossentry id="kse-glossary"> + <glossentry xml:id="kse-glossary"> <glossterm>Kernel Scheduler Entities</glossterm> <acronym>KSE</acronym> <glossdef> - <para>A kernel-supported threading system. See the <ulink - url="http://www.FreeBSD.org/kse">project home page</ulink> + <para>A kernel-supported threading system. See the <link xlink:href="http://www.FreeBSD.org/kse">project home page</link> for further details.</para> </glossdef> </glossentry> - <glossentry id="kva-glossary"> + <glossentry xml:id="kva-glossary"> <glossterm>Kernel Virtual Address</glossterm> <acronym>KVA</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="kdc-glossary"> + <glossentry xml:id="kdc-glossary"> <glossterm>Key Distribution Center</glossterm> <acronym>KDC</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="kbps-glossary"> + <glossentry xml:id="kbps-glossary"> <glossterm>Kilo Bits Per Second</glossterm> <acronym>Kbps</acronym> <glossdef> @@ -928,15 +924,15 @@ <glosssee otherterm="lpd-glossary"/> </glossentry> - <glossentry id="lpd-glossary"> + <glossentry xml:id="lpd-glossary"> <glossterm>Line Printer Daemon</glossterm> <acronym>LPD</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="lan-glossary"> + <glossentry xml:id="lan-glossary"> <glossterm>Local Area Network</glossterm> <acronym>LAN</acronym> <glossdef> @@ -945,7 +941,7 @@ </glossdef> </glossentry> - <glossentry id="lor-glossary"> + <glossentry xml:id="lor-glossary"> <glossterm>Lock Order Reversal</glossterm> <acronym>LOR</acronym> <glossdef> @@ -961,8 +957,8 @@ <para>True positive LORs tend to get fixed quickly, so check &a.current.url; and the - <ulink url="http://sources.zabbadoz.net/freebsd/lor.html"> - LORs Seen</ulink> page before posting to the mailing lists.</para> + <link xlink:href="http://sources.zabbadoz.net/freebsd/lor.html"> + LORs Seen</link> page before posting to the mailing lists.</para> </glossdef> </glossentry> </glossdiv> @@ -1020,7 +1016,7 @@ <glosssee otherterm="mua-glossary"/> </glossentry> - <glossentry id="mta-glossary"> + <glossentry xml:id="mta-glossary"> <glossterm>Mail Transfer Agent</glossterm> <acronym>MTA</acronym> <glossdef> @@ -1032,7 +1028,7 @@ </glossdef> </glossentry> - <glossentry id="mua-glossary"> + <glossentry xml:id="mua-glossary"> <glossterm>Mail User Agent</glossterm> <acronym>MUA</acronym> <glossdef> @@ -1040,23 +1036,23 @@ </glossdef> </glossentry> - <glossentry id="mac-glossary"> + <glossentry xml:id="mac-glossary"> <glossterm>Mandatory Access Control</glossterm> <acronym>MAC</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="mit-glossary"> + <glossentry xml:id="mit-glossary"> <glossterm>Massachusetts Institute of Technology</glossterm> <acronym>MIT</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="mfc-glossary"> + <glossentry xml:id="mfc-glossary"> <glossterm>Merge From Current</glossterm> <acronym>MFC</acronym> <glossdef subject="FreeBSD"> @@ -1065,7 +1061,7 @@ </glossdef> </glossentry> - <glossentry id="mfp4-glossary"> + <glossentry xml:id="mfp4-glossary"> <glossterm>Merge From Perforce</glossterm> <acronym>MFP4</acronym> <glossdef subject="FreeBSD"> @@ -1075,7 +1071,7 @@ </glossdef> </glossentry> - <glossentry id="mfs-glossary"> + <glossentry xml:id="mfs-glossary"> <glossterm>Merge From Stable</glossterm> <acronym>MFS</acronym> <glossdef subject="FreeBSD"> @@ -1090,7 +1086,7 @@ </glossdef> </glossentry> - <glossentry id="motd-glossary"> + <glossentry xml:id="motd-glossary"> <glossterm>Message Of The Day</glossterm> <acronym>MOTD</acronym> <glossdef> @@ -1099,19 +1095,19 @@ </glossdef> </glossentry> - <glossentry id="mls-glossary"> + <glossentry xml:id="mls-glossary"> <glossterm>Multi-Level Security</glossterm> <acronym>MLS</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="madt-glossary"> + <glossentry xml:id="madt-glossary"> <glossterm>Multiple <acronym>APIC</acronym> Description Table</glossterm> <acronym>MADT</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> </glossdiv> @@ -1144,7 +1140,7 @@ <glosssee otherterm="ntp-glossary"/> </glossentry> - <glossentry id="nat-glossary"> + <glossentry xml:id="nat-glossary"> <glossterm>Network Address Translation</glossterm> <acronym>NAT</acronym> <glossdef> @@ -1154,15 +1150,15 @@ </glossdef> </glossentry> - <glossentry id="nfs-glossary"> + <glossentry xml:id="nfs-glossary"> <glossterm>Network File System</glossterm> <acronym>NFS</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ntfs-glossary"> + <glossentry xml:id="ntfs-glossary"> <glossterm>New Technology File System</glossterm> <acronym>NTFS</acronym> <glossdef> @@ -1172,7 +1168,7 @@ </glossdef> </glossentry> - <glossentry id="ntp-glossary"> + <glossentry xml:id="ntp-glossary"> <glossterm>Network Time Protocol</glossterm> <acronym>NTP</acronym> <glossdef> @@ -1199,15 +1195,15 @@ <glosssee otherterm="os-glossary"/> </glossentry> - <glossentry id="odmr-glossary"> + <glossentry xml:id="odmr-glossary"> <glossterm>On-Demand Mail Relay</glossterm> <acronym>ODMR</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="os-glossary"> + <glossentry xml:id="os-glossary"> <glossterm>Operating System</glossterm> <acronym>OS</acronym> <glossdef> @@ -1221,7 +1217,7 @@ </glossdef> </glossentry> - <glossentry id="obe-glossary"> + <glossentry xml:id="obe-glossary"> <glossterm>Overtaken By Events</glossterm> <acronym>OBE</acronym> <glossdef> @@ -1312,19 +1308,19 @@ <glosssee otherterm="pppoe-glossary"/> </glossentry> - <glossentry id="pppoa-glossary"> + <glossentry xml:id="pppoa-glossary"> <glossterm><acronym>PPP</acronym> over <acronym>ATM</acronym></glossterm> <acronym>PPPoA</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pppoe-glossary"> + <glossentry xml:id="pppoe-glossary"> <glossterm><acronym>PPP</acronym> over <acronym>Ethernet</acronym></glossterm> <acronym>PPPoE</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> @@ -1338,19 +1334,19 @@ <glosssee otherterm="pxe-glossary"/> </glossentry> - <glossentry id="pap-glossary"> + <glossentry xml:id="pap-glossary"> <glossterm>Password Authentication Protocol</glossterm> <acronym>PAP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="perforce-glossary"> + <glossentry xml:id="perforce-glossary"> <glossterm>Perforce</glossterm> <glossdef> <para>A source code control product made by - <ulink url="http://www.perforce.com/">Perforce Software</ulink> + <link xlink:href="http://www.perforce.com/">Perforce Software</link> which is more advanced than CVS. Although not open source, its use is free of charge to open-source projects such as &os;.</para> @@ -1360,23 +1356,23 @@ </glossdef> </glossentry> - <glossentry id="pc-glossary"> + <glossentry xml:id="pc-glossary"> <glossterm>Personal Computer</glossterm> <acronym>PC</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pcnfsd-glossary"> + <glossentry xml:id="pcnfsd-glossary"> <glossterm>Personal Computer Network File System Daemon</glossterm> <acronym>PCNFSD</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pae-glossary"> + <glossentry xml:id="pae-glossary"> <glossterm>Physical Address Extensions</glossterm> <acronym>PAE</acronym> <glossdef> @@ -1386,23 +1382,23 @@ </glossdef> </glossentry> - <glossentry id="pam-glossary"> + <glossentry xml:id="pam-glossary"> <glossterm>Pluggable Authentication Modules</glossterm> <acronym>PAM</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ppp-glossary"> + <glossentry xml:id="ppp-glossary"> <glossterm>Point-to-Point Protocol</glossterm> <acronym>PPP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pointyhat"> + <glossentry xml:id="pointyhat"> <glossterm>Pointy Hat</glossterm> <glossdef subject="FreeBSD"> <para>A mythical piece of headgear, much like a @@ -1415,24 +1411,24 @@ </glossdef> </glossentry> - <glossentry id="pdf-glossary"> + <glossentry xml:id="pdf-glossary"> <glossterm>Portable Document Format</glossterm> <acronym>PDF</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pop-glossary"> + <glossentry xml:id="pop-glossary"> <glossterm>Post Office Protocol</glossterm> <acronym>POP</acronym> <glossdef> - <para></para> + <para/> <glossseealso otherterm="pop3-glossary"/> </glossdef> </glossentry> - <glossentry id="pop3-glossary"> + <glossentry xml:id="pop3-glossary"> <glossterm>Post Office Protocol Version 3</glossterm> <acronym>POP3</acronym> <glossdef> @@ -1443,23 +1439,23 @@ </glossdef> </glossentry> - <glossentry id="ppd-glossary"> + <glossentry xml:id="ppd-glossary"> <glossterm>PostScript Printer Description</glossterm> <acronym>PPD</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pxe-glossary"> + <glossentry xml:id="pxe-glossary"> <glossterm>Preboot eXecution Environment</glossterm> <acronym>PXE</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="pola-glossary"> + <glossentry xml:id="pola-glossary"> <glossterm>Principle Of Least Astonishment</glossterm> <acronym>POLA</acronym> <glossdef> @@ -1473,18 +1469,18 @@ </glossdef> </glossentry> - <glossentry id="pr-glossary"> + <glossentry xml:id="pr-glossary"> <glossterm>Problem Report</glossterm> <acronym>PR</acronym> <glossdef> <para>A description of some kind of problem that has been found in either the &os; source or documentation. See - <ulink url="&url.articles.problem-reports;/index.html"> - Writing &os; Problem Reports</ulink>.</para> + <link xlink:href="&url.articles.problem-reports;/index.html"> + Writing &os; Problem Reports</link>.</para> </glossdef> </glossentry> - <glossentry id="pid-glossary"> + <glossentry xml:id="pid-glossary"> <glossterm>Process ID</glossterm> <acronym>PID</acronym> <glossdef> @@ -1493,7 +1489,7 @@ </glossdef> </glossentry> - <glossentry id="projectevil-glossary"> + <glossentry xml:id="projectevil-glossary"> <glossterm>Project Evil</glossterm> <glossdef subject="FreeBSD"> <para>The working title for the <acronym>NDISulator</acronym>, @@ -1557,15 +1553,15 @@ <glosssee otherterm="rts-glossary"/> </glossentry> - <glossentry id="ram-glossary"> + <glossentry xml:id="ram-glossary"> <glossterm>Random Access Memory</glossterm> <acronym>RAM</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="rcs-glossary"> + <glossentry xml:id="rcs-glossary"> <glossterm>Revision Control System</glossterm> <acronym>RCS</acronym> <glossdef> @@ -1586,7 +1582,7 @@ </glossdef> </glossentry> - <glossentry id="rd-glossary"> + <glossentry xml:id="rd-glossary"> <glossterm>Received Data</glossterm> <acronym>RD</acronym> <glossdef> @@ -1596,7 +1592,7 @@ </glossdef> </glossentry> - <glossentry id="rs232c-glossary"> + <glossentry xml:id="rs232c-glossary"> <glossterm>Recommended Standard 232C</glossterm> <acronym>RS232C</acronym> <glossdef> @@ -1604,7 +1600,7 @@ </glossdef> </glossentry> - <glossentry id="risc-glossary"> + <glossentry xml:id="risc-glossary"> <glossterm>Reduced Instruction Set Computer</glossterm> <acronym>RISC</acronym> <glossdef> @@ -1617,19 +1613,19 @@ </glossdef> </glossentry> - <glossentry id="raid-glossary"> + <glossentry xml:id="raid-glossary"> <glossterm>Redundant Array of Inexpensive Disks</glossterm> <acronym>RAID</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="rpc-glossary"> + <glossentry xml:id="rpc-glossary"> <glossterm>Remote Procedure Call</glossterm> <acronym>RPC</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> @@ -1638,7 +1634,7 @@ <glosssee otherterm="repocopy-glossary"/> </glossentry> - <glossentry id="repocopy-glossary"> + <glossentry xml:id="repocopy-glossary"> <glossterm>Repository Copy</glossterm> <glossdef> <para>A direct copying of files within the CVS repository.</para> @@ -1659,13 +1655,13 @@ </glossdef> </glossentry> - <glossentry id="rfc-glossary"> + <glossentry xml:id="rfc-glossary"> <glossterm>Request For Comments</glossterm> <acronym>RFC</acronym> <glossdef> <para>A set of documents defining Internet standards, protocols, and so forth. See - <ulink url="http://www.rfc-editor.org/">www.rfc-editor.org</ulink>. + <link xlink:href="http://www.rfc-editor.org/">www.rfc-editor.org</link>. </para> <para>Also used as a general term when someone has a suggested change @@ -1673,7 +1669,7 @@ </glossdef> </glossentry> - <glossentry id="rts-glossary"> + <glossentry xml:id="rts-glossary"> <glossterm>Request To Send</glossterm> <acronym>RTS</acronym> <glossdef> @@ -1683,11 +1679,11 @@ </glossdef> </glossentry> - <glossentry id="ra-glossary"> + <glossentry xml:id="ra-glossary"> <glossterm>Router Advertisement</glossterm> <acronym>RA</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> </glossdiv> @@ -1745,23 +1741,23 @@ <glosssee otherterm="svn-glossary"/> </glossentry> - <glossentry id="smtpauth-glossary"> + <glossentry xml:id="smtpauth-glossary"> <glossterm><acronym>SMTP</acronym> Authentication</glossterm> <acronym>SMTP AUTH</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="smb-glossary"> + <glossentry xml:id="smb-glossary"> <glossterm>Server Message Block</glossterm> <acronym>SMB</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="sg-glossary"> + <glossentry xml:id="sg-glossary"> <glossterm>Signal Ground</glossterm> <acronym>SG</acronym> <glossdef> @@ -1770,31 +1766,31 @@ </glossdef> </glossentry> - <glossentry id="smtp-glossary"> + <glossentry xml:id="smtp-glossary"> <glossterm>Simple Mail Transfer Protocol</glossterm> <acronym>SMTP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="ssh-glossary"> + <glossentry xml:id="ssh-glossary"> <glossterm>Secure Shell</glossterm> <acronym>SSH</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="scsi-glossary"> + <glossentry xml:id="scsi-glossary"> <glossterm>Small Computer System Interface</glossterm> <acronym>SCSI</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="svn-glossary"> + <glossentry xml:id="svn-glossary"> <glossterm>Subversion</glossterm> <acronym>SVN</acronym> <glossdef> @@ -1804,27 +1800,27 @@ </glossdef> </glossentry> - <glossentry id="str-glossary"> + <glossentry xml:id="str-glossary"> <glossterm>Suspend To <acronym>RAM</acronym></glossterm> <acronym>STR</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="smp-glossary"> + <glossentry xml:id="smp-glossary"> <glossterm>Symmetric MultiProcessor</glossterm> <acronym>SMP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="sci-glossary"> + <glossentry xml:id="sci-glossary"> <glossterm>System Control Interrupt</glossterm> <acronym>SCI</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> </glossdiv> @@ -1862,15 +1858,15 @@ <glosssee otherterm="tsc-glossary"/> </glossentry> - <glossentry id="tgt-glossary"> + <glossentry xml:id="tgt-glossary"> <glossterm>Ticket-Granting Ticket</glossterm> <acronym>TGT</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> - <glossentry id="tsc-glossary"> + <glossentry xml:id="tsc-glossary"> <glossterm>Time Stamp Counter</glossterm> <acronym>TSC</acronym> <!-- From dg@, 20040814125503.GF40460@nexus.dglawrence.com --> @@ -1880,7 +1876,7 @@ </glossdef> </glossentry> - <glossentry id="tcp-glossary"> + <glossentry xml:id="tcp-glossary"> <glossterm>Transmission Control Protocol</glossterm> <acronym>TCP</acronym> <glossdef> @@ -1890,7 +1886,7 @@ </glossdef> </glossentry> - <glossentry id="tcpip-glossary"> + <glossentry xml:id="tcpip-glossary"> <glossterm>Transmission Control Protocol/Internet Protocol</glossterm> <acronym>TCP/IP</acronym> <glossdef> @@ -1900,7 +1896,7 @@ </glossdef> </glossentry> - <glossentry id="td-glossary"> + <glossentry xml:id="td-glossary"> <glossterm>Transmitted Data</glossterm> <acronym>TD</acronym> <glossdef> @@ -1910,11 +1906,11 @@ </glossdef> </glossentry> - <glossentry id="tftp-glossary"> + <glossentry xml:id="tftp-glossary"> <glossterm>Trivial <acronym>FTP</acronym></glossterm> <acronym>TFTP</acronym> <glossdef> - <para></para> + <para/> </glossdef> </glossentry> </glossdiv> @@ -1952,7 +1948,7 @@ <glosssee otherterm="usb-glossary"/> </glossentry> - <glossentry id="url-glossary"> + <glossentry xml:id="url-glossary"> <glossterm>Uniform Resource Locator</glossterm> <acronym>URL</acronym> <glossdef> @@ -1961,7 +1957,7 @@ </glossdef> </glossentry> - <glossentry id="ufs1-glossary"> + <glossentry xml:id="ufs1-glossary"> <glossterm>Unix File System Version 1</glossterm> <acronym>UFS1</acronym> <glossdef> @@ -1970,7 +1966,7 @@ </glossdef> </glossentry> - <glossentry id="ufs2-glossary"> + <glossentry xml:id="ufs2-glossary"> <glossterm>Unix File System Version 2</glossterm> <acronym>UFS2</acronym> <glossdef> @@ -1981,7 +1977,7 @@ </glossdef> </glossentry> - <glossentry id="usb-glossary"> + <glossentry xml:id="usb-glossary"> <glossterm>Universal Serial Bus</glossterm> <acronym>USB</acronym> <glossdef> @@ -1990,7 +1986,7 @@ </glossdef> </glossentry> - <glossentry id="uid-glossary"> + <glossentry xml:id="uid-glossary"> <glossterm>User ID</glossterm> <acronym>UID</acronym> <glossdef> @@ -2000,7 +1996,7 @@ </glossdef> </glossentry> - <glossentry id="udp-glossary"> + <glossentry xml:id="udp-glossary"> <glossterm>User Datagram Protocol</glossterm> <acronym>UDP</acronym> <glossdef> @@ -2020,7 +2016,7 @@ <glosssee otherterm="vpn-glossary"/> </glossentry> - <glossentry id="vpn-glossary"> + <glossentry xml:id="vpn-glossary"> <glossterm>Virtual Private Network</glossterm> <acronym>VPN</acronym> <glossdef> @@ -2032,4 +2028,3 @@ </glossentry> </glossdiv> </glossary> -'> diff --git a/en_US.ISO8859-1/share/xml/mailing-lists.ent b/en_US.ISO8859-1/share/xml/mailing-lists.ent index 0449230141..bdb1ab5099 100644 --- a/en_US.ISO8859-1/share/xml/mailing-lists.ent +++ b/en_US.ISO8859-1/share/xml/mailing-lists.ent @@ -5,72 +5,72 @@ --> <!ENTITY a.mailman.listinfo "http://lists.FreeBSD.org/mailman/listinfo"> -<!ENTITY a.mailman.lists "<ulink url='&a.mailman.listinfo;'>FreeBSD list server</ulink>"> -<!ENTITY a.mailman.lists.link "<ulink url='&a.mailman.listinfo;'>&a.mailman.listinfo;</ulink>"> +<!ENTITY a.mailman.lists "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mailman.listinfo;'>FreeBSD list server</link>"> +<!ENTITY a.mailman.lists.link "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mailman.listinfo;'>&a.mailman.listinfo;</link>"> <!ENTITY a.acpi.url "&a.mailman.listinfo;/freebsd-acpi"> -<!ENTITY a.acpi "<ulink url='&a.acpi.url;'>FreeBSD ACPI mailing list</ulink>"> -<!ENTITY a.acpi.name "<ulink url='&a.acpi.url;'>freebsd-acpi</ulink>"> +<!ENTITY a.acpi "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.acpi.url;'>FreeBSD ACPI mailing list</link>"> +<!ENTITY a.acpi.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.acpi.url;'>freebsd-acpi</link>"> <!ENTITY a.advocacy.url "&a.mailman.listinfo;/freebsd-advocacy"> -<!ENTITY a.advocacy "<ulink url='&a.advocacy.url;'>FreeBSD advocacy mailing list</ulink>"> -<!ENTITY a.advocacy.name "<ulink url='&a.advocacy.url;'>freebsd-advocacy</ulink>"> +<!ENTITY a.advocacy "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.advocacy.url;'>FreeBSD advocacy mailing list</link>"> +<!ENTITY a.advocacy.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.advocacy.url;'>freebsd-advocacy</link>"> <!ENTITY a.afs.url "&a.mailman.listinfo;/freebsd-afs"> -<!ENTITY a.afs "<ulink url='&a.afs.url;'>FreeBSD AFS porting mailing list</ulink>"> -<!ENTITY a.afs.name "<ulink url='&a.afs.url;'>freebsd-afs</ulink>"> +<!ENTITY a.afs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.afs.url;'>FreeBSD AFS porting mailing list</link>"> +<!ENTITY a.afs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.afs.url;'>freebsd-afs</link>"> <!ENTITY a.aic7xxx.url "&a.mailman.listinfo;/aic7xxx"> -<!ENTITY a.aic7xxx "<ulink url='&a.aic7xxx.url;'>FreeBSD Adaptec AIC7xxx discussions mailing list</ulink>"> -<!ENTITY a.aic7xxx.name "<ulink url='&a.aic7xxx.url;'>freebsd-aic7xxx</ulink>"> +<!ENTITY a.aic7xxx "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.aic7xxx.url;'>FreeBSD Adaptec AIC7xxx discussions mailing list</link>"> +<!ENTITY a.aic7xxx.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.aic7xxx.url;'>freebsd-aic7xxx</link>"> <!ENTITY a.amd64.url "&a.mailman.listinfo;/freebsd-amd64"> -<!ENTITY a.amd64 "<ulink url='&a.amd64.url;'>Porting FreeBSD to AMD64 systems</ulink>"> -<!ENTITY a.amd64.name "<ulink url='&a.amd64.url;'>freebsd-amd64</ulink>"> +<!ENTITY a.amd64 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.amd64.url;'>Porting FreeBSD to AMD64 systems</link>"> +<!ENTITY a.amd64.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.amd64.url;'>freebsd-amd64</link>"> <!ENTITY a.announce.url "&a.mailman.listinfo;/freebsd-announce"> -<!ENTITY a.announce "<ulink url='&a.announce.url;'>FreeBSD announcements mailing list</ulink>"> -<!ENTITY a.announce.name "<ulink url='&a.announce.url;'>freebsd-announce</ulink>"> +<!ENTITY a.announce "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.announce.url;'>FreeBSD announcements mailing list</link>"> +<!ENTITY a.announce.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.announce.url;'>freebsd-announce</link>"> <!ENTITY a.apache.url "&a.mailman.listinfo;/freebsd-apache"> -<!ENTITY a.apache "<ulink url='&a.apache.url;'>FreeBSD Apache mailing list</ulink>"> -<!ENTITY a.apache.name "<ulink url='&a.apache.url;'>freebsd-apache</ulink>"> +<!ENTITY a.apache "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.apache.url;'>FreeBSD Apache mailing list</link>"> +<!ENTITY a.apache.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.apache.url;'>freebsd-apache</link>"> <!ENTITY a.arch.url "&a.mailman.listinfo;/freebsd-arch"> -<!ENTITY a.arch "<ulink url='&a.arch.url;'>FreeBSD architecture and design mailing list</ulink>"> -<!ENTITY a.arch.name "<ulink url='&a.arch.url;'>freebsd-arch</ulink>"> +<!ENTITY a.arch "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.arch.url;'>FreeBSD architecture and design mailing list</link>"> +<!ENTITY a.arch.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.arch.url;'>freebsd-arch</link>"> <!ENTITY a.arm.url "&a.mailman.listinfo;/freebsd-arm"> -<!ENTITY a.arm "<ulink url='&a.arm.url;'>FreeBSD ARM porting mailing list</ulink>"> -<!ENTITY a.arm.name "<ulink url='&a.arm.url;'>freebsd-arm</ulink>"> +<!ENTITY a.arm "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.arm.url;'>FreeBSD ARM porting mailing list</link>"> +<!ENTITY a.arm.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.arm.url;'>freebsd-arm</link>"> <!ENTITY a.atm.url "&a.mailman.listinfo;/freebsd-atm"> -<!ENTITY a.atm "<ulink url='&a.atm.url;'>FreeBSD ATM networking mailing list</ulink>"> -<!ENTITY a.atm.name "<ulink url='&a.atm.url;'>freebsd-atm</ulink>"> +<!ENTITY a.atm "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.atm.url;'>FreeBSD ATM networking mailing list</link>"> +<!ENTITY a.atm.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.atm.url;'>freebsd-atm</link>"> <!ENTITY a.bluetooth.url "&a.mailman.listinfo;/freebsd-bluetooth"> -<!ENTITY a.bluetooth "<ulink url='&a.bluetooth.url;'>FreeBSD Bluetooth mailing list</ulink>"> -<!ENTITY a.bluetooth.name "<ulink url='&a.bluetooth.url;'>freebsd-bluetooth</ulink>"> +<!ENTITY a.bluetooth "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.bluetooth.url;'>FreeBSD Bluetooth mailing list</link>"> +<!ENTITY a.bluetooth.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.bluetooth.url;'>freebsd-bluetooth</link>"> <!ENTITY a.bugbusters.url "&a.mailman.listinfo;/freebsd-bugbusters"> -<!ENTITY a.bugbusters "<ulink url='&a.bugbusters.url;'>FreeBSD bugbusters mailing list</ulink>"> -<!ENTITY a.bugbusters.name "<ulink url='&a.bugbusters.url;'>freebsd-bugbusters</ulink>"> +<!ENTITY a.bugbusters "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.bugbusters.url;'>FreeBSD bugbusters mailing list</link>"> +<!ENTITY a.bugbusters.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.bugbusters.url;'>freebsd-bugbusters</link>"> <!ENTITY a.bugs.url "&a.mailman.listinfo;/freebsd-bugs"> -<!ENTITY a.bugs "<ulink url='&a.bugs.url;'>FreeBSD problem reports mailing list</ulink>"> -<!ENTITY a.bugs.name "<ulink url='&a.bugs.url;'>freebsd-bugs</ulink>"> +<!ENTITY a.bugs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.bugs.url;'>FreeBSD problem reports mailing list</link>"> +<!ENTITY a.bugs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.bugs.url;'>freebsd-bugs</link>"> <!ENTITY a.chat.url "&a.mailman.listinfo;/freebsd-chat"> -<!ENTITY a.chat "<ulink url='&a.chat.url;'>FreeBSD chat mailing list</ulink>"> -<!ENTITY a.chat.name "<ulink url='&a.chat.url;'>freebsd-chat</ulink>"> +<!ENTITY a.chat "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.chat.url;'>FreeBSD chat mailing list</link>"> +<!ENTITY a.chat.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.chat.url;'>freebsd-chat</link>"> <!ENTITY a.chromium.url "&a.mailman.listinfo;/freebsd-chromium"> -<!ENTITY a.chromium "<ulink url='&a.chromium.url;'>FreeBSD-specific Chromium issues</ulink>"> -<!ENTITY a.chromium.name "<ulink url='&a.chromium.url;'>freebsd-chromium</ulink>"> +<!ENTITY a.chromium "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.chromium.url;'>FreeBSD-specific Chromium issues</link>"> +<!ENTITY a.chromium.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.chromium.url;'>freebsd-chromium</link>"> <!ENTITY a.cluster.url "&a.mailman.listinfo;/freebsd-cluster"> -<!ENTITY a.cluster "<ulink url='&a.cluster.url;'>FreeBSD clustering mailing list</ulink>"> -<!ENTITY a.cluster.name "<ulink url='&a.cluster.url;'>freebsd-cluster</ulink>"> +<!ENTITY a.cluster "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cluster.url;'>FreeBSD clustering mailing list</link>"> +<!ENTITY a.cluster.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cluster.url;'>freebsd-cluster</link>"> <!ENTITY a.committers "FreeBSD committer's mailing list"> <!ENTITY a.committers.name "cvs-committers"> @@ -78,87 +78,87 @@ <!ENTITY a.core.name "freebsd-core"> <!ENTITY a.current.url "&a.mailman.listinfo;/freebsd-current"> -<!ENTITY a.current "<ulink url='&a.current.url;'>&os.current; mailing list</ulink>"> -<!ENTITY a.current.name "<ulink url='&a.current.url;'>freebsd-current</ulink>"> +<!ENTITY a.current "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.current.url;'>&os.current; mailing list</link>"> +<!ENTITY a.current.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.current.url;'>freebsd-current</link>"> <!ENTITY a.ctm-announce.url "&a.mailman.listinfo;/ctm-announce"> -<!ENTITY a.ctm-announce "<ulink url='&a.ctm-announce.url;'>CTM announcements</ulink>"> -<!ENTITY a.ctm-announce.name "<ulink url='&a.ctm-announce.url;'>ctm-announce</ulink>"> +<!ENTITY a.ctm-announce "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-announce.url;'>CTM announcements</link>"> +<!ENTITY a.ctm-announce.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-announce.url;'>ctm-announce</link>"> <!ENTITY a.ctm-src-4.url "&a.mailman.listinfo;/ctm-src-4"> -<!ENTITY a.ctm-src-4 "<ulink url='&a.ctm-src-4.url;'>CTM 4-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-4.name "<ulink url='&a.ctm-src-4.url;'>ctm-src-4</ulink>"> +<!ENTITY a.ctm-src-4 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-4.url;'>CTM 4-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-4.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-4.url;'>ctm-src-4</link>"> <!ENTITY a.ctm-src-5.url "&a.mailman.listinfo;/ctm-src-5"> -<!ENTITY a.ctm-src-5 "<ulink url='&a.ctm-src-5.url;'>CTM 5-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-5.name "<ulink url='&a.ctm-src-5.url;'>ctm-src-5</ulink>"> +<!ENTITY a.ctm-src-5 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-5.url;'>CTM 5-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-5.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-5.url;'>ctm-src-5</link>"> <!ENTITY a.ctm-src-6.url "&a.mailman.listinfo;/ctm-src-6"> -<!ENTITY a.ctm-src-6 "<ulink url='&a.ctm-src-6.url;'>CTM 6-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-6.name "<ulink url='&a.ctm-src-6.url;'>ctm-src-6</ulink>"> +<!ENTITY a.ctm-src-6 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-6.url;'>CTM 6-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-6.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-6.url;'>ctm-src-6</link>"> <!ENTITY a.ctm-src-7.url "&a.mailman.listinfo;/ctm-src-7"> -<!ENTITY a.ctm-src-7 "<ulink url='&a.ctm-src-7.url;'>CTM 7-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-7.name "<ulink url='&a.ctm-src-7.url;'>ctm-src-7</ulink>"> +<!ENTITY a.ctm-src-7 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-7.url;'>CTM 7-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-7.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-7.url;'>ctm-src-7</link>"> <!ENTITY a.ctm-src-8.url "&a.mailman.listinfo;/ctm-src-8"> -<!ENTITY a.ctm-src-8 "<ulink url='&a.ctm-src-8.url;'>CTM 8-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-8.name "<ulink url='&a.ctm-src-8.url;'>ctm-src-8</ulink>"> +<!ENTITY a.ctm-src-8 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-8.url;'>CTM 8-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-8.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-8.url;'>ctm-src-8</link>"> <!ENTITY a.ctm-src-9.url "&a.mailman.listinfo;/ctm-src-9"> -<!ENTITY a.ctm-src-9 "<ulink url='&a.ctm-src-9.url;'>CTM 9-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-9.name "<ulink url='&a.ctm-src-9.url;'>ctm-src-9</ulink>"> +<!ENTITY a.ctm-src-9 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-9.url;'>CTM 9-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-9.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-9.url;'>ctm-src-9</link>"> <!ENTITY a.ctm-src-10.url "&a.mailman.listinfo;/ctm-src-10"> -<!ENTITY a.ctm-src-10 "<ulink url='&a.ctm-src-10.url;'>CTM 10-STABLE src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-10.name "<ulink url='&a.ctm-src-10.url;'>ctm-src-10</ulink>"> +<!ENTITY a.ctm-src-10 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-10.url;'>CTM 10-STABLE src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-10.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-10.url;'>ctm-src-10</link>"> <!ENTITY a.ctm-src-cur.url "&a.mailman.listinfo;/ctm-src-cur"> -<!ENTITY a.ctm-src-cur "<ulink url='&a.ctm-src-cur.url;'>CTM -CURRENT src branch distribution mailing list</ulink>"> -<!ENTITY a.ctm-src-cur.name "<ulink url='&a.ctm-src-cur.url;'>ctm-src-cur</ulink>"> +<!ENTITY a.ctm-src-cur "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-cur.url;'>CTM -CURRENT src branch distribution mailing list</link>"> +<!ENTITY a.ctm-src-cur.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-src-cur.url;'>ctm-src-cur</link>"> <!ENTITY a.ctm-users.url "&a.mailman.listinfo;/ctm-users"> -<!ENTITY a.ctm-users "<ulink url='&a.ctm-users.url;'>CTM user discussion mailing list</ulink>"> -<!ENTITY a.ctm-users.name "<ulink url='&a.ctm-users.url;'>ctm-users</ulink>"> +<!ENTITY a.ctm-users "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-users.url;'>CTM user discussion mailing list</link>"> +<!ENTITY a.ctm-users.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ctm-users.url;'>ctm-users</link>"> <!ENTITY a.cvsall.url "&a.mailman.listinfo;/cvs-all"> -<!ENTITY a.cvsall "<ulink url='&a.cvsall.url;'>FreeBSD CVS commit message mailing list</ulink>"> -<!ENTITY a.cvsall.name "<ulink url='&a.cvsall.url;'>cvs-all</ulink>"> +<!ENTITY a.cvsall "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvsall.url;'>FreeBSD CVS commit message mailing list</link>"> +<!ENTITY a.cvsall.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvsall.url;'>cvs-all</link>"> <!ENTITY a.cvs-doc.url "&a.mailman.listinfo;/cvs-doc"> -<!ENTITY a.cvs-doc "<ulink url='&a.cvs-doc.url;'>FreeBSD CVS doc commit list</ulink>"> -<!ENTITY a.cvs-doc.name "<ulink url='&a.cvs-doc.url;'>cvs-doc</ulink>"> +<!ENTITY a.cvs-doc "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-doc.url;'>FreeBSD CVS doc commit list</link>"> +<!ENTITY a.cvs-doc.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-doc.url;'>cvs-doc</link>"> <!ENTITY a.cvs-ports.url "&a.mailman.listinfo;/cvs-ports"> -<!ENTITY a.cvs-ports "<ulink url='&a.cvs-ports.url;'>FreeBSD CVS ports commit list</ulink>"> -<!ENTITY a.cvs-ports.name "<ulink url='&a.cvs-ports.url;'>cvs-ports</ulink>"> +<!ENTITY a.cvs-ports "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-ports.url;'>FreeBSD CVS ports commit list</link>"> +<!ENTITY a.cvs-ports.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-ports.url;'>cvs-ports</link>"> <!ENTITY a.cvs-projects.url "&a.mailman.listinfo;/cvs-projects"> -<!ENTITY a.cvs-projects "<ulink url='&a.cvs-projects.url;'>FreeBSD CVS projects commit list</ulink>"> -<!ENTITY a.cvs-projects.name "<ulink url='&a.cvs-projects.url;'>cvs-projects</ulink>"> +<!ENTITY a.cvs-projects "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-projects.url;'>FreeBSD CVS projects commit list</link>"> +<!ENTITY a.cvs-projects.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-projects.url;'>cvs-projects</link>"> <!ENTITY a.cvs-src.url "&a.mailman.listinfo;/cvs-src"> -<!ENTITY a.cvs-src "<ulink url='&a.cvs-src.url;'>FreeBSD CVS src commit list</ulink>"> -<!ENTITY a.cvs-src.name "<ulink url='&a.cvs-src.url;'>cvs-src</ulink>"> +<!ENTITY a.cvs-src "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-src.url;'>FreeBSD CVS src commit list</link>"> +<!ENTITY a.cvs-src.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvs-src.url;'>cvs-src</link>"> <!ENTITY a.cvsweb.url "&a.mailman.listinfo;/freebsd-cvsweb"> -<!ENTITY a.cvsweb "<ulink url='&a.cvsweb.url;'>FreeBSD CVSweb maintenance mailing list</ulink>"> -<!ENTITY a.cvsweb.name "<ulink url='&a.cvsweb.url;'>freebsd-cvsweb</ulink>"> +<!ENTITY a.cvsweb "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvsweb.url;'>FreeBSD CVSweb maintenance mailing list</link>"> +<!ENTITY a.cvsweb.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.cvsweb.url;'>freebsd-cvsweb</link>"> <!ENTITY a.database.url "&a.mailman.listinfo;/freebsd-database"> -<!ENTITY a.database "<ulink url='&a.database.url;'>FreeBSD based Databases mailing list</ulink>"> -<!ENTITY a.database.name "<ulink url='&a.database.url;'>freebsd-database</ulink>"> +<!ENTITY a.database "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.database.url;'>FreeBSD based Databases mailing list</link>"> +<!ENTITY a.database.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.database.url;'>freebsd-database</link>"> <!ENTITY a.desktop.url "&a.mailman.listinfo;/freebsd-desktop"> -<!ENTITY a.desktop "<ulink url='&a.desktop.url;'>Using and improving &os; on the desktop</ulink>"> -<!ENTITY a.desktop.name "<ulink url='&a.desktop.url;'>freebsd-desktop</ulink>"> +<!ENTITY a.desktop "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.desktop.url;'>Using and improving &os; on the desktop</link>"> +<!ENTITY a.desktop.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.desktop.url;'>freebsd-desktop</link>"> <!ENTITY a.developers "FreeBSD developers mailing list"> <!ENTITY a.developers.name "freebsd-developers"> <!ENTITY a.doc.url "&a.mailman.listinfo;/freebsd-doc"> -<!ENTITY a.doc "<ulink url='&a.doc.url;'>FreeBSD documentation project mailing list</ulink>"> -<!ENTITY a.doc.name "<ulink url='&a.doc.url;'>freebsd-doc</ulink>"> +<!ENTITY a.doc "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.doc.url;'>FreeBSD documentation project mailing list</link>"> +<!ENTITY a.doc.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.doc.url;'>freebsd-doc</link>"> <!ENTITY a.doc-committers "FreeBSD doc/ committer's mailing list"> <!ENTITY a.doc-committers.name "doc-committers"> @@ -167,194 +167,194 @@ <!ENTITY a.doc-developers.name "doc-developers"> <!ENTITY a.drivers.url "&a.mailman.listinfo;/freebsd-drivers"> -<!ENTITY a.drivers "<ulink url='&a.drivers.url;'>Writing device drivers for FreeBSD</ulink>"> -<!ENTITY a.drivers.name "<ulink url='&a.drivers.url;'>freebsd-drivers</ulink>"> +<!ENTITY a.drivers "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.drivers.url;'>Writing device drivers for FreeBSD</link>"> +<!ENTITY a.drivers.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.drivers.url;'>freebsd-drivers</link>"> <!ENTITY a.dtrace.url "&a.mailman.listinfo;/freebsd-dtrace"> -<!ENTITY a.dtrace "<ulink url='&a.dtrace.url;'>Using and working on DTrace in &os;.</ulink>"> -<!ENTITY a.dtrace.name "<ulink url='&a.dtrace.url;'>freebsd-dtrace</ulink>"> +<!ENTITY a.dtrace "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.dtrace.url;'>Using and working on DTrace in &os;.</link>"> +<!ENTITY a.dtrace.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.dtrace.url;'>freebsd-dtrace</link>"> <!ENTITY a.eclipse.url "&a.mailman.listinfo;/freebsd-eclipse"> -<!ENTITY a.eclipse "<ulink url='&a.eclipse.url;'>FreeBSD users of Eclipse IDE, tools, rich client applications and ports</ulink>"> -<!ENTITY a.eclipse.name "<ulink url='&a.eclipse.url;'>freebsd-eclipse</ulink>"> +<!ENTITY a.eclipse "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.eclipse.url;'>FreeBSD users of Eclipse IDE, tools, rich client applications and ports</link>"> +<!ENTITY a.eclipse.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.eclipse.url;'>freebsd-eclipse</link>"> <!ENTITY a.embedded.url "&a.mailman.listinfo;/freebsd-embedded"> -<!ENTITY a.embedded "<ulink url='&a.embedded.url;'>FreeBSD-embedded mailing list</ulink>"> -<!ENTITY a.embedded.name "<ulink url='&a.embedded.url;'>freebsd-embedded</ulink>"> +<!ENTITY a.embedded "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.embedded.url;'>FreeBSD-embedded mailing list</link>"> +<!ENTITY a.embedded.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.embedded.url;'>freebsd-embedded</link>"> <!ENTITY a.emulation.url "&a.mailman.listinfo;/freebsd-emulation"> -<!ENTITY a.emulation "<ulink url='&a.emulation.url;'>FreeBSD-emulation mailing list</ulink>"> -<!ENTITY a.emulation.name "<ulink url='&a.emulation.url;'>freebsd-emulation</ulink>"> +<!ENTITY a.emulation "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.emulation.url;'>FreeBSD-emulation mailing list</link>"> +<!ENTITY a.emulation.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.emulation.url;'>freebsd-emulation</link>"> <!ENTITY a.eol.url "&a.mailman.listinfo;/freebsd-eol"> -<!ENTITY a.eol "<ulink url='&a.eol.url;'>FreeBSD-eol mailing list</ulink>"> -<!ENTITY a.eol.name "<ulink url='&a.eol.url;'>freebsd-eol</ulink>"> +<!ENTITY a.eol "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.eol.url;'>FreeBSD-eol mailing list</link>"> +<!ENTITY a.eol.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.eol.url;'>freebsd-eol</link>"> <!ENTITY a.firewire.url "&a.mailman.listinfo;/freebsd-firewire"> -<!ENTITY a.firewire "<ulink url='&a.firewire.url;'>FreeBSD FireWire (IEEE 1394) discussion mailing list</ulink>"> -<!ENTITY a.firewire.name "<ulink url='&a.firewire.url;'>freebsd-firewire</ulink>"> +<!ENTITY a.firewire "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.firewire.url;'>FreeBSD FireWire (IEEE 1394) discussion mailing list</link>"> +<!ENTITY a.firewire.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.firewire.url;'>freebsd-firewire</link>"> <!ENTITY a.fortran.url "&a.mailman.listinfo;/freebsd-fortran"> -<!ENTITY a.fortran "<ulink url='&a.fortran.url;'>Fortran on FreeBSD mailing list</ulink>"> -<!ENTITY a.fortran.name "<ulink url='&a.fortran.url;'>freebsd-fortran</ulink>"> +<!ENTITY a.fortran "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.fortran.url;'>Fortran on FreeBSD mailing list</link>"> +<!ENTITY a.fortran.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.fortran.url;'>freebsd-fortran</link>"> <!ENTITY a.fs.url "&a.mailman.listinfo;/freebsd-fs"> -<!ENTITY a.fs "<ulink url='&a.fs.url;'>FreeBSD file system project mailing list</ulink>"> -<!ENTITY a.fs.name "<ulink url='&a.fs.url;'>freebsd-fs</ulink>"> +<!ENTITY a.fs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.fs.url;'>FreeBSD file system project mailing list</link>"> +<!ENTITY a.fs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.fs.url;'>freebsd-fs</link>"> <!ENTITY a.gecko.url "&a.mailman.listinfo;/freebsd-gecko"> -<!ENTITY a.gecko "<ulink url='&a.gecko.url;'>FreeBSD gecko mailing list</ulink>"> -<!ENTITY a.gecko.name "<ulink url='&a.gecko.url;'>freebsd-gecko</ulink>"> +<!ENTITY a.gecko "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.gecko.url;'>FreeBSD gecko mailing list</link>"> +<!ENTITY a.gecko.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.gecko.url;'>freebsd-gecko</link>"> <!ENTITY a.geom.url "&a.mailman.listinfo;/freebsd-geom"> -<!ENTITY a.geom "<ulink url='&a.geom.url;'>FreeBSD GEOM mailing list</ulink>"> -<!ENTITY a.geom.name "<ulink url='&a.geom.url;'>freebsd-geom</ulink>"> +<!ENTITY a.geom "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.geom.url;'>FreeBSD GEOM mailing list</link>"> +<!ENTITY a.geom.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.geom.url;'>freebsd-geom</link>"> <!ENTITY a.gnome.url "&a.mailman.listinfo;/freebsd-gnome"> -<!ENTITY a.gnome "<ulink url='&a.gnome.url;'>FreeBSD GNOME and GNOME applications mailing list</ulink>"> -<!ENTITY a.gnome.name "<ulink url='&a.gnome.url;'>freebsd-gnome</ulink>"> +<!ENTITY a.gnome "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.gnome.url;'>FreeBSD GNOME and GNOME applications mailing list</link>"> +<!ENTITY a.gnome.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.gnome.url;'>freebsd-gnome</link>"> <!ENTITY a.hackers.url "&a.mailman.listinfo;/freebsd-hackers"> -<!ENTITY a.hackers "<ulink url='&a.hackers.url;'>FreeBSD technical discussions mailing list</ulink>"> -<!ENTITY a.hackers.name "<ulink url='&a.hackers.url;'>freebsd-hackers</ulink>"> +<!ENTITY a.hackers "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.hackers.url;'>FreeBSD technical discussions mailing list</link>"> +<!ENTITY a.hackers.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.hackers.url;'>freebsd-hackers</link>"> <!ENTITY a.hardware.url "&a.mailman.listinfo;/freebsd-hardware"> -<!ENTITY a.hardware "<ulink url='&a.hardware.url;'>FreeBSD hardware and equipment mailing list</ulink>"> -<!ENTITY a.hardware.name "<ulink url='&a.hardware.url;'>freebsd-hardware</ulink>"> +<!ENTITY a.hardware "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.hardware.url;'>FreeBSD hardware and equipment mailing list</link>"> +<!ENTITY a.hardware.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.hardware.url;'>freebsd-hardware</link>"> <!ENTITY a.hubs.url "&a.mailman.listinfo;/freebsd-hubs"> -<!ENTITY a.hubs "<ulink url='&a.hubs.url;'>FreeBSD mirror sites mailing lists</ulink>"> -<!ENTITY a.hubs.name "<ulink url='&a.hubs.url;'>freebsd-hubs</ulink>"> +<!ENTITY a.hubs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.hubs.url;'>FreeBSD mirror sites mailing lists</link>"> +<!ENTITY a.hubs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.hubs.url;'>freebsd-hubs</link>"> <!ENTITY a.i18n.url "&a.mailman.listinfo;/freebsd-i18n"> -<!ENTITY a.i18n "<ulink url='&a.i18n.url;'>FreeBSD internationalization mailing list</ulink>"> -<!ENTITY a.i18n.name "<ulink url='&a.i18n.url;'>freebsd-i18n</ulink>"> +<!ENTITY a.i18n "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.i18n.url;'>FreeBSD internationalization mailing list</link>"> +<!ENTITY a.i18n.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.i18n.url;'>freebsd-i18n</link>"> <!ENTITY a.i386.url "&a.mailman.listinfo;/freebsd-i386"> -<!ENTITY a.i386 "<ulink url='&a.i386.url;'>FreeBSD i386-specific issues mailing list</ulink>"> -<!ENTITY a.i386.name "<ulink url='&a.i386.url;'>freebsd-i386</ulink>"> +<!ENTITY a.i386 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.i386.url;'>FreeBSD i386-specific issues mailing list</link>"> +<!ENTITY a.i386.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.i386.url;'>freebsd-i386</link>"> <!ENTITY a.ia32.url "&a.mailman.listinfo;/freebsd-ia32"> -<!ENTITY a.ia32 "<ulink url='&a.ia32.url;'>FreeBSD IA32 porting mailing list</ulink>"> -<!ENTITY a.ia32.name "<ulink url='&a.ia32.url;'>freebsd-ia32</ulink>"> +<!ENTITY a.ia32 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ia32.url;'>FreeBSD IA32 porting mailing list</link>"> +<!ENTITY a.ia32.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ia32.url;'>freebsd-ia32</link>"> <!ENTITY a.ia64.url "&a.mailman.listinfo;/freebsd-ia64"> -<!ENTITY a.ia64 "<ulink url='&a.ia64.url;'>FreeBSD IA64 porting mailing list</ulink>"> -<!ENTITY a.ia64.name "<ulink url='&a.ia64.url;'>freebsd-ia64</ulink>"> +<!ENTITY a.ia64 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ia64.url;'>FreeBSD IA64 porting mailing list</link>"> +<!ENTITY a.ia64.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ia64.url;'>freebsd-ia64</link>"> <!ENTITY a.infiniband.url "&a.mailman.listinfo;/freebsd-infiniband"> -<!ENTITY a.infiniband "<ulink url='&a.infiniband.url;'>Infiniband on FreeBSD</ulink>"> -<!ENTITY a.infiniband.name "<ulink url='&a.infiniband.url;'>freebsd-infiniband</ulink>"> +<!ENTITY a.infiniband "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.infiniband.url;'>Infiniband on FreeBSD</link>"> +<!ENTITY a.infiniband.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.infiniband.url;'>freebsd-infiniband</link>"> <!ENTITY a.ipfw.url "&a.mailman.listinfo;/freebsd-ipfw"> -<!ENTITY a.ipfw "<ulink url='&a.ipfw.url;'>FreeBSD IPFW code mailing list</ulink>"> -<!ENTITY a.ipfw.name "<ulink url='&a.ipfw.url;'>freebsd-ipfw</ulink>"> +<!ENTITY a.ipfw "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ipfw.url;'>FreeBSD IPFW code mailing list</link>"> +<!ENTITY a.ipfw.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ipfw.url;'>freebsd-ipfw</link>"> <!ENTITY a.isdn.url "&a.mailman.listinfo;/freebsd-isdn"> -<!ENTITY a.isdn "<ulink url='&a.isdn.url;'>FreeBSD ISDN mailing list</ulink>"> -<!ENTITY a.isdn.name "<ulink url='&a.isdn.url;'>freebsd-isdn</ulink>"> +<!ENTITY a.isdn "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.isdn.url;'>FreeBSD ISDN mailing list</link>"> +<!ENTITY a.isdn.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.isdn.url;'>freebsd-isdn</link>"> <!ENTITY a.isp.url "&a.mailman.listinfo;/freebsd-isp"> -<!ENTITY a.isp "<ulink url='&a.isp.url;'>FreeBSD Internet service provider's mailing list</ulink>"> -<!ENTITY a.isp.name "<ulink url='&a.isp.url;'>freebsd-isp</ulink>"> +<!ENTITY a.isp "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.isp.url;'>FreeBSD Internet service provider's mailing list</link>"> +<!ENTITY a.isp.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.isp.url;'>freebsd-isp</link>"> <!ENTITY a.jail.url "&a.mailman.listinfo;/freebsd-jail"> -<!ENTITY a.jail "<ulink url='&a.jail.url;'>FreeBSD jails mailing list</ulink>"> -<!ENTITY a.jail.name "<ulink url='&a.jail.url;'>freebsd-jail</ulink>"> +<!ENTITY a.jail "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.jail.url;'>FreeBSD jails mailing list</link>"> +<!ENTITY a.jail.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.jail.url;'>freebsd-jail</link>"> <!ENTITY a.java.url "&a.mailman.listinfo;/freebsd-java"> -<!ENTITY a.java "<ulink url='&a.java.url;'>FreeBSD Java Language mailing list</ulink>"> -<!ENTITY a.java.name "<ulink url='&a.java.url;'>freebsd-java</ulink>"> +<!ENTITY a.java "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.java.url;'>FreeBSD Java Language mailing list</link>"> +<!ENTITY a.java.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.java.url;'>freebsd-java</link>"> <!ENTITY a.jobs.url "&a.mailman.listinfo;/freebsd-jobs"> -<!ENTITY a.jobs "<ulink url='&a.jobs.url;'>FreeBSD related employment mailing list</ulink>"> -<!ENTITY a.jobs.name "<ulink url='&a.jobs.url;'>freebsd-jobs</ulink>"> +<!ENTITY a.jobs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.jobs.url;'>FreeBSD related employment mailing list</link>"> +<!ENTITY a.jobs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.jobs.url;'>freebsd-jobs</link>"> <!ENTITY a.kde.url "https://mail.kde.org/mailman/listinfo/kde-freebsd"> -<!ENTITY a.kde "<ulink url='&a.kde.url;'>FreeBSD KDE/Qt and KDE applications mailing list</ulink>"> -<!ENTITY a.kde.name "<ulink url='&a.kde.url;'>freebsd-kde</ulink>"> +<!ENTITY a.kde "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.kde.url;'>FreeBSD KDE/Qt and KDE applications mailing list</link>"> +<!ENTITY a.kde.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.kde.url;'>freebsd-kde</link>"> <!ENTITY a.lfs.url "&a.mailman.listinfo;/freebsd-lfs"> -<!ENTITY a.lfs "<ulink url='&a.lfs.url;'>FreeBSD LFS porting mailing list</ulink>"> -<!ENTITY a.lfs.name "<ulink url='&a.lfs.url;'>freebsd-lfs</ulink>"> +<!ENTITY a.lfs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.lfs.url;'>FreeBSD LFS porting mailing list</link>"> +<!ENTITY a.lfs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.lfs.url;'>freebsd-lfs</link>"> <!ENTITY a.mips.url "&a.mailman.listinfo;/freebsd-mips"> -<!ENTITY a.mips "<ulink url='&a.mips.url;'>FreeBSD MIPS porting mailing list</ulink>"> -<!ENTITY a.mips.name "<ulink url='&a.mips.url;'>freebsd-mips</ulink>"> +<!ENTITY a.mips "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mips.url;'>FreeBSD MIPS porting mailing list</link>"> +<!ENTITY a.mips.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mips.url;'>freebsd-mips</link>"> <!ENTITY a.mirror-announce.url "&a.mailman.listinfo;/mirror-announce"> -<!ENTITY a.mirror-announce "<ulink url='&a.mirror-announce.url;'>FreeBSD mirror site administrators</ulink>"> -<!ENTITY a.mirror-announce.name "<ulink url='&a.mirror-announce.url;'>mirror-announce</ulink>"> +<!ENTITY a.mirror-announce "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mirror-announce.url;'>FreeBSD mirror site administrators</link>"> +<!ENTITY a.mirror-announce.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mirror-announce.url;'>mirror-announce</link>"> <!ENTITY a.mobile.url "&a.mailman.listinfo;/freebsd-mobile"> -<!ENTITY a.mobile "<ulink url='&a.mobile.url;'>FreeBSD laptop computer mailing list</ulink>"> -<!ENTITY a.mobile.name "<ulink url='&a.mobile.url;'>freebsd-mobile</ulink>"> +<!ENTITY a.mobile "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mobile.url;'>FreeBSD laptop computer mailing list</link>"> +<!ENTITY a.mobile.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mobile.url;'>freebsd-mobile</link>"> <!ENTITY a.mono.url "&a.mailman.listinfo;/freebsd-mono"> -<!ENTITY a.mono "<ulink url='&a.mono.url;'>Mono and C# applications on FreeBSD</ulink>"> -<!ENTITY a.mono.name "<ulink url='&a.mono.url;'>freebsd-mono</ulink>"> +<!ENTITY a.mono "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mono.url;'>Mono and C# applications on FreeBSD</link>"> +<!ENTITY a.mono.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.mono.url;'>freebsd-mono</link>"> <!ENTITY a.multimedia.url "&a.mailman.listinfo;/freebsd-multimedia"> -<!ENTITY a.multimedia "<ulink url='&a.multimedia.url;'>FreeBSD multimedia mailing list</ulink>"> -<!ENTITY a.multimedia.name "<ulink url='&a.multimedia.url;'>freebsd-multimedia</ulink>"> +<!ENTITY a.multimedia "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.multimedia.url;'>FreeBSD multimedia mailing list</link>"> +<!ENTITY a.multimedia.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.multimedia.url;'>freebsd-multimedia</link>"> <!ENTITY a.net.url "&a.mailman.listinfo;/freebsd-net"> -<!ENTITY a.net "<ulink url='&a.net.url;'>FreeBSD networking mailing list</ulink>"> -<!ENTITY a.net.name "<ulink url='&a.net.url;'>freebsd-net</ulink>"> +<!ENTITY a.net "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.net.url;'>FreeBSD networking mailing list</link>"> +<!ENTITY a.net.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.net.url;'>freebsd-net</link>"> <!ENTITY a.newbies.url "&a.mailman.listinfo;/freebsd-newbies"> -<!ENTITY a.newbies "<ulink url='&a.newbies.url;'>FreeBSD new users mailing list</ulink>"> -<!ENTITY a.newbies.name "<ulink url='&a.newbies.url;'>freebsd-newbies</ulink>"> +<!ENTITY a.newbies "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.newbies.url;'>FreeBSD new users mailing list</link>"> +<!ENTITY a.newbies.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.newbies.url;'>freebsd-newbies</link>"> <!ENTITY a.newbus.url "&a.mailman.listinfo;/freebsd-new-bus"> -<!ENTITY a.newbus "<ulink url='&a.newbus.url;'>FreeBSD new-bus mailing list</ulink>"> -<!ENTITY a.newbus.name "<ulink url='&a.newbus.url;'>freebsd-new-bus</ulink>"> +<!ENTITY a.newbus "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.newbus.url;'>FreeBSD new-bus mailing list</link>"> +<!ENTITY a.newbus.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.newbus.url;'>freebsd-new-bus</link>"> <!ENTITY a.numerics.url "&a.mailman.listinfo;/freebsd-numerics"> -<!ENTITY a.numerics "<ulink url='&a.numerics.url;'>Discussions of high quality implementation of libm functions</ulink>"> -<!ENTITY a.numerics.name "<ulink url='&a.numerics.url;'>freebsd-numerics</ulink>"> +<!ENTITY a.numerics "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.numerics.url;'>Discussions of high quality implementation of libm functions</link>"> +<!ENTITY a.numerics.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.numerics.url;'>freebsd-numerics</link>"> <!ENTITY a.office.url "&a.mailman.listinfo;/freebsd-office"> -<!ENTITY a.office "<ulink url='&a.office.url;'>Office applications on FreeBSD</ulink>"> -<!ENTITY a.office.name "<ulink url='&a.office.url;'>freebsd-office</ulink>"> +<!ENTITY a.office "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.office.url;'>Office applications on FreeBSD</link>"> +<!ENTITY a.office.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.office.url;'>freebsd-office</link>"> <!ENTITY a.ops-announce.url "&a.mailman.listinfo;/freebsd-ops-announce"> -<!ENTITY a.ops-announce "<ulink url='&a.ops-announce.url;'>Project Infrastructure Announcements</ulink>"> -<!ENTITY a.ops-announce.name "<ulink url='&a.ops-announce.url;'>freebsd-ops-announce</ulink>"> +<!ENTITY a.ops-announce "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ops-announce.url;'>Project Infrastructure Announcements</link>"> +<!ENTITY a.ops-announce.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ops-announce.url;'>freebsd-ops-announce</link>"> <!ENTITY a.performance.url "&a.mailman.listinfo;/freebsd-performance"> -<!ENTITY a.performance "<ulink url='&a.performance.url;'>FreeBSD performance mailing list</ulink>"> -<!ENTITY a.performance.name "<ulink url='&a.performance.url;'>freebsd-performance</ulink>"> +<!ENTITY a.performance "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.performance.url;'>FreeBSD performance mailing list</link>"> +<!ENTITY a.performance.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.performance.url;'>freebsd-performance</link>"> <!ENTITY a.perl.url "&a.mailman.listinfo;/freebsd-perl"> -<!ENTITY a.perl "<ulink url='&a.perl.url;'>FreeBSD Perl mailing list</ulink>"> -<!ENTITY a.perl.name "<ulink url='&a.perl.url;'>freebsd-perl</ulink>"> +<!ENTITY a.perl "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.perl.url;'>FreeBSD Perl mailing list</link>"> +<!ENTITY a.perl.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.perl.url;'>freebsd-perl</link>"> <!ENTITY a.pf.url "&a.mailman.listinfo;/freebsd-pf"> -<!ENTITY a.pf "<ulink url='&a.pf.url;'>FreeBSD packet filter mailing list</ulink>"> -<!ENTITY a.pf.name "<ulink url='&a.pf.url;'>freebsd-pf</ulink>"> +<!ENTITY a.pf "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.pf.url;'>FreeBSD packet filter mailing list</link>"> +<!ENTITY a.pf.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.pf.url;'>freebsd-pf</link>"> <!ENTITY a.pkg.url "&a.mailman.listinfo;/freebsd-pkg"> -<!ENTITY a.pkg "<ulink url='&a.pkg.url;'>Binary package management and package tools discussion</ulink>"> -<!ENTITY a.pkg.name "<ulink url='&a.pkg.url;'>freebsd-pkg</ulink>"> +<!ENTITY a.pkg "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.pkg.url;'>Binary package management and package tools discussion</link>"> +<!ENTITY a.pkg.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.pkg.url;'>freebsd-pkg</link>"> <!ENTITY a.pkg-fallout.url "&a.mailman.listinfo;/freebsd-pkg-fallout"> -<!ENTITY a.pkg-fallout "<ulink url='&a.pkg-fallout.url;'>Fallout logs from package building</ulink>"> -<!ENTITY a.pkg-fallout.name "<ulink url='&a.pkg-fallout.url;'>freebsd-pkg-fallout</ulink>"> +<!ENTITY a.pkg-fallout "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.pkg-fallout.url;'>Fallout logs from package building</link>"> +<!ENTITY a.pkg-fallout.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.pkg-fallout.url;'>freebsd-pkg-fallout</link>"> <!ENTITY a.platforms.url "&a.mailman.listinfo;/freebsd-platforms"> -<!ENTITY a.platforms "<ulink url='&a.platforms.url;'>FreeBSD non-Intel platforms porting mailing list</ulink>"> -<!ENTITY a.platforms.name "<ulink url='&a.platforms.url;'>freebsd-platforms</ulink>"> +<!ENTITY a.platforms "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.platforms.url;'>FreeBSD non-Intel platforms porting mailing list</link>"> +<!ENTITY a.platforms.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.platforms.url;'>freebsd-platforms</link>"> <!ENTITY a.ports.url "&a.mailman.listinfo;/freebsd-ports"> -<!ENTITY a.ports "<ulink url='&a.ports.url;'>FreeBSD ports mailing list</ulink>"> -<!ENTITY a.ports.name "<ulink url='&a.ports.url;'>freebsd-ports</ulink>"> +<!ENTITY a.ports "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ports.url;'>FreeBSD ports mailing list</link>"> +<!ENTITY a.ports.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ports.url;'>freebsd-ports</link>"> <!ENTITY a.ports-announce.url "&a.mailman.listinfo;/freebsd-ports-announce"> -<!ENTITY a.ports-announce "<ulink url='&a.ports-announce.url;'>FreeBSD ports announce mailing list</ulink>"> -<!ENTITY a.ports-announce.name "<ulink url='&a.ports-announce.url;'>freebsd-ports-announce</ulink>"> +<!ENTITY a.ports-announce "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ports-announce.url;'>FreeBSD ports announce mailing list</link>"> +<!ENTITY a.ports-announce.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ports-announce.url;'>freebsd-ports-announce</link>"> <!ENTITY a.ports-bugs.url "&a.mailman.listinfo;/freebsd-ports-bugs"> -<!ENTITY a.ports-bugs "<ulink url='&a.ports-bugs.url;'>FreeBSD ports bugs mailing list</ulink>"> -<!ENTITY a.ports-bugs.name "<ulink url='&a.ports-bugs.url;'>freebsd-ports-bugs</ulink>"> +<!ENTITY a.ports-bugs "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ports-bugs.url;'>FreeBSD ports bugs mailing list</link>"> +<!ENTITY a.ports-bugs.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ports-bugs.url;'>freebsd-ports-bugs</link>"> <!ENTITY a.ports-committers "FreeBSD ports/ committer's mailing list"> <!ENTITY a.ports-committers.name "ports-committers"> @@ -363,56 +363,56 @@ <!ENTITY a.ports-developers.name "ports-developers"> <!ENTITY a.ppc.url "&a.mailman.listinfo;/freebsd-ppc"> -<!ENTITY a.ppc "<ulink url='&a.ppc.url;'>FreeBSD PowerPC porting mailing list</ulink>"> -<!ENTITY a.ppc.name "<ulink url='&a.ppc.url;'>freebsd-ppc</ulink>"> +<!ENTITY a.ppc "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ppc.url;'>FreeBSD PowerPC porting mailing list</link>"> +<!ENTITY a.ppc.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ppc.url;'>freebsd-ppc</link>"> <!ENTITY a.proliant.url "&a.mailman.listinfo;/freebsd-proliant"> -<!ENTITY a.proliant "<ulink url='&a.proliant.url;'>Technical discussion of FreeBSD on HP ProLiant server platforms</ulink>"> -<!ENTITY a.proliant.name "<ulink url='&a.proliant.url;'>freebsd-proliant</ulink>"> +<!ENTITY a.proliant "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.proliant.url;'>Technical discussion of FreeBSD on HP ProLiant server platforms</link>"> +<!ENTITY a.proliant.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.proliant.url;'>freebsd-proliant</link>"> <!ENTITY a.python.url "&a.mailman.listinfo;/freebsd-python"> -<!ENTITY a.python "<ulink url='&a.python.url;'>FreeBSD Python mailing list</ulink>"> -<!ENTITY a.python.name "<ulink url='&a.python.url;'>freebsd-python</ulink>"> +<!ENTITY a.python "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.python.url;'>FreeBSD Python mailing list</link>"> +<!ENTITY a.python.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.python.url;'>freebsd-python</link>"> <!ENTITY a.questions.url "&a.mailman.listinfo;/freebsd-questions"> -<!ENTITY a.questions "<ulink url='&a.questions.url;'>FreeBSD general questions mailing list</ulink>"> -<!ENTITY a.questions.name "<ulink url='&a.questions.url;'>freebsd-questions</ulink>"> +<!ENTITY a.questions "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.questions.url;'>FreeBSD general questions mailing list</link>"> +<!ENTITY a.questions.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.questions.url;'>freebsd-questions</link>"> <!ENTITY a.rc.url "&a.mailman.listinfo;/freebsd-rc"> -<!ENTITY a.rc "<ulink url='&a.rc.url;'>FreeBSD boot script system mailing list</ulink>"> -<!ENTITY a.rc.name "<ulink url='&a.rc.url;'>freebsd-rc</ulink>"> +<!ENTITY a.rc "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.rc.url;'>FreeBSD boot script system mailing list</link>"> +<!ENTITY a.rc.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.rc.url;'>freebsd-rc</link>"> <!ENTITY a.realtime.url "&a.mailman.listinfo;/freebsd-realtime"> -<!ENTITY a.realtime "<ulink url='&a.realtime.url;'>FreeBSD realtime extensions mailing list</ulink>"> -<!ENTITY a.realtime.name "<ulink url='&a.realtime.url;'>freebsd-realtime</ulink>"> +<!ENTITY a.realtime "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.realtime.url;'>FreeBSD realtime extensions mailing list</link>"> +<!ENTITY a.realtime.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.realtime.url;'>freebsd-realtime</link>"> <!ENTITY a.ruby.url "&a.mailman.listinfo;/freebsd-ruby"> -<!ENTITY a.ruby "<ulink url='&a.ruby.url;'>FreeBSD Ruby mailing list</ulink>"> -<!ENTITY a.ruby.name "<ulink url='&a.ruby.url;'>freebsd-ruby</ulink>"> +<!ENTITY a.ruby "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ruby.url;'>FreeBSD Ruby mailing list</link>"> +<!ENTITY a.ruby.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.ruby.url;'>freebsd-ruby</link>"> <!ENTITY a.scsi.url "&a.mailman.listinfo;/freebsd-scsi"> -<!ENTITY a.scsi "<ulink url='&a.scsi.url;'>FreeBSD SCSI subsystem mailing list</ulink>"> -<!ENTITY a.scsi.name "<ulink url='&a.scsi.url;'>freebsd-scsi</ulink>"> +<!ENTITY a.scsi "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.scsi.url;'>FreeBSD SCSI subsystem mailing list</link>"> +<!ENTITY a.scsi.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.scsi.url;'>freebsd-scsi</link>"> <!ENTITY a.security.url "&a.mailman.listinfo;/freebsd-security"> -<!ENTITY a.security "<ulink url='&a.security.url;'>FreeBSD security mailing list</ulink>"> -<!ENTITY a.security.name "<ulink url='&a.security.url;'>freebsd-security</ulink>"> +<!ENTITY a.security "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.security.url;'>FreeBSD security mailing list</link>"> +<!ENTITY a.security.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.security.url;'>freebsd-security</link>"> <!ENTITY a.security-notifications.url "&a.mailman.listinfo;/freebsd-security-notifications"> -<!ENTITY a.security-notifications "<ulink url='&a.security-notifications.url;'>FreeBSD security notifications mailing list</ulink>"> -<!ENTITY a.security-notifications.name "<ulink url='&a.security-notifications.url;'>freebsd-security-notifications</ulink>"> +<!ENTITY a.security-notifications "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.security-notifications.url;'>FreeBSD security notifications mailing list</link>"> +<!ENTITY a.security-notifications.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.security-notifications.url;'>freebsd-security-notifications</link>"> <!ENTITY a.small.url "&a.mailman.listinfo;/freebsd-small"> -<!ENTITY a.small "<ulink url='&a.small.url;'>FreeBSD-small mailing list</ulink>"> -<!ENTITY a.small.name "<ulink url='&a.small.url;'>freebsd-small</ulink>"> +<!ENTITY a.small "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.small.url;'>FreeBSD-small mailing list</link>"> +<!ENTITY a.small.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.small.url;'>freebsd-small</link>"> <!ENTITY a.snapshots.url "&a.mailman.listinfo;/freebsd-snapshots"> -<!ENTITY a.snapshots "<ulink url='&a.snapshots.url;'>FreeBSD Development Snapshot Announcements</ulink>"> -<!ENTITY a.snapshots.name "<ulink url='&a.snapshots.url;'>freebsd-snapshots</ulink>"> +<!ENTITY a.snapshots "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.snapshots.url;'>FreeBSD Development Snapshot Announcements</link>"> +<!ENTITY a.snapshots.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.snapshots.url;'>freebsd-snapshots</link>"> <!ENTITY a.sparc.url "&a.mailman.listinfo;/freebsd-sparc64"> -<!ENTITY a.sparc "<ulink url='&a.sparc.url;'>FreeBSD SPARC porting mailing list</ulink>"> -<!ENTITY a.sparc.name "<ulink url='&a.sparc.url;'>freebsd-sparc64</ulink>"> +<!ENTITY a.sparc "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.sparc.url;'>FreeBSD SPARC porting mailing list</link>"> +<!ENTITY a.sparc.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.sparc.url;'>freebsd-sparc64</link>"> <!ENTITY a.src-committers "FreeBSD src/ committer's mailing list"> <!ENTITY a.src-committers.name "freebsd-src-committers"> @@ -421,196 +421,196 @@ <!ENTITY a.src-developers.name "freebsd-src-developers"> <!ENTITY a.stable.url "&a.mailman.listinfo;/freebsd-stable"> -<!ENTITY a.stable "<ulink url='&a.stable.url;'>&os.stable; mailing list</ulink>"> -<!ENTITY a.stable.name "<ulink url='&a.stable.url;'>freebsd-stable</ulink>"> +<!ENTITY a.stable "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.stable.url;'>&os.stable; mailing list</link>"> +<!ENTITY a.stable.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.stable.url;'>freebsd-stable</link>"> <!ENTITY a.standards.url "&a.mailman.listinfo;/freebsd-standards"> -<!ENTITY a.standards "<ulink url='&a.standards.url;'>FreeBSD C99 and POSIX compliance mailing list</ulink>"> -<!ENTITY a.standards.name "<ulink url='&a.standards.url;'>freebsd-standards</ulink>"> +<!ENTITY a.standards "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.standards.url;'>FreeBSD C99 and POSIX compliance mailing list</link>"> +<!ENTITY a.standards.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.standards.url;'>freebsd-standards</link>"> <!ENTITY a.sun4v.url "&a.mailman.listinfo;/freebsd-sun4v"> -<!ENTITY a.sun4v "<ulink url='&a.sun4v.url;'>FreeBSD sun4v porting mailing list</ulink>"> -<!ENTITY a.sun4v.name "<ulink url='&a.sun4v.url;'>freebsd-sun4v</ulink>"> +<!ENTITY a.sun4v "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.sun4v.url;'>FreeBSD sun4v porting mailing list</link>"> +<!ENTITY a.sun4v.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.sun4v.url;'>freebsd-sun4v</link>"> <!ENTITY a.svn-doc-all.url "&a.mailman.listinfo;/svn-doc-all"> -<!ENTITY a.svn-doc-all "<ulink url='&a.svn-doc-all.url;'>SVN commit messages for the entire doc tree (except for <quote>user</quote>, <quote>projects</quote> and <quote>translations</quote>)</ulink>"> -<!ENTITY a.svn-doc-all.name "<ulink url='&a.svn-doc-all.url;'>svn-doc-all</ulink>"> +<!ENTITY a.svn-doc-all "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-all.url;'>SVN commit messages for the entire doc tree (except for <quote>user</quote>, <quote>projects</quote> and <quote>translations</quote>)</link>"> +<!ENTITY a.svn-doc-all.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-all.url;'>svn-doc-all</link>"> <!ENTITY a.svn-doc-head.url "&a.mailman.listinfo;/svn-doc-head"> -<!ENTITY a.svn-doc-head "<ulink url='&a.svn-doc-head.url;'>SVN commit messages for the doc tree for head/</ulink>"> -<!ENTITY a.svn-doc-head.name "<ulink url='&a.svn-doc-head.url;'>svn-doc-head</ulink>"> +<!ENTITY a.svn-doc-head "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-head.url;'>SVN commit messages for the doc tree for head/</link>"> +<!ENTITY a.svn-doc-head.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-head.url;'>svn-doc-head</link>"> <!ENTITY a.svn-doc-projects.url "&a.mailman.listinfo;/svn-doc-projects"> -<!ENTITY a.svn-doc-projects "<ulink url='&a.svn-doc-projects.url;'>SVN commit messages for the doc <quote>projects</quote> tree</ulink>"> -<!ENTITY a.svn-doc-projects.name "<ulink url='&a.svn-doc-projects.url;'>svn-doc-projects</ulink>"> +<!ENTITY a.svn-doc-projects "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-projects.url;'>SVN commit messages for the doc <quote>projects</quote> tree</link>"> +<!ENTITY a.svn-doc-projects.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-projects.url;'>svn-doc-projects</link>"> <!ENTITY a.svn-doc-svnadmin.url "&a.mailman.listinfo;/svn-doc-svnadmin"> -<!ENTITY a.svn-doc-svnadmin "<ulink url='&a.svn-doc-svnadmin.url;'>SVN commit messages for the doc admin / configuration tree</ulink>"> -<!ENTITY a.svn-doc-svnadmin.name "<ulink url='&a.svn-doc-svnadmin.url;'>svn-doc-svnadmin</ulink>"> +<!ENTITY a.svn-doc-svnadmin "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-svnadmin.url;'>SVN commit messages for the doc admin / configuration tree</link>"> +<!ENTITY a.svn-doc-svnadmin.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-doc-svnadmin.url;'>svn-doc-svnadmin</link>"> <!ENTITY a.svn-ports-all.url "&a.mailman.listinfo;/svn-ports-all"> -<!ENTITY a.svn-ports-all "<ulink url='&a.svn-ports-all.url;'>SVN commit messages for the entire ports tree</ulink>"> -<!ENTITY a.svn-ports-all.name "<ulink url='&a.svn-ports-all.url;'>svn-ports-all</ulink>"> +<!ENTITY a.svn-ports-all "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-ports-all.url;'>SVN commit messages for the entire ports tree</link>"> +<!ENTITY a.svn-ports-all.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-ports-all.url;'>svn-ports-all</link>"> <!ENTITY a.svn-ports-head.url "&a.mailman.listinfo;/svn-ports-head"> -<!ENTITY a.svn-ports-head "<ulink url='&a.svn-ports-head.url;'>SVN commit messages for the ports tree for head/</ulink>"> -<!ENTITY a.svn-ports-head.name "<ulink url='&a.svn-ports-head.url;'>svn-ports-head</ulink>"> +<!ENTITY a.svn-ports-head "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-ports-head.url;'>SVN commit messages for the ports tree for head/</link>"> +<!ENTITY a.svn-ports-head.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-ports-head.url;'>svn-ports-head</link>"> <!ENTITY a.svn-ports-svnadmin.url "&a.mailman.listinfo;/svn-ports-svnadmin"> -<!ENTITY a.svn-ports-svnadmin "<ulink url='&a.svn-ports-svnadmin.url;'>SVN commit messages for the ports admin / configuration tree</ulink>"> -<!ENTITY a.svn-ports-svnadmin.name "<ulink url='&a.svn-ports-svnadmin.url;'>svn-ports-svnadmin</ulink>"> +<!ENTITY a.svn-ports-svnadmin "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-ports-svnadmin.url;'>SVN commit messages for the ports admin / configuration tree</link>"> +<!ENTITY a.svn-ports-svnadmin.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-ports-svnadmin.url;'>svn-ports-svnadmin</link>"> <!ENTITY a.svn-src-all.url "&a.mailman.listinfo;/svn-src-all"> -<!ENTITY a.svn-src-all "<ulink url='&a.svn-src-all.url;'>SVN commit messages for the entire src tree (except for <quote>user</quote> and <quote>projects</quote>)</ulink>"> -<!ENTITY a.svn-src-all.name "<ulink url='&a.svn-src-all.url;'>svn-src-all</ulink>"> +<!ENTITY a.svn-src-all "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-all.url;'>SVN commit messages for the entire src tree (except for <quote>user</quote> and <quote>projects</quote>)</link>"> +<!ENTITY a.svn-src-all.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-all.url;'>svn-src-all</link>"> <!ENTITY a.svn-src-head.url "&a.mailman.listinfo;/svn-src-head"> -<!ENTITY a.svn-src-head "<ulink url='&a.svn-src-head.url;'>SVN commit messages for the src tree for head/-current</ulink>"> -<!ENTITY a.svn-src-head.name "<ulink url='&a.svn-src-head.url;'>svn-src-head</ulink>"> +<!ENTITY a.svn-src-head "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-head.url;'>SVN commit messages for the src tree for head/-current</link>"> +<!ENTITY a.svn-src-head.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-head.url;'>svn-src-head</link>"> <!ENTITY a.svn-src-projects.url "&a.mailman.listinfo;/svn-src-projects"> -<!ENTITY a.svn-src-projects "<ulink url='&a.svn-src-projects.url;'>SVN commit messages for the src <quote>projects</quote> tree</ulink>"> -<!ENTITY a.svn-src-projects.name "<ulink url='&a.svn-src-projects.url;'>svn-src-projects</ulink>"> +<!ENTITY a.svn-src-projects "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-projects.url;'>SVN commit messages for the src <quote>projects</quote> tree</link>"> +<!ENTITY a.svn-src-projects.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-projects.url;'>svn-src-projects</link>"> <!ENTITY a.svn-src-release.url "&a.mailman.listinfo;/svn-src-release"> -<!ENTITY a.svn-src-release "<ulink url='&a.svn-src-release.url;'>SVN commit messages for releases in the src tree</ulink>"> -<!ENTITY a.svn-src-release.name "<ulink url='&a.svn-src-release.url;'>svn-src-release</ulink>"> +<!ENTITY a.svn-src-release "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-release.url;'>SVN commit messages for releases in the src tree</link>"> +<!ENTITY a.svn-src-release.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-release.url;'>svn-src-release</link>"> <!ENTITY a.svn-src-releng.url "&a.mailman.listinfo;/svn-src-releng"> -<!ENTITY a.svn-src-releng "<ulink url='&a.svn-src-releng.url;'>SVN commit messages for the release engineering / security commits to the src tree</ulink>"> -<!ENTITY a.svn-src-releng.name "<ulink url='&a.svn-src-releng.url;'>svn-src-releng</ulink>"> +<!ENTITY a.svn-src-releng "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-releng.url;'>SVN commit messages for the release engineering / security commits to the src tree</link>"> +<!ENTITY a.svn-src-releng.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-releng.url;'>svn-src-releng</link>"> <!ENTITY a.svn-src-stable.url "&a.mailman.listinfo;/svn-src-stable"> -<!ENTITY a.svn-src-stable "<ulink url='&a.svn-src-stable.url;'>SVN commit messages for all the -stable branches of the src tree</ulink>"> -<!ENTITY a.svn-src-stable.name "<ulink url='&a.svn-src-stable.url;'>svn-src-stable</ulink>"> +<!ENTITY a.svn-src-stable "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable.url;'>SVN commit messages for all the -stable branches of the src tree</link>"> +<!ENTITY a.svn-src-stable.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable.url;'>svn-src-stable</link>"> <!ENTITY a.svn-src-stable-6.url "&a.mailman.listinfo;/svn-src-stable-6"> -<!ENTITY a.svn-src-stable-6 "<ulink url='&a.svn-src-stable-6.url;'>SVN commit messages for only the 6-stable src tree</ulink>"> -<!ENTITY a.svn-src-stable-6.name "<ulink url='&a.svn-src-stable-6.url;'>svn-src-stable-6</ulink>"> +<!ENTITY a.svn-src-stable-6 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-6.url;'>SVN commit messages for only the 6-stable src tree</link>"> +<!ENTITY a.svn-src-stable-6.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-6.url;'>svn-src-stable-6</link>"> <!ENTITY a.svn-src-stable-7.url "&a.mailman.listinfo;/svn-src-stable-7"> -<!ENTITY a.svn-src-stable-7 "<ulink url='&a.svn-src-stable-7.url;'>SVN commit messages for only the 7-stable src tree</ulink>"> -<!ENTITY a.svn-src-stable-7.name "<ulink url='&a.svn-src-stable-7.url;'>svn-src-stable-7</ulink>"> +<!ENTITY a.svn-src-stable-7 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-7.url;'>SVN commit messages for only the 7-stable src tree</link>"> +<!ENTITY a.svn-src-stable-7.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-7.url;'>svn-src-stable-7</link>"> <!ENTITY a.svn-src-stable-8.url "&a.mailman.listinfo;/svn-src-stable-8"> -<!ENTITY a.svn-src-stable-8 "<ulink url='&a.svn-src-stable-8.url;'>SVN commit messages for only the 8-stable src tree</ulink>"> -<!ENTITY a.svn-src-stable-8.name "<ulink url='&a.svn-src-stable-8.url;'>svn-src-stable-8</ulink>"> +<!ENTITY a.svn-src-stable-8 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-8.url;'>SVN commit messages for only the 8-stable src tree</link>"> +<!ENTITY a.svn-src-stable-8.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-8.url;'>svn-src-stable-8</link>"> <!ENTITY a.svn-src-stable-9.url "&a.mailman.listinfo;/svn-src-stable-9"> -<!ENTITY a.svn-src-stable-9 "<ulink url='&a.svn-src-stable-9.url;'>SVN commit messages for only the 9-stable src tree</ulink>"> -<!ENTITY a.svn-src-stable-9.name "<ulink url='&a.svn-src-stable-9.url;'>svn-src-stable-9</ulink>"> +<!ENTITY a.svn-src-stable-9 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-9.url;'>SVN commit messages for only the 9-stable src tree</link>"> +<!ENTITY a.svn-src-stable-9.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-9.url;'>svn-src-stable-9</link>"> <!ENTITY a.svn-src-stable-10.url "&a.mailman.listinfo;/svn-src-stable-10"> -<!ENTITY a.svn-src-stable-10 "<ulink url='&a.svn-src-stable-10.url;'>SVN commit messages for only the 10-stable src tree</ulink>"> -<!ENTITY a.svn-src-stable-10.name "<ulink url='&a.svn-src-stable-10.url;'>svn-src-stable-10</ulink>"> +<!ENTITY a.svn-src-stable-10 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-10.url;'>SVN commit messages for only the 10-stable src tree</link>"> +<!ENTITY a.svn-src-stable-10.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-10.url;'>svn-src-stable-10</link>"> <!ENTITY a.svn-src-stable-other.url "&a.mailman.listinfo;/svn-src-stable-other"> -<!ENTITY a.svn-src-stable-other "<ulink url='&a.svn-src-stable-other.url;'>SVN commit messages for the old stable src trees</ulink>"> -<!ENTITY a.svn-src-stable-other.name "<ulink url='&a.svn-src-stable-other.url;'>svn-src-stable-other</ulink>"> +<!ENTITY a.svn-src-stable-other "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-other.url;'>SVN commit messages for the old stable src trees</link>"> +<!ENTITY a.svn-src-stable-other.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-stable-other.url;'>svn-src-stable-other</link>"> <!ENTITY a.svn-src-svnadmin.url "&a.mailman.listinfo;/svn-src-svnadmin"> -<!ENTITY a.svn-src-svnadmin "<ulink url='&a.svn-src-svnadmin.url;'>SVN commit messages for the admin / configuration tree</ulink>"> -<!ENTITY a.svn-src-svnadmin.name "<ulink url='&a.svn-src-svnadmin.url;'>svn-src-svnadmin</ulink>"> +<!ENTITY a.svn-src-svnadmin "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-svnadmin.url;'>SVN commit messages for the admin / configuration tree</link>"> +<!ENTITY a.svn-src-svnadmin.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-svnadmin.url;'>svn-src-svnadmin</link>"> <!ENTITY a.svn-src-user.url "&a.mailman.listinfo;/svn-src-user"> -<!ENTITY a.svn-src-user "<ulink url='&a.svn-src-user.url;'>SVN commit messages for the experimental <quote>user</quote> src tree</ulink>"> -<!ENTITY a.svn-src-user.name "<ulink url='&a.svn-src-user.url;'>svn-src-user</ulink>"> +<!ENTITY a.svn-src-user "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-user.url;'>SVN commit messages for the experimental <quote>user</quote> src tree</link>"> +<!ENTITY a.svn-src-user.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-user.url;'>svn-src-user</link>"> <!ENTITY a.svn-src-vendor.url "&a.mailman.listinfo;/svn-src-vendor"> -<!ENTITY a.svn-src-vendor "<ulink url='&a.svn-src-vendor.url;'>SVN commit messages for the vendor work area tree</ulink>"> -<!ENTITY a.svn-src-vendor.name "<ulink url='&a.svn-src-vendor.url;'>svn-src-vendor</ulink>"> +<!ENTITY a.svn-src-vendor "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-vendor.url;'>SVN commit messages for the vendor work area tree</link>"> +<!ENTITY a.svn-src-vendor.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.svn-src-vendor.url;'>svn-src-vendor</link>"> <!ENTITY a.sysinstall.url "&a.mailman.listinfo;/freebsd-sysinstall"> -<!ENTITY a.sysinstall "<ulink url='&a.sysinstall.url;'>Sysinstall development mailing list</ulink>"> -<!ENTITY a.sysinstall.name "<ulink url='&a.sysinstall.url;'>freebsd-sysinstall</ulink>"> +<!ENTITY a.sysinstall "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.sysinstall.url;'>Sysinstall development mailing list</link>"> +<!ENTITY a.sysinstall.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.sysinstall.url;'>freebsd-sysinstall</link>"> <!ENTITY a.tcltk.url "&a.mailman.listinfo;/freebsd-tcltk"> -<!ENTITY a.tcltk "<ulink url='&a.tcltk.url;'>FreeBSD-specific Tcl/Tk discussions</ulink>"> -<!ENTITY a.tcltk.name "<ulink url='&a.tcltk.url;'>freebsd-tcltk</ulink>"> +<!ENTITY a.tcltk "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tcltk.url;'>FreeBSD-specific Tcl/Tk discussions</link>"> +<!ENTITY a.tcltk.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tcltk.url;'>freebsd-tcltk</link>"> <!ENTITY a.test.url "&a.mailman.listinfo;/freebsd-test"> -<!ENTITY a.test "<ulink url='&a.test.url;'>FreeBSD test mailing list</ulink>"> -<!ENTITY a.test.name "<ulink url='&a.test.url;'>freebsd-test</ulink>"> +<!ENTITY a.test "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.test.url;'>FreeBSD test mailing list</link>"> +<!ENTITY a.test.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.test.url;'>freebsd-test</link>"> <!ENTITY a.testing.url "&a.mailman.listinfo;/freebsd-testing"> -<!ENTITY a.testing "<ulink url='&a.testing.url;'>Testing on &os;</ulink>"> -<!ENTITY a.testing.name "<ulink url='&a.testing.url;'>freebsd-testing</ulink>"> +<!ENTITY a.testing "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.testing.url;'>Testing on &os;</link>"> +<!ENTITY a.testing.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.testing.url;'>freebsd-testing</link>"> <!ENTITY a.tex.url "&a.mailman.listinfo;/freebsd-tex"> -<!ENTITY a.tex "<ulink url='&a.tex.url;'>Porting TeX and its applications to &os;</ulink>"> -<!ENTITY a.tex.name "<ulink url='&a.tex.url;'>freebsd-tex</ulink>"> +<!ENTITY a.tex "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tex.url;'>Porting TeX and its applications to &os;</link>"> +<!ENTITY a.tex.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tex.url;'>freebsd-tex</link>"> <!ENTITY a.threads.url "&a.mailman.listinfo;/freebsd-threads"> -<!ENTITY a.threads "<ulink url='&a.threads.url;'>FreeBSD threads mailing list</ulink>"> -<!ENTITY a.threads.name "<ulink url='&a.threads.url;'>freebsd-threads</ulink>"> +<!ENTITY a.threads "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.threads.url;'>FreeBSD threads mailing list</link>"> +<!ENTITY a.threads.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.threads.url;'>freebsd-threads</link>"> <!ENTITY a.tilera.url "&a.mailman.listinfo;/freebsd-tilera"> -<!ENTITY a.tilera "<ulink url='&a.tilera.url;'>Porting FreeBSD to the Tilera family of CPUs</ulink>"> -<!ENTITY a.tilera.name "<ulink url='&a.tilera.url;'>freebsd-tilera</ulink>"> +<!ENTITY a.tilera "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tilera.url;'>Porting FreeBSD to the Tilera family of CPUs</link>"> +<!ENTITY a.tilera.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tilera.url;'>freebsd-tilera</link>"> <!ENTITY a.tokenring.url "&a.mailman.listinfo;/freebsd-tokenring"> -<!ENTITY a.tokenring "<ulink url='&a.tokenring.url;'>FreeBSD tokenring mailing list</ulink>"> -<!ENTITY a.tokenring.name "<ulink url='&a.tokenring.url;'>freebsd-tokenring</ulink>"> +<!ENTITY a.tokenring "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tokenring.url;'>FreeBSD tokenring mailing list</link>"> +<!ENTITY a.tokenring.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.tokenring.url;'>freebsd-tokenring</link>"> <!ENTITY a.toolchain.url "&a.mailman.listinfo;/freebsd-toolchain"> -<!ENTITY a.toolchain "<ulink url='&a.toolchain.url;'>FreeBSD integrated toolchain mailing list</ulink>"> -<!ENTITY a.toolchain.name "<ulink url='&a.toolchain.url;'>freebsd-toolchain</ulink>"> +<!ENTITY a.toolchain "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.toolchain.url;'>FreeBSD integrated toolchain mailing list</link>"> +<!ENTITY a.toolchain.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.toolchain.url;'>freebsd-toolchain</link>"> <!ENTITY a.usb.url "&a.mailman.listinfo;/freebsd-usb"> -<!ENTITY a.usb "<ulink url='&a.usb.url;'>FreeBSD USB mailing list</ulink>"> -<!ENTITY a.usb.name "<ulink url='&a.usb.url;'>freebsd-usb</ulink>"> +<!ENTITY a.usb "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.usb.url;'>FreeBSD USB mailing list</link>"> +<!ENTITY a.usb.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.usb.url;'>freebsd-usb</link>"> <!ENTITY a.usergroups.url "&a.mailman.listinfo;/freebsd-user-groups"> -<!ENTITY a.usergroups "<ulink url='&a.usergroups.url;'>FreeBSD user group coordination mailing list</ulink>"> -<!ENTITY a.usergroups.name "<ulink url='&a.usergroups.url;'>freebsd-user-groups</ulink>"> +<!ENTITY a.usergroups "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.usergroups.url;'>FreeBSD user group coordination mailing list</link>"> +<!ENTITY a.usergroups.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.usergroups.url;'>freebsd-user-groups</link>"> <!ENTITY a.vendors.url "&a.mailman.listinfo;/freebsd-vendors"> -<!ENTITY a.vendors "<ulink url='&a.vendors.url;'>FreeBSD vendors pre-release coordination mailing list</ulink>"> -<!ENTITY a.vendors.name "<ulink url='&a.vendors.url;'>freebsd-vendors</ulink>"> +<!ENTITY a.vendors "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.vendors.url;'>FreeBSD vendors pre-release coordination mailing list</link>"> +<!ENTITY a.vendors.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.vendors.url;'>freebsd-vendors</link>"> <!ENTITY a.virtualization.url "&a.mailman.listinfo;/freebsd-virtualization"> -<!ENTITY a.virtualization "<ulink url='&a.virtualization.url;'>Discussion of various virtualization techniques supported by FreeBSD</ulink>"> -<!ENTITY a.virtualization.name "<ulink url='&a.virtualization.url;'>freebsd-virtualization</ulink>"> +<!ENTITY a.virtualization "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.virtualization.url;'>Discussion of various virtualization techniques supported by FreeBSD</link>"> +<!ENTITY a.virtualization.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.virtualization.url;'>freebsd-virtualization</link>"> <!ENTITY a.vuxml.url "&a.mailman.listinfo;/freebsd-vuxml"> -<!ENTITY a.vuxml "<ulink url='&a.vuxml.url;'>Discussion on the VuXML -infrastructure</ulink>"> -<!ENTITY a.vuxml.name "<ulink url='&a.vuxml.url;'>freebsd-vuxml</ulink>"> +<!ENTITY a.vuxml "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.vuxml.url;'>Discussion on the VuXML +infrastructure</link>"> +<!ENTITY a.vuxml.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.vuxml.url;'>freebsd-vuxml</link>"> <!ENTITY a.wip-status.url "&a.mailman.listinfo;/freebsd-wip-status"> -<!ENTITY a.wip-status "<ulink url='&a.wip-status.url;'>FreeBSD Work-In-Progress Status</ulink>"> -<!ENTITY a.wip-status.name "<ulink url='&a.wip-status.url;'>freebsd-wip-status</ulink>"> +<!ENTITY a.wip-status "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.wip-status.url;'>FreeBSD Work-In-Progress Status</link>"> +<!ENTITY a.wip-status.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.wip-status.url;'>freebsd-wip-status</link>"> <!ENTITY a.wireless.url "&a.mailman.listinfo;/freebsd-wireless"> -<!ENTITY a.wireless "<ulink url='&a.wireless.url;'>Discussions of 802.11 stack, tools, device driver development</ulink>"> -<!ENTITY a.wireless.name "<ulink url='&a.wireless.url;'>freebsd-wireless</ulink>"> +<!ENTITY a.wireless "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.wireless.url;'>Discussions of 802.11 stack, tools, device driver development</link>"> +<!ENTITY a.wireless.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.wireless.url;'>freebsd-wireless</link>"> <!ENTITY a.www.url "&a.mailman.listinfo;/freebsd-www"> -<!ENTITY a.www "<ulink url='&a.www.url;'>FreeBSD Webmaster mailing list</ulink>"> -<!ENTITY a.www.name "<ulink url='&a.www.url;'>freebsd-www</ulink>"> +<!ENTITY a.www "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.www.url;'>FreeBSD Webmaster mailing list</link>"> +<!ENTITY a.www.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.www.url;'>freebsd-www</link>"> <!ENTITY a.x11.url "&a.mailman.listinfo;/freebsd-x11"> -<!ENTITY a.x11 "<ulink url='&a.x11.url;'>FreeBSD X11 mailing list</ulink>"> -<!ENTITY a.x11.name "<ulink url='&a.x11.url;'>freebsd-x11</ulink>"> +<!ENTITY a.x11 "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.x11.url;'>FreeBSD X11 mailing list</link>"> +<!ENTITY a.x11.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.x11.url;'>freebsd-x11</link>"> <!ENTITY a.xen.url "&a.mailman.listinfo;/freebsd-xen"> -<!ENTITY a.xen "<ulink url='&a.xen.url;'>FreeBSD port to Xen mailing list</ulink>"> -<!ENTITY a.xen.name "<ulink url='&a.xen.url;'>freebsd-xen</ulink>"> +<!ENTITY a.xen "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.xen.url;'>FreeBSD port to Xen mailing list</link>"> +<!ENTITY a.xen.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.xen.url;'>freebsd-xen</link>"> <!ENTITY a.xfce.url "&a.mailman.listinfo;/freebsd-xfce"> -<!ENTITY a.xfce "<ulink url='&a.xfce.url;'>XFCE for FreeBSD mailing list</ulink>"> -<!ENTITY a.xfce.name "<ulink url='&a.xfce.url;'>freebsd-xfce</ulink>"> +<!ENTITY a.xfce "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.xfce.url;'>XFCE for FreeBSD mailing list</link>"> +<!ENTITY a.xfce.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.xfce.url;'>freebsd-xfce</link>"> <!ENTITY a.zope.url "&a.mailman.listinfo;/freebsd-zope"> -<!ENTITY a.zope "<ulink url='&a.zope.url;'>Zope for FreeBSD mailing list</ulink>"> -<!ENTITY a.zope.name "<ulink url='&a.zope.url;'>freebsd-zope</ulink>"> +<!ENTITY a.zope "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.zope.url;'>Zope for FreeBSD mailing list</link>"> +<!ENTITY a.zope.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.zope.url;'>freebsd-zope</link>"> <!-- Not really proper mailing lists --> -<!ENTITY a.bugfollowup "<email>bug-followup@FreeBSD.org</email>"> +<!ENTITY a.bugfollowup "<email xmlns='http://docbook.org/ns/docbook' >bug-followup@FreeBSD.org</email>"> <!ENTITY a.bugsubmit "&a.bugfollowup;"> -<!ENTITY a.majordomo "<email>majordomo@FreeBSD.org</email>"> +<!ENTITY a.majordomo "<email xmlns='http://docbook.org/ns/docbook'>majordomo@FreeBSD.org</email>"> <!-- The following mailinglists are deactivated. Keep them until all references @@ -618,13 +618,13 @@ infrastructure</ulink>"> --> <!ENTITY a.alpha.url "&a.mailman.listinfo;/freebsd-alpha"> -<!ENTITY a.alpha "<ulink url='&a.alpha.url;'>FreeBSD Alpha porting mailing list</ulink>"> -<!ENTITY a.alpha.name "<ulink url='&a.alpha.url;'>freebsd-alpha</ulink>"> +<!ENTITY a.alpha "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.alpha.url;'>FreeBSD Alpha porting mailing list</link>"> +<!ENTITY a.alpha.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.alpha.url;'>freebsd-alpha</link>"> <!ENTITY a.qa.url "&a.mailman.listinfo;/freebsd-qa"> -<!ENTITY a.qa "<ulink url='&a.qa.url;'>FreeBSD Quality Assurance mailing list</ulink>"> -<!ENTITY a.qa.name "<ulink url='&a.qa.url;'>freebsd-qa</ulink>"> +<!ENTITY a.qa "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.qa.url;'>FreeBSD Quality Assurance mailing list</link>"> +<!ENTITY a.qa.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.qa.url;'>freebsd-qa</link>"> <!ENTITY a.smp.url "&a.mailman.listinfo;/freebsd-smp"> -<!ENTITY a.smp "<ulink url='&a.smp.url;'>FreeBSD symmetric multiprocessing mailing list</ulink>"> -<!ENTITY a.smp.name "<ulink url='&a.smp.url;'>freebsd-smp</ulink>"> +<!ENTITY a.smp "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.smp.url;'>FreeBSD symmetric multiprocessing mailing list</link>"> +<!ENTITY a.smp.name "<link xmlns='http://docbook.org/ns/docbook' xlink:href='&a.smp.url;'>freebsd-smp</link>"> diff --git a/en_US.ISO8859-1/share/xml/newsgroups.ent b/en_US.ISO8859-1/share/xml/newsgroups.ent index db6585344a..33dc50cfd8 100644 --- a/en_US.ISO8859-1/share/xml/newsgroups.ent +++ b/en_US.ISO8859-1/share/xml/newsgroups.ent @@ -5,6 +5,6 @@ --> <!ENTITY ng.misc "the - <ulink url='news:comp.unix.bsd.freebsd.misc'>comp.unix.bsd.freebsd.misc</ulink> + <link xmlns='http://docbook.org/ns/docbook' xlink:href='news:comp.unix.bsd.freebsd.misc'>comp.unix.bsd.freebsd.misc</link> newsgroup"> diff --git a/en_US.ISO8859-1/share/xml/teams.ent b/en_US.ISO8859-1/share/xml/teams.ent index efa3d65356..8a42d88669 100644 --- a/en_US.ISO8859-1/share/xml/teams.ent +++ b/en_US.ISO8859-1/share/xml/teams.ent @@ -15,42 +15,42 @@ $FreeBSD$ --> -<!ENTITY a.admins "FreeBSD Administrators <email>admins@FreeBSD.org</email>"> +<!ENTITY a.admins "FreeBSD Administrators <email xmlns='http://docbook.org/ns/docbook'>admins@FreeBSD.org</email>"> -<!ENTITY a.bugmeister "Problem Report Database administrators <email>bugmeister@FreeBSD.org</email>"> +<!ENTITY a.bugmeister "Problem Report Database administrators <email xmlns='http://docbook.org/ns/docbook'>bugmeister@FreeBSD.org</email>"> -<!ENTITY a.core "Core Team <email>core@FreeBSD.org</email>"> +<!ENTITY a.core "Core Team <email xmlns='http://docbook.org/ns/docbook'>core@FreeBSD.org</email>"> -<!ENTITY a.core-secretary "Core Team Secretary <email>core-secretary@FreeBSD.org</email>"> +<!ENTITY a.core-secretary "Core Team Secretary <email xmlns='http://docbook.org/ns/docbook'>core-secretary@FreeBSD.org</email>"> -<!ENTITY a.cvsadm "CVS Repository Meisters <email>cvsadm@FreeBSD.org</email>"> +<!ENTITY a.cvsadm "CVS Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>cvsadm@FreeBSD.org</email>"> -<!ENTITY a.cvsup-master "CVSup Mirror Site Coordinator <email>cvsup-master@FreeBSD.org</email>"> +<!ENTITY a.cvsup-master "CVSup Mirror Site Coordinator <email xmlns='http://docbook.org/ns/docbook'>cvsup-master@FreeBSD.org</email>"> -<!ENTITY a.doceng "Documentation Engineering Team <email>doceng@FreeBSD.org</email>"> +<!ENTITY a.doceng "Documentation Engineering Team <email xmlns='http://docbook.org/ns/docbook'>doceng@FreeBSD.org</email>"> -<!ENTITY a.donations "Donations Liaison Office <email>donations@FreeBSD.org</email>"> +<!ENTITY a.donations "Donations Liaison Office <email xmlns='http://docbook.org/ns/docbook'>donations@FreeBSD.org</email>"> -<!ENTITY a.faq "FAQ Maintainer <email>faq@FreeBSD.org</email>"> +<!ENTITY a.faq "FAQ Maintainer <email xmlns='http://docbook.org/ns/docbook'>faq@FreeBSD.org</email>"> -<!ENTITY a.ftp-master "FTP Mirror Site Coordinator <email>ftp-master@FreeBSD.org</email>"> +<!ENTITY a.ftp-master "FTP Mirror Site Coordinator <email xmlns='http://docbook.org/ns/docbook'>ftp-master@FreeBSD.org</email>"> -<!ENTITY a.mirror-admin "FTP/WWW Mirror Site Coordinator <email>mirror-admin@FreeBSD.org</email>"> +<!ENTITY a.mirror-admin "FTP/WWW Mirror Site Coordinator <email xmlns='http://docbook.org/ns/docbook'>mirror-admin@FreeBSD.org</email>"> -<!ENTITY a.ncvs "CVS src Repository Meisters <email>ncvs@FreeBSD.org</email>"> +<!ENTITY a.ncvs "CVS src Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>ncvs@FreeBSD.org</email>"> -<!ENTITY a.perforce-admin "Perforce Repository Meisters <email>perforce-admin@FreeBSD.org</email>"> +<!ENTITY a.perforce-admin "Perforce Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>perforce-admin@FreeBSD.org</email>"> -<!ENTITY a.pcvs "CVS ports Repository Meisters <email>pcvs@FreeBSD.org</email>"> +<!ENTITY a.pcvs "CVS ports Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>pcvs@FreeBSD.org</email>"> -<!ENTITY a.portmgr "Ports Management Team <email>portmgr@FreeBSD.org</email>"> +<!ENTITY a.portmgr "Ports Management Team <email xmlns='http://docbook.org/ns/docbook'>portmgr@FreeBSD.org</email>"> -<!ENTITY a.portmgr-secretary "Ports Management Team Secretary <email>portmgr-secretary@FreeBSD.org</email>"> +<!ENTITY a.portmgr-secretary "Ports Management Team Secretary <email xmlns='http://docbook.org/ns/docbook'>portmgr-secretary@FreeBSD.org</email>"> -<!ENTITY a.projcvs "CVS Third-Party Projects Repository Meisters <email>projcvs@FreeBSD.org</email>"> +<!ENTITY a.projcvs "CVS Third-Party Projects Repository Meisters <email xmlns='http://docbook.org/ns/docbook'>projcvs@FreeBSD.org</email>"> -<!ENTITY a.re "Release Engineering Team <email>re@FreeBSD.org</email>"> +<!ENTITY a.re "Release Engineering Team <email xmlns='http://docbook.org/ns/docbook'>re@FreeBSD.org</email>"> -<!ENTITY a.secteam-secretary "Security Team Secretary <email>secteam-secretary@FreeBSD.org</email>"> +<!ENTITY a.secteam-secretary "Security Team Secretary <email xmlns='http://docbook.org/ns/docbook'>secteam-secretary@FreeBSD.org</email>"> -<!ENTITY a.security-officer "Security Officer Team <email>security-officer@FreeBSD.org</email>"> +<!ENTITY a.security-officer "Security Officer Team <email xmlns='http://docbook.org/ns/docbook'>security-officer@FreeBSD.org</email>"> |