diff options
| author | Gabor Kovesdan <gabor@FreeBSD.org> | 2013-11-07 15:39:28 +0000 |
|---|---|---|
| committer | Gabor Kovesdan <gabor@FreeBSD.org> | 2013-11-07 15:39:28 +0000 |
| commit | 24d129e8d1984a0b46a543bc523b63d216813bb0 (patch) | |
| tree | 7dd0501c857c6f2139f4a71191c93bf19136412a /en_US.ISO8859-1/books/pmake | |
| parent | 35f1d6c78be90eb13320d655cd68f94333a0ab26 (diff) | |
| download | doc-24d129e8d1984a0b46a543bc523b63d216813bb0.tar.gz doc-24d129e8d1984a0b46a543bc523b63d216813bb0.zip | |
- Definitively upgrade to DocBook 5.0
Notes
Notes:
svn path=/projects/db5/; revision=43125
Diffstat (limited to 'en_US.ISO8859-1/books/pmake')
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/answers/chapter.xml | 3 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/basics/chapter.xml | 108 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/book.xml | 18 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/glossary/glossary.xml | 17 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/gods/chapter.xml | 77 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/intro/chapter.xml | 3 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/legalnotice.xml | 3 | ||||
| -rw-r--r-- | en_US.ISO8859-1/books/pmake/shortcuts/chapter.xml | 130 |
8 files changed, 172 insertions, 187 deletions
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> |