diff options
Diffstat (limited to 'en_US.ISO8859-1/books')
33 files changed, 4778 insertions, 4286 deletions
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 af76ac8d6d..8e94b8904e 100644 --- a/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/scsi/chapter.xml @@ -9,16 +9,16 @@ <chapterinfo> <authorgroup> <author> - <firstname>Sergey</firstname> - <surname>Babkin</surname> - <contrib>Written by </contrib> + <firstname>Sergey</firstname> + <surname>Babkin</surname> + <contrib>Written by </contrib> </author> </authorgroup> <authorgroup> <author> - <firstname>Murray</firstname> - <surname>Stokely</surname> - <contrib>Modifications for Handbook made by </contrib> + <firstname>Murray</firstname> + <surname>Stokely</surname> + <contrib>Modifications for Handbook made by </contrib> </author> </authorgroup> </chapterinfo> @@ -34,69 +34,79 @@ protocol. Much of the information in this document was extracted from the drivers:</para> - <itemizedlist> - - <listitem><para>ncr (<filename>/sys/pci/ncr.c</filename>) by - Wolfgang Stanglmeier and Stefan Esser</para></listitem> - - <listitem><para>sym (<filename>/sys/dev/sym/sym_hipd.c</filename>) by - Gerard Roudier</para></listitem> - - <listitem><para>aic7xxx - (<filename>/sys/dev/aic7xxx/aic7xxx.c</filename>) by Justin - T. Gibbs</para></listitem> + <itemizedlist> - </itemizedlist> + <listitem><para>ncr (<filename>/sys/pci/ncr.c</filename>) by + Wolfgang Stanglmeier and Stefan Esser</para></listitem> - <para>and from the CAM code itself (by Justin T. Gibbs, see - <filename>/sys/cam/*</filename>). When some solution looked the - most logical and was essentially verbatim extracted from the code - by Justin T. Gibbs, I marked it as <quote>recommended</quote>.</para> + <listitem> + <para>sym (<filename>/sys/dev/sym/sym_hipd.c</filename>) by + Gerard Roudier</para> + </listitem> - <para>The document is illustrated with examples in - pseudo-code. Although sometimes the examples have many details - and look like real code, it is still pseudo-code. It was written - to demonstrate the concepts in an understandable way. For a real - driver other approaches may be more modular and efficient. It - also abstracts from the hardware details, as well as issues that - would cloud the demonstrated concepts or that are supposed to be - described in the other chapters of the developers handbook. Such - details are commonly shown as calls to functions with descriptive - names, comments or pseudo-statements. Fortunately real life - full-size examples with all the details can be found in the real - drivers.</para> + <listitem> + <para>aic7xxx + (<filename>/sys/dev/aic7xxx/aic7xxx.c</filename>) by Justin + T. Gibbs</para> + </listitem> + </itemizedlist> + <para>and from the CAM code itself (by Justin T. Gibbs, see + <filename>/sys/cam/*</filename>). When some solution looked the + most logical and was essentially verbatim extracted from the + code by Justin T. Gibbs, I marked it as + <quote>recommended</quote>.</para> + + <para>The document is illustrated with examples in + pseudo-code. Although sometimes the examples have many details + and look like real code, it is still pseudo-code. It was + written to demonstrate the concepts in an understandable way. + For a real driver other approaches may be more modular and + efficient. It also abstracts from the hardware details, as well + as issues that would cloud the demonstrated concepts or that are + supposed to be described in the other chapters of the developers + handbook. Such details are commonly shown as calls to functions + with descriptive names, comments or pseudo-statements. + Fortunately real life full-size examples with all the details + can be found in the real drivers.</para> </sect1> <sect1 id="scsi-general"> <title>General Architecture</title> - <indexterm><primary>Common Access Method (CAM)</primary></indexterm> + <indexterm> + <primary>Common Access Method (CAM)</primary> + </indexterm> - <para>CAM stands for Common Access Method. It is a generic way to - address the I/O buses in a SCSI-like way. This allows a + <para>CAM stands for Common Access Method. It is a generic way to + address the I/O buses in a SCSI-like way. This allows a separation of the generic device drivers from the drivers - controlling the I/O bus: for example the disk driver becomes able - to control disks on both SCSI, IDE, and/or any other bus so the - disk driver portion does not have to be rewritten (or copied and - modified) for every new I/O bus. Thus the two most important - active entities are:</para> + controlling the I/O bus: for example the disk driver becomes + able to control disks on both SCSI, IDE, and/or any other bus so + the disk driver portion does not have to be rewritten (or copied + and modified) for every new I/O bus. Thus the two most + important active entities are:</para> <indexterm><primary>CD-ROM</primary></indexterm> <indexterm><primary>tape</primary></indexterm> <indexterm><primary>IDE</primary></indexterm> <itemizedlist> - <listitem><para><emphasis>Peripheral Modules</emphasis> - a - driver for peripheral devices (disk, tape, CD-ROM, - etc.)</para></listitem> - <listitem><para><emphasis>SCSI Interface Modules </emphasis>(SIM) - - a Host Bus Adapter drivers for connecting to an I/O bus such - as SCSI or IDE.</para></listitem> + <listitem> + <para><emphasis>Peripheral Modules</emphasis> - a + driver for peripheral devices (disk, tape, CD-ROM, + etc.)</para> + </listitem> + + <listitem> + <para><emphasis>SCSI Interface Modules </emphasis>(SIM) - a + Host Bus Adapter drivers for connecting to an I/O bus such + as SCSI or IDE.</para> + </listitem> </itemizedlist> <para>A peripheral driver receives requests from the OS, converts them to a sequence of SCSI commands and passes these SCSI - commands to a SCSI Interface Module. The SCSI Interface Module + commands to a SCSI Interface Module. The SCSI Interface Module is responsible for passing these commands to the actual hardware (or if the actual hardware is not SCSI but, for example, IDE then also converting the SCSI commands to the native commands of @@ -109,7 +119,7 @@ <para>A typical SIM driver needs to include the following CAM-related header files:</para> -<programlisting>#include <cam/cam.h> + <programlisting>#include <cam/cam.h> #include <cam/cam_ccb.h> #include <cam/cam_sim.h> #include <cam/cam_xpt_sim.h> @@ -117,9 +127,9 @@ #include <cam/scsi/scsi_all.h></programlisting> <para>The first thing each SIM driver must do is register itself - with the CAM subsystem. This is done during the driver's + with the CAM subsystem. This is done during the driver's <function>xxx_attach()</function> function (here and further - xxx_ is used to denote the unique driver name prefix). The + xxx_ is used to denote the unique driver name prefix). The <function>xxx_attach()</function> function itself is called by the system bus auto-configuration code which we do not describe here.</para> @@ -127,22 +137,23 @@ <para>This is achieved in multiple steps: first it is necessary to allocate the queue of requests associated with this SIM:</para> -<programlisting> struct cam_devq *devq; + <programlisting> struct cam_devq *devq; if(( devq = cam_simq_alloc(SIZE) )==NULL) { error; /* some code to handle the error */ }</programlisting> - <para>Here <literal>SIZE</literal> is the size of the queue to be allocated, maximal - number of requests it could contain. It is the number of requests - that the SIM driver can handle in parallel on one SCSI - card. Commonly it can be calculated as:</para> + <para>Here <literal>SIZE</literal> is the size of the queue to be + allocated, maximal number of requests it could contain. It is + the number of requests that the SIM driver can handle in + parallel on one SCSI card. Commonly it can be calculated + as:</para> -<programlisting>SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET</programlisting> + <programlisting>SIZE = NUMBER_OF_SUPPORTED_TARGETS * MAX_SIMULTANEOUS_COMMANDS_PER_TARGET</programlisting> <para>Next we create a descriptor of our SIM:</para> -<programlisting> struct cam_sim *sim; + <programlisting> struct cam_sim *sim; if(( sim = cam_sim_alloc(action_func, poll_func, driver_name, softc, unit, max_dev_transactions, @@ -155,10 +166,10 @@ free the <structname>devq</structname> also because we can do nothing else with it and we want to conserve memory.</para> - <indexterm><primary>SCSI</primary><secondary>bus</secondary></indexterm> - <para>If a SCSI card has multiple SCSI buses on it then each bus - requires its own <structname>cam_sim</structname> - structure.</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> <para>An interesting question is what to do if a SCSI card has more than one SCSI bus, do we need one @@ -167,71 +178,86 @@ either way, as the driver's author prefers.</para> <para>The arguments are:</para> - <itemizedlist> - <listitem><para><function>action_func</function> - pointer to - the driver's <function>xxx_action</function> function. - <funcsynopsis><funcprototype> - <funcdef>static void - <function>xxx_action</function> - </funcdef> - <paramdef> - <parameter>struct cam_sim *sim</parameter>, - <parameter>union ccb *ccb</parameter> - </paramdef> - </funcprototype></funcsynopsis> - </para></listitem> - - <listitem><para><function>poll_func</function> - pointer to - the driver's <function>xxx_poll()</function> - <funcsynopsis><funcprototype> - <funcdef>static void - <function>xxx_poll</function> - </funcdef> - <paramdef> - <parameter>struct cam_sim *sim</parameter> - </paramdef> - </funcprototype></funcsynopsis> - </para></listitem> - - <listitem><para>driver_name - the name of the actual driver, - such as <quote>ncr</quote> or <quote>wds</quote>.</para></listitem> - - <listitem><para><structname>softc</structname> - 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></listitem> - - <listitem><para>unit - the controller unit number, for example - for controller <quote>wds0</quote> this number will be - 0</para></listitem> - - <listitem><para>max_dev_transactions - maximal number of - simultaneous transactions per SCSI target in the non-tagged - mode. This value will be almost universally equal to 1, with - possible exceptions only for the non-SCSI cards. Also the - drivers that hope to take advantage by preparing one - transaction while another one is executed may set it to 2 - but this does not seem to be worth the - complexity.</para></listitem> - - <listitem><para>max_tagged_dev_transactions - the same thing, - but in the tagged mode. Tags are the SCSI way to initiate - multiple transactions on a device: each transaction is - assigned a unique tag and the transaction is sent to the - device. When the device completes some transaction it sends - back the result together with the tag so that the SCSI - adapter (and the driver) can tell which transaction was - completed. This argument is also known as the maximal tag - depth. It depends on the abilities of the SCSI - adapter.</para></listitem> - </itemizedlist> - - <indexterm><primary>SCSI</primary><secondary>adapter</secondary></indexterm> + <itemizedlist> + <listitem> + <para><function>action_func</function> - pointer to + the driver's <function>xxx_action</function> function. + <funcsynopsis> + <funcprototype> + <funcdef>static void + <function>xxx_action</function> + </funcdef> + <paramdef> + <parameter>struct cam_sim *sim</parameter>, + <parameter>union ccb *ccb</parameter> + </paramdef> + </funcprototype> + </funcsynopsis></para> + </listitem> + + <listitem> + <para><function>poll_func</function> - pointer to + the driver's <function>xxx_poll()</function> + <funcsynopsis> + <funcprototype> + <funcdef>static void + <function>xxx_poll</function> + </funcdef> + <paramdef> + <parameter>struct cam_sim *sim</parameter> + </paramdef> + </funcprototype> + </funcsynopsis></para> + </listitem> + + <listitem> + <para>driver_name - the name of the actual driver, + such as <quote>ncr</quote> or + <quote>wds</quote>.</para> + </listitem> + + <listitem> + <para><structname>softc</structname> - 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> + </listitem> + + <listitem> + <para>unit - the controller unit number, for example + for controller <quote>wds0</quote> this number will be + 0</para> + </listitem> + + <listitem> + <para>max_dev_transactions - maximal number of simultaneous + transactions per SCSI target in the non-tagged mode. This + value will be almost universally equal to 1, with possible + exceptions only for the non-SCSI cards. Also the drivers + that hope to take advantage by preparing one transaction + while another one is executed may set it to 2 but this does + not seem to be worth the complexity.</para> + </listitem> + + <listitem> + <para>max_tagged_dev_transactions - the same thing, but in the + tagged mode. Tags are the SCSI way to initiate multiple + transactions on a device: each transaction is assigned a + unique tag and the transaction is sent to the device. When + the device completes some transaction it sends back the + result together with the tag so that the SCSI adapter (and + the driver) can tell which transaction was completed. This + argument is also known as the maximal tag depth. It depends + on the abilities of the SCSI adapter.</para> + </listitem> + + </itemizedlist> + <para>Finally we register the SCSI buses associated with our SCSI - adapter:</para> + adapter<indexterm><primary>SCSI</primary><secondary>adapter</secondary></indexterm>:</para> -<programlisting> if(xpt_bus_register(sim, bus_number) != CAM_SUCCESS) { + <programlisting> if(xpt_bus_register(sim, bus_number) != CAM_SUCCESS) { cam_sim_free(sim, /*free_devq*/ TRUE); error; /* some code to handle the error */ }</programlisting> @@ -240,38 +266,38 @@ 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 - distinct number. Each bus needs its own separate structure + distinct number. Each bus needs its own separate structure 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 <structname>devq</structname> 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> - <para>CAM provides the framework for such asynchronous - events. Some events originate from the lower levels (the SIM - drivers), some events originate from the peripheral drivers, - some events originate from the CAM subsystem itself. Any driver - can register callbacks for some types of the asynchronous - events, so that it would be notified if these events - occur.</para> + <para>CAM provides the framework for such asynchronous events. + Some events originate from the lower levels (the SIM drivers), + some events originate from the peripheral drivers, some events + originate from the CAM subsystem itself. Any driver can + register callbacks for some types of the asynchronous events, so + that it would be notified if these events occur.</para> - <para>A typical example of such an event is a device reset. Each + <para>A typical example of such an event is a device reset. Each transaction and event identifies the devices to which it applies - by the means of <quote>path</quote>. The target-specific events normally - occur during a transaction with this device. So the path from - that transaction may be re-used to report this event (this is - safe because the event path is copied in the event reporting - routine but not deallocated nor passed anywhere further). Also - it is safe to allocate paths dynamically at any time including - the interrupt routines, although that incurs certain overhead, - and a possible problem with this approach is that there may be - no free memory at that time. For a bus reset event we need to - define a wildcard path including all devices on the bus. So we - can create the path for the future bus reset events in advance - and avoid problems with the future memory shortage:</para> - -<programlisting> struct cam_path *path; + by the means of <quote>path</quote>. The target-specific events + normally occur during a transaction with this device. So the + path from that transaction may be re-used to report this event + (this is safe because the event path is copied in the event + reporting routine but not deallocated nor passed anywhere + further). Also it is safe to allocate paths dynamically at any + time including the interrupt routines, although that incurs + certain overhead, and a possible problem with this approach is + that there may be no free memory at that time. For a bus reset + event we need to define a wildcard path including all devices on + the bus. So we can create the path for the future bus reset + events in advance and avoid problems with the future memory + shortage:</para> + + <programlisting> struct cam_path *path; if(xpt_create_path(&path, /*periph*/NULL, cam_sim_path(sim), CAM_TARGET_WILDCARD, @@ -287,39 +313,47 @@ <para>As you can see the path includes:</para> <itemizedlist> - <listitem><para>ID of the peripheral driver (NULL here because we have - none)</para></listitem> + <listitem> + <para>ID of the peripheral driver (NULL here because we have + none)</para> + </listitem> - <listitem><para>ID of the SIM driver - (<function>cam_sim_path(sim)</function>)</para></listitem> + <listitem> + <para>ID of the SIM driver + (<function>cam_sim_path(sim)</function>)</para> + </listitem> - <listitem><para>SCSI target number of the device (CAM_TARGET_WILDCARD - means <quote>all devices</quote>)</para></listitem> + <listitem> + <para>SCSI target number of the device (CAM_TARGET_WILDCARD + means <quote>all devices</quote>)</para> + </listitem> - <listitem><para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means - <quote>all LUNs</quote>)</para></listitem> + <listitem> + <para>SCSI LUN number of the subdevice (CAM_LUN_WILDCARD means + <quote>all LUNs</quote>)</para> + </listitem> </itemizedlist> - <para>If the driver can not allocate this path it will not be able to - work normally, so in that case we dismantle that SCSI + <para>If the driver can not allocate this path it will not be able + to work normally, so in that case we dismantle that SCSI bus.</para> <para>And we save the path pointer in the - <structname>softc</structname> structure for future use. After + <structname>softc</structname> 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> - <para>That is all for a minimalistic initialization. To do things - right there is one more issue left. </para> + <para>That is all for a minimalistic initialization. To do things + right there is one more issue left.</para> <para>For a SIM driver there is one particularly interesting - event: when a target device is considered lost. In this case + event: when a target device is considered lost. In this case resetting the SCSI negotiations with this device may be a good - idea. So we register a callback for this event with CAM. The + idea. So we register a callback for this event with CAM. The request is passed to CAM by requesting CAM action on a CAM control block for this type of request:</para> -<programlisting> struct ccb_setasync csa; + <programlisting> struct ccb_setasync csa; xpt_setup_ccb(&csa.ccb_h, path, /*priority*/5); csa.ccb_h.func_code = XPT_SASYNC_CB; @@ -332,59 +366,71 @@ and <function>xxx_poll()</function> driver entry points.</para> <para> - <funcsynopsis><funcprototype> - <funcdef>static void - <function>xxx_action</function> - </funcdef> - <paramdef> - <parameter>struct cam_sim *sim</parameter>, - <parameter>union ccb *ccb</parameter> - </paramdef> - </funcprototype></funcsynopsis> - </para> - - <para>Do some action on request of the CAM subsystem. Sim - describes the SIM for the request, CCB is the request - itself. CCB stands for <quote>CAM Control Block</quote>. It is a union of - many specific instances, each describing arguments for some type - of transactions. All of these instances share the CCB header - where the common part of arguments is stored.</para> + <funcsynopsis> + <funcprototype> + <funcdef>static void + <function>xxx_action</function> + </funcdef> + <paramdef> + <parameter>struct cam_sim *sim</parameter>, + <parameter>union ccb *ccb</parameter> + </paramdef> + </funcprototype> + </funcsynopsis></para> + + <para>Do some action on request of the CAM subsystem. Sim + describes the SIM for the request, CCB is the request itself. + CCB stands for <quote>CAM Control Block</quote>. It is a union + of many specific instances, each describing arguments for some + type of transactions. All of these instances share the CCB + header where the common part of arguments is stored.</para> <para>CAM supports the SCSI controllers working in both initiator - (<quote>normal</quote>) mode and target (simulating a SCSI device) mode. Here - we only consider the part relevant to the initiator mode.</para> + (<quote>normal</quote>) mode and target (simulating a SCSI + device) mode. Here we only consider the part relevant to the + initiator mode.</para> <para>There are a few function and macros (in other words, - methods) defined to access the public data in the struct sim:</para> + methods) defined to access the public data in the struct + sim:</para> <itemizedlist> - <listitem><para><function>cam_sim_path(sim)</function> - the - path ID (see above)</para></listitem> + <listitem> + <para><function>cam_sim_path(sim)</function> - the path ID + (see above)</para> + </listitem> - <listitem><para><function>cam_sim_name(sim)</function> - the - name of the sim</para></listitem> + <listitem> + <para><function>cam_sim_name(sim)</function> - the name of the + sim</para> + </listitem> - <listitem><para><function>cam_sim_softc(sim)</function> - the - pointer to the softc (driver private data) - structure</para></listitem> + <listitem> + <para><function>cam_sim_softc(sim)</function> - the pointer to + the softc (driver private data) structure</para> + </listitem> - <listitem><para><function> cam_sim_unit(sim)</function> - the - unit number</para></listitem> + <listitem> + <para><function> cam_sim_unit(sim)</function> - the unit + number</para> + </listitem> - <listitem><para><function> cam_sim_bus(sim)</function> - the bus - ID</para></listitem> + <listitem> + <para><function> cam_sim_bus(sim)</function> - the bus + ID</para> + </listitem> </itemizedlist> - <para>To identify the device, <function>xxx_action()</function> can - get the unit number and pointer to its structure softc using + <para>To identify the device, <function>xxx_action()</function> + can get the unit number and pointer to its structure softc using these functions.</para> <para>The type of request is stored in - <structfield>ccb->ccb_h.func_code</structfield>. So generally - <function>xxx_action()</function> consists of a big + <structfield>ccb->ccb_h.func_code</structfield>. So + generally <function>xxx_action()</function> consists of a big switch:</para> -<programlisting> struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim); + <programlisting> struct xxx_softc *softc = (struct xxx_softc *) cam_sim_softc(sim); struct ccb_hdr *ccb_h = &ccb->ccb_h; int unit = cam_sim_unit(sim); int bus = cam_sim_bus(sim); @@ -400,9 +446,9 @@ <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 completed - CCB is returned back to CAM by calling - <function>xpt_done(ccb)</function>. </para> + <structfield>ccb->ccb_h.status</structfield> and the + completed CCB is returned back to CAM by calling + <function>xpt_done(ccb)</function>.</para> <para><function>xpt_done()</function> does not have to be called from <function>xxx_action()</function>: For example an I/O @@ -413,55 +459,61 @@ handling routine.</para> <para>Actually, the CCB status is not only assigned as a return - code but a CCB has some status all the time. Before CCB is + code but a CCB has some status all the time. Before CCB is passed to the <function>xxx_action()</function> routine it gets the status CCB_REQ_INPROG meaning that it is in progress. There are a surprising number of status values defined in <filename>/sys/cam/cam.h</filename> which should be able to represent the status of a request in great detail. More - interesting yet, the status is in fact a <quote>bitwise or</quote> of an - enumerated status value (the lower 6 bits) and possible - additional flag-like bits (the upper bits). The enumerated - values will be discussed later in more detail. The summary of - them can be found in the Errors Summary section. The possible - status flags are:</para> + interesting yet, the status is in fact a <quote>bitwise + or</quote> of an enumerated status value (the lower 6 bits) and + possible additional flag-like bits (the upper bits). The + enumerated values will be discussed later in more detail. The + summary of them can be found in the Errors Summary section. The + possible status flags are:</para> <itemizedlist> + <listitem> + <para><emphasis>CAM_DEV_QFRZN</emphasis> - if the SIM driver + gets a serious error (for example, the device does not + respond to the selection or breaks the SCSI protocol) when + processing a CCB it should freeze the request queue by + calling <function>xpt_freeze_simq()</function>, return the + other enqueued but not processed yet CCBs for this device + back to the CAM queue, then set this flag for the + troublesome CCB and call <function>xpt_done()</function>. + This flag causes the CAM subsystem to unfreeze the queue + after it handles the error.</para> + </listitem> - <listitem><para><emphasis>CAM_DEV_QFRZN</emphasis> - if the - SIM driver gets a serious error (for example, the device does - not respond to the selection or breaks the SCSI protocol) when - processing a CCB it should freeze the request queue by calling - <function>xpt_freeze_simq()</function>, return the other - enqueued but not processed yet CCBs for this device back to - the CAM queue, then set this flag for the troublesome CCB and - call <function>xpt_done()</function>. This flag causes the CAM - subsystem to unfreeze the queue after it handles the - error.</para></listitem> - - <listitem><para><emphasis>CAM_AUTOSNS_VALID</emphasis> - if - the device returned an error condition and the flag - CAM_DIS_AUTOSENSE is not set in CCB the SIM driver must - execute the REQUEST SENSE command automatically to extract the - sense (extended error information) data from the device. If - this attempt was successful the sense data should be saved in - the CCB and this flag set.</para></listitem> - - <listitem><para><emphasis>CAM_RELEASE_SIMQ</emphasis> - like - CAM_DEV_QFRZN but used in case there is some problem (or - resource shortage) with the SCSI controller itself. Then all - the future requests to the controller should be stopped by - <function>xpt_freeze_simq()</function>. The controller queue - will be restarted after the SIM driver overcomes the shortage - and informs CAM by returning some CCB with this flag - set.</para></listitem> - - <listitem><para><emphasis>CAM_SIM_QUEUED</emphasis> - when SIM - puts a CCB into its request queue this flag should be set (and - removed when this CCB gets dequeued before being returned back - to CAM). This flag is not used anywhere in the CAM code now, - so its purpose is purely diagnostic.</para></listitem> + <listitem> + <para><emphasis>CAM_AUTOSNS_VALID</emphasis> - if the + device returned an error condition and the flag + CAM_DIS_AUTOSENSE is not set in CCB the SIM driver must + execute the REQUEST SENSE command automatically to extract + the sense (extended error information) data from the device. + If this attempt was successful the sense data should be + saved in the CCB and this flag set.</para> + </listitem> + + <listitem> + <para><emphasis>CAM_RELEASE_SIMQ</emphasis> - like + CAM_DEV_QFRZN but used in case there is some problem (or + resource shortage) with the SCSI controller itself. Then + all the future requests to the controller should be stopped + by <function>xpt_freeze_simq()</function>. The controller + queue will be restarted after the SIM driver overcomes the + shortage and informs CAM by returning some CCB with this + flag set.</para> + </listitem> + <listitem> + <para><emphasis>CAM_SIM_QUEUED</emphasis> - when SIM puts a + CCB into its request queue this flag should be set (and + removed when this CCB gets dequeued before being returned + back to CAM). This flag is not used anywhere in the CAM + code now, so its purpose is purely diagnostic.</para> + </listitem> </itemizedlist> <para>The function <function>xxx_action()</function> is not @@ -475,126 +527,159 @@ <para>The CCB header contains the following fields:</para> <itemizedlist> + <listitem> + <para><emphasis>path</emphasis> - path ID for the + request</para> + </listitem> - <listitem><para><emphasis>path</emphasis> - path ID for the - request</para></listitem> - - <listitem><para><emphasis>target_id</emphasis> - target device - ID for the request</para></listitem> - - <listitem><para><emphasis>target_lun</emphasis> - LUN ID of - the target device</para></listitem> + <listitem> + <para><emphasis>target_id</emphasis> - target device ID for + the request</para> + </listitem> - <listitem><para><emphasis>timeout</emphasis> - timeout - interval for this command, in milliseconds</para></listitem> + <listitem> + <para><emphasis>target_lun</emphasis> - LUN ID of the target + device</para> + </listitem> - <listitem><para><emphasis>timeout_ch</emphasis> - a - convenience place for the SIM driver to store the timeout handle - (the CAM subsystem itself does not make any assumptions about - it)</para></listitem> + <listitem> + <para><emphasis>timeout</emphasis> - timeout interval for this + command, in milliseconds</para> + </listitem> - <listitem><para><emphasis>flags</emphasis> - various bits of - information about the request spriv_ptr0, spriv_ptr1 - fields - reserved for private use by the SIM driver (such as linking to - the SIM queues or SIM private control blocks); actually, they - exist as unions: spriv_ptr0 and spriv_ptr1 have the type (void - *), spriv_field0 and spriv_field1 have the type unsigned long, - sim_priv.entries[0].bytes and sim_priv.entries[1].bytes are byte - arrays of the size consistent with the other incarnations of the - union and sim_priv.bytes is one array, twice - bigger.</para></listitem> + <listitem> + <para><emphasis>timeout_ch</emphasis> - a convenience place + for the SIM driver to store the timeout handle (the CAM + subsystem itself does not make any assumptions about + it)</para> + </listitem> + <listitem> + <para><emphasis>flags</emphasis> - various bits of information + about the request spriv_ptr0, spriv_ptr1 - fields reserved + for private use by the SIM driver (such as linking to the + SIM queues or SIM private control blocks); actually, they + exist as unions: spriv_ptr0 and spriv_ptr1 have the type + (void *), spriv_field0 and spriv_field1 have the type + unsigned long, sim_priv.entries[0].bytes and + sim_priv.entries[1].bytes are byte arrays of the size + consistent with the other incarnations of the union and + sim_priv.bytes is one array, twice bigger.</para> + </listitem> </itemizedlist> <para>The recommended way of using the SIM private fields of CCB is to define some meaningful names for them and use these meaningful names in the driver, like:</para> -<programlisting>#define ccb_some_meaningful_name sim_priv.entries[0].bytes + <programlisting>#define ccb_some_meaningful_name sim_priv.entries[0].bytes #define ccb_hcb spriv_ptr1 /* for hardware control block */</programlisting> <para>The most common initiator mode requests are:</para> + <itemizedlist> - <listitem><para><emphasis>XPT_SCSI_IO</emphasis> - execute an - I/O transaction</para> - - <para>The instance <quote>struct ccb_scsiio csio</quote> of the union ccb is - used to transfer the arguments. They are:</para> - - <itemizedlist> - <listitem><para><emphasis>cdb_io</emphasis> - pointer to - the SCSI command buffer or the buffer - itself</para></listitem> - - <listitem><para><emphasis>cdb_len</emphasis> - SCSI - command length</para></listitem> - - <listitem><para><emphasis>data_ptr</emphasis> - pointer to - the data buffer (gets a bit complicated if scatter/gather is - used)</para></listitem> - - <listitem><para><emphasis>dxfer_len</emphasis> - length of - the data to transfer</para></listitem> - - <listitem><para><emphasis>sglist_cnt</emphasis> - counter - of the scatter/gather segments</para></listitem> - - <listitem><para><emphasis>scsi_status</emphasis> - place - to return the SCSI status</para></listitem> - - <listitem><para><emphasis>sense_data</emphasis> - buffer - for the SCSI sense information if the command returns an - error (the SIM driver is supposed to run the REQUEST SENSE - command automatically in this case if the CCB flag - CAM_DIS_AUTOSENSE is not set)</para></listitem> - - <listitem><para><emphasis>sense_len</emphasis> - the - length of that buffer (if it happens to be higher than size - of sense_data the SIM driver must silently assume the - smaller value) resid, sense_resid - if the transfer of data - or SCSI sense returned an error these are the returned - counters of the residual (not transferred) data. They do not - seem to be especially meaningful, so in a case when they are - difficult to compute (say, counting bytes in the SCSI - controller's FIFO buffer) an approximate value will do as - well. For a successfully completed transfer they must be set - to zero.</para></listitem> - - <listitem><para><emphasis>tag_action</emphasis> - the kind - of tag to use:</para> - - <itemizedlist> - <listitem><para>CAM_TAG_ACTION_NONE - do not use tags for this - transaction</para></listitem> - <listitem><para>MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, - MSG_ORDERED_Q_TAG - value equal to the appropriate tag - message (see /sys/cam/scsi/scsi_message.h); this gives only - the tag type, the SIM driver must assign the tag value - itself</para></listitem> - </itemizedlist> + <listitem> + <para><emphasis>XPT_SCSI_IO</emphasis> - execute an I/O + transaction</para> + + <para>The instance <quote>struct ccb_scsiio csio</quote> of + the union ccb is used to transfer the arguments. They + are:</para> + + <itemizedlist> + <listitem> + <para><emphasis>cdb_io</emphasis> - pointer to the SCSI + command buffer or the buffer itself</para> + </listitem> + <listitem> + <para><emphasis>cdb_len</emphasis> - SCSI command + length</para> </listitem> - </itemizedlist> + <listitem> + <para><emphasis>data_ptr</emphasis> - pointer to the data + buffer (gets a bit complicated if scatter/gather is + used)</para> + </listitem> - <para>The general logic of handling this request is the - following:</para> + <listitem> + <para><emphasis>dxfer_len</emphasis> - length of the data + to transfer</para> + </listitem> + + <listitem> + <para><emphasis>sglist_cnt</emphasis> - counter of the + scatter/gather segments</para> + </listitem> + + <listitem> + <para><emphasis>scsi_status</emphasis> - place to return + the SCSI status</para> + </listitem> + + <listitem> + <para><emphasis>sense_data</emphasis> - buffer for the + SCSI sense information if the command returns an error + (the SIM driver is supposed to run the REQUEST SENSE + command automatically in this case if the CCB flag + CAM_DIS_AUTOSENSE is not set)</para> + </listitem> + + <listitem> + <para><emphasis>sense_len</emphasis> - the length of that + buffer (if it happens to be higher than size of + sense_data the SIM driver must silently assume the + smaller value) resid, sense_resid - if the transfer of + data or SCSI sense returned an error these are the + returned counters of the residual (not transferred) + data. They do not seem to be especially meaningful, so + in a case when they are difficult to compute (say, + counting bytes in the SCSI controller's FIFO buffer) an + approximate value will do as well. For a successfully + completed transfer they must be set to + zero.</para> + </listitem> + + <listitem> + <para><emphasis>tag_action</emphasis> - the kind of tag to + use:</para> + + <itemizedlist> + <listitem> + <para>CAM_TAG_ACTION_NONE - do not use tags for this + transaction</para> + </listitem> + + <listitem> + <para>MSG_SIMPLE_Q_TAG, MSG_HEAD_OF_Q_TAG, + MSG_ORDERED_Q_TAG - value equal to the appropriate + tag message (see /sys/cam/scsi/scsi_message.h); this + gives only the tag type, the SIM driver must assign + the tag value itself</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> - <para>The first thing to do is to check for possible races, to - make sure that the command did not get aborted when it was - sitting in the queue:</para> + <para>The general logic of handling this request is the + following:</para> -<programlisting> struct ccb_scsiio *csio = &ccb->csio; + <para>The first thing to do is to check for possible races, to + make sure that the command did not get aborted when it was + sitting in the queue:</para> + + <programlisting> struct ccb_scsiio *csio = &ccb->csio; if ((ccb_h->status & CAM_STATUS_MASK) != CAM_REQ_INPROG) { xpt_done(ccb); return; }</programlisting> - <para>Also we check that the device is supported at all by our - controller:</para> + <para>Also we check that the device is supported at all by our + controller:</para> -<programlisting> if(ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID + <programlisting> if(ccb_h->target_id > OUR_MAX_SUPPORTED_TARGET_ID || cch_h->target_id == OUR_SCSI_CONTROLLERS_OWN_ID) { ccb_h->status = CAM_TID_INVALID; xpt_done(ccb); @@ -606,19 +691,20 @@ return; }</programlisting> - <indexterm><primary>hardware control block</primary></indexterm> - - <para>Then allocate whatever data structures (such as - card-dependent hardware control block) we need to process this - request. If we can not then freeze the SIM queue and remember - that we have a pending operation, return the CCB back and ask - CAM to re-queue it. Later when the resources become available - the SIM queue must be unfrozen by returning a ccb with the - <literal>CAM_SIMQ_RELEASE</literal> bit set in its status. Otherwise, if all went - well, link the CCB with the hardware control block (HCB) and - mark it as queued.</para> - -<programlisting> struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus); + <para>Then allocate whatever data structures (such as + card-dependent hardware control + block<indexterm><primary>hardware control + block</primary></indexterm>) we need to process this + request. If we can not then freeze the SIM queue and + remember that we have a pending operation, return the CCB + back and ask CAM to re-queue it. Later when the resources + become available the SIM queue must be unfrozen by returning + a ccb with the <literal>CAM_SIMQ_RELEASE</literal> bit set + in its status. Otherwise, if all went well, link the CCB + with the hardware control block (HCB) and mark it as + queued.</para> + + <programlisting> struct xxx_hcb *hcb = allocate_hcb(softc, unit, bus); if(hcb == NULL) { softc->flags |= RESOURCE_SHORTAGE; @@ -631,44 +717,49 @@ hcb->ccb = ccb; ccb_h->ccb_hcb = (void *)hcb; ccb_h->status |= CAM_SIM_QUEUED;</programlisting> - <para>Extract the target data from CCB into the hardware control - block. Check if we are asked to assign a tag and if yes then - generate an unique tag and build the SCSI tag messages. The - SIM driver is also responsible for negotiations with the - devices to set the maximal mutually supported bus width, - synchronous rate and offset.</para> + <para>Extract the target data from CCB into the hardware + control block. Check if we are asked to assign a tag and if + yes then generate an unique tag and build the SCSI tag + messages. The SIM driver is also responsible for + negotiations with the devices to set the maximal mutually + supported bus width, synchronous rate and offset.</para> -<programlisting> hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun; + <programlisting> hcb->target = ccb_h->target_id; hcb->lun = ccb_h->target_lun; generate_identify_message(hcb); if( ccb_h->tag_action != CAM_TAG_ACTION_NONE ) generate_unique_tag_message(hcb, ccb_h->tag_action); if( !target_negotiated(hcb) ) generate_negotiation_messages(hcb);</programlisting> - <para>Then set up the SCSI command. The command storage may be - specified in the CCB in many interesting ways, specified by - the CCB flags. The command buffer can be contained in CCB or - pointed to, in the latter case the pointer may be physical or - virtual. Since the hardware commonly needs physical address we - always convert the address to the physical one.</para> - - <para>A NOT-QUITE RELATED NOTE: Normally this is done by a call - to <function>vtophys()</function>, but for the PCI device (which account for most - of the SCSI controllers now) drivers' portability to the Alpha - architecture the conversion must be done by <function>vtobus()</function> instead - due to special Alpha quirks. [IMHO it would be much better to - have two separate functions, <function>vtop()</function> and <function>ptobus()</function> then <function>vtobus()</function> - would be a simple superposition of them.] In case if a - physical address is requested it is OK to return the CCB with - the status <errorname>CAM_REQ_INVALID</errorname>, the current drivers do that. But - it is also possible to compile the Alpha-specific piece of - code, as in this example (there should be a more direct way to - do that, without conditional compilation in the drivers). If - necessary a physical address can be also converted or mapped - back to a virtual address but with big pain, so we do not do - that.</para> - -<programlisting> if(ccb_h->flags & CAM_CDB_POINTER) { + <para>Then set up the SCSI command. The command storage may + be specified in the CCB in many interesting ways, specified + by the CCB flags. The command buffer can be contained in + CCB or pointed to, in the latter case the pointer may be + physical or virtual. Since the hardware commonly needs + physical address we always convert the address to the + physical one.</para> + + <para>A NOT-QUITE RELATED NOTE: Normally this is done by a + call to <function>vtophys()</function>, but for the PCI + device (which account for most of the SCSI controllers now) + drivers' portability to the Alpha architecture the + conversion must be done by <function>vtobus()</function> + instead due to special Alpha quirks. [IMHO it would be much + better to have two separate functions, + <function>vtop()</function> and + <function>ptobus()</function> then + <function>vtobus()</function> would be a simple + superposition of them.] In case if a physical address is + requested it is OK to return the CCB with the status + <errorname>CAM_REQ_INVALID</errorname>, the current drivers + do that. But it is also possible to compile the + Alpha-specific piece of code, as in this example (there + should be a more direct way to do that, without conditional + compilation in the drivers). If necessary a physical + address can be also converted or mapped back to a virtual + address but with big pain, so we do not do that.</para> + + <programlisting> if(ccb_h->flags & CAM_CDB_POINTER) { /* CDB is a pointer */ if(!(ccb_h->flags & CAM_CDB_PHYS)) { /* CDB pointer is virtual */ @@ -687,35 +778,36 @@ } hcb->cmdlen = csio->cdb_len;</programlisting> - <para>Now it is time to set up the data. Again, the data storage - may be specified in the CCB in many interesting ways, - specified by the CCB flags. First we get the direction of the - data transfer. The simplest case is if there is no data to - transfer:</para> + <para>Now it is time to set up the data. Again, the data + storage may be specified in the CCB in many interesting + ways, specified by the CCB flags. First we get the + direction of the data transfer. The simplest case is if + there is no data to transfer:</para> -<programlisting> int dir = (ccb_h->flags & CAM_DIR_MASK); + <programlisting> int dir = (ccb_h->flags & CAM_DIR_MASK); if (dir == CAM_DIR_NONE) goto end_data;</programlisting> - <para>Then we check if the data is in one chunk or in a - scatter-gather list, and the addresses are physical or - virtual. The SCSI controller may be able to handle only a - limited number of chunks of limited length. If the request - hits this limitation we return an error. We use a special - function to return the CCB to handle in one place the HCB - resource shortages. The functions to add chunks are - driver-dependent, and here we leave them without detailed - implementation. See description of the SCSI command (CDB) - handling for the details on the address-translation issues. - If some variation is too difficult or impossible to implement - with a particular card it is OK to return the status - <errorname>CAM_REQ_INVALID</errorname>. Actually, it seems like the scatter-gather - ability is not used anywhere in the CAM code now. But at least - the case for a single non-scattered virtual buffer must be - implemented, it is actively used by CAM.</para> - -<programlisting> int rv; + <para>Then we check if the data is in one chunk or in a + scatter-gather list, and the addresses are physical or + virtual. The SCSI controller may be able to handle only a + limited number of chunks of limited length. If the request + hits this limitation we return an error. We use a special + function to return the CCB to handle in one place the HCB + resource shortages. The functions to add chunks are + driver-dependent, and here we leave them without detailed + implementation. See description of the SCSI command (CDB) + handling for the details on the address-translation issues. + If some variation is too difficult or impossible to + implement with a particular card it is OK to return the + status <errorname>CAM_REQ_INVALID</errorname>. Actually, it + seems like the scatter-gather ability is not used anywhere + in the CAM code now. But at least the case for a single + non-scattered virtual buffer must be implemented, it is + actively used by CAM.</para> + + <programlisting> int rv; initialize_hcb_for_data(hcb); @@ -764,30 +856,30 @@ } end_data:</programlisting> - <para>If disconnection is disabled for this CCB we pass this - information to the hcb:</para> + <para>If disconnection is disabled for this CCB we pass this + information to the hcb:</para> -<programlisting> if(ccb_h->flags & CAM_DIS_DISCONNECT) + <programlisting> if(ccb_h->flags & CAM_DIS_DISCONNECT) hcb_disable_disconnect(hcb);</programlisting> - <para>If the controller is able to run REQUEST SENSE command all - by itself then the value of the flag CAM_DIS_AUTOSENSE should - also be passed to it, to prevent automatic REQUEST SENSE if the - CAM subsystem does not want it.</para> + <para>If the controller is able to run REQUEST SENSE command + all by itself then the value of the flag CAM_DIS_AUTOSENSE + should also be passed to it, to prevent automatic REQUEST + SENSE if the CAM subsystem does not want it.</para> - <para>The only thing left is to set up the timeout, pass our hcb - to the hardware and return, the rest will be done by the - interrupt handler (or timeout handler).</para> + <para>The only thing left is to set up the timeout, pass our + hcb to the hardware and return, the rest will be done by the + interrupt handler (or timeout handler).</para> -<programlisting> ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, + <programlisting> ccb_h->timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, (ccb_h->timeout * hz) / 1000); /* convert milliseconds to ticks */ put_hcb_into_hardware_queue(hcb); return;</programlisting> - <para>And here is a possible implementation of the function - returning CCB:</para> + <para>And here is a possible implementation of the function + returning CCB:</para> -<programlisting> static void + <programlisting> static void free_hcb_and_ccb_done(struct xxx_hcb *hcb, union ccb *ccb, u_int32_t status) { struct xxx_softc *softc = hcb->softc; @@ -806,45 +898,51 @@ (ccb->ccb_h.status & ~(CAM_STATUS_MASK|CAM_SIM_QUEUED)); xpt_done(ccb); }</programlisting> - </listitem> - - <listitem><para><emphasis>XPT_RESET_DEV</emphasis> - send the SCSI <quote>BUS - DEVICE RESET</quote> message to a device</para> - - <para>There is no data transferred in CCB except the header and - the most interesting argument of it is target_id. Depending on - the controller hardware a hardware control block just like for - the XPT_SCSI_IO request may be constructed (see XPT_SCSI_IO - request description) and sent to the controller or the SCSI - controller may be immediately programmed to send this RESET - message to the device or this request may be just not supported - (and return the status <errorname>CAM_REQ_INVALID</errorname>). Also on completion of - the request all the disconnected transactions for this target - must be aborted (probably in the interrupt routine).</para> - - <para>Also all the current negotiations for the target are lost on - reset, so they might be cleaned too. Or they clearing may be - deferred, because anyway the target would request re-negotiation - on the next transaction.</para></listitem> - - <listitem><para><emphasis>XPT_RESET_BUS</emphasis> - send the RESET signal - to the SCSI bus</para> - - <para>No arguments are passed in the CCB, the only interesting - argument is the SCSI bus indicated by the struct sim - pointer.</para> - - <para>A minimalistic implementation would forget the SCSI - negotiations for all the devices on the bus and return the - status CAM_REQ_CMP.</para> - - <para>The proper implementation would in addition actually reset - the SCSI bus (possible also reset the SCSI controller) and mark - all the CCBs being processed, both those in the hardware queue - and those being disconnected, as done with the status - CAM_SCSI_BUS_RESET. Like:</para> - -<programlisting> int targ, lun; + </listitem> + + <listitem> + <para><emphasis>XPT_RESET_DEV</emphasis> - send the SCSI + <quote>BUS DEVICE RESET</quote> message to a device</para> + + <para>There is no data transferred in CCB except the header + and the most interesting argument of it is target_id. + Depending on the controller hardware a hardware control + block just like for the XPT_SCSI_IO request may be + constructed (see XPT_SCSI_IO request description) and sent + to the controller or the SCSI controller may be immediately + programmed to send this RESET message to the device or this + request may be just not supported (and return the status + <errorname>CAM_REQ_INVALID</errorname>). Also on completion + of the request all the disconnected transactions for this + target must be aborted (probably in the interrupt + routine).</para> + + <para>Also all the current negotiations for the target are + lost on reset, so they might be cleaned too. Or they + clearing may be deferred, because anyway the target would + request re-negotiation on the next + transaction.</para> + </listitem> + + <listitem> + <para><emphasis>XPT_RESET_BUS</emphasis> - send the RESET + signal to the SCSI bus</para> + + <para>No arguments are passed in the CCB, the only interesting + argument is the SCSI bus indicated by the struct sim + pointer.</para> + + <para>A minimalistic implementation would forget the SCSI + negotiations for all the devices on the bus and return the + status CAM_REQ_CMP.</para> + + <para>The proper implementation would in addition actually + reset the SCSI bus (possible also reset the SCSI controller) + and mark all the CCBs being processed, both those in the + hardware queue and those being disconnected, as done with + the status CAM_SCSI_BUS_RESET. Like:</para> + + <programlisting> int targ, lun; struct xxx_hcb *h, *hh; struct ccb_trans_settings neg; struct cam_path *path; @@ -893,28 +991,31 @@ xpt_async(AC_BUS_RESET, softc->wpath, NULL); return;</programlisting> - <para>Implementing the SCSI bus reset as a function may be a good - idea because it would be re-used by the timeout function as a - last resort if the things go wrong.</para></listitem> + <para>Implementing the SCSI bus reset as a function may be a + good idea because it would be re-used by the timeout + function as a last resort if the things go + wrong.</para> + </listitem> - <listitem><para><emphasis>XPT_ABORT</emphasis> - abort the specified - CCB</para> + <listitem> + <para><emphasis>XPT_ABORT</emphasis> - abort the specified + CCB</para> - <para>The arguments are transferred in the instance <quote>struct - ccb_abort cab</quote> of the union ccb. The only argument field in it - is:</para> + <para>The arguments are transferred in the instance + <quote>struct ccb_abort cab</quote> of the union ccb. The + only argument field in it is:</para> - <para><emphasis>abort_ccb</emphasis> - pointer to the CCB to be - aborted</para> + <para><emphasis>abort_ccb</emphasis> - pointer to the CCB to + be aborted</para> - <para>If the abort is not supported just return the status - CAM_UA_ABORT. This is also the easy way to minimally implement - this call, return CAM_UA_ABORT in any case.</para> + <para>If the abort is not supported just return the status + CAM_UA_ABORT. This is also the easy way to minimally + implement this call, return CAM_UA_ABORT in any case.</para> - <para>The hard way is to implement this request honestly. First - check that abort applies to a SCSI transaction:</para> + <para>The hard way is to implement this request honestly. + First check that abort applies to a SCSI transaction:</para> -<programlisting> struct ccb *abort_ccb; + <programlisting> struct ccb *abort_ccb; abort_ccb = ccb->cab.abort_ccb; if(abort_ccb->ccb_h.func_code != XPT_SCSI_IO) { @@ -923,11 +1024,12 @@ return; }</programlisting> - <para>Then it is necessary to find this CCB in our queue. This can - be done by walking the list of all our hardware control blocks - in search for one associated with this CCB:</para> + <para>Then it is necessary to find this CCB in our queue. + This can be done by walking the list of all our hardware + control blocks in search for one associated with this + CCB:</para> -<programlisting> struct xxx_hcb *hcb, *h; + <programlisting> struct xxx_hcb *hcb, *h; hcb = NULL; @@ -951,17 +1053,17 @@ hcb=found_hcb;</programlisting> - <para>Now we look at the current processing status of the HCB. It - may be either sitting in the queue waiting to be sent to the - SCSI bus, being transferred right now, or disconnected and - waiting for the result of the command, or actually completed by - hardware but not yet marked as done by software. To make sure - that we do not get in any races with hardware we mark the HCB as - being aborted, so that if this HCB is about to be sent to the - SCSI bus the SCSI controller will see this flag and skip - it.</para> + <para>Now we look at the current processing status of the HCB. + It may be either sitting in the queue waiting to be sent to + the SCSI bus, being transferred right now, or disconnected + and waiting for the result of the command, or actually + completed by hardware but not yet marked as done by + software. To make sure that we do not get in any races with + hardware we mark the HCB as being aborted, so that if this + HCB is about to be sent to the SCSI bus the SCSI controller + will see this flag and skip it.</para> -<programlisting> int hstatus; + <programlisting> int hstatus; /* shown as a function, in case special action is needed to make * this flag visible to hardware @@ -980,20 +1082,21 @@ free_hcb_and_ccb_done(hcb, abort_ccb, CAM_REQ_ABORTED); break;</programlisting> - <para>If the CCB is being transferred right now we would like to - signal to the SCSI controller in some hardware-dependent way - that we want to abort the current transfer. The SCSI controller - would set the SCSI ATTENTION signal and when the target responds - to it send an ABORT message. We also reset the timeout to make - sure that the target is not sleeping forever. If the command - would not get aborted in some reasonable time like 10 seconds - the timeout routine would go ahead and reset the whole SCSI bus. - Because the command will be aborted in some reasonable time we - can just return the abort request now as successfully completed, - and mark the aborted CCB as aborted (but not mark it as done - yet).</para> - -<programlisting> case HCB_BEING_TRANSFERRED: + <para>If the CCB is being transferred right now we would like + to signal to the SCSI controller in some hardware-dependent + way that we want to abort the current transfer. The SCSI + controller would set the SCSI ATTENTION signal and when the + target responds to it send an ABORT message. We also reset + the timeout to make sure that the target is not sleeping + forever. If the command would not get aborted in some + reasonable time like 10 seconds the timeout routine would go + ahead and reset the whole SCSI bus. Because the command + will be aborted in some reasonable time we can just return + the abort request now as successfully completed, and mark + the aborted CCB as aborted (but not mark it as done + yet).</para> + + <programlisting> case HCB_BEING_TRANSFERRED: untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch); abort_ccb->ccb_h.timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, 10 * hz); @@ -1009,12 +1112,12 @@ break;</programlisting> - <para>If the CCB is in the list of disconnected then set it up as - an abort request and re-queue it at the front of hardware - queue. Reset the timeout and report the abort request to be - completed.</para> + <para>If the CCB is in the list of disconnected then set it up + as an abort request and re-queue it at the front of hardware + queue. Reset the timeout and report the abort request to be + completed.</para> -<programlisting> case HCB_DISCONNECTED: + <programlisting> case HCB_DISCONNECTED: untimeout(xxx_timeout, (caddr_t) hcb, abort_ccb->ccb_h.timeout_ch); abort_ccb->ccb_h.timeout_ch = timeout(xxx_timeout, (caddr_t) hcb, 10 * hz); @@ -1026,20 +1129,21 @@ xpt_done(ccb); return;</programlisting> - <para>That is all for the ABORT request, although there is one more - issue. Because the ABORT message cleans all the ongoing - transactions on a LUN we have to mark all the other active - transactions on this LUN as aborted. That should be done in the - interrupt routine, after the transaction gets aborted.</para> - - <para>Implementing the CCB abort as a function may be quite a good - idea, this function can be re-used if an I/O transaction times - out. The only difference would be that the timed out transaction - would return the status CAM_CMD_TIMEOUT for the timed out - request. Then the case XPT_ABORT would be small, like - that:</para> - -<programlisting> case XPT_ABORT: + <para>That is all for the ABORT request, although there is one + more issue. Because the ABORT message cleans all the + ongoing transactions on a LUN we have to mark all the other + active transactions on this LUN as aborted. That should be + done in the interrupt routine, after the transaction gets + aborted.</para> + + <para>Implementing the CCB abort as a function may be quite a + good idea, this function can be re-used if an I/O + transaction times out. The only difference would be that + the timed out transaction would return the status + CAM_CMD_TIMEOUT for the timed out request. Then the case + XPT_ABORT would be small, like that:</para> + + <programlisting> case XPT_ABORT: struct ccb *abort_ccb; abort_ccb = ccb->cab.abort_ccb; @@ -1055,101 +1159,137 @@ ccb->ccb_h.status = CAM_REQ_CMP; xpt_done(ccb); return;</programlisting> - </listitem> - - <listitem><para><emphasis>XPT_SET_TRAN_SETTINGS</emphasis> - explicitly - set values of SCSI transfer settings</para> - - <para>The arguments are transferred in the instance <quote>struct ccb_trans_setting cts</quote> -of the union ccb:</para> - - <itemizedlist> - <listitem><para><emphasis>valid</emphasis> - a bitmask showing - which settings should be updated:</para></listitem> + </listitem> - <listitem><para><emphasis>CCB_TRANS_SYNC_RATE_VALID</emphasis> - - synchronous transfer rate</para></listitem> + <listitem> + <para><emphasis>XPT_SET_TRAN_SETTINGS</emphasis> - explicitly + set values of SCSI transfer settings</para> - <listitem><para><emphasis>CCB_TRANS_SYNC_OFFSET_VALID</emphasis> - - synchronous offset</para></listitem> + <para>The arguments are transferred in the instance + <quote>struct ccb_trans_setting cts</quote> of the union + ccb:</para> - <listitem><para><emphasis>CCB_TRANS_BUS_WIDTH_VALID</emphasis> - - bus width</para></listitem> + <itemizedlist> + <listitem> + <para><emphasis>valid</emphasis> - a bitmask showing which + settings should be updated:</para> + </listitem> - <listitem><para><emphasis>CCB_TRANS_DISC_VALID</emphasis> - - set enable/disable disconnection</para></listitem> + <listitem> + <para><emphasis>CCB_TRANS_SYNC_RATE_VALID</emphasis> - + synchronous transfer rate</para> + </listitem> - <listitem><para><emphasis>CCB_TRANS_TQ_VALID</emphasis> - set - enable/disable tagged queuing</para></listitem> + <listitem> + <para><emphasis>CCB_TRANS_SYNC_OFFSET_VALID</emphasis> - + synchronous offset</para> + </listitem> - <listitem><para><emphasis>flags</emphasis> - consists of two - parts, binary arguments and identification of - sub-operations. The binary arguments are:</para> - <itemizedlist> - <listitem><para><emphasis>CCB_TRANS_DISC_ENB</emphasis> - enable disconnection</para></listitem> - <listitem><para><emphasis>CCB_TRANS_TAG_ENB</emphasis> - - enable tagged queuing</para></listitem> - </itemizedlist> - </listitem> + <listitem> + <para><emphasis>CCB_TRANS_BUS_WIDTH_VALID</emphasis> - bus + width</para> + </listitem> - <listitem><para>the sub-operations are:</para> - <itemizedlist> - <listitem><para><emphasis>CCB_TRANS_CURRENT_SETTINGS</emphasis> - - change the current negotiations</para></listitem> - - <listitem><para><emphasis>CCB_TRANS_USER_SETTINGS</emphasis> - - remember the desired user values sync_period, sync_offset - - self-explanatory, if sync_offset==0 then the asynchronous mode - is requested bus_width - bus width, in bits (not - bytes)</para></listitem> - </itemizedlist> - </listitem> + <listitem> + <para><emphasis>CCB_TRANS_DISC_VALID</emphasis> - set + enable/disable disconnection</para> + </listitem> - </itemizedlist> + <listitem> + <para><emphasis>CCB_TRANS_TQ_VALID</emphasis> - set + enable/disable tagged queuing</para> + </listitem> - <para>Two sets of negotiated parameters are supported, the user - settings and the current settings. The user settings are not - really used much in the SIM drivers, this is mostly just a piece - of memory where the upper levels can store (and later recall) - its ideas about the parameters. Setting the user parameters - does not cause re-negotiation of the transfer rates. But when - the SCSI controller does a negotiation it must never set the - values higher than the user parameters, so it is essentially the - top boundary.</para> - - <para>The current settings are, as the name says, - current. Changing them means that the parameters must be - re-negotiated on the next transfer. Again, these <quote>new current - settings</quote> are not supposed to be forced on the device, just they - are used as the initial step of negotiations. Also they must be - limited by actual capabilities of the SCSI controller: for - example, if the SCSI controller has 8-bit bus and the request - asks to set 16-bit wide transfers this parameter must be - silently truncated to 8-bit transfers before sending it to the - device.</para> - - <para>One caveat is that the bus width and synchronous parameters - are per target while the disconnection and tag enabling - parameters are per lun.</para> - - <para>The recommended implementation is to keep 3 sets of - negotiated (bus width and synchronous transfer) - parameters:</para> + <listitem> + <para><emphasis>flags</emphasis> - consists of two parts, + binary arguments and identification of sub-operations. + The binary arguments are:</para> + + <itemizedlist> + <listitem> + <para><emphasis>CCB_TRANS_DISC_ENB</emphasis> - enable + disconnection</para> + </listitem> + + <listitem> + <para><emphasis>CCB_TRANS_TAG_ENB</emphasis> - enable + tagged queuing</para> + </listitem> + </itemizedlist> + </listitem> - <itemizedlist> - <listitem><para><emphasis>user</emphasis> - the user set, as - above</para></listitem> + <listitem> + <para>the sub-operations are:</para> + + <itemizedlist> + <listitem> + <para><emphasis>CCB_TRANS_CURRENT_SETTINGS</emphasis> + - change the current negotiations</para> + </listitem> + + <listitem> + <para><emphasis>CCB_TRANS_USER_SETTINGS</emphasis> - + remember the desired user values sync_period, + sync_offset - self-explanatory, if sync_offset==0 + then the asynchronous mode is requested bus_width - + bus width, in bits (not bytes)</para> + </listitem> + </itemizedlist> + </listitem> + </itemizedlist> + + <para>Two sets of negotiated parameters are supported, the + user settings and the current settings. The user settings + are not really used much in the SIM drivers, this is mostly + just a piece of memory where the upper levels can store (and + later recall) its ideas about the parameters. Setting the + user parameters does not cause re-negotiation of the + transfer rates. But when the SCSI controller does a + negotiation it must never set the values higher than the + user parameters, so it is essentially the top + boundary.</para> + + <para>The current settings are, as the name says, current. + Changing them means that the parameters must be + re-negotiated on the next transfer. Again, these + <quote>new current settings</quote> are not supposed to be + forced on the device, just they are used as the initial step + of negotiations. Also they must be limited by actual + capabilities of the SCSI controller: for example, if the + SCSI controller has 8-bit bus and the request asks to set + 16-bit wide transfers this parameter must be silently + truncated to 8-bit transfers before sending it to the + device.</para> + + <para>One caveat is that the bus width and synchronous + parameters are per target while the disconnection and tag + enabling parameters are per lun.</para> + + <para>The recommended implementation is to keep 3 sets of + negotiated (bus width and synchronous transfer) + parameters:</para> + + <itemizedlist> + <listitem> + <para><emphasis>user</emphasis> - the user set, as + above</para> + </listitem> - <listitem><para><emphasis>current</emphasis> - those actually - in effect</para></listitem> + <listitem> + <para><emphasis>current</emphasis> - those actually in + effect</para> + </listitem> - <listitem><para><emphasis>goal</emphasis> - those requested by - setting of the <quote>current</quote> parameters</para></listitem> - </itemizedlist> + <listitem> + <para><emphasis>goal</emphasis> - those requested by + setting of the <quote>current</quote> + parameters</para> + </listitem> + </itemizedlist> - <para>The code looks like:</para> + <para>The code looks like:</para> -<programlisting> struct ccb_trans_settings *cts; + <programlisting> struct ccb_trans_settings *cts; int targ, lun; int flags; @@ -1197,12 +1337,12 @@ of the union ccb:</para> xpt_done(ccb); return;</programlisting> - <para>Then when the next I/O request will be processed it will - check if it has to re-negotiate, for example by calling the - function target_negotiated(hcb). It can be implemented like - this:</para> + <para>Then when the next I/O request will be processed it will + check if it has to re-negotiate, for example by calling the + function target_negotiated(hcb). It can be implemented like + this:</para> -<programlisting> int + <programlisting> int target_negotiated(struct xxx_hcb *hcb) { struct softc *softc = hcb->softc; @@ -1216,61 +1356,72 @@ of the union ccb:</para> return 1; /* TRUE */ }</programlisting> - <para>After the values are re-negotiated the resulting values must - be assigned to both current and goal parameters, so for future - I/O transactions the current and goal parameters would be the - same and <function>target_negotiated()</function> would return - TRUE. When the card is initialized (in - <function>xxx_attach()</function>) the current negotiation - values must be initialized to narrow asynchronous mode, the goal - and current values must be initialized to the maximal values - supported by controller.</para> - - <para><emphasis>XPT_GET_TRAN_SETTINGS</emphasis> - get values of - SCSI transfer settings</para> - - <para>This operations is the reverse of - XPT_SET_TRAN_SETTINGS. Fill up the CCB instance <quote>struct - ccb_trans_setting cts</quote> with data as requested by the flags - CCB_TRANS_CURRENT_SETTINGS or CCB_TRANS_USER_SETTINGS (if both - are set then the existing drivers return the current - settings). Set all the bits in the valid field.</para> - - <indexterm><primary>BIOS</primary></indexterm> - - <para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate logical - (BIOS) geometry of the disk</para> - - <para>The arguments are transferred in the instance <quote>struct - ccb_calc_geometry ccg</quote> of the union ccb:</para> - - <itemizedlist> - - <listitem><para><emphasis>block_size</emphasis> - input, block - (A.K.A sector) size in bytes</para></listitem> - - <listitem><para><emphasis>volume_size</emphasis> - input, - volume size in bytes</para></listitem> + <para>After the values are re-negotiated the resulting values + must be assigned to both current and goal parameters, so for + future I/O transactions the current and goal parameters + would be the same and + <function>target_negotiated()</function> would return TRUE. + When the card is initialized (in + <function>xxx_attach()</function>) the current negotiation + values must be initialized to narrow asynchronous mode, the + goal and current values must be initialized to the maximal + values supported by controller.</para> + + <para><emphasis>XPT_GET_TRAN_SETTINGS</emphasis> - get values + of SCSI transfer settings</para> + + <para>This operations is the reverse of XPT_SET_TRAN_SETTINGS. + Fill up the CCB instance + <quote>struct ccb_trans_setting cts</quote> with data as + requested by the flags CCB_TRANS_CURRENT_SETTINGS or + CCB_TRANS_USER_SETTINGS (if both are set then the existing + drivers return the current settings). Set all the bits in + the valid field.</para> + + <para><emphasis>XPT_CALC_GEOMETRY</emphasis> - calculate + logical (BIOS)<indexterm><primary>BIOS</primary></indexterm> + geometry of the disk</para> + + <para>The arguments are transferred in the instance + <quote>struct ccb_calc_geometry ccg</quote> of the union + ccb:</para> + + <itemizedlist> + + <listitem> + <para><emphasis>block_size</emphasis> - input, block + (A.K.A sector) size in bytes</para> + </listitem> - <listitem><para><emphasis>cylinders</emphasis> - output, - logical cylinders</para></listitem> + <listitem> + <para><emphasis>volume_size</emphasis> - input, volume + size in bytes</para> + </listitem> - <listitem><para><emphasis>heads</emphasis> - output, logical - heads</para></listitem> + <listitem> + <para><emphasis>cylinders</emphasis> - output, logical + cylinders</para> + </listitem> - <listitem><para><emphasis>secs_per_track</emphasis> - output, - logical sectors per track</para></listitem> + <listitem> + <para><emphasis>heads</emphasis> - output, logical + heads</para> + </listitem> - </itemizedlist> + <listitem> + <para><emphasis>secs_per_track</emphasis> - output, + logical sectors per track</para> + </listitem> + </itemizedlist> - <indexterm><primary>SCSI</primary><secondary>BIOS</secondary></indexterm> - <para>If the returned geometry differs much enough from what the - SCSI controller BIOS thinks and a disk on this SCSI controller - is used as bootable the system may not be able to boot. The - typical calculation example taken from the aic7xxx driver - is:</para> + <para>If the returned geometry differs much enough from what + the SCSI controller BIOS<indexterm><primary>SCSI</primary> + <secondary>BIOS</secondary></indexterm> thinks and a disk on + this SCSI controller is used as bootable the system may not + be able to boot. The typical calculation example taken from + the aic7xxx driver is:</para> -<programlisting> struct ccb_calc_geometry *ccg; + <programlisting> struct ccb_calc_geometry *ccg; u_int32_t size_mb; u_int32_t secs_per_cylinder; int extended; @@ -1293,164 +1444,219 @@ of the union ccb:</para> xpt_done(ccb); return;</programlisting> - <para>This gives the general idea, the exact calculation depends - on the quirks of the particular BIOS. If BIOS provides no way - set the <quote>extended translation</quote> flag in EEPROM this flag should - normally be assumed equal to 1. Other popular geometries - are:</para> + <para>This gives the general idea, the exact calculation + depends on the quirks of the particular BIOS. If BIOS + provides no way set the <quote>extended translation</quote> + flag in EEPROM this flag should normally be assumed equal to + 1. Other popular geometries are:</para> -<programlisting> 128 heads, 63 sectors - Symbios controllers + <programlisting> 128 heads, 63 sectors - Symbios controllers 16 heads, 63 sectors - old controllers</programlisting> - <para>Some system BIOSes and SCSI BIOSes fight with each other - with variable success, for example a combination of Symbios - 875/895 SCSI and Phoenix BIOS can give geometry 128/63 after - power up and 255/63 after a hard reset or soft reboot.</para> - </listitem> - - <listitem><para><emphasis>XPT_PATH_INQ</emphasis> - path inquiry, in other - words get the SIM driver and SCSI controller (also known as HBA - - Host Bus Adapter) properties</para> - - <para>The properties are returned in the instance <quote>struct -ccb_pathinq cpi</quote> of the union ccb:</para> + <para>Some system BIOSes and SCSI BIOSes fight with each other + with variable success, for example a combination of Symbios + 875/895 SCSI and Phoenix BIOS can give geometry 128/63 after + power up and 255/63 after a hard reset or soft + reboot.</para> + </listitem> - <itemizedlist> + <listitem> + <para><emphasis>XPT_PATH_INQ</emphasis> - path inquiry, in + other words get the SIM driver and SCSI controller (also + known as HBA - Host Bus Adapter) properties</para> - <listitem><para>version_num - the SIM driver version number, now - all drivers use 1</para></listitem> + <para>The properties are returned in the instance + <quote>struct ccb_pathinq cpi</quote> of the union + ccb:</para> - <listitem><para>hba_inquiry - bitmask of features supported by - the controller:</para></listitem> + <itemizedlist> + <listitem> + <para>version_num - the SIM driver version number, now all + drivers use 1</para> + </listitem> - <listitem><para>PI_MDP_ABLE - supports MDP message (something - from SCSI3?)</para></listitem> + <listitem> + <para>hba_inquiry - bitmask of features supported by the + controller:</para> + </listitem> - <listitem><para>PI_WIDE_32 - supports 32 bit wide - SCSI</para></listitem> + <listitem> + <para>PI_MDP_ABLE - supports MDP message (something from + SCSI3?)</para> + </listitem> - <listitem><para>PI_WIDE_16 - supports 16 bit wide - SCSI</para></listitem> + <listitem> + <para>PI_WIDE_32 - supports 32 bit wide + SCSI</para> + </listitem> - <listitem><para>PI_SDTR_ABLE - can negotiate synchronous - transfer rate</para></listitem> + <listitem> + <para>PI_WIDE_16 - supports 16 bit wide + SCSI</para> + </listitem> - <listitem><para>PI_LINKED_CDB - supports linked - commands</para></listitem> + <listitem> + <para>PI_SDTR_ABLE - can negotiate synchronous transfer + rate</para> + </listitem> - <listitem><para>PI_TAG_ABLE - supports tagged - commands</para></listitem> + <listitem> + <para>PI_LINKED_CDB - supports linked + commands</para> + </listitem> - <listitem><para>PI_SOFT_RST - supports soft reset alternative - (hard reset and soft reset are mutually exclusive within a - SCSI bus)</para></listitem> + <listitem> + <para>PI_TAG_ABLE - supports tagged + commands</para> + </listitem> - <listitem><para>target_sprt - flags for target mode support, 0 - if unsupported</para></listitem> + <listitem> + <para>PI_SOFT_RST - supports soft reset alternative (hard + reset and soft reset are mutually exclusive within a + SCSI bus)</para> + </listitem> - <listitem><para>hba_misc - miscellaneous controller - features:</para></listitem> + <listitem> + <para>target_sprt - flags for target mode support, 0 if + unsupported</para> + </listitem> - <listitem><para>PIM_SCANHILO - bus scans from high ID to low - ID</para></listitem> + <listitem> + <para>hba_misc - miscellaneous controller + features:</para> + </listitem> - <listitem><para>PIM_NOREMOVE - removable devices not included in - scan</para></listitem> + <listitem> + <para>PIM_SCANHILO - bus scans from high ID to low + ID</para> + </listitem> - <listitem><para>PIM_NOINITIATOR - initiator role not - supported</para></listitem> + <listitem> + <para>PIM_NOREMOVE - removable devices not included in + scan</para> + </listitem> - <listitem><para>PIM_NOBUSRESET - user has disabled initial BUS - RESET</para></listitem> + <listitem> + <para>PIM_NOINITIATOR - initiator role not + supported</para> + </listitem> - <listitem><para>hba_eng_cnt - mysterious HBA engine count, - something related to compression, now is always set to - 0</para></listitem> + <listitem> + <para>PIM_NOBUSRESET - user has disabled initial BUS + RESET</para> + </listitem> - <listitem><para>vuhba_flags - vendor-unique flags, unused - now</para></listitem> + <listitem> + <para>hba_eng_cnt - mysterious HBA engine count, something + related to compression, now is always set to 0</para> + </listitem> - <listitem><para>max_target - maximal supported target ID (7 for - 8-bit bus, 15 for 16-bit bus, 127 for Fibre - Channel)</para></listitem> + <listitem> + <para>vuhba_flags - vendor-unique flags, unused now</para> + </listitem> - <listitem><para>max_lun - maximal supported LUN ID (7 for older - SCSI controllers, 63 for newer ones)</para></listitem> + <listitem> + <para>max_target - maximal supported target ID (7 for + 8-bit bus, 15 for 16-bit bus, 127 for Fibre + Channel)</para> + </listitem> - <listitem><para>async_flags - bitmask of installed Async - handler, unused now</para></listitem> + <listitem> + <para>max_lun - maximal supported LUN ID (7 for older SCSI + controllers, 63 for newer ones)</para> + </listitem> - <listitem><para>hpath_id - highest Path ID in the subsystem, - unused now</para></listitem> + <listitem> + <para>async_flags - bitmask of installed Async handler, + unused now</para> + </listitem> - <listitem><para>unit_number - the controller unit number, - cam_sim_unit(sim)</para></listitem> + <listitem> + <para>hpath_id - highest Path ID in the subsystem, unused + now</para> + </listitem> - <listitem><para>bus_id - the bus number, - cam_sim_bus(sim)</para></listitem> + <listitem> + <para>unit_number - the controller unit number, + cam_sim_unit(sim)</para> + </listitem> - <listitem><para>initiator_id - the SCSI ID of the controller - itself</para></listitem> + <listitem> + <para>bus_id - the bus number, cam_sim_bus(sim)</para> + </listitem> - <listitem><para>base_transfer_speed - nominal transfer speed in - KB/s for asynchronous narrow transfers, equals to 3300 for - SCSI</para></listitem> + <listitem> + <para>initiator_id - the SCSI ID of the controller + itself</para> + </listitem> - <listitem><para>sim_vid - SIM driver's vendor id, a - zero-terminated string of maximal length SIM_IDLEN including - the terminating zero</para></listitem> + <listitem> + <para>base_transfer_speed - nominal transfer speed in KB/s + for asynchronous narrow transfers, equals to 3300 for + SCSI</para> + </listitem> - <listitem><para>hba_vid - SCSI controller's vendor id, a - zero-terminated string of maximal length HBA_IDLEN including - the terminating zero</para></listitem> + <listitem> + <para>sim_vid - SIM driver's vendor id, a zero-terminated + string of maximal length SIM_IDLEN including the + terminating zero</para> + </listitem> - <listitem><para>dev_name - device driver name, a zero-terminated - string of maximal length DEV_IDLEN including the terminating - zero, equal to cam_sim_name(sim)</para></listitem> + <listitem> + <para>hba_vid - SCSI controller's vendor id, a + zero-terminated string of maximal length HBA_IDLEN + including the terminating zero</para> + </listitem> - </itemizedlist> + <listitem> + <para>dev_name - device driver name, a zero-terminated + string of maximal length DEV_IDLEN including the + terminating zero, equal to cam_sim_name(sim)</para> + </listitem> + </itemizedlist> - <para>The recommended way of setting the string fields is using - strncpy, like:</para> + <para>The recommended way of setting the string fields is + using strncpy, like:</para> -<programlisting> strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN);</programlisting> + <programlisting> strncpy(cpi->dev_name, cam_sim_name(sim), DEV_IDLEN);</programlisting> - <para>After setting the values set the status to CAM_REQ_CMP and mark the -CCB as done.</para> - </listitem> + <para>After setting the values set the status to CAM_REQ_CMP + and mark the CCB as done.</para> + </listitem> </itemizedlist> - </sect1> <sect1 id="scsi-polling"> <title>Polling</title> - <funcsynopsis><funcprototype> - <funcdef>static void - <function>xxx_poll</function> - </funcdef> - <paramdef> - <parameter>struct cam_sim *sim</parameter> - </paramdef> - </funcprototype></funcsynopsis> + <funcsynopsis> + <funcprototype> + <funcdef>static void + <function>xxx_poll</function> + </funcdef> + <paramdef> + <parameter>struct cam_sim *sim</parameter> + </paramdef> + </funcprototype> + </funcsynopsis> <para>The poll function is used to simulate the interrupts when the interrupt subsystem is not functioning (for example, when - the system has crashed and is creating the system dump). The CAM - subsystem sets the proper interrupt level before calling the - poll routine. So all it needs to do is to call the interrupt + the system has crashed and is creating the system dump). The + CAM subsystem sets the proper interrupt level before calling the + poll routine. So all it needs to do is to call the interrupt routine (or the other way around, the poll routine may be doing the real action and the interrupt routine would just call the - poll routine). Why bother about a separate function then? - Because of different calling conventions. The + poll routine). Why bother about a separate function then? + Because of different calling conventions. The <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 - gets just the device unit number. So the poll routine would + gets just the device unit number. So the poll routine would normally look as:</para> -<programlisting>static void + <programlisting>static void xxx_poll(struct cam_sim *sim) { xxx_intr((struct xxx_softc *)cam_sim_softc(sim)); /* for PCI device */ @@ -1458,12 +1664,11 @@ xxx_poll(struct cam_sim *sim) <para>or</para> -<programlisting>static void + <programlisting>static void xxx_poll(struct cam_sim *sim) { xxx_intr(cam_sim_unit(sim)); /* for ISA device */ }</programlisting> - </sect1> <sect1 id="scsi-async"> @@ -1472,25 +1677,33 @@ xxx_poll(struct cam_sim *sim) <para>If an asynchronous event callback has been set up then the callback function should be defined.</para> -<programlisting>static void + <programlisting>static void ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)</programlisting> <itemizedlist> - <listitem><para>callback_arg - the value supplied when registering the - callback</para></listitem> + <listitem> + <para>callback_arg - the value supplied when registering the + callback</para> + </listitem> - <listitem><para>code - identifies the type of event</para></listitem> + <listitem> + <para>code - identifies the type of event</para> + </listitem> - <listitem><para>path - identifies the devices to which the event - applies</para></listitem> + <listitem> + <para>path - identifies the devices to which the event + applies</para> + </listitem> - <listitem><para>arg - event-specific argument</para></listitem> + <listitem> + <para>arg - event-specific argument</para> + </listitem> </itemizedlist> <para>Implementation for a single type of event, AC_LOST_DEVICE, looks like:</para> -<programlisting> struct xxx_softc *softc; + <programlisting> struct xxx_softc *softc; struct cam_sim *sim; int targ; struct ccb_trans_settings neg; @@ -1513,7 +1726,6 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< default: break; }</programlisting> - </sect1> <sect1 id="scsi-interrupts"> @@ -1526,19 +1738,19 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< controller is connected.</para> <para>The interrupt routines of the SIM drivers run at the - interrupt level splcam. So <function>splcam()</function> should + interrupt level splcam. So <function>splcam()</function> should be used in the driver to synchronize activity between the interrupt routine and the rest of the driver (for a multiprocessor-aware driver things get yet more interesting but - we ignore this case here). The pseudo-code in this document - happily ignores the problems of synchronization. The real code - must not ignore them. A simple-minded approach is to set + we ignore this case here). The pseudo-code in this document + happily ignores the problems of synchronization. The real code + must not ignore them. A simple-minded approach is to set <function>splcam()</function> on the entry to the other routines and reset it on return thus protecting them by one big critical - section. To make sure that the interrupt level will be always + section. To make sure that the interrupt level will be always restored a wrapper function can be defined, like:</para> -<programlisting> static void + <programlisting> static void xxx_action(struct cam_sim *sim, union ccb *ccb) { int s; @@ -1555,27 +1767,28 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>This approach is simple and robust but the problem with it is that interrupts may get blocked for a relatively long time - and this would negatively affect the system's performance. On + and this would negatively affect the system's performance. On the other hand the functions of the <function>spl()</function> family have rather high overhead, so vast amount of tiny critical sections may not be good either.</para> <para>The conditions handled by the interrupt routine and the - details depend very much on the hardware. We consider the set of - <quote>typical</quote> conditions.</para> + details depend very much on the hardware. We consider the set + of <quote>typical</quote> conditions.</para> <para>First, we check if a SCSI reset was encountered on the bus (probably caused by another SCSI controller on the same SCSI - bus). If so we drop all the enqueued and disconnected requests, - report the events and re-initialize our SCSI controller. It is - important that during this initialization the controller will not - issue another reset or else two controllers on the same SCSI bus - could ping-pong resets forever. The case of fatal controller - error/hang could be handled in the same place, but it will - probably need also sending RESET signal to the SCSI bus to reset - the status of the connections with the SCSI devices.</para> - -<programlisting> int fatal=0; + bus). If so we drop all the enqueued and disconnected requests, + report the events and re-initialize our SCSI controller. It is + important that during this initialization the controller will + not issue another reset or else two controllers on the same SCSI + bus could ping-pong resets forever. The case of fatal + controller error/hang could be handled in the same place, but it + will probably need also sending RESET signal to the SCSI bus to + reset the status of the connections with the SCSI + devices.</para> + + <programlisting> int fatal=0; struct ccb_trans_settings neg; struct cam_path *path; @@ -1637,11 +1850,11 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>If interrupt is not caused by a controller-wide condition then probably something has happened to the current hardware - control block. Depending on the hardware there may be other + control block. Depending on the hardware there may be other non-HCB-related events, we just do not consider them here. Then we analyze what happened to this HCB:</para> -<programlisting> struct xxx_hcb *hcb, *h, *hh; + <programlisting> struct xxx_hcb *hcb, *h, *hh; int hcb_status, scsi_status; int ccb_status; int targ; @@ -1662,13 +1875,13 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>First we check if the HCB has completed and if so we check the returned SCSI status.</para> -<programlisting> if(hcb_status == COMPLETED) { + <programlisting> if(hcb_status == COMPLETED) { scsi_status = get_completion_status(hcb);</programlisting> <para>Then look if this status is related to the REQUEST SENSE command and if so handle it in a simple way.</para> -<programlisting> if(hcb->flags & DOING_AUTOSENSE) { + <programlisting> if(hcb->flags & DOING_AUTOSENSE) { if(scsi_status == GOOD) { /* autosense was successful */ hcb->ccb->ccb_h.status |= CAM_AUTOSNS_VALID; free_hcb_and_ccb_done(hcb, hcb->ccb, CAM_SCSI_STATUS_ERROR); @@ -1685,7 +1898,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< command has failed with sense data then run REQUEST SENSE command to receive that data.</para> -<programlisting> hcb->ccb->csio.scsi_status = scsi_status; + <programlisting> hcb->ccb->csio.scsi_status = scsi_status; calculate_residue(hcb); if( (hcb->ccb->ccb_h.flags & CAM_DIS_AUTOSENSE)==0 @@ -1711,7 +1924,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< unable to negotiate (rejects our negotiation messages or does not answer them).</para> -<programlisting> switch(hcb_status) { + <programlisting> switch(hcb_status) { case TARGET_REJECTED_WIDE_NEG: /* revert to 8-bit bus */ softc->current_bus_width[targ] = softc->goal_bus_width[targ] = 8; @@ -1764,19 +1977,19 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< }</programlisting> <para>Then we handle any errors that could have happened during - auto-sense in the same simple-minded way as before. Otherwise we - look closer at the details again.</para> + auto-sense in the same simple-minded way as before. Otherwise + we look closer at the details again.</para> -<programlisting> if(hcb->flags & DOING_AUTOSENSE) + <programlisting> if(hcb->flags & DOING_AUTOSENSE) goto autosense_failed; switch(hcb_status) {</programlisting> - <para>The next event we consider is unexpected disconnect. Which + <para>The next event we consider is unexpected disconnect. Which is considered normal after an ABORT or BUS DEVICE RESET message and abnormal in other cases.</para> -<programlisting> case UNEXPECTED_DISCONNECT: + <programlisting> case UNEXPECTED_DISCONNECT: if(requested_abort(hcb)) { /* abort affects all commands on that target+LUN, so * mark all disconnected HCBs on that target+LUN as aborted too @@ -1818,7 +2031,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>If the target refuses to accept tags we notify CAM about that and return back all commands for this LUN:</para> -<programlisting> case TAGS_REJECTED: + <programlisting> case TAGS_REJECTED: /* report the event */ neg.flags = 0 & ~CCB_TRANS_TAG_ENB; neg.valid = CCB_TRANS_TQ_VALID; @@ -1833,7 +2046,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>Then we check a number of other conditions, with processing basically limited to setting the CCB status:</para> -<programlisting> case SELECTION_TIMEOUT: + <programlisting> case SELECTION_TIMEOUT: ccb_status = CAM_SEL_TIMEOUT; /* request the further code to freeze the queue */ hcb->ccb->ccb_h.status |= CAM_DEV_QFRZN; @@ -1858,7 +2071,7 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>Then we check if the error was serious enough to freeze the input queue until it gets proceeded and do so if it is:</para> -<programlisting> if(hcb->ccb->ccb_h.status & CAM_DEV_QFRZN) { + <programlisting> if(hcb->ccb->ccb_h.status & CAM_DEV_QFRZN) { /* freeze the queue */ xpt_freeze_devq(ccb->ccb_h.path, /*count*/1); @@ -1878,7 +2091,6 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <para>This concludes the generic interrupt handling although specific controllers may require some additions.</para> - </sect1> <sect1 id="scsi-errors"> @@ -1886,83 +2098,113 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <indexterm><primary>SCSI</primary><secondary>errors</secondary></indexterm> - <para>When executing an I/O request many things may go wrong. The + <para>When executing an I/O request many things may go wrong. The reason of error can be reported in the CCB status with great - detail. Examples of use are spread throughout this document. For - completeness here is the summary of recommended responses for - the typical error conditions:</para> + detail. Examples of use are spread throughout this document. + For completeness here is the summary of recommended responses + for the typical error conditions:</para> <itemizedlist> + <listitem> + <para><emphasis>CAM_RESRC_UNAVAIL</emphasis> - some resource + is temporarily unavailable and the SIM driver cannot + generate an event when it will become available. An example + of this resource would be some intra-controller hardware + resource for which the controller does not generate an + interrupt when it becomes available.</para> + </listitem> - <listitem><para><emphasis>CAM_RESRC_UNAVAIL</emphasis> - some - resource is temporarily unavailable and the SIM driver cannot - generate an event when it will become available. An example of - this resource would be some intra-controller hardware resource - for which the controller does not generate an interrupt when - it becomes available.</para></listitem> - - <listitem><para><emphasis>CAM_UNCOR_PARITY</emphasis> - - unrecovered parity error occurred</para></listitem> + <listitem> + <para><emphasis>CAM_UNCOR_PARITY</emphasis> - unrecovered + parity error occurred</para> + </listitem> - <listitem><para><emphasis>CAM_DATA_RUN_ERR</emphasis> - data - overrun or unexpected data phase (going in other direction - than specified in CAM_DIR_MASK) or odd transfer length for - wide transfer</para></listitem> + <listitem> + <para><emphasis>CAM_DATA_RUN_ERR</emphasis> - data overrun or + unexpected data phase (going in other direction than + specified in CAM_DIR_MASK) or odd transfer length for wide + transfer</para> + </listitem> - <listitem><para><emphasis>CAM_SEL_TIMEOUT</emphasis> - selection - timeout occurred (target does not respond)</para></listitem> + <listitem> + <para><emphasis>CAM_SEL_TIMEOUT</emphasis> - selection timeout + occurred (target does not respond)</para> + </listitem> - <listitem><para><emphasis>CAM_CMD_TIMEOUT</emphasis> - command - timeout occurred (the timeout function ran)</para></listitem> + <listitem> + <para><emphasis>CAM_CMD_TIMEOUT</emphasis> - command timeout + occurred (the timeout function ran)</para> + </listitem> - <listitem><para><emphasis>CAM_SCSI_STATUS_ERROR</emphasis> - the - device returned error</para></listitem> + <listitem> + <para><emphasis>CAM_SCSI_STATUS_ERROR</emphasis> - the device + returned error</para> + </listitem> - <listitem><para><emphasis>CAM_AUTOSENSE_FAIL</emphasis> - the - device returned error and the REQUEST SENSE COMMAND - failed</para></listitem> + <listitem> + <para><emphasis>CAM_AUTOSENSE_FAIL</emphasis> - the device + returned error and the REQUEST SENSE COMMAND failed</para> + </listitem> - <listitem><para><emphasis>CAM_MSG_REJECT_REC</emphasis> - MESSAGE - REJECT message was received</para></listitem> + <listitem> + <para><emphasis>CAM_MSG_REJECT_REC</emphasis> - MESSAGE REJECT + message was received</para> + </listitem> - <listitem><para><emphasis>CAM_SCSI_BUS_RESET</emphasis> - received - SCSI bus reset</para></listitem> + <listitem> + <para><emphasis>CAM_SCSI_BUS_RESET</emphasis> - received SCSI + bus reset</para> + </listitem> - <listitem><para><emphasis>CAM_REQ_CMP_ERR</emphasis> - - <quote>impossible</quote> SCSI phase occurred or something else as weird or - just a generic error if further detail is not - available</para></listitem> + <listitem> + <para><emphasis>CAM_REQ_CMP_ERR</emphasis> - + <quote>impossible</quote> SCSI phase occurred or something + else as weird or just a generic error if further detail is + not available</para> + </listitem> - <listitem><para><emphasis>CAM_UNEXP_BUSFREE</emphasis> - - unexpected disconnect occurred</para></listitem> + <listitem> + <para><emphasis>CAM_UNEXP_BUSFREE</emphasis> - unexpected + disconnect occurred</para> + </listitem> - <listitem><para><emphasis>CAM_BDR_SENT</emphasis> - BUS DEVICE - RESET message was sent to the target</para></listitem> + <listitem> + <para><emphasis>CAM_BDR_SENT</emphasis> - BUS DEVICE RESET + message was sent to the target</para> + </listitem> - <listitem><para><emphasis>CAM_UNREC_HBA_ERROR</emphasis> - - unrecoverable Host Bus Adapter Error</para></listitem> + <listitem> + <para><emphasis>CAM_UNREC_HBA_ERROR</emphasis> - unrecoverable + Host Bus Adapter Error</para> + </listitem> - <listitem><para><emphasis>CAM_REQ_TOO_BIG</emphasis> - the request - was too large for this controller</para></listitem> + <listitem> + <para><emphasis>CAM_REQ_TOO_BIG</emphasis> - the request was + too large for this controller</para> + </listitem> - <listitem><para><emphasis>CAM_REQUEUE_REQ</emphasis> - this - request should be re-queued to preserve transaction ordering. - This typically occurs when the SIM recognizes an error that - should freeze the queue and must place other queued requests - for the target at the sim level back into the XPT - queue. Typical cases of such errors are selection timeouts, - command timeouts and other like conditions. In such cases the - troublesome command returns the status indicating the error, - the and the other commands which have not be sent to the bus - yet get re-queued.</para></listitem> + <listitem> + <para><emphasis>CAM_REQUEUE_REQ</emphasis> - this request + should be re-queued to preserve transaction ordering. This + typically occurs when the SIM recognizes an error that + should freeze the queue and must place other queued requests + for the target at the sim level back into the XPT queue. + Typical cases of such errors are selection timeouts, command + timeouts and other like conditions. In such cases the + troublesome command returns the status indicating the error, + the and the other commands which have not be sent to the bus + yet get re-queued.</para> + </listitem> - <listitem><para><emphasis>CAM_LUN_INVALID</emphasis> - the LUN - ID in the request is not supported by the SCSI - controller</para></listitem> + <listitem> + <para><emphasis>CAM_LUN_INVALID</emphasis> - the LUN ID in the + request is not supported by the SCSI controller</para> + </listitem> - <listitem><para><emphasis>CAM_TID_INVALID</emphasis> - the - target ID in the request is not supported by the SCSI - controller</para></listitem> + <listitem> + <para><emphasis>CAM_TID_INVALID</emphasis> - the target ID in + the request is not supported by the SCSI controller</para> + </listitem> </itemizedlist> </sect1> @@ -1970,19 +2212,19 @@ ahc_async(void *callback_arg, u_int32_t code, struct cam_path *path, void *arg)< <title>Timeout Handling</title> <para>When the timeout for an HCB expires that request should be - aborted, just like with an XPT_ABORT request. The only + aborted, just like with an XPT_ABORT request. The only difference is that the returned status of aborted request should be CAM_CMD_TIMEOUT instead of CAM_REQ_ABORTED (that is why - implementation of the abort better be done as a function). But + implementation of the abort better be done as a function). But there is one more possible problem: what if the abort request itself will get stuck? In this case the SCSI bus should be reset, just like with an XPT_RESET_BUS request (and the idea about implementing it as a function called from both places - applies here too). Also we should reset the whole SCSI bus if a - device reset request got stuck. So after all the timeout + applies here too). Also we should reset the whole SCSI bus if a + device reset request got stuck. So after all the timeout function would look like:</para> -<programlisting>static void + <programlisting>static void xxx_timeout(void *arg) { struct xxx_hcb *hcb = (struct xxx_hcb *)arg; @@ -2001,13 +2243,11 @@ xxx_timeout(void *arg) }</programlisting> <para>When we abort a request all the other disconnected requests - to the same target/LUN get aborted too. So there appears a + to the same target/LUN get aborted too. So there appears a question, should we return them with status CAM_REQ_ABORTED or CAM_CMD_TIMEOUT? The current drivers use CAM_CMD_TIMEOUT. This seems logical because if one request got timed out then probably something really bad is happening to the device, so if they would not be disturbed they would time out by themselves.</para> - </sect1> - </chapter> 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 65c06106e4..aca69c4450 100644 --- a/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml +++ b/en_US.ISO8859-1/books/arch-handbook/sound/chapter.xml @@ -9,7 +9,7 @@ <chapterinfo> <authorgroup> <author> - <firstname>Jean-Francois</firstname> + <firstname>Jean-Francois</firstname> <surname>Dockes</surname> <contrib>Contributed by </contrib> </author> @@ -35,31 +35,35 @@ <itemizedlist> <listitem> - <para>A system call interface (read, write, ioctls) to - digitized sound and mixer functions. The ioctl command set - is compatible with the legacy <emphasis>OSS</emphasis> or - <emphasis>Voxware</emphasis> interface, allowing common - multimedia applications to be ported without - modification.</para> + <para>A system call interface (read, write, ioctls) to + digitized sound and mixer functions. The ioctl command set + is compatible with the legacy <emphasis>OSS</emphasis> or + <emphasis>Voxware</emphasis> interface, allowing common + multimedia applications to be ported without + modification.</para> </listitem> + <listitem> - <para>Common code for processing sound data (format - conversions, virtual channels).</para> + <para>Common code for processing sound data (format + conversions, virtual channels).</para> </listitem> + <listitem> - <para>A uniform software interface to hardware-specific audio - interface modules.</para> + <para>A uniform software interface to hardware-specific audio + interface modules.</para> </listitem> + <listitem> - <para>Additional support for some common hardware interfaces - (ac97), or shared hardware-specific code (ex: ISA DMA - routines).</para> + <para>Additional support for some common hardware interfaces + (ac97), or shared hardware-specific code (ex: ISA DMA + routines).</para> </listitem> </itemizedlist> <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> code.</para> + hardware-specific drivers, which provide channel and mixer + interfaces to plug into the generic <devicename>pcm</devicename> + code.</para> <para>In this chapter, the term <devicename>pcm</devicename> will refer to the central, common part of the sound driver, as @@ -75,8 +79,7 @@ <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> - + http://people.FreeBSD.org/~cg/template.c</ulink></para> </sect1> <sect1 id="oss-files"> @@ -92,7 +95,6 @@ while the <filename>pci/</filename>, <filename>isa/</filename> and <filename>usb/</filename> directories have the drivers for PCI and ISA boards, and for USB audio devices.</para> - </sect1> <sect1 id="pcm-probe-and-attach"> @@ -107,13 +109,13 @@ <para>However, sound drivers differ in some ways:</para> <itemizedlist> - <listitem> - <para>They declare themselves as <devicename>pcm</devicename> - class devices, with a <structname>struct - snddev_info</structname> device private structure:</para> + <para>They declare themselves as <devicename>pcm</devicename> + class devices, with a + <structname>struct snddev_info</structname> device private + structure:</para> - <programlisting> static driver_t xxx_driver = { + <programlisting> static driver_t xxx_driver = { "pcm", xxx_methods, sizeof(struct snddev_info) @@ -122,77 +124,80 @@ DRIVER_MODULE(snd_xxxpci, pci, xxx_driver, pcm_devclass, 0, 0); MODULE_DEPEND(snd_xxxpci, snd_pcm, PCM_MINVER, PCM_PREFVER,PCM_MAXVER);</programlisting> - <indexterm><primary>device drivers</primary><secondary>sound</secondary></indexterm> - <para>Most sound drivers 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 - <function>pcm_register()</function> and - <function>mixer_init()</function>. - <devicename>pcm</devicename> later passes back this address - as a parameter in calls to the sound driver - interfaces.</para> + <para>Most sound drivers<indexterm><primary>device + drivers</primary><secondary>sound</secondary></indexterm> + 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 + <function>pcm_register()</function> and + <function>mixer_init()</function>. + <devicename>pcm</devicename> 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 - <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> + <para>The sound driver attach routine should declare its MIXER + or AC97 interface to <devicename>pcm</devicename> 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> </listitem> <listitem> - <para>The sound driver attach routine declares its general - CHANNEL configuration to <devicename>pcm</devicename> 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> - and <varname>nrec</varname> are the number of play and - record channels.</para> + <para>The sound driver attach routine declares its general + CHANNEL configuration to <devicename>pcm</devicename> 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> + and <varname>nrec</varname> are the number of play and + record channels.</para> </listitem> <listitem> - <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 - turn a call to - <link linkend="xxxchannel-init"> - <function>xxxchannel_init()</function></link>.</para> + <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 + turn a call to + <link linkend="xxxchannel-init"> + <function>xxxchannel_init()</function></link>.</para> </listitem> <listitem> - <para>The sound driver detach routine should call - <function>pcm_unregister()</function> before releasing its - resources.</para> + <para>The sound driver detach routine should call + <function>pcm_unregister()</function> before releasing its + resources.</para> </listitem> </itemizedlist> - <para>There are two possible methods to handle non-PnP devices:</para> + <para>There are two possible methods to handle non-PnP + devices:</para> + <itemizedlist> <listitem> - <para>Use a <function>device_identify()</function> method - (example: <filename>sound/isa/es1888.c</filename>). The - <function>device_identify()</function> method probes for the - hardware at known addresses and, if it finds a supported - device, creates a new pcm device which is then passed to - probe/attach.</para> + <para>Use a <function>device_identify()</function> method + (example: <filename>sound/isa/es1888.c</filename>). The + <function>device_identify()</function> method probes for the + hardware at known addresses and, if it finds a supported + device, creates a new pcm device which is then passed to + probe/attach.</para> </listitem> + <listitem> - <para>Use a custom kernel configuration with appropriate hints - for pcm devices (example: - <filename>sound/isa/mss.c</filename>).</para> + <para>Use a custom kernel configuration with appropriate hints + for pcm devices (example: + <filename>sound/isa/mss.c</filename>).</para> </listitem> </itemizedlist> <para><devicename>pcm</devicename> 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> - + <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"> @@ -200,7 +205,7 @@ <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> + 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 @@ -216,86 +221,84 @@ <title>The CHANNEL Interface</title> <sect3> - <title>Common Notes for Function Parameters</title> - - <para>Sound drivers usually have a private data structure to - describe their device, and one structure for each play and - record data channel that it supports.</para> + <title>Common Notes for Function Parameters</title> - <para>For all CHANNEL interface functions, the first parameter - is an opaque pointer.</para> + <para>Sound drivers usually have a private data structure to + describe their device, and one structure for each play and + record data channel that it supports.</para> - <para>The second parameter is a pointer to the private - channel data structure, except for - <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> + <para>For all CHANNEL interface functions, the first parameter + is an opaque pointer.</para> + <para>The second parameter is a pointer to the private + channel data structure, except for + <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> </sect3> <sect3> - <title>Overview of Data Transfer Operations</title> - - <para>For sound data transfers, the - <devicename>pcm</devicename> core and the sound drivers - communicate through a shared memory area, described by a - <structname>struct snd_dbuf</structname>.</para> - - <para><structname>struct snd_dbuf</structname> is private to - <devicename>pcm</devicename>, and sound drivers obtain - values of interest by calls to accessor functions - (<function>sndbuf_getxxx()</function>).</para> - - <para>The shared memory area has a size of - <function>sndbuf_getsize()</function> and is divided into - fixed size blocks of <function>sndbuf_getblksz()</function> - bytes.</para> - - <para>When playing, the general transfer mechanism is as - follows (reverse the idea for recording):</para> - - <itemizedlist> - <listitem> - <para><devicename>pcm</devicename> 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> - - <listitem> - <para>The sound driver then arranges to repeatedly - transfer the whole memory area - (<function>sndbuf_getbuf()</function>, - <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 - transferred block (this will typically happen at - interrupt time).</para> - </listitem> - - <listitem> - <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> - </listitem> - - </itemizedlist> - + <title>Overview of Data Transfer Operations</title> + + <para>For sound data transfers, the + <devicename>pcm</devicename> core and the sound drivers + communicate through a shared memory area, described by a + <structname>struct snd_dbuf</structname>.</para> + + <para><structname>struct snd_dbuf</structname> is private to + <devicename>pcm</devicename>, and sound drivers obtain + values of interest by calls to accessor functions + (<function>sndbuf_getxxx()</function>).</para> + + <para>The shared memory area has a size of + <function>sndbuf_getsize()</function> and is divided into + fixed size blocks of <function>sndbuf_getblksz()</function> + bytes.</para> + + <para>When playing, the general transfer mechanism is as + follows (reverse the idea for recording):</para> + + <itemizedlist> + <listitem> + <para><devicename>pcm</devicename> 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> + + <listitem> + <para>The sound driver then arranges to repeatedly + transfer the whole memory area + (<function>sndbuf_getbuf()</function>, + <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 + transferred block (this will typically happen at + interrupt time).</para> + </listitem> + + <listitem> + <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> + </listitem> + </itemizedlist> </sect3> <sect3 id="xxxchannel-init"> - <title>channel_init</title> + <title>channel_init</title> - <para><function>xxxchannel_init()</function> is called to - initialize each of the play or record channels. The calls - are initiated from the sound driver attach routine. (See - the <link linkend="pcm-probe-and-attach">probe and attach - section</link>).</para> + <para><function>xxxchannel_init()</function> is called to + initialize each of the play or record channels. The calls + are initiated from the sound driver attach routine. (See + the <link linkend="pcm-probe-and-attach">probe and attach + section</link>).</para> - <programlisting> static void * + <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"/> { @@ -305,46 +308,43 @@ return ch;<co 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 - 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 - 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: - <function>chn_intr(c)</function>).</para> - - <para><varname>dir</varname> indicates the channel - direction (<literal>PCMDIR_PLAY</literal> or - <literal>PCMDIR_REC</literal>).</para> - </callout> - - <callout arearefs="co-chinit-return"> - <para>The function should return a pointer to the private - area used to control this channel. This will be passed - as a parameter to other channel interface calls.</para> - </callout> - - </calloutlist> - + <calloutlist> + <callout arearefs="co-chinit-params"> + <para><varname>b</varname> is the address for the channel + <structname>struct snd_dbuf</structname>. 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 + 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: + <function>chn_intr(c)</function>).</para> + + <para><varname>dir</varname> indicates the channel + direction (<literal>PCMDIR_PLAY</literal> or + <literal>PCMDIR_REC</literal>).</para> + </callout> + + <callout arearefs="co-chinit-return"> + <para>The function should return a pointer to the private + area used to control this channel. This will be passed + as a parameter to other channel interface calls.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>channel_setformat</title> + <title>channel_setformat</title> - <para><function>xxxchannel_setformat()</function> should set - up the hardware for the specified channel for the specified - sound format.</para> + <para><function>xxxchannel_setformat()</function> should set + up the hardware for the specified channel for the specified + sound format.</para> - <programlisting> static int + <programlisting> static int xxxchannel_setformat(kobj_t obj, void *data, u_int32_t format)<co id="co-chsetformat-params"/> { struct xxx_chinfo *ch = data; @@ -352,51 +352,49 @@ return 0; }</programlisting> - <calloutlist> - <callout arearefs="co-chsetformat-params"> - <para><varname>format</varname> is specified as an - <literal>AFMT_XXX value</literal> - (<filename>soundcard.h</filename>).</para> - </callout> - - </calloutlist> + <calloutlist> + <callout arearefs="co-chsetformat-params"> + <para><varname>format</varname> is specified as an + <literal>AFMT_XXX value</literal> + (<filename>soundcard.h</filename>).</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>channel_setspeed</title> + <title>channel_setspeed</title> - <para><function>xxxchannel_setspeed()</function> sets up the - channel hardware for the specified sampling speed, and - returns the possibly adjusted speed.</para> + <para><function>xxxchannel_setspeed()</function> sets up the + channel hardware for the specified sampling speed, and + returns the possibly adjusted speed.</para> - <programlisting> static int + <programlisting> static int xxxchannel_setspeed(kobj_t obj, void *data, u_int32_t speed) { struct xxx_chinfo *ch = data; ... return speed; }</programlisting> - </sect3> <sect3> - <title>channel_setblocksize</title> - - <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 - 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 - <function>chn_intr()</function> every time this size has - been transferred.</para> - - <para>Most sound drivers only take note of the block size - here, to be used when an actual transfer will be - started.</para> - - <programlisting> static int + <title>channel_setblocksize</title> + + <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 + 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 + <function>chn_intr()</function> every time this size has + been transferred.</para> + + <para>Most sound drivers only take note of the block size + here, to be used when an actual transfer will be + started.</para> + + <programlisting> static int xxxchannel_setblocksize(kobj_t obj, void *data, u_int32_t blocksize) { struct xxx_chinfo *ch = data; @@ -404,26 +402,24 @@ return blocksize;<co id="co-chsetblocksize-return"/> }</programlisting> - <calloutlist> - <callout arearefs="co-chsetblocksize-return"> - <para>The function returns the possibly adjusted block - size. In case the block size is indeed changed, - <function>sndbuf_resize()</function> should be called to - adjust the buffer.</para> - - </callout> - </calloutlist> - + <calloutlist> + <callout arearefs="co-chsetblocksize-return"> + <para>The function returns the possibly adjusted block + size. In case the block size is indeed changed, + <function>sndbuf_resize()</function> should be called to + adjust the buffer.</para> + </callout> + </calloutlist> </sect3> <sect3 id="channel-trigger"> - <title>channel_trigger</title> + <title>channel_trigger</title> - <para><function>xxxchannel_trigger()</function> is called by - <devicename>pcm</devicename> to control data transfer - operations in the driver.</para> + <para><function>xxxchannel_trigger()</function> is called by + <devicename>pcm</devicename> to control data transfer + operations in the driver.</para> - <programlisting> static int + <programlisting> static int xxxchannel_trigger(kobj_t obj, void *data, int go)<co id="co-chtrigger-params"/> { struct xxx_chinfo *ch = data; @@ -431,120 +427,115 @@ return 0; }</programlisting> - <calloutlist> - <callout arearefs="co-chtrigger-params"> - <para><varname>go</varname> defines the action for the - current call. The possible values are:</para> - <itemizedlist> - - <listitem> - <para><literal>PCMTRIG_START</literal>: the driver - should start a data transfer from or to the channel - buffer. If needed, the buffer base and size can be - retrieved through - <function>sndbuf_getbuf()</function> and - <function>sndbuf_getsize()</function>.</para> - </listitem> - - <listitem> - <para><literal>PCMTRIG_EMLDMAWR</literal> / - <literal>PCMTRIG_EMLDMARD</literal>: this tells the - driver that the input or output buffer may have been - updated. Most drivers just ignore these - calls.</para> - </listitem> - - <listitem> - <para><literal>PCMTRIG_STOP</literal> / - <literal>PCMTRIG_ABORT</literal>: the driver should - stop the current transfer.</para> - </listitem> - </itemizedlist> - - </callout> - </calloutlist> - - <note><para>If the driver uses ISA DMA, - <function>sndbuf_isadma()</function> should be called before - performing actions on the device, and will take care of the - DMA chip side of things.</para> - </note> - + <calloutlist> + <callout arearefs="co-chtrigger-params"> + <para><varname>go</varname> defines the action for the + current call. The possible values are:</para> + + <itemizedlist> + <listitem> + <para><literal>PCMTRIG_START</literal>: the driver + should start a data transfer from or to the channel + buffer. If needed, the buffer base and size can be + retrieved through + <function>sndbuf_getbuf()</function> and + <function>sndbuf_getsize()</function>.</para> + </listitem> + + <listitem> + <para><literal>PCMTRIG_EMLDMAWR</literal> / + <literal>PCMTRIG_EMLDMARD</literal>: this tells the + driver that the input or output buffer may have been + updated. Most drivers just ignore these + calls.</para> + </listitem> + + <listitem> + <para><literal>PCMTRIG_STOP</literal> / + <literal>PCMTRIG_ABORT</literal>: the driver should + stop the current transfer.</para> + </listitem> + </itemizedlist> + </callout> + </calloutlist> + + <note> + <para>If the driver uses ISA DMA, + <function>sndbuf_isadma()</function> should be called + before performing actions on the device, and will take + care of the DMA chip side of things.</para> + </note> </sect3> <sect3> - <title>channel_getptr</title> - - <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 - new data.</para> + <title>channel_getptr</title> + <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 + new data.</para> </sect3> <sect3> - <title>channel_free</title> - - <para><function>xxxchannel_free()</function> is called to free - up channel resources, for example when the driver is - unloaded, and should be implemented if the channel data - structures are dynamically allocated or if - <function>sndbuf_alloc()</function> was not used for buffer - allocation.</para> - + <title>channel_free</title> + + <para><function>xxxchannel_free()</function> is called to free + up channel resources, for example when the driver is + unloaded, and should be implemented if the channel data + structures are dynamically allocated or if + <function>sndbuf_alloc()</function> was not used for buffer + allocation.</para> </sect3> <sect3> - <title>channel_getcaps</title> + <title>channel_getcaps</title> - <programlisting> struct pcmchan_caps * + <programlisting> struct pcmchan_caps * xxxchannel_getcaps(kobj_t obj, void *data) { return &xxx_caps;<co id="co-chgetcaps-return"/> }</programlisting> - <calloutlist> - - <callout arearefs="co-chgetcaps-return"> - <para>The routine returns a pointer to a (usually - statically-defined) <structname>pcmchan_caps</structname> - 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 any sound driver for an - example.</para> - </callout> - - </calloutlist> - + <calloutlist> + + <callout arearefs="co-chgetcaps-return"> + <para>The routine returns a pointer to a (usually + statically-defined) + <structname>pcmchan_caps</structname> 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 + any sound driver for an example.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>More Functions</title> + <title>More Functions</title> - <para><function>channel_reset()</function>, - <function>channel_resetdone()</function>, and - <function>channel_notify()</function> are for special purposes - and should not be implemented in a driver without discussing - it on the &a.multimedia;.</para> + <para><function>channel_reset()</function>, + <function>channel_resetdone()</function>, and + <function>channel_notify()</function> are for special + purposes and should not be implemented in a driver without + discussing it on the &a.multimedia;.</para> - <para><function>channel_setdir()</function> is deprecated.</para> + <para><function>channel_setdir()</function> is + deprecated.</para> </sect3> - </sect2> <sect2> <title>The MIXER Interface</title> <sect3 id="xxxmixer-init"> - <title>mixer_init</title> + <title>mixer_init</title> - <para><function>xxxmixer_init()</function> initializes the - hardware and tells <devicename>pcm</devicename> what mixer - devices are available for playing and recording</para> + <para><function>xxxmixer_init()</function> initializes the + hardware and tells <devicename>pcm</devicename> what mixer + devices are available for playing and recording</para> - <programlisting> static int + <programlisting> static int xxxmixer_init(struct snd_mixer *m) { struct xxx_info *sc = mix_getdevinfo(m); @@ -560,29 +551,28 @@ return 0; }</programlisting> - <calloutlist> - <callout arearefs="co-mxini-sd"> - <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> - </callout> - </calloutlist> - - <para>Mixer bits definitions can be found in - <filename>soundcard.h</filename> - (<literal>SOUND_MASK_XXX</literal> values and - <literal>SOUND_MIXER_XXX</literal> bit shifts).</para> - + <calloutlist> + <callout arearefs="co-mxini-sd"> + <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> + </callout> + </calloutlist> + + <para>Mixer bits definitions can be found in + <filename>soundcard.h</filename> + (<literal>SOUND_MASK_XXX</literal> values and + <literal>SOUND_MIXER_XXX</literal> bit shifts).</para> </sect3> <sect3> - <title>mixer_set</title> + <title>mixer_set</title> - <para><function>xxxmixer_set()</function> sets the volume - level for one mixer device.</para> + <para><function>xxxmixer_set()</function> sets the volume + level for one mixer device.</para> - <programlisting> static int + <programlisting> static int xxxmixer_set(struct snd_mixer *m, unsigned dev, unsigned left, unsigned right)<co id="co-mxset-params"/> { @@ -591,31 +581,32 @@ return left | (right << 8);<co id="co-mxset-return"/> }</programlisting> - <calloutlist> - <callout arearefs="co-mxset-params"> - <para>The device is specified as a <literal>SOUND_MIXER_XXX</literal> - value</para> <para>The volume values are specified in - range [0-100]. A value of zero should mute the - device.</para> - </callout> - - <callout arearefs="co-mxset-return"> - <para>As the hardware levels probably will not match the - input scale, and some rounding will occur, the routine - returns the actual level values (in range 0-100) as - shown.</para> - </callout> - </calloutlist> + <calloutlist> + <callout arearefs="co-mxset-params"> + <para>The device is specified as a + <literal>SOUND_MIXER_XXX</literal> value</para> + + <para>The volume values are specified in range [0-100]. + A value of zero should mute the device.</para> + </callout> + + <callout arearefs="co-mxset-return"> + <para>As the hardware levels probably will not match the + input scale, and some rounding will occur, the routine + returns the actual level values (in range 0-100) as + shown.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>mixer_setrecsrc</title> + <title>mixer_setrecsrc</title> - <para><function>xxxmixer_setrecsrc()</function> sets the - recording source device.</para> + <para><function>xxxmixer_setrecsrc()</function> sets the + recording source device.</para> - <programlisting> static int + <programlisting> static int xxxmixer_setrecsrc(struct snd_mixer *m, u_int32_t src)<co id="co-mxsr-params"/> { struct xxx_info *sc = mix_getdevinfo(m); @@ -626,62 +617,61 @@ return src;<co id="co-mxsr-return"/> }</programlisting> - <calloutlist> - <callout arearefs="co-mxsr-params"> - <para>The desired recording devices are specified as a - bit field</para> - </callout> - - <callout arearefs="co-mxsr-return"> - <para>The actual devices set for recording are returned. - Some drivers can only set one device for recording. The - function should return -1 if an error occurs.</para> - </callout> - </calloutlist> + <calloutlist> + <callout arearefs="co-mxsr-params"> + <para>The desired recording devices are specified as a + bit field</para> + </callout> + + <callout arearefs="co-mxsr-return"> + <para>The actual devices set for recording are returned. + Some drivers can only set one device for recording. The + function should return -1 if an error occurs.</para> + </callout> + </calloutlist> </sect3> <sect3> - <title>mixer_uninit, mixer_reinit</title> - - <para><function>xxxmixer_uninit()</function> should ensure - that all sound is muted and if possible mixer hardware - should be powered down </para> + <title>mixer_uninit, mixer_reinit</title> - <para><function>xxxmixer_reinit()</function> should ensure - that the mixer hardware is powered up and any settings not - controlled by <function>mixer_set()</function> or - <function>mixer_setrecsrc()</function> are restored.</para> + <para><function>xxxmixer_uninit()</function> should ensure + that all sound is muted and if possible mixer hardware + should be powered down </para> + <para><function>xxxmixer_reinit()</function> should ensure + that the mixer hardware is powered up and any settings not + controlled by <function>mixer_set()</function> or + <function>mixer_setrecsrc()</function> are restored.</para> </sect3> </sect2> <sect2> <title>The AC97 Interface</title> - <indexterm><primary>AC97</primary></indexterm> + <indexterm><primary>AC97</primary></indexterm> <para>The <emphasis>AC97</emphasis> interface is implemented - by drivers with an AC97 codec. It only has three methods:</para> + by drivers with an AC97 codec. It only has three + methods:</para> <itemizedlist> - - <listitem><para><function>xxxac97_init()</function> returns - the number of ac97 codecs found.</para> - </listitem> - - <listitem><para><function>ac97_read()</function> and - <function>ac97_write()</function> read or write a specified - register.</para> - </listitem> - + <listitem> + <para><function>xxxac97_init()</function> returns the number + of ac97 codecs found.</para> + </listitem> + + <listitem> + <para><function>ac97_read()</function> and + <function>ac97_write()</function> read or write a + specified register.</para> + </listitem> </itemizedlist> <para>The <emphasis>AC97</emphasis> interface is used by the - AC97 code in <devicename>pcm</devicename> 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> - + AC97 code in <devicename>pcm</devicename> 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> </sect2> </sect1> </chapter> 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 6d7432628c..7da8cc7186 100644 --- a/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml +++ b/en_US.ISO8859-1/books/developers-handbook/policies/chapter.xml @@ -13,7 +13,7 @@ <surname>Kamp</surname> <contrib>Contributed by </contrib> </author> - <author> + <author> <firstname>Giorgos</firstname> <surname>Keramidas</surname> </author> @@ -23,70 +23,76 @@ <title>Source Tree Guidelines and Policies</title> - <para>This chapter documents various guidelines and policies in force for - the FreeBSD source tree.</para> + <para>This chapter documents various guidelines and policies in + force for the FreeBSD source tree.</para> <sect1 id="policies-style"> <title>Style Guidelines</title> + <indexterm><primary>style</primary></indexterm> <para>Consistent coding style is extremely important, particularly - with large projects like &os;. Code should follow the &os; coding - styles described in &man.style.9; and + with large projects like &os;. Code should follow the &os; + coding styles described in &man.style.9; and &man.style.Makefile.5;.</para> </sect1> <sect1 id="policies-maintainer"> <title><makevar>MAINTAINER</makevar> on Makefiles</title> + <indexterm><primary>ports maintainer</primary></indexterm> - <para>If a particular portion of the &os; <filename>src/</filename> - distribution is being maintained by a person or group of persons, - this is communicated through an 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 + <para>If a particular portion of the &os; + <filename>src/</filename> distribution is being maintained by a + person or group of persons, this is communicated through an + 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 <filename>Makefile</filename> of the port in question:</para> <programlisting><makevar>MAINTAINER</makevar>= <replaceable>email-addresses</replaceable></programlisting> <tip> - <para>For other parts of the repository, or for sections not listed - as having a maintainer, or when you are unsure who the active - maintainer is, try looking at the recent commit history of the - relevant parts of the source tree. It is quite often the case - that a maintainer is not explicitly named, but the people who are - actively working in a part of the source tree for, say, the last - couple of years are interested in reviewing changes. Even if this - is not specifically mentioned in the documentation or the source - itself, asking for a review as a form of courtesy is a very - reasonable thing to do.</para> + <para>For other parts of the repository, or for sections not + listed as having a maintainer, or when you are unsure who the + active maintainer is, try looking at the recent commit history + of the relevant parts of the source tree. It is quite often + the case that a maintainer is not explicitly named, but the + people who are actively working in a part of the source tree + for, say, the last couple of years are interested in reviewing + changes. Even if this is not specifically mentioned in the + documentation or the source itself, asking for a review as a + form of courtesy is a very reasonable thing to do.</para> </tip> <para>The role of the maintainer is as follows:</para> <itemizedlist> <listitem> - <para>The maintainer owns and is responsible for that code. This means - that he or she is responsible for fixing bugs and answering problem reports - pertaining to that piece of the code, and in the case of contributed - software, for tracking new versions, as appropriate.</para> + <para>The maintainer owns and is responsible for that code. + This means that he or she is responsible for fixing bugs and + answering problem reports pertaining to that piece of the + code, and in the case of contributed software, for tracking + new versions, as appropriate.</para> </listitem> <listitem> - <para>Changes to directories which have a maintainer defined shall be sent - to the maintainer for review before being committed. Only if the - maintainer does not respond for an unacceptable period of time, to - several emails, will it be acceptable to commit changes without review - by the maintainer. However, it is suggested that you try to have the - changes reviewed by someone else if at all possible.</para> + <para>Changes to directories which have a maintainer defined + shall be sent to the maintainer for review before being + committed. Only if the maintainer does not respond for an + unacceptable period of time, to several emails, will it be + acceptable to commit changes without review by the + maintainer. However, it is suggested that you try to have + the changes reviewed by someone else if at all + possible.</para> </listitem> <listitem> - <para>It is of course not acceptable to add a person or group as - maintainer unless they agree to assume this duty. On the other hand it - does not have to be a committer and it can easily be a group of - people.</para> + <para>It is of course not acceptable to add a person or group + as maintainer unless they agree to assume this duty. On the + other hand it does not have to be a committer and it can + easily be a group of people.</para> </listitem> </itemizedlist> </sect1> @@ -115,37 +121,44 @@ <indexterm><primary>contributed software</primary></indexterm> - <para>Some parts of the FreeBSD distribution consist of software that is - actively being maintained outside the FreeBSD project. For historical - reasons, we call this <emphasis>contributed</emphasis> software. Some - examples are <application>sendmail</application>, <application>gcc</application> and <application>patch</application>.</para> - - <para>Over the last couple of years, various methods have been used in - dealing with this type of software and all have some number of - advantages and drawbacks. No clear winner has emerged.</para> - - <para>Since this is the case, after some debate one of these methods has - been selected as the <quote>official</quote> method and will be required - for future imports of software of this kind. Furthermore, it is - strongly suggested that existing contributed software converge on this - model over time, as it has significant advantages over the old method, - including the ability to easily obtain diffs relative to the - <quote>official</quote> versions of the source by everyone (even without - direct repository access). This will make it significantly easier to return changes - to the primary developers of the contributed software.</para> - - <para>Ultimately, however, it comes down to the people actually doing the - work. If using this model is particularly unsuited to the package being - dealt with, exceptions to these rules may be granted only with the - approval of the core team and with the general consensus of the other - developers. The ability to maintain the package in the future will be a - key issue in the decisions.</para> + <para>Some parts of the FreeBSD distribution consist of software + that is actively being maintained outside the FreeBSD project. + For historical reasons, we call this + <emphasis>contributed</emphasis> software. Some examples are + <application>sendmail</application>, + <application>gcc</application> and + <application>patch</application>.</para> + + <para>Over the last couple of years, various methods have been + used in dealing with this type of software and all have some + number of advantages and drawbacks. No clear winner has + emerged.</para> + + <para>Since this is the case, after some debate one of these + methods has been selected as the <quote>official</quote> method + and will be required for future imports of software of this + kind. Furthermore, it is strongly suggested that existing + contributed software converge on this model over time, as it has + significant advantages over the old method, including the + ability to easily obtain diffs relative to the + <quote>official</quote> versions of the source by everyone (even + without direct repository access). This will make it + significantly easier to return changes to the primary developers + of the contributed software.</para> + + <para>Ultimately, however, it comes down to the people actually + doing the work. If using this model is particularly unsuited to + the package being dealt with, exceptions to these rules may be + granted only with the approval of the core team and with the + general consensus of the other developers. The ability to + maintain the package in the future will be a key issue in the + decisions.</para> <note> <para>Because it makes it harder to import future versions - minor, trivial and/or - cosmetic changes are <emphasis>strongly discouraged</emphasis> on - files that are still tracking the vendor branch.</para> + minor, trivial and/or cosmetic changes are + <emphasis>strongly discouraged</emphasis> on files that are + still tracking the vendor branch.</para> </note> <sect2 id="vendor-import-svn"> @@ -169,16 +182,16 @@ <para>If this is your first import after the switch to <acronym>SVN</acronym>, you will have to flatten and clean - up the vendor tree, and bootstrap merge history in the main - tree. If not, you can safely omit this step.</para> + up the vendor tree, and bootstrap merge history in the + main tree. If not, you can safely omit this step.</para> <para>During the conversion from <acronym>CVS</acronym> to <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>, - but it is pointless and rather inconvenient. What we really - want is to have the vendor source directly in + 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>, like this:</para> @@ -192,9 +205,9 @@ <para>Note that, the <literal>propdel</literal> bit is necessary because starting with 1.5, Subversion will automatically add <literal>svn:mergeinfo</literal> to any - directory you copy or move. In this case, you will not need - this information, since you are not going to merge anything - from the tree you deleted.</para> + directory you copy or move. In this case, you will not + need this information, since you are not going to merge + anything from the tree you deleted.</para> <note> <para>You may want to flatten the tags as well. The @@ -202,19 +215,19 @@ the commit until the end.</para> </note> - <para>Check the <filename>dist</filename> tree and perform any - cleanup that is deemed to be necessary. You may want to - disable keyword expansion, as it makes no sense on + <para>Check the <filename>dist</filename> tree and perform + any cleanup that is deemed to be necessary. You may want + to disable keyword expansion, as it makes no sense on 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> - <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> + <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> @@ -228,16 +241,17 @@ <step> <title>Importing New Sources</title> - <para>Prepare a full, clean tree of the vendor sources. With - <acronym>SVN</acronym>, we can keep a full distribution in - the vendor tree without bloating the main tree. Import - everything but merge only what is needed.</para> + <para>Prepare a full, clean tree of the vendor sources. + With <acronym>SVN</acronym>, we can keep a full + distribution in the vendor tree without bloating the main + tree. Import everything but merge only what is + needed.</para> - <para>Note that you will need to add any files that were added - since the last vendor import, and remove any that were - removed. To facilitate this, you should prepare sorted - lists of the contents of the vendor tree and of the sources - you are about to import:</para> + <para>Note that you will need to add any files that were + added since the last vendor import, and remove any that + were removed. To facilitate this, you should prepare + 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> @@ -265,11 +279,11 @@ &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> <warning> - <para>If there are new directories in the new distribution, - the last command will fail. You will have to add the - directories, and run it again. Conversely, if any - directories were removed, you will have to remove them - manually.</para> + <para>If there are new directories in the new + distribution, the last command will fail. You will have + to add the directories, and run it again. Conversely, + if any directories were removed, you will have to remove + them manually.</para> </warning> <para>Check properties on any new files:</para> @@ -302,8 +316,9 @@ <note> <para>You are ready to commit, but you should first check - the output of <command>svn stat</command> and <command>svn - diff</command> to make sure everything is in order.</para> + the output of <command>svn stat</command> and + <command>svn diff</command> to make sure everything is + in order.</para> </note> <para>Once you have committed the new vendor release, you @@ -312,12 +327,13 @@ <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> - <para>To get the new tag, you can update your working copy of + <para>To get the new tag, you can update your working copy + of <filename>vendor/<replaceable>foo</replaceable></filename>.</para> <note> - <para>If you choose to do the copy in the checkout instead, - do not forget to remove the generated + <para>If you choose to do the copy in the checkout + instead, do not forget to remove the generated <literal>svn:mergeinfo</literal> as described above.</para> </note> @@ -335,10 +351,11 @@ &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> - <para>Resolve any conflicts, and make sure that any files that - were added or removed in the vendor tree have been properly - added or removed in the main tree. It is always a good idea - to check differences against the vendor branch:</para> + <para>Resolve any conflicts, and make sure that any files + that were added or removed in the vendor tree have been + properly added or removed in the main tree. It is always + 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> @@ -347,16 +364,16 @@ vendor tree but not in the main tree.</para> <note> - <para>With <acronym>SVN</acronym>, there is no concept of on - or off the vendor branch. If a file that previously had - local modifications no longer does, just remove any + <para>With <acronym>SVN</acronym>, there is no concept of + on or off the vendor branch. If a file that previously + had local modifications no longer does, just remove any left-over cruft, such as &os; version tags, so it no longer shows up in diffs against the vendor tree.</para> </note> - <para>If any changes are required for the world to build with - the new sources, make them now — and test until you - are satisfied that everything build and runs + <para>If any changes are required for the world to build + with the new sources, make them now — and test until + you are satisfied that everything build and runs correctly.</para> </step> @@ -378,93 +395,103 @@ <sect1 id="policies-encumbered"> <title>Encumbered Files</title> - <para>It might occasionally be necessary to include an encumbered file in - the FreeBSD source tree. For example, if a device requires a small - piece of binary code to be loaded to it before the device will operate, - and we do not have the source to that code, then the binary file is said - to be encumbered. The following policies apply to including encumbered - files in the FreeBSD source tree.</para> + <para>It might occasionally be necessary to include an encumbered + file in the FreeBSD source tree. For example, if a device + requires a small piece of binary code to be loaded to it before + the device will operate, and we do not have the source to that + code, then the binary file is said to be encumbered. The + following policies apply to including encumbered files in the + FreeBSD source tree.</para> <orderedlist> <listitem> - <para>Any file which is interpreted or executed by the system CPU(s) - and not in source format is encumbered.</para> + <para>Any file which is interpreted or executed by the system + CPU(s) and not in source format is encumbered.</para> </listitem> <listitem> - <para>Any file with a license more restrictive than BSD or GNU is - encumbered.</para> + <para>Any file with a license more restrictive than BSD or GNU + is encumbered.</para> </listitem> <listitem> - <para>A file which contains downloadable binary data for use by the - hardware is not encumbered, unless (1) or (2) apply to it. It must - be stored in an architecture neutral ASCII format (file2c or - uuencoding is recommended).</para> + <para>A file which contains downloadable binary data for use + by the hardware is not encumbered, unless (1) or (2) apply + to it. It must be stored in an architecture neutral ASCII + format (file2c or uuencoding is recommended).</para> </listitem> <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> + <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> </listitem> <listitem> - <para>Encumbered files go in <filename>src/contrib</filename> or - <filename>src/sys/contrib</filename>.</para> + <para>Encumbered files go in <filename>src/contrib</filename> + or <filename>src/sys/contrib</filename>.</para> </listitem> <listitem> - <para>The entire module should be kept together. There is no point in - splitting it, unless there is code-sharing with non-encumbered - code.</para> + <para>The entire module should be kept together. There is no + point in splitting it, unless there is code-sharing with + non-encumbered code.</para> </listitem> <listitem> - <para>Object files are named + <para>Object files are named <filename><replaceable>arch</replaceable>/<replaceable>filename</replaceable>.o.uu></filename>.</para> </listitem> <listitem> - <para>Kernel files:</para> + <para>Kernel files:</para> + + <orderedlist> + <listitem> + <para>Should always be referenced in + <filename>conf/files.*</filename> (for build + simplicity).</para> + </listitem> - <orderedlist> - <listitem> - <para>Should always be referenced in - <filename>conf/files.*</filename> (for build simplicity).</para> + <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 + on.</para> </listitem> - <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 on.</para> - </listitem> - - <listitem> - <para>The <firstterm>Release Engineer</firstterm> - decides whether or not it goes into the release.</para> - </listitem> - </orderedlist> + <listitem> + <para>The <firstterm>Release Engineer</firstterm> + decides whether or not it goes into the release.</para> + </listitem> + </orderedlist> </listitem> <listitem> - <para>User-land files:</para> - - <orderedlist> - <listitem> - <indexterm><primary>core team</primary></indexterm> - <para>The <ulink url="&url.base;/administration.html#t-core">Core team</ulink> decides if - the code should be part of <command>make world</command>.</para> - </listitem> - - <listitem> - <indexterm><primary>release engineering</primary></indexterm> - <para>The <ulink url="&url.base;/administration.html#t-re">Release Engineering</ulink> - decides if it goes into the release.</para> - </listitem> - </orderedlist> + <para>User-land files:</para> + + <orderedlist> + <listitem> + <para>The <ulink + url="&url.base;/administration.html#t-core">Core + team</ulink><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 + engineering</primary></indexterm> + decides if it goes into the release.</para> + </listitem> + </orderedlist> </listitem> </orderedlist> </sect1> @@ -491,10 +518,11 @@ <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 should follow these - rules. Generally, the resulting numbers will have nothing to do with - the release version of the software.</para> + <para>If you are adding shared library support to a port or other + piece of software that does not have one, the version numbers + should follow these rules. Generally, the resulting numbers + will have nothing to do with the release version of the + software.</para> <para>The three principles of shared library building are:</para> @@ -504,57 +532,64 @@ </listitem> <listitem> - <para>If there is a change that is backwards compatible, bump minor - number (note that ELF systems ignore the minor number)</para> + <para>If there is a change that is backwards compatible, bump + minor number (note that ELF systems ignore the minor + number)</para> </listitem> <listitem> - <para>If there is an incompatible change, bump major number</para> + <para>If there is an incompatible change, bump major + number</para> </listitem> </itemizedlist> - <para>For instance, added functions and bugfixes result in the minor - version number being bumped, while deleted functions, changed function - call syntax, etc. will force the major version number to change.</para> + <para>For instance, added functions and bugfixes result in the + minor version number being bumped, while deleted functions, + changed function call syntax, etc. will force the major version + number to change.</para> <para>Stick to version numbers of the form major.minor - (<replaceable>x</replaceable>.<replaceable>y</replaceable>). Our a.out - dynamic linker does not handle version numbers of the form + (<replaceable>x</replaceable>.<replaceable>y</replaceable>). + Our a.out dynamic linker does not handle version numbers of the + form <replaceable>x</replaceable>.<replaceable>y</replaceable>.<replaceable>z</replaceable> well. Any version number after the <replaceable>y</replaceable> - (i.e. the third digit) is totally ignored when comparing shared lib - version numbers to decide which library to link with. Given two shared - libraries that differ only in the <quote>micro</quote> revision, - <command>ld.so</command> will link with the higher one. That is, if you link - with <filename>libfoo.so.3.3.3</filename>, the linker only records - <literal>3.3</literal> in the headers, and will link with anything - starting with - <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything >= - 3)</replaceable>.<replaceable>(highest + (i.e. the third digit) is totally ignored when comparing shared + lib version numbers to decide which library to link with. Given + two shared libraries that differ only in the + <quote>micro</quote> revision, <command>ld.so</command> will + link with the higher one. That is, if you link with + <filename>libfoo.so.3.3.3</filename>, the linker only records + <literal>3.3</literal> in the headers, and will link with + anything starting with + <replaceable>libfoo.so.3</replaceable>.<replaceable>(anything + >= 3)</replaceable>.<replaceable>(highest available)</replaceable>.</para> <note> <para><command>ld.so</command> will always use the highest <quote>minor</quote> revision. For instance, it will use <filename>libc.so.2.2</filename> in preference to - <filename>libc.so.2.0</filename>, even if the program was initially - linked with <filename>libc.so.2.0</filename>.</para> + <filename>libc.so.2.0</filename>, even if the program was + initially linked with <filename>libc.so.2.0</filename>.</para> </note> - <para>In addition, our ELF dynamic linker does not handle minor version - numbers at all. However, one should still specify a major and minor - version number as our <filename>Makefile</filename>s <quote>do the right thing</quote> - based on the type of system.</para> - - <para>For non-port libraries, it is also our policy to change the shared - library version number only once between releases. In addition, it is - our policy to change the major shared library version number only once - between major OS releases (i.e. from 6.0 to 7.0). When you make a - change to a system library that requires the version number to be - bumped, check the <filename>Makefile</filename>'s commit logs. It is the - responsibility of the committer to ensure that the first such change - since the release will result in the shared library version number in - the <filename>Makefile</filename> to be updated, and any subsequent - changes will not.</para> + <para>In addition, our ELF dynamic linker does not handle minor + version numbers at all. However, one should still specify a + major and minor version number as our + <filename>Makefile</filename>s <quote>do the right thing</quote> + based on the type of system.</para> + + <para>For non-port libraries, it is also our policy to change the + shared library version number only once between releases. In + addition, it is our policy to change the major shared library + version number only once between major OS releases (i.e. from + 6.0 to 7.0). When you make a change to a system library that + requires the version number to be bumped, check the + <filename>Makefile</filename>'s commit logs. It is the + responsibility of the committer to ensure that the first such + change since the release will result in the shared library + version number in the <filename>Makefile</filename> to be + updated, and any subsequent changes will not.</para> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/fdp-primer/Makefile b/en_US.ISO8859-1/books/fdp-primer/Makefile index ea2b447772..a1be3e53f1 100644 --- a/en_US.ISO8859-1/books/fdp-primer/Makefile +++ b/en_US.ISO8859-1/books/fdp-primer/Makefile @@ -21,18 +21,19 @@ INSTALL_ONLY_COMPRESSED?= # XML content SRCS= book.xml SRCS+= overview/chapter.xml -SRCS+= psgml-mode/chapter.xml -SRCS+= see-also/chapter.xml -SRCS+= xhtml-markup/chapter.xml -SRCS+= docbook-markup/chapter.xml -SRCS+= xml-primer/chapter.xml -SRCS+= stylesheets/chapter.xml +SRCS+= tools/chapter.xml +SRCS+= working-copy/chapter.xml SRCS+= structure/chapter.xml SRCS+= doc-build/chapter.xml SRCS+= the-website/chapter.xml -SRCS+= tools/chapter.xml +SRCS+= xml-primer/chapter.xml +SRCS+= xhtml-markup/chapter.xml +SRCS+= docbook-markup/chapter.xml +SRCS+= stylesheets/chapter.xml SRCS+= translations/chapter.xml SRCS+= writing-style/chapter.xml +SRCS+= editor-config/chapter.xml +SRCS+= see-also/chapter.xml SRCS+= examples/appendix.xml diff --git a/en_US.ISO8859-1/books/fdp-primer/book.xml b/en_US.ISO8859-1/books/fdp-primer/book.xml index ef7a67032f..c1e16f1040 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.xml +++ b/en_US.ISO8859-1/books/fdp-primer/book.xml @@ -250,16 +250,17 @@ The time is 09:18</screen></entry> &chap.overview; &chap.tools; + &chap.working-copy; + &chap.structure; + &chap.doc-build; + &chap.the-website; &chap.xml-primer; &chap.xhtml-markup; &chap.docbook-markup; &chap.stylesheets; - &chap.structure; - &chap.doc-build; - &chap.the-website; &chap.translations; &chap.writing-style; - &chap.psgml-mode; + &chap.editor-config; &chap.see-also; &app.examples; diff --git a/en_US.ISO8859-1/books/fdp-primer/chapters.ent b/en_US.ISO8859-1/books/fdp-primer/chapters.ent index cf5895677e..81278d507e 100644 --- a/en_US.ISO8859-1/books/fdp-primer/chapters.ent +++ b/en_US.ISO8859-1/books/fdp-primer/chapters.ent @@ -11,17 +11,18 @@ --> <!ENTITY chap.overview SYSTEM "overview/chapter.xml"> -<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> <!ENTITY chap.tools SYSTEM "tools/chapter.xml"> +<!ENTITY chap.working-copy SYSTEM "working-copy/chapter.xml"> +<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> +<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> +<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> +<!ENTITY chap.xml-primer SYSTEM "xml-primer/chapter.xml"> <!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml"> <!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml"> <!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml"> -<!ENTITY chap.structure SYSTEM "structure/chapter.xml"> -<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml"> <!ENTITY chap.translations SYSTEM "translations/chapter.xml"> <!ENTITY chap.writing-style SYSTEM "writing-style/chapter.xml"> -<!ENTITY chap.psgml-mode SYSTEM "psgml-mode/chapter.xml"> +<!ENTITY chap.editor-config SYSTEM "editor-config/chapter.xml"> <!ENTITY chap.see-also SYSTEM "see-also/chapter.xml"> -<!ENTITY chap.doc-build SYSTEM "doc-build/chapter.xml"> <!ENTITY app.examples SYSTEM "examples/appendix.xml"> 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 05d5abbea4..95ab3e73a0 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 @@ -34,75 +34,37 @@ <chapter id="doc-build"> <title>The Documentation Build Process</title> - <para>This chapter's main purpose is to clearly explain - <emphasis>how the documentation build process is - organized</emphasis>, and <emphasis>how to affect modifications - to this process</emphasis>.</para> - - <para>After you have finished reading this chapter you - should:</para> - - <itemizedlist> - <listitem> - <para>Know what you need to build the FDP documentation, in - addition to those mentioned in the - <link linkend="tools">XML tools chapter</link>.</para> - </listitem> - - <listitem> - <para>Be able to read and understand the - <application>make</application> instructions that are present - in each document's <filename>Makefile</filename>s, as well as - an overview of the <filename>doc.project.mk</filename> - includes.</para> - </listitem> - - <listitem> - <para>Be able to customize the build process by using - <application>make</application> variables and - <application>make</application> targets.</para> - </listitem> - </itemizedlist> + <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"> - <title>The FreeBSD Documentation Build Toolset</title> + <title>The &os; Documentation Build Toolset</title> - <para>Here are your tools. Use them every way you can.</para> + <para>These are the tools used to build and install the + <acronym>FDP</acronym> documentation.</para> <itemizedlist> <listitem> - <para>The primary build tool you will need is - <application>make</application>, but specifically + <para>The primary build tool is &man.make.1;, specifically <application>Berkeley Make</application>.</para> </listitem> <listitem> - <para>Package building is handled by FreeBSD's - <application>pkg_create</application>. If you are not using - FreeBSD, you will either have to live without packages, or - compile the source yourself.</para> + <para>Package building is handled by &os;'s + &man.pkg.create.1;.</para> </listitem> <listitem> - <para><application>gzip</application> is needed to create - compressed versions of the document. - <application>bzip2</application> compression and - <application>zip</application> archives are also supported. - <application>tar</application> is supported, but package - building demands it.</para> + <para>&man.gzip.1; is used to create compressed versions of + the document. &man.bzip2.1; archives are also supported. + &man.tar.1; is used for package building.</para> </listitem> <listitem> - <para><application>install</application> is the default method - to install the documentation. There are alternatives, - however.</para> + <para>&man.install.1; is used to install the + documentation.</para> </listitem> </itemizedlist> - - <note> - <para>It is unlikely you will have any trouble finding these - last two, they are mentioned for completeness only.</para> - </note> </sect1> <sect1 id="doc-build-makefiles"> @@ -111,7 +73,7 @@ Documentation Tree</title> <para>There are three main types of <filename>Makefile</filename>s - in the FreeBSD Documentation Project tree.</para> + in the &os; Documentation Project tree.</para> <itemizedlist> <listitem> @@ -150,13 +112,13 @@ COMPAT_SYMLINK = en DOC_PREFIX?= ${.CURDIR}/.. .include "${DOC_PREFIX}/share/mk/doc.project.mk"</programlisting> - <para>In quick summary, the first four non-empty lines define - the <application>make</application> variables, - <makevar>SUBDIR</makevar>, <makevar>COMPAT_SYMLINK</makevar>, - and <makevar>DOC_PREFIX</makevar>.</para> + <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> - <para>The first <makevar>SUBDIR</makevar> statement, as well as - the <makevar>COMPAT_SYMLINK</makevar> statement, shows how to + <para>The <makevar>SUBDIR</makevar> statement and + <makevar>COMPAT_SYMLINK</makevar> statement show how to assign a value to a variable, overriding any previous value.</para> @@ -172,7 +134,7 @@ DOC_PREFIX?= ${.CURDIR}/.. <filename>Makefile</filename> thinks it is - the user can override this and provide the correct value.</para> - <para>Now what does it all mean? <makevar>SUBDIR</makevar> + <para>What does it all mean? <makevar>SUBDIR</makevar> mentions which subdirectories below this one the build process should pass any work on to.</para> @@ -182,24 +144,24 @@ DOC_PREFIX?= ${.CURDIR}/.. point to <filename>en_US.ISO-8859-1</filename>).</para> <para><makevar>DOC_PREFIX</makevar> is the path to the root of - the FreeBSD 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 - <application>make</application> builtin variable with the path - to the current directory.</para> - - <para>The final line includes the FreeBSD Documentation - Project's project-wide <application>make</application> system - file <filename>doc.project.mk</filename> which is the glue - which converts these variables into build instructions.</para> + 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; + builtin variable with the path to the current + directory.</para> + + <para>The final line includes the &os; Documentation Project's + project-wide &man.make.1; system file + <filename>doc.project.mk</filename> which is the glue which + converts these variables into build instructions.</para> </sect2> <sect2 id="doc-make"> <title>Documentation <filename>Makefile</filename>s</title> - <para>These <filename>Makefile</filename>s set a bunch of - <application>make</application> variables that describe how to - build the documentation contained in that directory.</para> + <para>These <filename>Makefile</filename>s set &man.make.1; + variables that describe how to build the documentation + contained in that directory.</para> <para>Here is an example:</para> @@ -219,10 +181,9 @@ DOC_PREFIX?= ${.CURDIR}/../../.. .include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"</programlisting> - <para>The <makevar>MAINTAINER</makevar> variable is a very - important one. This variable provides the ability to claim - ownership over a document in the FreeBSD Documentation - Project, whereby you gain the responsibility for maintaining + <para>The <makevar>MAINTAINER</makevar> 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 @@ -240,22 +201,17 @@ DOC_PREFIX?= ${.CURDIR}/../../.. default, should be non-empty if only compressed documents are desired in the build.</para> - <note> - <para>We covered optional variable assignments in the - <link linkend="sub-make">previous section</link>.</para> - </note> - <para>The <makevar>DOC_PREFIX</makevar> and include statements should be familiar already.</para> </sect2> </sect1> <sect1 id="make-includes"> - <title>FreeBSD Documentation Project + <title>&os; Documentation Project <application>Make</application> Includes</title> - <para>This is best explained by inspection of the code. Here are - the system include files:</para> + <para>&man.make.1; includes are best explained by inspection of + the code. Here are the system include files:</para> <itemizedlist> <listitem> @@ -321,10 +277,10 @@ PRI_LANG?= en_US.ISO8859-1 default.</para> <note> - <para><makevar>PRI_LANG</makevar> in no way affects what + <para><makevar>PRI_LANG</makevar> does not affect which documents can, or even will, be built. Its main use is creating links to commonly referenced documents into the - FreeBSD documentation install root.</para> + &os; documentation install root.</para> </note> </sect3> @@ -332,11 +288,10 @@ PRI_LANG?= en_US.ISO8859-1 <title>Conditionals</title> <para>The <literal>.if defined(DOC)</literal> line is an - example of a <application>make</application> conditional - which, like in other programs, defines behavior if some - condition is true or if it is false. - <literal>defined</literal> is a function which returns - whether the variable given is defined or not.</para> + example of a &man.make.1; conditional which, like in other + programs, defines behavior if some condition is true or if + it is false. <literal>defined</literal> is a function which + 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 @@ -351,9 +306,8 @@ PRI_LANG?= en_US.ISO8859-1 <sect2> <title><filename>doc.subdir.mk</filename></title> - <para>This is too long to explain by inspection, you should be - able to work it out with the knowledge gained from the - previous chapters, and a little help given here.</para> + <para>This file is too long to explain in detail. These notes + describe the most important features.</para> <sect3> <title>Variables</title> @@ -389,8 +343,8 @@ PRI_LANG?= en_US.ISO8859-1 <literal><replaceable>target</replaceable>: <replaceable>dependency1 dependency2 ...</replaceable></literal> tuples, where to build - <literal>target</literal>, you need to build the given - dependencies first.</para> + <literal>target</literal>, the given + dependencies must be built first.</para> <para>After that descriptive tuple, instructions on how to build the target may be given, if the conversion process 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 7eb15d0ea5..9cf9617c8b 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 @@ -46,8 +46,9 @@ not answer to the &a.doc;.</para> <para>DocBook was originally developed by HaL Computer Systems and - O'Reilly & Associates to be a <acronym>DTD</acronym> for - writing technical documentation <footnote><para>A short history + 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>. @@ -92,31 +93,262 @@ <title>&os; Extensions</title> <para>The &os; Documentation Project has extended the - DocBook <acronym>DTD</acronym> by adding some new elements. - These elements serve to make some of the markup more - precise.</para> - - <para>Where a &os;-specific element is listed below, it is - clearly marked.</para> + DocBook <acronym>DTD</acronym> with additional elements and + entities. These additions serve to make some of the markup + easier or more precise.</para> <para>Throughout the rest of this document, the term <quote>DocBook</quote> is used to mean the &os;-extended DocBook <acronym>DTD</acronym>.</para> <note> - <para>There is nothing about these extensions that is &os; - specific, it was just felt that they were useful + <para>Most of these extensions are not unique to &os;, + 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 + DocBook extension set, please contact &a.doceng;.</para> </note> - <para>The &os; extensions 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> + <sect2 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> + + <para>&os;-specific elements used in the examples below are + clearly marked.</para> + </sect2> + + <sect2 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> + + <informaltable frame="none" pgwide="1"> + <tgroup cols="3"> + <colspec colname="entity"/> + <colspec colname="expandsto"/> + <colspec colname="notes"/> + + <tbody valign="top"> + <row> + <entry namest="entity" nameend="notes">&os; Name Entities</entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry><literal>&os;</literal></entry> + <entry><literal>&os;</literal></entry> + <entry></entry> + </row> + + <row> + <entry><literal>&os.stable;</literal></entry> + <entry><literal>&os.stable;</literal></entry> + <entry></entry> + </row> + + <row> + <entry><literal>&os.current;</literal></entry> + <entry><literal>&os.current;</literal></entry> + <entry></entry> + </row> + + <row> + <entry></entry> + </row> + + <row> + <entry namest="entity" nameend="notes">Manual Page Entities</entry> + <entry></entry> + <entry></entry> + </row> + + <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> + </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> + </row> + + <row> + <entry><literal>&man.<replaceable>command</replaceable>.<replaceable>sectionnumber</replaceable>;</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> + </row> + + <row> + <entry></entry> + </row> + + <row> + <entry namest="entity" nameend="notes">&os; Mailing List Entities</entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry><literal>&a.doc;</literal></entry> + <entry><literal>&a.doc;</literal></entry> + <entry>Usage: <literal>A link to the &a.doc;.</literal></entry> + </row> + + <row> + <entry><literal>&a.questions;</literal></entry> + <entry><literal>&a.questions;</literal></entry> + <entry>Usage: <literal>A link to the &a.questions;.</literal></entry> + </row> + + <row> + <entry><literal>&a.<replaceable>listname</replaceable>;</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> + </row> + + <row> + <entry></entry> + </row> + + <row> + <entry namest="entity" nameend="notes">&os; Document Link Entities</entry> + <entry></entry> + <entry></entry> + </row> + + <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> + chapter of the Handbook.</literal></entry> + </row> + + <row> + <entry><literal>&url.books.<replaceable>bookname</replaceable>;</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> + </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> + article.</literal></entry> + </row> + + <row> + <entry><literal>&url.articles.<replaceable>articlename</replaceable>;</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> + </row> + + <row> + <entry></entry> + </row> + + <row> + <entry namest="entity" nameend="notes">Other Operating System Name Entities</entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry><literal>&linux;</literal></entry> + <entry>&linux;</entry> + <entry>The &linux; operating system.</entry> + </row> + + <row> + <entry><literal>&unix;</literal></entry> + <entry>&unix;</entry> + <entry>The &unix; operating system.</entry> + </row> + + <row> + <entry><literal>&windows;</literal></entry> + <entry>&windows;</entry> + <entry>The &windows; operating system.</entry> + </row> + + <row> + <entry></entry> + </row> + + <row> + <entry namest="entity" nameend="notes">Miscellaneous Entities</entry> + <entry></entry> + <entry></entry> + </row> + + <row> + <entry><literal>&prompt.root;</literal></entry> + <entry><literal>&prompt.root;</literal></entry> + <entry>The <username>root</username> user + prompt.</entry> + </row> + + <row> + <entry><literal>&prompt.user;</literal></entry> + <entry><literal>&prompt.user;</literal></entry> + <entry>A prompt for an unprivileged user.</entry> + </row> + + <row> + <entry><literal>&postscript;</literal></entry> + <entry>&postscript;</entry> + <entry>The + &postscript; programming language.</entry> + </row> + + <row> + <entry><literal>&tex;</literal></entry> + <entry>&tex;</entry> + <entry>The + &tex; typesetting language.</entry> + </row> + + <row> + <entry><literal>&xorg;</literal></entry> + <entry>&xorg;</entry> + <entry>The &xorg; open source X + Window System.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + </sect2> </sect1> <sect1 id="docbook-markup-fpi"> @@ -1057,16 +1289,48 @@ This is the file called 'foo2'</screen> <para>Usage:</para> <programlisting><sgmltag class="starttag">para</sgmltag>FreeBSD is without doubt <sgmltag class="starttag">emphasis</sgmltag>the<sgmltag class="endtag">emphasis</sgmltag> - premiere Unix like operating system for the Intel architecture.<sgmltag class="endtag">para</sgmltag></programlisting> + premiere &unix;-like operating system for the Intel + architecture.<sgmltag class="endtag">para</sgmltag></programlisting> <para>Appearance:</para> <para>FreeBSD is without doubt <emphasis>the</emphasis> - premiere Unix like operating system for the Intel + premiere &unix;-like operating system for the Intel architecture.</para> </example> </sect2> + <sect2 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 + reader when an acronym is defined on the first use, as shown + in the example below.</para> + + <example> + <title>Acronyms</title> + + <para>Usage:</para> + + <programlisting><sgmltag class="starttag">para</sgmltag>Request For Comments (<sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag>) 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> + + <para>Appearance:</para> + + <para>Request For Comments (<acronym>RFC</acronym>) 1149 + defined the use of avian carriers for transmission of + Internet Protocol (<acronym>IP</acronym>) data. The + quantity of <acronym>IP</acronym> data currently + transmitted in that manner is unknown.</para> + </example> + </sect2> + <sect2 id="docbook-markup-quotations"> <title>Quotations</title> @@ -1083,13 +1347,14 @@ This is the file called 'foo2'</screen> <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 RFC 1535 calls it.<sgmltag class="endtag">para</sgmltag></programlisting> + as <sgmltag class="starttag">acronym</sgmltag>RFC<sgmltag class="endtag">acronym</sgmltag> 1535 calls it.<sgmltag class="endtag">para</sgmltag></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> + administration</quote>, as <acronym>RFC</acronym> 1535 + calls it.</para> </example> </sect2> @@ -1572,24 +1837,26 @@ This is the file called 'foo2'</screen> <sect2 id="docbook-markup-email-addresses"> <title>Email Addresses</title> - <para>Email addresses are marked up with - <sgmltag>email</sgmltag> tags. 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> + <para>Email addresses are marked up as <sgmltag>email</sgmltag> + 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> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Questions about &os; may be sent to - <sgmltag class="starttag">email</sgmltag>questions@&os;.org<sgmltag class="endtag">email</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <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> <para>Appearance:</para> - <para>Questions about &os; may be sent to - <email>questions@&os;.org</email>.</para> + <para>An email address that does not actually exist, like + <email>notreal@example.com</email>, can be used as an + example.</para> </example> <para>A &os;-specific extension allows setting the @@ -1602,13 +1869,15 @@ This is the file called 'foo2'</screen> <para>Usage:</para> - <programlisting><sgmltag class="starttag">para</sgmltag>Questions about &os; may be sent to - <sgmltag class="starttag">email role="nolink"</sgmltag>questions@&os;.org<sgmltag class="endtag">email</sgmltag>.<sgmltag class="endtag">para</sgmltag></programlisting> + <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> <para>Appearance:</para> - <para>Questions about &os; may be sent to - <email role="nolink">questions@&os;.org</email>.</para> + <para>Sometimes a link to an email address like + <email role="nolink">notreal@example.com</email> is not + desired.</para> </example> </sect2> @@ -1631,9 +1900,10 @@ This is the file called 'foo2'</screen> 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 - set (in the environment, on the <command>make</command> - command line, or within the <filename>Makefile</filename>) - to influence the process.</para> + 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 @@ -1767,6 +2037,31 @@ This is the file called 'foo2'</screen> </example> </sect2> + <sect2 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 + like a graphical button, brackets and non-breaking spaces are + added surrounding the text.</para> + + <example> + <title><sgmltag>guibutton</sgmltag></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> + + <para>Appearance:</para> + + <para>Edit the file, then click + <guibutton>[ Save ]</guibutton> to save the + changes.</para> + </example> + </sect2> + <sect2 id="docbook-markup-system-errors"> <title>Quoting System Errors</title> 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 new file mode 100644 index 0000000000..68e5c76ce5 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/editor-config/chapter.xml @@ -0,0 +1,121 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Copyright (c) 2013 Warren Block + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 THE + AUTHORS OR CONTRIBUTORS 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 SOFTWARE, + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> + +<chapter 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"> + <title><application>Vim</application></title> + + <para>Install from <filename role="package">editors/vim</filename> + or <filename role="package">editors/vim-lite</filename>.</para> + + <para>Edit <filename>~/.vimrc</filename>, adding these + lines:</para> + + <programlisting>augroup sgmledit + autocmd FileType sgml set formatoptions=cq2l " Special formatting options + autocmd FileType sgml set textwidth=70 " Wrap lines at 70 columns + autocmd FileType sgml set shiftwidth=2 " Automatically indent + autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces + autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab + autocmd FileType sgml set autoindent " Automatic indentation +augroup END</programlisting> + + </sect1> + + <sect1 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> + + <para>Edit <filename>~/.emacs</filename>, adding these + lines:</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> + </sect1> + + <sect1 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> + + <para>Configuration:</para> + + <screen>&prompt.user; <userinput>cp /usr/local/share/nano/xml.nanorc ~/.nanorc</userinput></screen> + + <para>Use <command>printf</command> to add lines to the + configuration file. Some have embedded <keycap>Tab</keycap> + characters, making this easier than editing the file + directly:</para> + + <screen>&prompt.user; <userinput>printf '# trailing whitespace\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf 'color ,blue "[[:space:]]+$"\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf '# multiples of eight spaces at the start a line\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf '# (after zero or more tabs) should be a tab\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf 'color ,blue "^([\t]*[ ]{8})+"\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf '# tabs after spaces\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf 'color ,yellow "( )+\t"\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf '# lines longer than 70 characters\n' >> ~/.nanorc</userinput> +&prompt.user; <userinput>printf 'color ,red "^(([ ]{2})+|(\t+))*[ ]{1}[^ ]{1}"\n' >> ~/.nanorc</userinput></screen> + + <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> + + <para>Users of &man.csh.1; can define an alias in + <filename>~/.cshrc</filename> to automate these options:</para> + + <programlisting>alias nano "nano -AKipwz -r 70 -T8"</programlisting> + + <para>After the alias is defined, the options will be added + automatically:</para> + + <screen>&prompt.user; <userinput>nano <replaceable>chapter.xml</replaceable></userinput></screen> + </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 ee6b7e139e..f8a98e33fc 100644 --- a/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml +++ b/en_US.ISO8859-1/books/fdp-primer/examples/appendix.xml @@ -34,23 +34,24 @@ <appendix id="examples"> <title>Examples</title> - <para>This appendix contains example XML files and command lines - you can use to convert them from one output format to another. If - you have successfully installed the Documentation Project tools - then you should be able to use these examples directly.</para> + <para>This appendix contains example <acronym>XML</acronym> files + and the commands to convert them from one output format to + another. After installing the Documentation Project tools (see + <xref linkend="tools-required"/>), these examples can be used + directly.</para> <para>These examples are not exhaustive—they do not contain - all the elements you might want to use, particularly in your - document's front matter. For more examples of DocBook markup you - should examine the XML source for this and other documents, - available in the <application>svn</application> + all the elements that might be desirable to use, particularly in a + document's front matter. For more examples of DocBook markup, + 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> <para>To avoid confusion, these examples use the standard DocBook - 4.1 DTD rather than the FreeBSD extension. They also use the - stock stylesheets distributed by Norm Walsh, rather than any - customizations made to those stylesheets by the FreeBSD + 4.1 <acronym>DTD</acronym> rather than the &os; extension. They + also use the stock stylesheets distributed by Norm Walsh, rather + than any customizations made to those stylesheets by the &os; Documentation Project. This makes them more useful as generic DocBook examples.</para> @@ -60,50 +61,50 @@ <example> <title>DocBook <sgmltag>book</sgmltag></title> - <programlisting><![CDATA[<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + <programlisting><!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> -<book lang='en'> - <bookinfo> - <title>An Example Book</title> +<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> - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>foo@example.com</email></address> - </affiliation> - </author> + <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> - <copyright> - <year>2000</year> - <holder>Copyright string here</holder> - </copyright> + <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> - <abstract> - <para>If your book has an abstract then it should go here.</para> - </abstract> - </bookinfo> + <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> - <preface> - <title>Preface</title> + <sgmltag class="starttag">preface</sgmltag> + <sgmltag class="starttag">title</sgmltag>Preface<sgmltag class="endtag">title</sgmltag> - <para>Your book may have a preface, in which case it should be placed - here.</para> - </preface> + <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> - <chapter> - <title>My First Chapter</title> + <sgmltag class="starttag">chapter</sgmltag> + <sgmltag class="starttag">title</sgmltag>My First Chapter<sgmltag class="endtag">title</sgmltag> - <para>This is the first chapter in my book.</para> + <sgmltag class="starttag">para</sgmltag>This is the first chapter in my book.<sgmltag class="endtag">para</sgmltag> - <sect1> - <title>My First Section</title> + <sgmltag class="starttag">sect1</sgmltag> + <sgmltag class="starttag">title</sgmltag>My First Section<sgmltag class="endtag">title</sgmltag> - <para>This is the first section in my book.</para> - </sect1> - </chapter> -</book>]]></programlisting> + <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> </example> </sect1> @@ -113,63 +114,58 @@ <example> <title>DocBook <sgmltag>article</sgmltag></title> - <programlisting><![CDATA[<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" - "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> + <programlisting><!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" + "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd"> -<article lang='en'> - <articleinfo> - <title>An Example Article</title> +<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> - <author> - <firstname>Your first name</firstname> - <surname>Your surname</surname> - <affiliation> - <address><email>foo@example.com</email></address> - </affiliation> - </author> + <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> - <copyright> - <year>2000</year> - <holder>Copyright string here</holder> - </copyright> + <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> - <abstract> - <para>If your article has an abstract then it should go here.</para> - </abstract> - </articleinfo> + <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> - <sect1> - <title>My First Section</title> + <sgmltag class="starttag">sect1</sgmltag> + <sgmltag class="starttag">title</sgmltag>My First Section<sgmltag class="endtag">title</sgmltag> - <para>This is the first section in my article.</para> + <sgmltag class="starttag">para</sgmltag>This is the first section in my article.<sgmltag class="endtag">para</sgmltag> - <sect2> - <title>My First Sub-Section</title> + <sgmltag class="starttag">sect2</sgmltag> + <sgmltag class="starttag">title</sgmltag>My First Sub-Section<sgmltag class="endtag">title</sgmltag> - <para>This is the first sub-section in my article.</para> - </sect2> - </sect1> -</article>]]></programlisting> + <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> </example> </sect1> <sect1 id="examples-formatted"> <title>Producing Formatted Output</title> - <para>This section assumes that you have installed the software - listed in the <filename - role="package">textproc/docproj</filename> port, either by - hand, or by using the port. Further, it is assumed that your - software is installed in subdirectories under - <filename>/usr/local/</filename>, and the directory where - binaries have been installed is in your <envar>PATH</envar>. - Adjust the paths as necessary for your system.</para> + <para>Before using these examples, install the required tools as + shown in <xref linkend="tools-required"/>.</para> <sect2> - <title>Using Jade</title> + <title>Using <application>Jade</application></title> <example> - <title>Converting DocBook to HTML (One Large File)</title> + <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"/> @@ -190,23 +186,27 @@ <para>Specifies the catalogs that <application>Jade</application> will need to process. Three catalogs are required. The first is a catalog - that contains information about the DSSSL stylesheets. - The second contains information about the DocBook DTD. - The third contains information specific to - <application>Jade</application>.</para> + that contains information about the + <acronym>DSSSL</acronym> stylesheets. The second + contains information about the DocBook + <acronym>DTD</acronym>. The third contains information + specific to <application>Jade</application>.</para> </callout> <callout arearefs="examples-co-jade-1-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that + <para>Specifies the full path to the + <acronym>DSSSL</acronym> stylesheet that <application>Jade</application> will use when processing the document.</para> </callout> <callout arearefs="examples-co-jade-1-transform"> <para>Instructs <application>Jade</application> to perform - a <emphasis>transformation</emphasis> from one DTD to - another. In this case, the input is being transformed - from the DocBook DTD to the HTML DTD.</para> + a <emphasis>transformation</emphasis> from one + <acronym>DTD</acronym> to another. In this case, the + input is being transformed from the DocBook + <acronym>DTD</acronym> to the <acronym>XHTML</acronym> + <acronym>DTD</acronym>.</para> </callout> <callout arearefs="examples-co-jade-1-filename"> @@ -219,8 +219,8 @@ </example> <example> - <title>Converting DocBook to HTML (Several Small - Files)</title> + <title>Converting DocBook to <acronym>XHTML</acronym> (Several + Small Files)</title> <screen>&prompt.user; <userinput>jade \ -c /usr/local/share/xml/docbook/dsssl/modular/catalog \ <co id="examples-co-jade-2-catalog"/> @@ -234,45 +234,50 @@ <para>Specifies the catalogs that <application>Jade</application> will need to process. Three catalogs are required. The first is a catalog - that contains information about the DSSSL stylesheets. - The second contains information about the DocBook DTD. - The third contains information specific to Jade.</para> + that contains information about the + <acronym>DSSSL</acronym> stylesheets. The second + contains information about the DocBook + <acronym>DTD</acronym>. The third contains information + specific to <application>Jade</application>.</para> </callout> <callout arearefs="examples-co-jade-2-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that + <para>Specifies the full path to the + <acronym>DSSSL</acronym> stylesheet that <application>Jade</application> will use when processing the document.</para> </callout> <callout arearefs="examples-co-jade-2-transform"> <para>Instructs <application>Jade</application> to perform - a <emphasis>transformation</emphasis> from one DTD to - another. In this case, the input is being transformed - from the DocBook DTD to the HTML DTD.</para> + a <emphasis>transformation</emphasis> from one + <acronym>DTD</acronym> to another. In this case, the + input is being transformed from the DocBook + <acronym>DTD</acronym> to the <acronym>XHTML</acronym> + <acronym>DTD</acronym>.</para> </callout> <callout arearefs="examples-co-jade-2-filename"> <para>Specifies the file that <application>Jade</application> should process. The - stylesheets determine how the individual HTML files will - be named, and the name of the <quote>root</quote> file - (i.e., the one that contains the start of the - document.</para> + stylesheets determine how the individual + <acronym>XHTML</acronym> files will be named, and the + name of the <quote>root</quote> file, the one that + contains the start of the document.</para> </callout> </calloutlist> - <para>This example may still only generate one HTML file, - depending on the structure of the document you are - processing, and the stylesheet's rules for splitting - output.</para> + <para>This example may still only generate one + <acronym>XHTML</acronym> file, depending on the structure of + the document you are processing, and the stylesheet's rules + for splitting output.</para> </example> <example id="examples-docbook-postscript"> - <title>Converting DocBook to Postscript</title> + <title>Converting DocBook to &postscript;</title> - <para>The source XML file must be converted to a &tex; - file.</para> + <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"/> @@ -291,13 +296,16 @@ <para>Specifies the catalogs that <application>Jade</application> will need to process. Three catalogs are required. The first is a catalog - that contains information about the DSSSL stylesheets. - The second contains information about the DocBook DTD. - The third contains information specific to Jade.</para> + that contains information about the + <acronym>DSSSL</acronym> stylesheets. The second + contains information about the DocBook + <acronym>DTD</acronym>. The third contains information + specific to <application>Jade</application>.</para> </callout> <callout arearefs="examples-co-jade-3-dsssl"> - <para>Specifies the full path to the DSSSL stylesheet that + <para>Specifies the full path to the + <acronym>DSSSL</acronym> stylesheet that <application>Jade</application> will use when processing the document.</para> </callout> @@ -314,11 +322,11 @@ <screen>&prompt.user; <userinput>tex "&jadetex" <replaceable>file</replaceable>.tex</userinput></screen> - <para>You have to run <command>tex</command> <emphasis>at - least</emphasis> three times. The first run processes the - document, and determines areas of the document which are - referenced from other parts of the document, for use in - indexing, and so on.</para> + <para><command>tex</command> commands must be run + <emphasis>at least</emphasis> three times. The first run + processes the document, and determines areas of the document + which are referenced from other parts of the document, for + use in indexing, and so on.</para> <para>Do not be alarmed if you see warning messages such as <errorname>LaTeX Warning: Reference `136' on page 5 @@ -337,21 +345,21 @@ <filename><replaceable>file</replaceable>.dvi</filename>.</para> <para>Finally, run <command>dvips</command> to convert the - <filename>.dvi</filename> file to Postscript.</para> + <filename>.dvi</filename> file to &postscript;.</para> <screen>&prompt.user; <userinput>dvips -o <replaceable>file</replaceable>.ps <replaceable>file.dvi</replaceable></userinput></screen> </example> <example> - <title>Converting DocBook to PDF</title> + <title>Converting DocBook to <acronym>PDF</acronym></title> - <para>The first part of this process is identical to that when - converting DocBook to Postscript, using the same + <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> - <para>When the <filename>.tex</filename> file has been - generated you run <application>pdfTeX</application>. + <para>After the <filename>.tex</filename> file has been + generated, run <application>pdfTeX</application>. However, use the <literal>&pdfjadetex</literal> macro package instead.</para> 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 7694d17704..66eb8593f2 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml @@ -47,7 +47,7 @@ <acronym>FDP</acronym>. Willingness to contribute is the only membership requirement.</para> - <para>This primer shows the reader how to:</para> + <para>This primer shows how to:</para> <itemizedlist> <listitem> @@ -64,8 +64,8 @@ </listitem> <listitem> - <para>Submit changes back for review and eventual inclusion in - the &os; documentation.</para> + <para>Submit changes back for review and inclusion in the &os; + documentation.</para> </listitem> </itemizedlist> @@ -110,185 +110,144 @@ <para>Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages - are not translated.</para> + are not translated at present.</para> <para>Documentation source for the &os; web site, Handbook, and - <acronym>FAQ</acronym> is available in the Subversion + <acronym>FAQ</acronym> is available in the documentation repository at <literal>https://svn.FreeBSD.org/doc/</literal>.</para> <para>Source for manual pages is available in a separate - Subversion repository located at + source repository located at <literal>https://svn.FreeBSD.org/base/</literal>.</para> <para>Documentation commit messages are visible with - <application>svn</application>. Commit messages are also + <command>svn log</command>. Commit messages are also archived at <ulink url="&a.svn-doc-all.url;"></ulink>.</para> - <para>In addition, many people have written tutorials or how-to - articles about &os;. Some are stored as part of the - <acronym>FDP</acronym> files. In other cases, the author has - decided to keep the documentation separate. The - <acronym>FDP</acronym> endeavors to provide links to as much of - this external documentation as possible.</para> + <para>Many people have written tutorials or how-to articles about + &os;. Some are stored as part of the <acronym>FDP</acronym> + files. In other cases, the author has decided to keep the + documentation separate. The <acronym>FDP</acronym> endeavors to + provide links to as much of this external documentation as + possible.</para> </sect1> <sect1 id="overview-quick-start"> <title>Quick Start</title> - <para>Here we describe the steps contributors must take before - making changes to the <acronym>FDP</acronym>. New - contributors will interact with other members of the &os; - Documentation Team, which can assist in learning to use - <acronym>XML</acronym> and the suggestions in - <xref linkend="writing-style-guide"/>. If a new user - contributes regularly, a Documentation Team member may be - assigned as a mentor to guide the user through the process from - contributor to documentation committer.</para> + <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 + can help with questions or problems involving the + documentation.</para> <procedure> <step> - <para>Subscribe to the &a.doc;. Some members of the mailing - list also interact on the <literal>#bsddocs</literal> - <acronym>IRC</acronym> channel on <ulink - url="http://www.efnet.org/">EFnet</ulink>.</para> - </step> - - <step> <para>Install the <filename role="package">textproc/docproj</filename> package or port. This meta-port installs all of the - utilities needed by the <acronym>FDP</acronym>.</para> + software needed to edit and build &os; documentation.</para> + </step> + + <step> + <para>Install a local working copy of the documentation from a + mirror of the &os; repository in + <filename class="directory">~/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> </step> <step> - <para>Install a local working copy of the documentation - from a mirror of the &os; repository. For the fastest - download, pick the nearest mirror from the list of <ulink - url="&url.books.handbook;/subversion-mirrors.html">Subversion - mirror sites</ulink>. If <filename - class="directory">/usr/doc</filename> already exists, move - or delete it first to prevent file conflicts.</para> - - <screen>&prompt.user; <userinput>svn checkout https://<replaceable>svn0.us-west.FreeBSD.org</replaceable>/doc/head <replaceable>/usr/doc</replaceable></userinput></screen> - </step> - - <step> - <para>Before making any documentation edits, configure your - editor to conform to <acronym>FDP</acronym> standards. - How to do so varies by editor. Some editor configurations - are listed in <xref linkend="writing-style"/>. The editor - should be configured as follows:</para> - - <itemizedlist> - <listitem> - <para>Word wrap set to 70 characters.</para> - </listitem> - - <listitem> - <para>Tab stops set to 2.</para> - </listitem> - - <listitem> - <para>Replace each group of 8 leading spaces with a - single tab.</para> - </listitem> - </itemizedlist> - </step> - - <step> - <para>Locate the file to edit. Run - <command>svn up</command> within the local working copy to - make sure that it is up to date. Before making major - changes to a file, discuss the proposed changes with the - &a.doc;.</para> - - <para>When making edits, determine which tags and entities - are needed to achieve the desired formatting. One way to - learn is to compare some text in the - <acronym>HTML</acronym> formatted version of the document - to the tags which surround the text or the entities that - represent that text in the <acronym>XML</acronym> file. - References to the commonly used tags and entities can be - found in <xref linkend="xhtml-markup"/> and - <xref linkend="docbook-markup"/>.</para> - </step> - - <step> - <para>After edits are complete, check for problems by - running:</para> - - <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen> - - <para>Review the output and edit the file to fix any listed - tab errors, spelling mistakes, and improper grammar. Save - the changes and rerun this command to find any remaining - problems. Repeat until all of the errors that you deem - fixable are resolved. If you get stuck trying to fix - errors, ask for assistance on the &a.doc;.</para> - </step> - - <step> - <para><emphasis>Always</emphasis> build-test changes before - submitting them. By default, typing - <userinput>make</userinput> in the top-level directory of - the type of documentation being edited will generate that - documentation in split HTML format. For example, to build - the English version of the Handbook, type - <command>make</command> in the - <filename>en_US.ISO8859-1/books/handbook/</filename> - directory. This step is necessary to make sure that the - edits do not break the build.</para> - </step> - - <step> - <para>In order to build the output in other formats, other - <application>make</application> targets are defined in - <filename>head/share/mk/doc.docbook.mk</filename>. Use - quotes around the list of formats when building more than - one format with a single command.</para> - - <para>For example, to convert the document to both - <literal>.html</literal> and <literal>.txt</literal>, use - this command:</para> - - <screen>&prompt.user; <userinput>make FORMATS="html txt"</userinput></screen> - - <para>Once these steps are successfully completed, generate - a <quote>diff file</quote> of the changes. While in - <filename class="directory">/usr/doc</filename>, run this - command, replacing <replaceable>bsdinstall</replaceable> - with the name of the directory containing the - edits:</para> - - <screen>&prompt.user; <userinput>svn diff > <replaceable>bsdinstall</replaceable>.diff.txt</userinput></screen> - </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 - the web form, input a synopsis of <emphasis>[patch] - <replaceable>short description of - problem</replaceable></emphasis>. Select the category - <literal>docs</literal> and the class - <literal>doc-bug</literal>. The body of the message - should contain a short description of the edits and any - important discussion points. Use the - <guibutton>[ Browse... ]</guibutton> button to - attach the <literal>.diff.txt</literal> file and enter - the captcha phrase.</para> - - <para>It is important to remember that the - <acronym>FDP</acronym> is comprised of volunteers who - review edits in their spare time and who live in different - time zones around the globe. It takes time to review - edits and to either commit them or respond if additional - edits are required. If you do not receive a response in a - reasonable amount of time, send a follow-up email to the - &a.doc; and ask if anyone has had a chance to review the - patch or if additional information is required.</para> - </step> - </procedure> - </sect1> - </chapter> + <para>Configure the text editor:</para> + + <itemizedlist> + <listitem> + <para>Word wrap set to 70 characters.</para> + </listitem> + + <listitem> + <para>Tab stops set to 2.</para> + </listitem> + + <listitem> + <para>Replace each group of 8 leading spaces with a + single tab.</para> + </listitem> + </itemizedlist> + + <para>Specific editor configurations are listed in + <xref linkend="editor-config"/>.</para> + </step> + + <step> + <para>Update the local working copy:</para> + + <screen>&prompt.user; <userinput>svn up <replaceable>~/doc</replaceable></userinput></screen> + </step> + + <step> + <para>Edit the documentation files that require changes. If a + file needs major changes, consult the mailing list for + input.</para> + + <para>References to tag and entity usage can be found in + <xref linkend="xhtml-markup"/> and + <xref linkend="docbook-markup"/>.</para> + </step> + + <step> + <para>After editing, check for problems by running:</para> + + <screen>&prompt.user; <userinput>igor -R filename.xml | less -RS</userinput></screen> + + <para>Review the output and edit the file to fix any problems + shown, then rerun the command to find any remaining + problems. Repeat until all of the errors are + resolved.</para> + </step> + + <step> + <para><emphasis>Always</emphasis> build-test changes before + submitting them. Running <userinput>make</userinput> in the + top-level directory of the documentation being edited will + generate that documentation in split HTML format. For + example, to build the English version of the Handbook in + <acronym>HTML</acronym>, run <command>make</command> in the + <filename>en_US.ISO8859-1/books/handbook/</filename> + directory.</para> + </step> + + <step> + <para>When changes are complete and tested, generate a + <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> + + <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 + 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 + the web form, enter a synopsis of + <emphasis>[patch] <replaceable>short description of + problem</replaceable></emphasis>. Select the category + <literal>docs</literal> and the class + <literal>doc-bug</literal>. In the body of the message, + enter a short description of the changes and any important + details about them. Use the + <guibutton>[ Browse... ]</guibutton> button to + attach the <literal>.diff.txt</literal>.</para> + </step> + </procedure> + </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 7a688264b4..ad0cd93676 100644 --- a/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/structure/chapter.xml @@ -32,12 +32,11 @@ --> <chapter id="structure"> - <title>Structuring Documents Under <filename>doc/</filename></title> + <title>Documentation Directory Structure</title> - <para>The <filename>doc/</filename> tree is organized in a - particular fashion, and the documents that are part of the FDP are - in turn organized in a particular fashion. The aim is to make it - simple to add new documentation into the tree and:</para> + <para>Files and directories in the + <filename class="directory">doc/</filename> tree follow a + structure meant to:</para> <orderedlist> <listitem> @@ -57,51 +56,63 @@ </listitem> </orderedlist> - <para>In addition, the documentation tree has to accommodate - documentation that could be in many different languages and in - many different encodings. It is important that the structure of - the documentation tree does not enforce any particular defaults or - cultural preferences.</para> + <para>In addition, the documentation tree must accommodate + documents in many different languages and encodings. It is + important that the documentation tree structure does not enforce + any particular defaults or cultural preferences.</para> <sect1 id="structure-top"> - <title>The Top Level, <filename>doc/</filename></title> + <title>The Top Level, + <filename class="directory">doc/</filename></title> <para>There are two types of directory under - <filename>doc/</filename>, each with very specific directory - names and meanings.</para> - - <segmentedlist> - <segtitle>Directory</segtitle> - - <segtitle>Meaning</segtitle> - - <seglistitem> - <seg><filename>share/</filename></seg> - - <seg>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>share/mk</filename>, while - the additional XML support files (such as the FreeBSD - extended DocBook DTD) are in - <filename>share/xml</filename>.</seg> - </seglistitem> - - <seglistitem> - <seg><filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename></seg> - - <seg>One directory exists for each available translation and - encoding of the documentation, for example - <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 should a translation team want to provide - the documentation in the same language but in more than one - encoding. This also completely isolates us from any - problems that might be caused by a switch to Unicode.</seg> - </seglistitem> - </segmentedlist> + <filename class="directory">doc/</filename>, each with very + specific directory names and meanings.</para> + + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Directory</entry> + <entry>Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top"> + <filename class="directory">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 + 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> + </row> + + <row> + <entry valign="top"><filename + class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></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>. + 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 + same language but in more than one encoding. This also + avoids problems that might be caused by a future switch + to Unicode.</entry> + </row> + </tbody> + </tgroup> + </informaltable> </sect1> <sect1 id="structure-locale"> @@ -113,51 +124,61 @@ documentation is split into up to three more categories at this level, indicated by the different directory names.</para> - <segmentedlist> - <segtitle>Directory</segtitle> - - <segtitle>Contents</segtitle> - - <seglistitem> - <seg><filename>articles</filename></seg> - - <seg>Documentation marked up as a DocBook - <sgmltag>article</sgmltag> (or equivalent). Reasonably - short, and broken up into sections. Normally only available - as one XHTML file.</seg> - </seglistitem> - - <seglistitem> - <seg><filename>books</filename></seg> - - <seg>Documentation marked up as a DocBook - <sgmltag>book</sgmltag> (or equivalent). Book length, and - broken up into chapters. Normally available as both one - large XHTML file (for people with fast connections, or who - want to print it easily from a browser) and as a collection - of linked, smaller files.</seg> - </seglistitem> - - <seglistitem> - <seg><filename>man</filename></seg> - - <seg>For translations of the system manual pages. This - directory will contain one or more - <filename>man<replaceable>n</replaceable></filename> - directories, corresponding to the sections that have been - translated.</seg> - </seglistitem> - </segmentedlist> - - <para>Not every - <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></filename> - directory will contain all of these directories. It depends on - how much translation has been accomplished by that translation - team.</para> + <informaltable pgwide="1" frame="none"> + <tgroup cols="2"> + <thead> + <row> + <entry>Directory</entry> + <entry>Usage</entry> + </row> + </thead> + + <tbody> + <row> + <entry valign="top"> + <filename class="directory">articles</filename></entry> + + <entry>Documentation marked up as a DocBook + <sgmltag>article</sgmltag> (or equivalent). Reasonably + short, and broken up into sections. Normally only + available as one <acronym>XHTML</acronym> file.</entry> + </row> + + <row> + <entry valign="top"><filename>books</filename></entry> + + <entry>Documentation marked up as a DocBook + <sgmltag>book</sgmltag> (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 + browser) and as a collection of linked, smaller + files.</entry> + </row> + + <row> + <entry valign="top"> + <filename class="directory">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> + directories, corresponding to the sections that have + been translated.</entry> + </row> + </tbody> + </tgroup> + </informaltable> + + <para>Not every <filename + class="directory"><replaceable>lang</replaceable>.<replaceable>encoding</replaceable></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"> - <title>Document Specific Information</title> + <title>Document-Specific Information</title> <para>This section contains specific notes about particular documents managed by the FDP.</para> @@ -167,12 +188,12 @@ <subtitle><filename>books/handbook/</filename></subtitle> - <para>The Handbook is written to comply with the FreeBSD DocBook - extended DTD.</para> + <para>The Handbook is written in DocBook <acronym>XML</acronym> + using the &os; DocBook extended <acronym>DTD</acronym>.</para> <para>The Handbook is organized as a DocBook - <sgmltag>book</sgmltag>. It is then divided into - <sgmltag>part</sgmltag>s, each of which may contain several + <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>, @@ -187,20 +208,20 @@ <note> <para>The Handbook's organization may change over time, and this document may lag in detailing the organizational - changes. If you have any questions about how the Handbook - is organized, please contact the &a.doc;.</para> + changes. Post questions about Handbook organization to + &a.doc;.</para> </note> <sect4> <title><filename>Makefile</filename></title> <para>The <filename>Makefile</filename> defines some - variables that affect how the XML source is converted to - other formats, and lists the various source files that - make up the Handbook. It then includes the standard - <filename>doc.project.mk</filename> file, to bring in the - rest of the code that handles converting documents from - one format to another.</para> + variables that affect how the <acronym>XML</acronym> + source is converted to other formats, and lists the + various source files that make up the Handbook. It then + includes the standard <filename>doc.project.mk</filename>, + to bring in the rest of the code that handles converting + documents from one format to another.</para> </sect4> <sect4> @@ -223,7 +244,8 @@ </sect4> <sect4> - <title><filename><replaceable>directory</replaceable>/chapter.xml</filename></title> + <title><filename + class="directory"><replaceable>directory</replaceable>/chapter.xml</filename></title> <para>Each chapter in the Handbook is stored in a file called <filename>chapter.xml</filename> in a separate @@ -235,23 +257,23 @@ <para>For example, if one of the chapter files contains:</para> - <programlisting><![CDATA[ -<chapter id="kernelconfig"> + <programlisting><sgmltag class="starttag">chapter id="kernelconfig"</sgmltag> ... -</chapter>]]></programlisting> +<sgmltag class="endtag">chapter</sgmltag></programlisting> <para>Then it will be called <filename>chapter.xml</filename> in the <filename>kernelconfig</filename> directory. In general, - the entire contents of the chapter will be held in this + the entire contents of the chapter are in this one file.</para> - <para>When the XHTML version of the Handbook is produced, - this will yield <filename>kernelconfig.html</filename>. - This is because of the <literal>id</literal> value, and is - not related to the name of the directory.</para> + <para>When the <acronym>XHTML</acronym> version of the + Handbook is produced, this will yield + <filename>kernelconfig.html</filename>. This is because + of the <literal>id</literal> value, and is not related to + the name of the directory.</para> - <para>In earlier versions of the Handbook the files were + <para>In earlier versions of the Handbook, the files were 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 @@ -259,12 +281,12 @@ to include images in each chapter. Images for each Handbook chapter are stored within <filename class="directory">share/images/books/handbook</filename>. - Note that localized version of these images should be - placed in the same directory as the XML sources for each - chapter. Namespace collisions would be inevitable, and it - is easier to work with several directories with a few - files in them than it is to work with one directory that - has many files in it.</para> + 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 + inevitable, and it is easier to work with several + directories with a few files in them than it is to work + with one directory that has many files in it.</para> <para>A brief look will show that there are many directories with individual <filename>chapter.xml</filename> files, @@ -273,27 +295,18 @@ <filename>printing/chapter.xml</filename>.</para> <important> - <para>Chapters and/or directories should not be named in a - fashion that reflects their ordering within the - Handbook. This ordering might change as the content - within the Handbook is reorganized; this sort of - reorganization should not (generally) include the need - to rename files (unless entire chapters are being - promoted or demoted within the hierarchy).</para> + <para>Do not name chapters or directories after + their ordering within the Handbook. This ordering can + change as the content within the Handbook is + reorganized. Reorganization should be possible without + renaming files, unless entire chapters are being + promoted or demoted within the hierarchy.</para> </important> - <para>Each <filename>chapter.xml</filename> file will not - be a complete XML document. In particular, they will not - have their own DOCTYPE lines at the start of the - files.</para> - - <para>This is unfortunate as it makes it impossible to treat - these as generic XML files and simply convert them to - HTML, RTF, PS, and other formats in the same way the main - Handbook is generated. This <emphasis>would</emphasis> - force you to rebuild the Handbook every time you want to - see the effect a change has had on just one - chapter.</para> + <para>The <filename>chapter.xml</filename> files are not + complete <acronym>XML</acronym> documents that can be + built individually. They can only be built + as parts of the whole Handbook.</para> </sect4> </sect3> </sect2> 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 27e37e1370..a9905d4cf3 100644 --- a/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/stylesheets/chapter.xml @@ -32,35 +32,45 @@ --> <chapter id="stylesheets"> - <title>Stylesheets</title> + <title>Style Sheets</title> - <para>XML says nothing about how a document should be displayed to - the user, or rendered on paper. To do that, various languages - have been developed to describe stylesheets, including XSLT, XSL FO - or CSS.</para> + <para><acronym>XML</acronym> is concerned with content, and says + nothing about how that content should be presented to the reader + or rendered on paper. Multiple <emphasis>style sheet</emphasis> + languages have been developed to describe visual layout, including + Extensible Stylesheet Language Transformation + (<acronym>XSLT</acronym>), Document Style Semantics and + Specification Language (<acronym>DSSSL</acronym>), and Cascading + Style Sheets (<acronym>CSS</acronym>).</para> - <para>We use XSLT stylesheets to transform DocBook into XHTML and then - we apply CSS formatting to XHTML pages. Currently, the printable - output is rendered with legacy DSSSL stylesheets but this may - probably change in the future.</para> + <para>The <acronym>FDP</acronym> documents use + <acronym>XSLT</acronym> stylesheets to transform DocBook into + <acronym>XHTML</acronym>, and then <acronym>CSS</acronym> + formatting is applied to the <acronym>XHTML</acronym> pages. + Printable output is currently rendered with legacy + <acronym>DSSSL</acronym> stylesheets, but this will probably + change in the future.</para> <sect1 id="stylesheets-css"> - <title>CSS</title> + <title><acronym>CSS</acronym></title> - <para>Cascading Stylesheets (CSS) are a mechanism for attaching - style information (font, weight, size, color, and so forth) to - elements in an XHTML document without abusing XHTML to do + <para>Cascading Style Sheets (<acronym>CSS</acronym>) are a + mechanism for attaching style information (font, weight, size, + color, and so forth) to elements in an <acronym>XHTML</acronym> + document without abusing <acronym>XHTML</acronym> to do so.</para> <sect2> <title>The DocBook Documents</title> - <para>The FreeBSD DSSSL stylesheets include a reference to a - stylesheet, <filename>docbook.css</filename>, which is - expected to appear in the same directory as the XHTML files. - The project-wide CSS file is copied from - <filename>doc/share/misc/docbook.css</filename> when documents - are converted to XHTML, and is installed automatically.</para> + <para>The &os; <acronym>XSLT</acronym> and + <acronym>DSSSL</acronym> stylesheets refer to + <filename>docbook.css</filename>, which is expected to be + present in the same directory as the <acronym>XHTML</acronym> + files. The project-wide <acronym>CSS</acronym> file is copied + from <filename>doc/share/misc/docbook.css</filename> when + documents are converted to <acronym>XHTML</acronym>, and is + installed automatically.</para> </sect2> </sect1> </chapter> 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 3b1cfee227..e95a3ca560 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 @@ -34,55 +34,6 @@ <chapter id="the-website"> <title>The Website</title> - <sect1 id="the-website-prep"> - <title>Preparation</title> - - <para>Use a disk with sufficient free space. A full copy of - the documentation and web site files takes over 700 MB. - Allowing a full gigabyte provides some breathing room. This - space will hold the XML tools, the documentation tree, temporary - build space and the installed web pages.</para> - - <note> - <para>Make sure the documentation ports are updated to the - latest version. See - <ulink url="&url.books.handbook;/ports.html#ports-using">the - Handbook section on ports</ulink> for more - information.</para> - </note> - - <sect2 id="the-website-svn"> - <title>Using <command>svn</command></title> - - <para><command>svn</command> is needed to check out the - documentation and web site files from the - <literal>doc</literal> Subversion repository. - <command>svn</command> can be installed with &man.pkg.add.1; - or from the &os; Ports Collection by running:</para> - - <screen>&prompt.root; <userinput><command>cd /usr/ports/devel/subversion</command></userinput> -&prompt.root; <userinput><command>make</command> <maketarget>install clean</maketarget></userinput></screen> - - <para>To check out the source files for the &os; web site and - the rest of the documentation, run:</para> - - <screen>&prompt.user; <userinput><command>svn checkout <replaceable>https://svn0.us-east.FreeBSD.org</replaceable>/doc/head/ <replaceable>~/doc</replaceable></command></userinput></screen> - - <para><ulink - url="https://svn0.us-east.FreeBSD.org/">svn0.us-east.FreeBSD.org</ulink> - 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> - - <para>After the checkout completes, the current version of the - &os; documentation, including the web site files, will be - present in - <filename class="directory">~/doc</filename>.</para> - </sect2> - </sect1> - <sect1 id="the-website-build"> <title>Build the Web Pages</title> 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 f18f63a6ae..7c14882085 100644 --- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml +++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.xml @@ -34,133 +34,54 @@ <chapter id="tools"> <title>Tools</title> - <para>The FDP uses a number of different software tools to help - manage the FreeBSD documentation, convert it to different output - formats, and so on. You will need to use these tools yourself if - you are to work with the FreeBSD documentation.</para> - - <para>All these tools are available as FreeBSD Ports and Packages, - greatly simplifying the work you have to do to install - them.</para> - - <para>You will need to install these tools before you work through - any of the examples in later chapters. The actual usage of these - tools is covered in later chapters.</para> - - <tip> - <title>Use <filename role="package">textproc/docproj</filename> If - Possible</title> - - <para>You can save yourself a lot of time if you install the - <filename role="package">textproc/docproj</filename> port. This - is a <emphasis>meta-port</emphasis> which does not contain any - software itself. Instead, it depends on various other ports - being installed correctly. Installing this port - <emphasis>should</emphasis> automatically download and install - all of the packages listed in this chapter that you need.</para> - - <para>One of the packages that you might need is the - <application>JadeTeX</application> macro set. In turn, this - macro set requires &tex; to be installed. &tex; is a large - package, and you only need it if you want to produce Postscript - or PDF output.</para> - - <para>To save yourself time and space you must specify whether or - not you want <application>JadeTeX</application> (and therefore - &tex;) installed when you install this port. Either do:</para> - - <screen>&prompt.root; <userinput>make JADETEX=yes install</userinput></screen> - - <para>or</para> - - <screen>&prompt.root; <userinput>make JADETEX=no install</userinput></screen> - - <para>as necessary. Alternatively you may install - <filename role="package">textproc/docproj-jadetex</filename> or - <filename role="package">textproc/docproj-nojadetex</filename>. - These slave ports define the <makevar>JADETEX</makevar> variable - for you, therefore they will install the same suite of - applications on your machine. Note that you can produce only - XHTML or ASCII text output if you do not install - <application>JadeTeX</application>. PostScript or PDF output - requires &tex;.</para> - </tip> - - <sect1 id="tools-mandatory"> - <title>Mandatory Tools</title> + <para>Several software tools are used to manage the FreeBSD + documentation and render it to different output formats. Some of + these tools are required and must be installed before working + through the examples in the following chapters. Some are + optional, adding capabilities or making the job of creating + documentation less demanding.</para> + + <sect1 id="tools-required"> + <title>Required Tools</title> + + <para>Install + <filename role="package">textproc/docproj</filename> 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 + given below.</para> <sect2> - <title>Software</title> - - <para>These programs are required before you can usefully work - with the FreeBSD documentation, and they will allow you to - convert the documentation to XHTML, plain text, and RTF - formats. They are all included in <filename - role="package">textproc/docproj</filename>.</para> - - <variablelist> - <varlistentry> - <term><application>Jade</application> - (<filename role="package">textproc/jade</filename>)</term> - - <listitem> - <para>A DSSSL implementation. Used for converting marked - up documents to other formats, including HTML and - &tex;.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>Links</application> - (<filename role="package">www/links</filename>)</term> - - <listitem> - <para>A text-mode WWW browser that can also convert - XHTML files to plain text.</para> - </listitem> - </varlistentry> - - <varlistentry> - <term><application>peps</application> - (<filename role="package">graphics/peps</filename>)</term> + <title><acronym>DTD</acronym>s and + <acronym>Entities</acronym></title> - <listitem> - <para>Some of the documentation includes images, some of - which are stored as EPS files. These must be converted - to PNG before most web browsers will display - them.</para> - </listitem> - </varlistentry> - </variablelist> - </sect2> - - <sect2> - <title>DTDs and Entities</title> - - <para>These are the DTDs and entity sets used by the FDP. They - need to be installed before you can work with any of the - documentation.</para> + <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> + port.</para> <variablelist> <varlistentry> - <term>XHTML DTD (<filename + <term><acronym>XHTML</acronym> <acronym>DTD</acronym> + (<filename role="package">textproc/xhtml</filename>)</term> <listitem> - <para>XHTML is the markup language of choice for the World - Wide Web, and is used throughout the FreeBSD web - site.</para> + <para><acronym>XHTML</acronym> is the markup language of + choice for the World Wide Web, and is used throughout + the &os; web site.</para> </listitem> </varlistentry> <varlistentry> - <term>DocBook DTD (<filename + <term>DocBook <acronym>DTD</acronym> (<filename role="package">textproc/docbook-xml-450</filename>)</term> <listitem> <para>DocBook is designed for marking up technical - documentation. All the FreeBSD documentation is written - in DocBook.</para> + documentation. Most of the &os; documentation is + written in DocBook.</para> </listitem> </varlistentry> @@ -170,11 +91,11 @@ role="package">textproc/iso8879</filename>)</term> <listitem> - <para>19 of the ISO 8879:1986 character entity sets used - by many DTDs. Includes named mathematical symbols, - additional characters in the Latin character set - (accents, diacriticals, and so on), and Greek - symbols.</para> + <para>Character entities from the ISO 8879:1986 standard + used by many <acronym>DTD</acronym>s. Includes named + mathematical symbols, additional characters in the Latin + character set (accents, diacriticals, and so on), and + Greek symbols.</para> </listitem> </varlistentry> </variablelist> @@ -184,10 +105,8 @@ <sect1 id="tools-optional"> <title>Optional Tools</title> - <para>You do not need to have any of the following installed. - However, you may find it easier to work with the documentation - if you do, and they may give you more flexibility in the output - formats that can be generated.</para> + <para>These applications are not required, but can make working on + the documentation easier or add capabilities.</para> <sect2> <title>Software</title> @@ -195,33 +114,37 @@ <variablelist> <varlistentry> <term><application>JadeTeX</application>, - <application>teTeX</application> and Modular DocBook Stylesheets + <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> + <filename + role="package">textproc/dsssl-docbook-modular</filename>)</term> <listitem> <para><application>Jade</application>, - <application>teTeX</application> and Modular DocBook Stylesheets are used to convert - DocBook documents to DVI, Postscript, and PDF formats. - The <application>JadeTeX</application> macros are needed - in order to do this.</para> - - <para>If you do not intend to convert your documentation - to one of these formats (i.e., HTML and plain text - are sufficient) then you do not need to install - these.</para> - - <important> - <para>If you decide to install - <application>JadeTeX</application> and - <application>teTeX</application> then you will need to - configure <application>teTeX</application> after - <application>JadeTeX</application> has been installed. - <filename>print/jadetex/pkg-message</filename> - contains detailed instructions explaining what you - need to do.</para> - </important> + <application>teTeX</application> and Modular DocBook + Stylesheets are used to convert DocBook documents to + DVI, Postscript, and PDF formats. The + <application>JadeTeX</application> macros are needed to + do this.</para> + + <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> + configuration screen can be disabled.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><application>Vim</application> + (<filename role="package">editors/vim</filename>)</term> + + <listitem> + <para>A popular editor for working with + <acronym>XML</acronym> and derived documents, like + DocBook <acronym>XML</acronym>.</para> </listitem> </varlistentry> @@ -232,22 +155,15 @@ <filename role="package">editors/xemacs</filename>)</term> <listitem> - <para>Both these editors include a special mode for - editing documents marked up according to an SGML DTD. - This mode includes commands to reduce the amount of - typing you need, and help reduce the possibility of + <para>Both of these editors include a special mode for + editing documents marked up according to an + <acronym>XML</acronym> <acronym>DTD</acronym>. This + mode includes commands to reduce the amount of typing + needed, and help reduce the possibility of errors.</para> - - <para>You do not need to use them; any text editor can be - used to edit marked up documents. You may find they - make you more efficient.</para> </listitem> </varlistentry> </variablelist> - - <para>If anyone has recommendations for other software that is - useful when manipulating XML documents, please let &a.doceng; - know, so they can be added to this list.</para> </sect2> </sect1> </chapter> 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 new file mode 100644 index 0000000000..bc725c1544 --- /dev/null +++ b/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml @@ -0,0 +1,193 @@ +<?xml version="1.0" encoding="iso-8859-1"?> +<!-- Copyright (c) 2013 Warren Block + All rights reserved. + + Redistribution and use in source and binary forms, with or without + modification, are permitted provided that the following conditions + are met: + 1. Redistributions of source code must retain the above copyright + notice, this list of conditions and the following disclaimer. + 2. Redistributions in binary form 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 SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``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 THE + AUTHORS OR CONTRIBUTORS 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 SOFTWARE, + EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. + + $FreeBSD$ +--> + +<chapter id="working-copy"> + <title>The Working Copy</title> + + <para>The <emphasis>working copy</emphasis> is a copy of the &os; + repository documentation tree downloaded onto the local computer. + Changes are made to the local working copy, tested, and then + submitted as patches to be committed to the main + repository.</para> + + <para>A full copy of the documentation tree can occupy 700 megabytes + of disk space. Allow for a full gigabyte of space to have room + for temporary files and test versions of various output + formats.</para> + + <para><ulink + url="&url.books.handbook;/svn.html"><application>Subversion</application></ulink> + is used to manage the &os; documentation files. It is installed + by <filename role="package">textproc/docproj</filename> as one of + the required applications.</para> + + <sect1 id="working-copy-doc-and-src"> + <title>Documentation and Manual Pages</title> + + <para>&os; documentation is not just books and articles. Manual + pages for all the commands and configuration files are also part + of the documentation, and part of the <acronym>FDP</acronym>'s + territory. Two repositories are involved: + <literal>doc</literal> for the books and articles, and + <literal>base</literal> for the operating system and manual + pages. To edit manual pages, the <literal>base</literal> + repository must be checked out separately.</para> + + <para>Repositories may contain multiple versions of documentation + and source code. New modifications are almost always made only + to the latest version, called <literal>head</literal>.</para> + </sect1> + + <sect1 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. + 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"> + <title>Choosing a Directory</title> + + <para>&os; documentation is traditionally stored in + <filename class="directory">/usr/doc/</filename>, and system + source code with manual pages in + <filename class="directory">/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 + subdirectories of the user's home directory.</para> + </sect1> + + <sect1 id="working-copy-checking-out"> + <title>Checking Out a Copy</title> + + <para>A download of a working copy from the repository is called + a <emphasis>checkout</emphasis>, and done with + <command>svn checkout</command>. This example checks out a + 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> + + <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> + </sect1> + + <sect1 id="working-copy-updating"> + <title>Updating a Working Copy</title> + + <para>The documents and files in the &os; repository change daily. + People modify files and commit changes frequently. Even a short + time after an initial checkout, there will already be + differences between the local working copy and the main &os; + repository. To update the local version with the changes that + have been made to the main repository, use + <command>svn update</command> on the directory containing the + local working copy:</para> + + <screen>&prompt.user; <userinput>svn update <replaceable>~/doc</replaceable></userinput></screen> + + <para>Get in the protective habit of using + <command>svn update</command> before editing document files. + Someone else may have edited that file very recently, and the + local working copy will not include the latest changes until it + has been updated. Editing the newest version of a file is much + easier than trying to combine an older, edited local file with + the newer version from the repository.</para> + </sect1> + + <sect1 id="working-copy-revert"> + <title>Reverting Changes</title> + + <para>Sometimes it turns out that changes were + not necessary after all, or the writer just wants to start over. + Files can be <quote>reset</quote> to their unchanged form with + <command>svn revert</command>. For example, to erase the edits + made to <filename>chapter.xml</filename> and reset it to + unmodified form:</para> + + <screen>&prompt.user; <userinput>svn revert chapter.xml</userinput></screen> + </sect1> + + <sect1 id="working-copy-making-diff"> + <title>Making a Diff</title> + + <para>After edits to a file or group of files are completed, the + differences between the local working copy and the version on + the &os; repository must be collected into a single file for + submission. These <emphasis>diff</emphasis> files are produced + 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> + + <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 + <filename>.txt</filename> extension to give the earnest and + simple-minded web form a clue that the contents are plain + text.</para> + + <para>Be careful: <command>svn diff</command> includes all changes + made in the current directory and any subdirectories. If there + are files in the working copy with edits that are not ready to + 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> + </sect1> + + <sect1 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> + </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 d4cac87418..c749efcaa3 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 @@ -38,7 +38,7 @@ <title>Tips</title> <para>Technical documentation can be improved by consistent use of - several principes. Most of these can be classified into three + several principles. Most of these can be classified into three goals: <emphasis>be clear</emphasis>, <emphasis>be complete</emphasis>, and <emphasis>be concise</emphasis>. These goals can conflict with @@ -75,7 +75,7 @@ A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like <quote>but really it should never - be done that way</quote>. Bad examples are worse than no + be done that way</quote>. Bad examples are worse than no examples. Give good examples, because <emphasis>even when warned not to use the example as shown</emphasis>, the reader will usually just use the example as shown.</para> @@ -119,7 +119,7 @@ <title>Guidelines</title> <para>To promote consistency between the myriad authors of the - FreeBSD documentation, some guidelines have been drawn up for + &os; documentation, some guidelines have been drawn up for authors to follow.</para> <variablelist> @@ -148,7 +148,7 @@ <listitem> <para>Do not use contractions. Always spell the phrase out - in full. <quote>Don't use contractions</quote> would be + in full. <quote>Don't use contractions</quote> is wrong.</para> <para>Avoiding contractions makes for a more formal tone, is @@ -166,7 +166,7 @@ from the others with a comma and the word <quote>and</quote>.</para> - <para>For example, look at the following:</para> + <para>For example:</para> <blockquote> <para>This is a list of one, two and three items.</para> @@ -190,66 +190,62 @@ <term>Avoid redundant phrases</term> <listitem> - <para>Try not to use redundant phrases. In particular, + <para>Do not use redundant phrases. In particular, <quote>the command</quote>, <quote>the file</quote>, and - <quote>man command</quote> are probably redundant.</para> + <quote>man command</quote> are often redundant.</para> - <para>These two examples show this for commands. The second - example is preferred.</para> + <para>For example, commands:</para> <informalexample> - <para>Use the command <command>svn</command> to update - your sources.</para> + <para>Wrong: Use the command <command>svn</command> to + update sources.</para> </informalexample> <informalexample> - <para>Use <command>svn</command> to update your + <para>Right: Use <command>svn</command> to update sources.</para> </informalexample> - <para>These two examples show this for filenames. The - second example is preferred.</para> + <para>Filenames:</para> <informalexample> - <para>… in the filename + <para>Wrong: … in the filename <filename>/etc/rc.local</filename>…</para> </informalexample> <informalexample> - <para>… in + <para>Right: … in <filename>/etc/rc.local</filename>…</para> </informalexample> - <para>These two examples show this for manual references. - The second example is preferred (the second example uses - <sgmltag>citerefentry</sgmltag>).</para> + <para>Manual page references (the second example uses + <sgmltag>citerefentry</sgmltag> with the + <literal>&man.csh.1;</literal> entity):.</para> <informalexample> - <para>See <command>man csh</command> for more + <para>Wrong: See <command>man csh</command> for more information.</para> </informalexample> <informalexample> - <para>See &man.csh.1;.</para> + <para>Right: See &man.csh.1;.</para> </informalexample> </listitem> </varlistentry> <varlistentry> - <term>Two spaces at the end of sentences</term> + <term>Two spaces between sentences</term> <listitem> - <para>Always use two spaces at the end of sentences, as this - improves readability, and eases use of tools such as + <para>Always use two spaces between sentences, as it + improves readability and eases use of tools such as <application>Emacs</application>.</para> - <para>While it may be argued that a capital letter following - a period denotes a new sentence, this is not the case, - especially in name usage. - <quote>Jordan K. Hubbard</quote> is a good example; it has - a capital <literal>H</literal> following a period and a - space, and there certainly is not a new sentence - there.</para> + <para>A period and spaces followed by a capital letter + does not always mark a new sentence, especially in names. + <quote>Jordan K. Hubbard</quote> is a good example. It + has a capital <literal>H</literal> following a period and + a space, and is certainly not a new sentence.</para> </listitem> </varlistentry> </variablelist> @@ -283,79 +279,57 @@ <sect2> <title>Acronyms</title> - <para>Acronyms should generally be spelled out the first time - they appear in a document, as in: <quote>Network Time Protocol - (<acronym role="Network Time Protocol">NTP</acronym>)</quote>. - After the acronym has been defined, you should generally use - the acronym only (not the whole term, unless it makes more - sense contextually to use the whole term). Usually, acronyms - are defined only one per document. But if you prefer, you can - also define them the first time they appear in each - chapter.</para> + <para>Acronyms should be defined the first time they appear in a + document, as in: + <quote>Network Time Protocol (<acronym>NTP</acronym>)</quote>. + After the acronym has been defined, use the acronym alone + unless it makes more sense contextually to use the whole term. + Acronyms are usually defined only once per chapter or per + document.</para> <para>All acronyms should be enclosed in - <sgmltag>acronym</sgmltag> tags, with a - <literal>role</literal> attribute with the full term defined. - This allows a link to the glossary to be created, and for - mouseovers to be rendered with the fully expanded term.</para> + <sgmltag>acronym</sgmltag> tags.</para> </sect2> <sect2> <title>Indentation</title> - <para>Each file starts with indentation set at column 0, + <para>The first line in each file starts with no indentation, <emphasis>regardless</emphasis> of the indentation level of - the file which might contain this one.</para> + the file which might contain the current file.</para> - <para>Opening tags increase the indentation level by 2 spaces. - Closing tags decrease the indentation level by 2 spaces. - Blocks of 8 spaces at the start of a line should be replaced - with a tab. Do not use spaces in front of tabs, and do not - add extraneous whitespace at the end of a line. Content - within elements should be indented by two spaces if the - content runs over more than one line.</para> + <para>Opening tags increase the indentation level by two spaces. + Closing tags decrease the indentation level by two spaces. + Blocks of eight spaces at the start of a line should be + replaced with a tab. Do not use spaces in front of tabs, and + do not add extraneous whitespace at the end of a line. + Content within elements should be indented by two spaces if + the content runs over more than one line.</para> - <para>For example, the source for this section looks something - like:</para> + <para>For example, the source for this section looks like + this:</para> - <programlisting><![CDATA[+--- This is column 0 -V -<chapter> - <title>...</title> + <programlisting><sgmltag class="starttag">chapter</sgmltag> + <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> - <sect1> - <title>...</title> + <sgmltag class="starttag">sect1</sgmltag> + <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> - <sect2> - <title>Indentation</title> + <sgmltag class="starttag">sect2</sgmltag> + <sgmltag class="starttag">title</sgmltag>Indentation<sgmltag class="endtag">title</sgmltag> - <para>Each file starts with indentation set at column 0, - <emphasis>regardless</emphasis> of the indentation level of the file - which might contain this one.</para> + <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> ... - </sect2> - </sect1> -</chapter>]]></programlisting> - - <para>If you use <application>Emacs</application> or - <application>XEmacs</application> to edit the files then - <literal>sgml-mode</literal> should be loaded automatically, - and the <application>Emacs</application> local variables at - the bottom of each file should enforce these styles.</para> - - <para><application>Vim</application> users might want to - configure their editor with:</para> - - <programlisting>augroup sgmledit - autocmd FileType sgml set formatoptions=cq2l " Special formatting options - autocmd FileType sgml set textwidth=70 " Wrap lines at 70 columns - autocmd FileType sgml set shiftwidth=2 " Automatically indent - autocmd FileType sgml set softtabstop=2 " Tab key indents 2 spaces - autocmd FileType sgml set tabstop=8 " Replace 8 spaces with a tab - autocmd FileType sgml set autoindent " Automatic indentation -augroup END</programlisting> + <sgmltag class="endtag">sect2</sgmltag> + <sgmltag class="endtag">sect1</sgmltag> +<sgmltag class="endtag">chapter</sgmltag></programlisting> + <para>Configurations to help various text editors conform to + these guidelines can be found in + <xref linkend="editor-config"/>.</para> </sect2> <sect2> @@ -369,31 +343,31 @@ augroup END</programlisting> at the same indent as a previous tag should not:</para> <informalexample> - <programlisting><![CDATA[<article lang='en'> - <articleinfo> - <title>NIS</title> + <programlisting><sgmltag class="starttag">article lang='en'</sgmltag> + <sgmltag class="starttag">articleinfo</sgmltag> + <sgmltag class="starttag">title</sgmltag>NIS<sgmltag class="endtag">title</sgmltag> - <pubdate>October 1999</pubdate> + <sgmltag class="starttag">pubdate</sgmltag>October 1999<sgmltag class="endtag">pubdate</sgmltag> - <abstract> - <para>... + <sgmltag class="starttag">abstract</sgmltag> + <sgmltag class="starttag">para</sgmltag>... ... - ...</para> - </abstract> - </articleinfo> + ...<sgmltag class="endtag">para</sgmltag> + <sgmltag class="endtag">abstract</sgmltag> + <sgmltag class="endtag">articleinfo</sgmltag> - <sect1> - <title>...</title> + <sgmltag class="starttag">sect1</sgmltag> + <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> - <para>...</para> - </sect1> + <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag> + <sgmltag class="endtag">sect1</sgmltag> - <sect1> - <title>...</title> + <sgmltag class="starttag">sect1</sgmltag> + <sgmltag class="starttag">title</sgmltag>...<sgmltag class="endtag">title</sgmltag> - <para>...</para> - </sect1> -</article>]]></programlisting> + <sgmltag class="starttag">para</sgmltag>...<sgmltag class="endtag">para</sgmltag> + <sgmltag class="endtag">sect1</sgmltag> +<sgmltag class="endtag">article</sgmltag></programlisting> </informalexample> </sect3> @@ -428,25 +402,23 @@ augroup END</programlisting> </sect2> <sect2> - <title>White Space Changes</title> + <title>Whitespace Changes</title> - <para>When committing changes, <emphasis>do not commit changes - to the content at the same time as changes to the + <para><emphasis>Do not commit changes + to content at the same time as changes to formatting</emphasis>.</para> - <para>This is so that the teams that convert the documentation - to other languages can quickly see what content has actually - changed in your commit, without having to decide whether a - line has changed because of the content, or just because it - has been refilled.</para> + <para>When content and whitespace changes are kept separate, + translation teams can easily see whether a change was content + that must be translated or only whitespace.</para> - <para>For example, if you have added two sentences to a - paragraph, such that the line lengths on the paragraph now go - over 80 columns, first commit your change with the too-long - line lengths. Then fix the line wrapping, and commit this + <para>For example, if two sentences have been added to a + paragraph so that the line lengths now go + over 80 columns, first commit the change with the too-long + lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, - be sure to indicate that this is a whitespace-only change, and - that the translation team can ignore it.</para> + indicate that this is a whitespace-only change that can be + ignored by translators.</para> </sect2> <sect2> @@ -468,18 +440,18 @@ GB. Hardware compression …</literallayout> <itemizedlist> <listitem> <para>between numbers and units:</para> - <programlisting><![CDATA[57600 bps]]></programlisting> + <programlisting>57600&nbsp;bps</programlisting> </listitem> <listitem> <para>between program names and version numbers:</para> - <programlisting><![CDATA[FreeBSD 4.7]]></programlisting> + <programlisting>&os;&nbsp;9.2</programlisting> </listitem> <listitem> <para>between multiword names (use with caution when applying this to more than 3-4 word names like - <quote>The FreeBSD Brazilian Portuguese Documentation + <quote>The &os; Brazilian Portuguese Documentation Project</quote>):</para> <programlisting><![CDATA[Sun Microsystems]]></programlisting> </listitem> @@ -491,7 +463,7 @@ GB. Hardware compression …</literallayout> <title>Word List</title> <para>This list of words shows the correct spelling and - capitalization when used in FreeBSD Documentation. If a word is + capitalization when used in &os; documentation. If a word is not on this list, ask about it on the &a.doc;.</para> <informaltable frame="none" pgwide="0"> @@ -507,12 +479,17 @@ GB. Hardware compression …</literallayout> <tbody> <row> <entry>CD-ROM</entry> - <entry><sgmltag class="starttag">acronym</sgmltag><literal>CD-ROM</literal><sgmltag class="endtag">acronym</sgmltag></entry> + + <entry><sgmltag + class="starttag">acronym</sgmltag><literal>CD-ROM</literal><sgmltag + class="endtag">acronym</sgmltag></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><sgmltag + class="starttag">acronym</sgmltag><literal>DoS</literal><sgmltag + class="endtag">acronym</sgmltag></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 cb7aa0e13a..eded9cac18 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 @@ -60,9 +60,9 @@ <emphasis>transitional</emphasis> variants.</para> <para>The <acronym>XHTML</acronym> <acronym>DTDs</acronym> are - available from the Ports Collection in + available from the Ports Collection in <filename role="package">textproc/xhtml</filename>. They are - automatically installed as part of the <filename + automatically installed by the <filename role="package">textproc/docproj</filename> port.</para> <note> @@ -91,8 +91,8 @@ <para>There are a number of <acronym>XHTML</acronym> <acronym>FPI</acronym>s, depending upon the version, or <emphasis>level</emphasis> of <acronym>XHTML</acronym> to which - a document conforms. Most XHTML documents on the FreeBSD web - site comply with the transitional version of + a document conforms. Most <acronym>XHTML</acronym> documents on + the &os; web site comply with the transitional version of <acronym>XHTML</acronym> 1.0.</para> <programlisting>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"</programlisting> @@ -106,7 +106,7 @@ <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 + <emphasis>body</emphasis>, contains content that will be displayed to the user.</para> <para>These sections are indicated with <sgmltag>head</sgmltag> @@ -118,17 +118,17 @@ <title>Normal <acronym>XHTML</acronym> Document Structure</title> - <programlisting><html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title><replaceable>The Document's Title</replaceable></title> - </head> + <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> - <body> + <sgmltag class="starttag">body</sgmltag> … - </body> -</html></programlisting> + <sgmltag class="endtag">body</sgmltag> +<sgmltag class="endtag">html</sgmltag></programlisting> </example> </sect1> @@ -153,19 +153,19 @@ <para>Usage:</para> - <programlisting><h1>First section</h1> + <programlisting><sgmltag class="starttag">h1</sgmltag>First section<sgmltag class="endtag">h1</sgmltag> <!-- Document introduction goes here --> -<h2>This is the heading for the first section</h2> +<sgmltag class="starttag">h2</sgmltag>This is the heading for the first section<sgmltag class="endtag">h2</sgmltag> <!-- Content for the first section goes here --> -<h3>This is the heading for the first sub-section</h3> +<sgmltag class="starttag">h3</sgmltag>This is the heading for the first sub-section<sgmltag class="endtag">h3</sgmltag> <!-- Content for the first sub-section goes here --> -<h2>This is the heading for the second section</h2> +<sgmltag class="starttag">h2</sgmltag>This is the heading for the second section<sgmltag class="endtag">h2</sgmltag> <!-- Content for the second section goes here --></programlisting> </example> @@ -173,27 +173,8 @@ <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>), - which can in turn contain many third level headings. Each - <sgmltag>h<replaceable>n</replaceable></sgmltag> element - should have the same element, but one further up the - hierarchy, preceding it. Leaving gaps in the numbering is to - be avoided.</para> - - <example> - <title>Bad Ordering of - <sgmltag>h<replaceable>n</replaceable></sgmltag> - Elements</title> - - <para>Usage:</para> - - <programlisting><h1>First section</h1> - -<!-- Document introduction --> - -<h3>Sub-section</h3> - -<!-- This is bad, <h2> has been left out --></programlisting> - </example> + 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"> @@ -207,8 +188,8 @@ <para>Usage:</para> - <programlisting><![CDATA[<p>This is a paragraph. It can contain just about any - other element.</p>]]></programlisting> + <programlisting><sgmltag class="starttag">p</sgmltag>This is a paragraph. It can contain just about any + other element.<sgmltag class="endtag">p</sgmltag></programlisting> </example> </sect2> @@ -216,22 +197,21 @@ <title>Block Quotations</title> <para>A block quotation is an extended quotation from another - document that should not appear within the current - paragraph.</para> + document that will appear in a separate paragraph.</para> <example> <title><sgmltag>blockquote</sgmltag></title> <para>Usage:</para> - <programlisting><![CDATA[<p>A small excerpt from the US Constitution:</p> + <programlisting><sgmltag class="starttag">p</sgmltag>A small excerpt from the US Constitution:<sgmltag class="endtag">p</sgmltag> -<blockquote>We the People of the United States, in Order to form +<sgmltag class="starttag">blockquote</sgmltag>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> + United States of America.<sgmltag class="endtag">blockquote</sgmltag></programlisting> </example> </sect2> @@ -241,12 +221,11 @@ <para><acronym>XHTML</acronym> 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>Entries in an ordered list will be numbered, while entries + in an unordered list will be preceded by bullet points. + Definition lists have two sections for each entry. The first + 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> @@ -270,31 +249,31 @@ <para>Usage:</para> - <programlisting><![CDATA[<p>An unordered list. Listitems will probably be - preceded by bullets.</p> + <programlisting><sgmltag class="starttag">p</sgmltag>An unordered list. Listitems will probably be + preceded by bullets.<sgmltag class="endtag">p</sgmltag> -<ul> - <li>First item</li> +<sgmltag class="starttag">ul</sgmltag> + <sgmltag class="starttag">li</sgmltag>First item<sgmltag class="endtag">li</sgmltag> - <li>Second item</li> + <sgmltag class="starttag">li</sgmltag>Second item<sgmltag class="endtag">li</sgmltag> - <li>Third item</li> -</ul> + <sgmltag class="starttag">li</sgmltag>Third item<sgmltag class="endtag">li</sgmltag> +<sgmltag class="endtag">ul</sgmltag> -<p>An ordered list, with list items consisting of multiple +<sgmltag class="starttag">p</sgmltag>An ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be - numbered.</p> + numbered.<sgmltag class="endtag">p</sgmltag> -<ol> - <li><p>This is the first item. It only has one paragraph.</p></li> +<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> - <li><p>This is the first paragraph of the second item.</p> + <sgmltag class="starttag">li</sgmltag><sgmltag class="starttag">p</sgmltag>This is the first paragraph of the second item.<sgmltag class="endtag">p</sgmltag> - <p>This is the second paragraph of the second item.</p></li> + <sgmltag class="starttag">p</sgmltag>This is the second paragraph of the second item.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">li</sgmltag> - <li><p>This is the first and only paragraph of the third - item.</p></li> -</ol>]]></programlisting> + <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> </example> <example> @@ -302,34 +281,34 @@ <para>Usage:</para> - <programlisting><![CDATA[<dl> - <dt>Term 1</dt> + <programlisting><sgmltag class="starttag">dl</sgmltag> + <sgmltag class="starttag">dt</sgmltag>Term 1<sgmltag class="endtag">dt</sgmltag> - <dd><p>Paragraph 1 of definition 1.</p> + <sgmltag class="starttag">dd</sgmltag><sgmltag class="starttag">p</sgmltag>Paragraph 1 of definition 1.<sgmltag class="endtag">p</sgmltag> - <p>Paragraph 2 of definition 1.</p></dd> + <sgmltag class="starttag">p</sgmltag>Paragraph 2 of definition 1.<sgmltag class="endtag">p</sgmltag><sgmltag class="endtag">dd</sgmltag> - <dt>Term 2</dt> + <sgmltag class="starttag">dt</sgmltag>Term 2<sgmltag class="endtag">dt</sgmltag> - <dd><p>Paragraph 1 of definition 2.</p></dd> + <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> - <dt>Term 3</dt> + <sgmltag class="starttag">dt</sgmltag>Term 3<sgmltag class="endtag">dt</sgmltag> - <dd><p>Paragraph 1 of definition 3.</p></dd> -</dl>]]></programlisting> + <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> </example> </sect2> <sect2 id="xhtml-markup-block-elements-preformatted-text"> <title>Pre-formatted Text</title> - <para>Pre-formatted text can 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>Pre-formatted text is shown to the user exactly as it is + in the file. Text is shown in a fixed font. Multiple spaces + and line breaks are shown exactly as they are in the + file.</para> - <para>In order to do this, wrap the content in the - <sgmltag>pre</sgmltag> element.</para> + <para>Wrap pre-formatted text in the <sgmltag>pre</sgmltag> + element.</para> <example> <title><sgmltag>pre</sgmltag></title> @@ -337,18 +316,18 @@ <para>For example, the <sgmltag>pre</sgmltag> tags could be used to mark up an email message:</para> - <programlisting><![CDATA[<pre> From: nik@FreeBSD.org + <programlisting><sgmltag class="starttag">pre</sgmltag> 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> + &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt; Comments appreciated. - N</pre>]]></programlisting> + N<sgmltag class="endtag">pre</sgmltag></programlisting> <para>Keep in mind that <literal><</literal> and <literal>&</literal> still are recognized as special @@ -379,97 +358,104 @@ <para>Usage:</para> - <programlisting><![CDATA[<p>This is a simple 2x2 table.</p> + <programlisting><sgmltag class="starttag">p</sgmltag>This is a simple 2x2 table.<sgmltag class="endtag">p</sgmltag> -<table> - <tr> - <td>Top left cell</td> +<sgmltag class="starttag">table</sgmltag> + <sgmltag class="starttag">tr</sgmltag> + <sgmltag class="starttag">td</sgmltag>Top left cell<sgmltag class="endtag">td</sgmltag> - <td>Top right cell</td> - </tr> + <sgmltag class="starttag">td</sgmltag>Top right cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> - <tr> - <td>Bottom left cell</td> + <sgmltag class="starttag">tr</sgmltag> + <sgmltag class="starttag">td</sgmltag>Bottom left cell<sgmltag class="endtag">td</sgmltag> - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> + <sgmltag class="starttag">td</sgmltag>Bottom right cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> +<sgmltag class="endtag">table</sgmltag></programlisting> </example> - <para>A cell can span multiple rows and columns. To indicate - this, add the <literal>rowspan</literal> and/or - <literal>colspan</literal> attributes, with values indicating - the number of rows or columns that should be spanned.</para> + <para>A cell can span multiple rows and columns by adding the + <sgmltag class="attribute">rowspan</sgmltag> or + <sgmltag class="attribute">colspan</sgmltag> attributes with + values for the number of rows or columns to be spanned.</para> <example> - <title>Using <literal>rowspan</literal></title> + <title>Using + <sgmltag class="attribute">rowspan</sgmltag></title> <para>Usage:</para> - <programlisting><![CDATA[<p>One tall thin cell on the left, two short cells next to - it on the right.</p> + <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> -<table> - <tr> - <td rowspan="2">Long and thin</td> - </tr> +<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> - <tr> - <td>Top cell</td> + <sgmltag class="starttag">tr</sgmltag> + <sgmltag class="starttag">td</sgmltag>Top cell<sgmltag class="endtag">td</sgmltag> - <td>Bottom cell</td> - </tr> -</table>]]></programlisting> + <sgmltag class="starttag">td</sgmltag>Bottom cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> +<sgmltag class="endtag">table</sgmltag></programlisting> </example> <example> - <title>Using <literal>colspan</literal></title> + <title>Using + <sgmltag class="attribute">colspan</sgmltag></title> <para>Usage:</para> - <programlisting><![CDATA[<p>One long cell on top, two short cells below it.</p> + <programlisting><sgmltag class="starttag">p</sgmltag>One long cell on top, two short cells below it.<sgmltag class="endtag">p</sgmltag> -<table> - <tr> - <td colspan="2">Top cell</td> - </tr> +<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> - <tr> - <td>Bottom left cell</td> + <sgmltag class="starttag">tr</sgmltag> + <sgmltag class="starttag">td</sgmltag>Bottom left cell<sgmltag class="endtag">td</sgmltag> - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> + <sgmltag class="starttag">td</sgmltag>Bottom right cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> +<sgmltag class="endtag">table</sgmltag></programlisting> </example> <example> - <title>Using <literal>rowspan</literal> and - <literal>colspan</literal> Together</title> + <title>Using <sgmltag class="attribute">rowspan</sgmltag> and + <sgmltag class="attribute">colspan</sgmltag> + Together</title> <para>Usage:</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> + <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> + +<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> -<table> - <tr> - <td colspan="2" rowspan="2">Top left large cell</td> + <sgmltag class="starttag">td</sgmltag>Top right cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> - <td>Top right cell</td> - </tr> + <sgmltag class="starttag">tr</sgmltag> + <!-- Because the large cell on the left merges into + this row, the first <td> will occur on its + right --> - <tr> - <td>Middle right cell</td> - </tr> + <sgmltag class="starttag">td</sgmltag>Middle right cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> - <tr> - <td>Bottom left cell</td> + <sgmltag class="starttag">tr</sgmltag> + <sgmltag class="starttag">td</sgmltag>Bottom left cell<sgmltag class="endtag">td</sgmltag> - <td>Bottom middle cell</td> + <sgmltag class="starttag">td</sgmltag>Bottom middle cell<sgmltag class="endtag">td</sgmltag> - <td>Bottom right cell</td> - </tr> -</table>]]></programlisting> + <sgmltag class="starttag">td</sgmltag>Bottom right cell<sgmltag class="endtag">td</sgmltag> + <sgmltag class="endtag">tr</sgmltag> +<sgmltag class="endtag">table</sgmltag></programlisting> </example> </sect2> </sect1> @@ -482,15 +468,15 @@ <para>Two levels of emphasis are available in <acronym>XHTML</acronym>, <sgmltag>em</sgmltag> and - <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a + <sgmltag>strong</sgmltag>. <sgmltag>em</sgmltag> is for a normal level of emphasis and <sgmltag>strong</sgmltag> indicates stronger emphasis.</para> - <para>Typically, <sgmltag>em</sgmltag> is rendered in italic + <para><sgmltag>em</sgmltag> is typically rendered in italic and <sgmltag>strong</sgmltag> is rendered in bold. This is - not always the case, however, and should not be relied upon. - According to best practices, webpages only hold structural and - semantical information and stylesheets are later applied to + 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 them. Think of semantics, not formatting, when using these tags.</para> @@ -500,8 +486,8 @@ <para>Usage:</para> - <programlisting><![CDATA[<p><em>This</em> has been emphasized, while - <strong>this</strong> has been strongly emphasized.</p>]]></programlisting> + <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> </example> </sect2> @@ -517,9 +503,8 @@ <para>Usage:</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> + <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> </example> </sect2> @@ -533,75 +518,83 @@ <sect3 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 another + <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 <literal>href</literal> - attribute contains the <acronym>URL</acronym> of the target - document. The content of the element becomes the link, and - is normally indicated to the user in some way, - typically by a different color or underlining.</para> + <sgmltag>a</sgmltag>, and the + <sgmltag class="attribute">href</sgmltag> 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 + underline.</para> <example> - <title>Using <literal><a href="..."></literal></title> + <title>Using + <sgmltag class="starttag">a href="..."</sgmltag></title> <para>Usage:</para> - <programlisting><![CDATA[<p>More information is available at the - <a href="http://www.FreeBSD.org/">FreeBSD web site</a>.</p>]]></programlisting> + <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> </example> - <para>These links will take the user to the top of the chosen + <para>This link always takes the user to the top of the linked document.</para> </sect3> - <sect3 id="xhtml-markup-inline-elements-other-parts"> - <title>Linking to Other Parts of Documents</title> + <sect3 id="xhtml-markup-inline-elements-specific-parts"> + <title>Linking to Specific Parts of Documents</title> - <para>Linking to a point within another document, or within - the same document, requires that the document author include - <emphasis>anchors</emphasis>. Anchors are indicated with - <sgmltag>a</sgmltag> and the <literal>id</literal> attribute - instead of <literal>href</literal>.</para> + <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 + 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> + element.</para> <example> - <title>Using <literal><a id="..."></literal></title> + <title>Creating an Anchor</title> <para>Usage:</para> - <programlisting><![CDATA[<p><a id="para1">This</a> paragraph can be referenced - in other links with the name <tt>para1</tt>.</p>]]></programlisting> + <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> </example> - <para>To link to a named part of a document, write a normal - link to that document, but include the <acronym>ID</acronym> - of the anchor after a <literal>#</literal> symbol.</para> + <para>Links to anchors are similar to plain links, but include + a <literal>#</literal> symbol and the anchor's + <acronym>ID</acronym> at the end of the + <acronym>URL</acronym>.</para> <example> - <title>Linking to a Named Part of Another Document</title> + <title>Linking to a Named Part of a Different + Document</title> - <para>Assume that the <literal>para1</literal> example - resides in a document called - <filename>foo.html</filename>.</para> + <para>The <literal>samplepara</literal> example is part of a + document called <filename>foo.html</filename>. A link to + that specific paragraph in the document is constructed in + this example.</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> + <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> </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> + <para>To link to a named anchor within the same document, omit + the document's <acronym>URL</acronym>, and just use the + <literal>#</literal> symbol followed by the name of the + anchor.</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> + <para>The <literal>samplepara</literal> example + resides in this document. To link to it:</para> - <programlisting><![CDATA[<p>More information can be found in the - <a href="#para1">first paragraph</a> of this - document.</p>]]></programlisting> + <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> </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 745bcdb16f..a7ff166cba 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 @@ -34,10 +34,11 @@ <chapter 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>Most <acronym>FDP</acronym> documentation is written with + markup languages based on <acronym>XML</acronym>. This chapter + explains what that means, how to read and understand the + documentation source, and the <acronym>XML</acronym> techniques + used.</para> <para>Portions of this section were inspired by Mark Galassi's <ulink @@ -47,31 +48,31 @@ <sect1 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>In the original days of computers, electronic text was + simple. There were a few character sets like + <acronym>ASCII</acronym> or <acronym>EBCDIC</acronym>, 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. When text is in a + machine-usable format, machines are expected to be able to use + and manipulate it intelligently. Authors want to indicate that + certain phrases should be emphasized, or added to a glossary, or + made into hyperlinks. Filenames could 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 + make this easy. The computer would read 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 + life has not happened quite like that, and computers still + require assistance before they can meaningfully process text.</para> <para>More precisely, they need help identifying what is what. - Let's look at this text:</para> + Consider this text:</para> <blockquote> <para>To remove <filename>/tmp/foo</filename> use @@ -95,96 +96,94 @@ 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 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> (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> + <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> -<screen>&prompt.user; <userinput>rm /tmp/foo</userinput></screen>]]></programlisting> +<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> - <para>As you can see, the markup is clearly separate from the - content.</para> + <para>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>Markup languages define what the markup means and how it + should be interpreted.</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> + requirements than a markup language that is intended for cookery + recipes. This, in turn, would be very different from a markup + language used to describe poetry. What is really needed is a + first language used 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> + Language (<acronym>XML</acronym>) is. Many markup languages + have been written in <acronym>XML</acronym>, including the two + most used by the <acronym>FDP</acronym>, + <acronym>XHTML</acronym> 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> + vocabulary, schema or Document Type Definition + (<acronym>DTD</acronym>). There are various languages to + specify an <acronym>XML</acronym> grammar, or + <emphasis>schema</emphasis>.</para> <para 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 + forth. This makes it possible to write an + <acronym>XML</acronym> <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 + <para>Validation 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> + in the grammar. It does <emphasis>not</emphasis> check + whether <emphasis>appropriate</emphasis> markup has been used + for the content. If all the filenames in a document were + marked up as function names, the parser would not flag this as + an error (assuming, of course, that the 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> + <para>Most contributions to the Documentation + Project will be content marked up in either + <acronym>XHTML</acronym> 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 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 + <para>All the vocabularies written in <acronym>XML</acronym> share + certain characteristics. This is hardly surprising, as the + philosophy behind <acronym>XML</acronym> 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>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> @@ -195,100 +194,95 @@ 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>It may be helpful to think of this as + <quote>chunking</quote> content. At the very top level is one + chunk, the book. Look a little deeper, and there are 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>Notice how this differentiation between different elements + of the content can be made without resorting to any + <acronym>XML</acronym> terms. It really is surprisingly + straightforward. This could be done 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> + content belongs to. In languages written in + <acronym>XML</acronym> (<acronym>XHTML</acronym>, 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> + 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 - <sgmltag><replaceable>element-name</replaceable></sgmltag>. The - corresponding closing tag for this element is - <sgmltag>/<replaceable>element-name</replaceable></sgmltag>.</para> + 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> <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 - <sgmltag>p</sgmltag>.</para> + <para><acronym>XHTML</acronym> has an element for indicating + that the content enclosed by the element is a paragraph, + called <sgmltag>p</sgmltag>.</para> - <programlisting><![CDATA[<p>This is a paragraph. It starts with the start tag for + <programlisting><sgmltag class="starttag">p</sgmltag>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> + element.<sgmltag class="endtag">p</sgmltag> -<p>This is another paragraph. But this one is much shorter.</p>]]></programlisting> +<sgmltag class="starttag">p</sgmltag>This is another paragraph. But this one is much shorter.<sgmltag class="endtag">p</sgmltag></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> + <para>Some elements have no content. For example, in + <acronym>XHTML</acronym>, a horizontal line can be included in + the document. For these <quote>empty</quote> elements, + <acronym>XML</acronym> introduced a shorthand form that is + completely equivalent to the two-tag version:</para> <example> - <title>Using an Element (Without Content)</title> + <title>Using an Element Without Content</title> - <para>XHTML has an element for indicating a horizontal rule, - called <sgmltag>hr</sgmltag>. This element does not wrap - content, so it looks like this.</para> + <para><acronym>XHTML</acronym> has an element for indicating a + horizontal rule, called <sgmltag>hr</sgmltag>. This element + does not wrap content, so it looks like this:</para> - <programlisting><![CDATA[<p>One paragraph.</p> -<hr></hr> + <programlisting><sgmltag class="starttag">p</sgmltag>One paragraph.<sgmltag class="endtag">p</sgmltag> +<sgmltag class="starttag">hr</sgmltag><sgmltag class="endtag">hr</sgmltag> -<p>This is another paragraph. A horizontal rule separates this - from the previous paragraph.</p>]]></programlisting> +<sgmltag class="starttag">p</sgmltag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<sgmltag class="endtag">p</sgmltag></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> + <para>The shorthand version consists of a single tag:</para> - <programlisting><![CDATA[<p>One paragraph.</p> -<hr/> + <programlisting><sgmltag class="starttag">p</sgmltag>One paragraph.<sgmltag class="endtag">p</sgmltag> +<sgmltag class="emptytag">hr</sgmltag> -<p>This is another paragraph. A horizontal rule separates this - from the previous paragraph.</p>]]></programlisting> +<sgmltag class="starttag">p</sgmltag>This is another paragraph. A horizontal rule separates this + from the previous paragraph.<sgmltag class="endtag">p</sgmltag></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> + <para>As shown above, 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; <sgmltag>em</sgmltag></title> + <title>Elements Within Elements; <sgmltag>em</sgmltag></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> + <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> </example> - <para>The grammar will specify the rules detailing which elements can - contain other elements, and exactly what they can + <para>The grammar consists of rules that describe which elements + can contain other elements, and exactly what they can contain.</para> <important> @@ -298,15 +292,16 @@ <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> + element starts and ends.</para> <para>When this document (or anyone else knowledgeable about - XML) refers to <quote>the <sgmltag>p</sgmltag> tag</quote> + <acronym>XML</acronym>) refers to + <quote>the <sgmltag class="starttag">p</sgmltag> 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 whole - element.</para> + <literal>></literal>. But the phrase + <quote>the <sgmltag>p</sgmltag> element</quote> refers to the + whole element.</para> <para>This distinction <emphasis>is</emphasis> very subtle. But keep it in mind.</para> @@ -323,74 +318,72 @@ take the form <literal><replaceable>attribute-name</replaceable>="<replaceable>attribute-value</replaceable>"</literal>.</para> - <para>In XHTML, the - <sgmltag>p</sgmltag> element has an attribute called - <sgmltag>align</sgmltag>, which suggests an alignment - (justification) for the paragraph to the program displaying the - XHTML.</para> + <para>In <acronym>XHTML</acronym>, the <sgmltag>p</sgmltag> + element has an attribute called + <sgmltag class="attribute">align</sgmltag>, which suggests an + alignment (justification) for the paragraph to the program + displaying the <acronym>XHTML</acronym>.</para> - <para>The <literal>align</literal> attribute can take one of four - defined values, <literal>left</literal>, + <para>The <sgmltag class="attribute">align</sgmltag> 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> + <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> + <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> -<p align="center">This may appear in the center.</p>]]></programlisting> +<sgmltag class="starttag">p align="center"</sgmltag>This may appear in the center.<sgmltag class="endtag">p</sgmltag></programlisting> </example> - <para>Some attributes will only take specific values, such as + <para>Some attributes only take specific values, such as <literal>left</literal> or <literal>justify</literal>. Others - will allow you to enter anything you want.</para> + allow any value.</para> <example> <title>Single Quotes Around Attributes</title> - <programlisting><![CDATA[<p align='right'>I am on the right!</p>]]></programlisting> + <programlisting><sgmltag class="starttag">p align='right'</sgmltag>I am on the right!<sgmltag class="endtag">p</sgmltag></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>Attribute values in <acronym>XML</acronym> must be enclosed + in either single or double quotes. Double quotes are + traditional. Single quotes are useful when the attribute value + contains double quotes.</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 - <filename role="package">textproc/docproj</filename> 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> + <para>Information about attributes, elements, and tags is stored + in catalog files. The Documentation Project uses standard + DocBook catalogs and includes additional catalogs for + &os;-specific features. Paths to the catalog files are defined + in an environment variable so they can be found by the document + build tools.</para> <sect2> - <title>For You to Do…</title> + <title>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> + <para>Before running the examples in this document, + application software must be installed and the catalog + environment variable configured.</para> <procedure> <step> - <para>Download and install + <para>Install <filename role="package">textproc/docproj</filename> 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> + the &os; Ports Collection. This is a + <emphasis>meta-port</emphasis> that downloads and installs + the standard programs and supporting files needed 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> + <para>Add lines to the shell startup files to set + <envar>SGML_CATALOG_FILES</envar>. When working on + non-English versions of the documentation, replace + <replaceable>en_US.ISO8859-1</replaceable> with the + appropriate directory for the target language.</para> <example id="xml-primer-envars"> <title><filename>.profile</filename>, for &man.sh.1; and @@ -402,7 +395,7 @@ 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 +SGML_CATALOG_FILES=/usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/share/xml/catalog:$SGML_CATALOG_FILES export SGML_CATALOG_FILES</programlisting> </example> @@ -416,79 +409,80 @@ 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> +setenv SGML_CATALOG_FILES /usr/doc/<replaceable>en_US.ISO8859-1</replaceable>/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> + <para>After making these changes, either log out and log + back in again, or run the 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> + this text:</para> - <programlisting><![CDATA[<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> + <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> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>An Example XHTML File</title> - </head> +<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> - <body> - <p>This is a paragraph containing some text.</p> + <sgmltag class="starttag">body</sgmltag> + <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag> - <p>This paragraph contains some more text.</p> + <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag> - <p align="right">This paragraph might be right-justified.</p> - </body> -</html>]]></programlisting> + <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> </step> <step> - <para>Try to validate this file using an XML parser.</para> + <para>Try to validate this file using an + <acronym>XML</acronym> parser.</para> - <para>Part of - <filename role="package">textproc/docproj</filename> is - the <command>xmllint</command> + <para><filename role="package">textproc/docproj</filename> + includes 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> + <para>Use <command>xmllint</command> to validate the + document:</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> + <para><command>xmllint</command> returns without displaying + any output, showing that the document validated + successfully.</para> </step> <step> <para>See what happens when required elements are omitted. - Try removing the <sgmltag>title</sgmltag> and - <sgmltag>/title</sgmltag> tags, and re-run the - validation.</para> + Delete the line with the + <sgmltag class="starttag">title</sgmltag> and + <sgmltag class="endtag">/title</sgmltag> 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 + <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>head</sgmltag> is the part, which - does not follow the rules described by the XHTML grammar.</para> + content of the <sgmltag class="starttag">head</sgmltag> is + the part which does not follow the rules of the + <acronym>XHTML</acronym> 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> + <para>Then <command>xmllint</command> shows the line where + the error was found and marks the exact character position + with a <literal>^</literal> sign.</para> </step> <step> - <para>Put the <sgmltag>title</sgmltag> element back - in.</para> + <para>Replace the <sgmltag>title</sgmltag> element.</para> </step> </procedure> </sect2> @@ -497,17 +491,17 @@ example.xml:5: element head: validity error : Element head content does not foll <sect1 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>The beginning of each document can specify the name of the + <acronym>DTD</acronym> to which the document conforms. This + DOCTYPE declaration is used by <acronym>XML</acronym> parsers to + identify the <acronym>DTD</acronym> 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> + version 1.0 of the <acronym>XHTML</acronym> + <acronym>DTD</acronym> 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> + <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> <para>That line contains a number of different components.</para> @@ -516,9 +510,8 @@ example.xml:5: element head: validity error : Element head content does not foll <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> + <para>The <emphasis>indicator</emphasis> shows + this is an <acronym>XML</acronym> declaration.</para> </listitem> </varlistentry> @@ -526,8 +519,8 @@ example.xml:5: element head: validity error : Element head content does not foll <term><literal>DOCTYPE</literal></term> <listitem> - <para>Shows that this is an XML declaration for the - document type.</para> + <para>Shows that this is an <acronym>XML</acronym> + declaration of the document type.</para> </listitem> </varlistentry> @@ -542,21 +535,27 @@ example.xml:5: element head: validity error : Element head content does not foll </varlistentry> <varlistentry> - <term><literal>PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"</literal></term> + <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) + <para>Lists the Formal Public Identifier + (<acronym>FPI</acronym>) <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 + for the <acronym>DTD</acronym> to which this document + conforms. The <acronym>XML</acronym> parser uses this to + find the correct <acronym>DTD</acronym> when processing + this document.</para> + + <para><literal>PUBLIC</literal> is not a part of the + <acronym>FPI</acronym>, but indicates to the + <acronym>XML</acronym> processor how to find the + <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> </listitem> </varlistentry> @@ -565,7 +564,8 @@ example.xml:5: element head: validity error : Element head content does not foll <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> + <para>A local filename or a <acronym>URL</acronym> to find + the <acronym>DTD</acronym>.</para> </listitem> </varlistentry> @@ -573,25 +573,29 @@ example.xml:5: element head: validity error : Element head content does not foll <term><literal>></literal></term> <listitem> - <para>Returns to the document.</para> + <para>Ends the declaration and returns to the + document.</para> </listitem> </varlistentry> </variablelist> <sect2> - <title>Formal Public Identifiers (FPIs) - <indexterm significance="preferred"> - <primary>Formal Public Identifier</primary> - </indexterm></title> + <title>Formal Public Identifiers + (<acronym>FPI</acronym>s)</title> + + <indexterm significance="preferred"> + <primary>Formal Public Identifier</primary> + </indexterm> <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> + <para>It is not necessary to know this, but it is useful + background, and might help debug problems when the + <acronym>XML</acronym> processor can not locate the + <acronym>DTD</acronym>.</para> </note> - <para>FPIs must follow a specific syntax. This syntax is as - follows:</para> + <para><acronym>FPI</acronym>s must follow a specific + syntax:</para> <programlisting>"<replaceable>Owner</replaceable>//<replaceable>Keyword</replaceable> <replaceable>Description</replaceable>//<replaceable>Language</replaceable>"</programlisting> @@ -600,16 +604,20 @@ example.xml:5: element head: validity error : Element head content does not foll <term><replaceable>Owner</replaceable></term> <listitem> - <para>This indicates the owner of the FPI.</para> + <para>The owner of the <acronym>FPI</acronym>.</para> - <para>If this string starts with <quote>ISO</quote> then - this is an ISO owned FPI. For example, the FPI + <para>The beginning of the string identifies the owner of + the <acronym>FPI</acronym>. For example, the + <acronym>FPI</acronym> <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> + the set of entities for Greek symbols. + <acronym>ISO</acronym> 8879:1986 is the International + Organization for Standardization + (<acronym>ISO</acronym>) number for the + <acronym>SGML</acronym> standard, the predecessor (and a + superset) of <acronym>XML</acronym>.</para> <para>Otherwise, this string will either look like <literal>-//<replaceable>Owner</replaceable></literal> @@ -620,22 +628,24 @@ example.xml:5: element head: validity error : Element head content does not foll <para>If the string starts with <literal>-</literal> then the owner information is unregistered, with a - <literal>+</literal> it identifies it as being + <literal>+</literal> identifying it as 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 + <para><acronym>ISO</acronym> 9070:1991 defines how + registered names are generated. It might be derived + from the number of an <acronym>ISO</acronym> + publication, an <acronym>ISBN</acronym> code, or an + organization code assigned according to + <acronym>ISO</acronym> 6523. Additionally, 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> + assign registered names. The <acronym>ISO</acronym> + council delegated this to the American National + Standards Institute (<acronym>ANSI</acronym>).</para> + + <para>Because the &os; Project has not been registered, + the owner string is <literal>-//&os;</literal>. As seen + in the example, the <acronym>W3C</acronym> are not a + registered owner either.</para> </listitem> </varlistentry> @@ -647,11 +657,13 @@ example.xml:5: element head: validity error : Element head content does not foll 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> + and <literal>TEXT</literal>. <literal>DTD</literal> is + used only for <acronym>DTD</acronym> files, + <literal>ELEMENT</literal> is usually used for + <acronym>DTD</acronym> fragments that contain only + entity or element declarations. <literal>TEXT</literal> + is used for <acronym>XML</acronym> content (text and + tags).</para> </listitem> </varlistentry> @@ -659,10 +671,10 @@ example.xml:5: element head: validity error : Element head content does not foll <term><replaceable>Description</replaceable></term> <listitem> - <para>Any description you want to supply for the contents + <para>Any description can be given 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> + short text that is meaningful and unique for the + <acronym>XML</acronym> system.</para> </listitem> </varlistentry> @@ -670,9 +682,9 @@ example.xml:5: element head: validity error : Element head content does not foll <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> + <para>An <acronym>ISO</acronym> two-character code that + identifies the native language for the file. + <literal>EN</literal> is used for English.</para> </listitem> </varlistentry> </variablelist> @@ -680,49 +692,46 @@ example.xml:5: element head: validity error : Element head content does not foll <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> + <para>With the syntax above, an <acronym>XML</acronym> + processor needs to have some way of turning the + <acronym>FPI</acronym> into the name of the file containing + the <acronym>DTD</acronym>. A catalog file (typically + called <filename>catalog</filename>) contains lines that map + <acronym>FPI</acronym>s 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 + <para>The <acronym>XML</acronym> processor knows that the + <acronym>DTD</acronym> is called <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> + <filename>1.0</filename> subdirectory of the directory that + held <filename>catalog</filename>.</para> - <para>Look at the contents of + <para>Examine 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 <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> </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>To locate a <filename>catalog</filename>, the + <acronym>XML</acronym> processor must know where to look. + Many 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>In addition, <envar>SGML_CATALOG_FILES</envar> can be + set to point to the files. This environment variable + consists of a colon-separated list of catalog files + (including their full path).</para> - <para>Typically, you will want to include the following - files:</para> + <para>Typically, the list includes these files:</para> <itemizedlist> <listitem> @@ -742,81 +751,73 @@ example.xml:5: element head: validity error : Element head content does not foll </listitem> </itemizedlist> - <para>You should <link linkend="xml-primer-envars">already - have done this</link>.</para> + <para>This was done + <link linkend="xml-primer-envars">earlier</link>.</para> </sect3> </sect2> <sect2 id="xml-primer-fpi-alternatives"> - <title>Alternatives to FPIs</title> + <title>Alternatives to <acronym>FPI</acronym>s</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>Instead of using an <acronym>FPI</acronym> to indicate the + <acronym>DTD</acronym> to which the document conforms (and + therefore, which file on the system contains the + <acronym>DTD</acronym>), the filename can be explicitly + specified.</para> - <para>The syntax for this is slightly different:</para> + <para>The syntax is slightly different:</para> - <programlisting><![CDATA[<!DOCTYPE html SYSTEM "/path/to/file.dtd">]]></programlisting> + <programlisting><sgmltag class="starttag">!DOCTYPE html SYSTEM "/path/to/file.dtd"</sgmltag></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> + <acronym>XML</acronym> processor should locate the + <acronym>DTD</acronym> in a system specific fashion. This + typically (but not always) means the <acronym>DTD</acronym> + will be provided as a filename.</para> + + <para>Using <acronym>FPI</acronym>s is preferred for reasons of + portability. If the <literal>SYSTEM</literal> identifier is + used, then the <acronym>DTD</acronym> must be provided and + kept in the same location for everyone.</para> </sect2> </sect1> <sect1 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 + <title>Escaping Back to <acronym>XML</acronym></title> + + <para>Some of the underlying <acronym>XML</acronym> syntax can be + useful within documents. For example, comments can be included + in the document, and will be ignored by the parser. Comments + are entered using <acronym>XML</acronym> syntax. Other uses for + <acronym>XML</acronym> syntax will be shown later.</para> + + <para><acronym>XML</acronym> sections begin with a + <literal><!</literal> tag and end with a + <literal>></literal>. These sections contain instructions + for the parser rather than elements of the document. Everything + between these tags is <acronym>XML</acronym> syntax. 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> + declaration</link> shown earlier is an example of + <acronym>XML</acronym> syntax included in the document.</para> + </sect1> <sect1 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>Comments are an <acronym>XML</acronym> construct, and are + normally only valid inside a <acronym>DTD</acronym>. However, + as <xref linkend="xml-primer-xml-escape"/> shows, it is possible + to use <acronym>XML</acronym> syntax within the 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> + <title><acronym>XML</acronym> Generic Comment</title> - <programlisting> -<!-- This is inside the comment --> + <programlisting><!-- This is inside the comment --> <!-- This is another comment --> @@ -824,51 +825,40 @@ example.xml:5: element head: validity error : Element head content does not foll of doing multiline comments --> <!-- This is another way of -- - -- doing multiline comments -->]]></programlisting> + -- 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 + <para><acronym>XHTML</acronym> users may be familiar with different + rules for comments. In particular, it is often believed 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> + <para>This is <emphasis>not</emphasis> correct. Many web browsers + have broken <acronym>XHTML</acronym> parsers, and will accept + incorrect input as valid. However, the <acronym>XML</acronym> + parsers used by the Documentation Project are more strict, and + will reject documents with that error.</para> <example> - <title>Erroneous XML Comments</title> + <title>Erroneous <acronym>XML</acronym> Comments</title> - <programlisting> -<!-- This is in the comment -- + <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> + <para>The <acronym>XML</acronym> 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> + <para>That is not valid <acronym>XML</acronym>, and may give + confusing error messages.</para> </example> <sect2> - <title>For You to Do…</title> + <title>To Do…</title> <procedure> <step> @@ -891,103 +881,101 @@ example.xml:5: element head: validity error : Element head content does not foll <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> + content. As an <acronym>XML</acronym> parser processes a + 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> + chunks of content in <acronym>XML</acronym> documents. It is + also the only way to include one marked up file inside another + using <acronym>XML</acronym>.</para> - <para>There are two types of entities which can be used in two - different situations; <emphasis>general entities</emphasis> and + <para>There are two types of entities for two different + situations: <emphasis>general entities</emphasis> and <emphasis>parameter entities</emphasis>.</para> <sect2 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>&<replaceable>entity-name</replaceable>;</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> + <para>General entities are used to assign names to reusable + chunks of text. These entities can only be used in the + document. They cannot be used in an + <acronym>XML</acronym> context.</para> + + <para>To include the text of a general entity in the document, + include + <literal>&<replaceable>entity-name</replaceable>;</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> + + <para>When the version number changes, edit the definition of + the general entity, replacing the value. Then reprocess the + document.</para> + + <para>General entities can also be used to enter characters that + could not otherwise be included in an <acronym>XML</acronym> + document. For example, <literal><</literal> and + <literal>&</literal> cannot normally appear in an + <acronym>XML</acronym> document. The <acronym>XML</acronym> + parser sees the <literal><</literal> symbol as the start of + a tag. Likewise, when the <literal>&</literal> symbol is + seen, the next text is expected to be an entity name.</para> + + <para>These symbols can be included by using two predefined + general entities: <literal>&lt;</literal> and + <literal>&amp;</literal>.</para> + + <para>General entities can only be defined within an + <acronym>XML</acronym> context. Such definitions are usually + 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" + <programlisting><!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> +<!ENTITY current.version "3.0-RELEASE"> +<!ENTITY last.version "2.2.7-RELEASE"> +]></programlisting> + + <para>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, the + square bracket is closed, and then the DOCTYPE declaration + is closed.</para> + + <para>The square brackets are necessary to indicate that the + DTD indicated by the DOCTYPE declaration is being + extended.</para> </example> </sect2> <sect2 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 + <para>Parameter entities, like + <link linkend="xml-primer-general-entities">general + entities</link>, are used to assign names to reusable chunks + of text. But 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>&<replaceable>entity-name</replaceable>;</literal> - to refer to them, use - <literal>%<replaceable>entity-name</replaceable>;</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> + <para>Parameter entity definitons are similar to those for + general entities. However, parameter entries are included + with + <literal>%<replaceable>entity-name</replaceable>;</literal>. + The definition also includes the <literal>%</literal> between + the <literal>ENTITY</literal> keyword and the name of the + entity.</para> + + <para>For a mnemonic, think + <quote><emphasis>P</emphasis>arameter entities use the + <emphasis>P</emphasis>ercent symbol</quote>.</para> <example> <title>Defining Parameter Entities</title> @@ -999,14 +987,12 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY % param.new "%param.some more %param.text"> <!-- %param.new now contains "some more text" --> -</programlisting> +]></programlisting> </example> - - <para>This may not seem particularly useful. It will be.</para> </sect2> <sect2> - <title>For You to Do…</title> + <title>To Do…</title> <procedure> <step> @@ -1018,23 +1004,23 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY version "1.1"> ]> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>An Example XHTML File</title> - </head> +<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> - <!-- You might well have some comments in here as well --> + <!-- There may be some comments in here as well --> - <body> - <p>This is a paragraph containing some text.</p> + <sgmltag class="starttag">body</sgmltag> + <sgmltag class="starttag">p</sgmltag>This is a paragraph containing some text.<sgmltag class="endtag">p</sgmltag> - <p>This paragraph contains some more text.</p> + <sgmltag class="starttag">p</sgmltag>This paragraph contains some more text.<sgmltag class="endtag">p</sgmltag> - <p align="right">This paragraph might be right-justified.</p> + <sgmltag class="starttag">p align="right"</sgmltag>This paragraph might be right-justified.<sgmltag class="endtag">p</sgmltag> - <p>The current version of this document is: &version;</p> - </body> -</html></programlisting> + <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> </step> <step> @@ -1043,40 +1029,40 @@ example.xml:5: element head: validity error : Element head content does not foll </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> + <para>Load <filename>example.xml</filename> into a web + browser. It may have to be copied to + <filename>example.html</filename> before the browser + recognizes it as an <acronym>XHTML</acronym> + document.</para> + + <para>Older browsers with simple parsers may not render this + file as expected. The entity reference + <literal>&version;</literal> may not be replaced by + the version number, or the <acronym>XML</acronym> context + closing <literal>]<</literal> may not be recognized and + instead shown in the output.</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> + <para>The solution is to <emphasis>normalize</emphasis> the + document with an <acronym>XML</acronym> normalizer. The + normalizer reads valid <acronym>XML</acronym> and writes + equally valid <acronym>XML</acronym> which has been + transformed in some way. One way the normalizer + transforms the input is by expanding all the entity + references in the document, replacing the entities with + the text that they represent.</para> + + <para><command>xmllint</command> can be used for this. It + also has an option to drop the initial + <acronym>DTD</acronym> 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> + <para>A normalized copy of the document with entities + expanded is produced in <filename>example.html</filename>, + ready to load into a web browser.</para> </step> </procedure> </sect2> @@ -1085,27 +1071,27 @@ example.xml:5: element head: validity error : Element head content does not foll <sect1 id="xml-primer-include"> <title>Using Entities to Include Files</title> - <para>Entities (both + <para>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 + <link linkend="xml-primer-parameter-entities">parameter</link> + entities are particularly useful for including one file inside another.</para> <sect2 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 + <para>Consider some content for an <acronym>XML</acronym> 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 + <filename>book.xml</filename> 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> + for entities, they are declared with the + <literal>SYSTEM</literal> keyword. This directs the + <acronym>XML</acronym> parser to include the contents of the + named file as the value of the entity.</para> <example> <title>Using General Entities to Include Files</title> @@ -1118,13 +1104,13 @@ example.xml:5: element head: validity error : Element head content does not foll <!-- And so forth --> ]> -<html xmlns="http://www.w3.org/1999/xhtml"> +<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> <!-- Use the entities to load in the chapters --> &chapter.1; &chapter.2; &chapter.3; -</html></programlisting> +<sgmltag class="endtag">html</sgmltag></programlisting> </example> <warning> @@ -1133,45 +1119,43 @@ example.xml:5: element head: validity error : Element head content does not foll (<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> + 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>Parameter entities can only be used inside an + <acronym>XML</acronym> context. Including a file in an + <acronym>XML</acronym> context can be used + to ensure that general entities are reusable.</para> - <para>Suppose that you had many chapters in your document, and - you reused these chapters in two different books, each book + <para>Suppose that there are many chapters in the document, and + these chapters were reused 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>The entities could be listed at the top of each book, but + that 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> + the 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> + <para>Place the entity definitions in a separate file + called <filename>chapters.ent</filename> and + containing this text:</para> - <programlisting><![CDATA[<!ENTITY chapter.1 SYSTEM "chapter1.xml"> -<!ENTITY chapter.2 SYSTEM "chapter2.xml"> -<!ENTITY chapter.3 SYSTEM "chapter3.xml">]]></programlisting> + <programlisting><!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 + <para>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 @@ -1186,16 +1170,16 @@ example.xml:5: element head: validity error : Element head content does not foll %chapters; ]> -<html xmlns="http://www.w3.org/1999/xhtml"> +<sgmltag class="starttag">html xmlns="http://www.w3.org/1999/xhtml"</sgmltag> &chapter.1; &chapter.2; &chapter.3; -</html></programlisting> +<sgmltag class="endtag">html</sgmltag></programlisting> </example> </sect2> <sect2> - <title>For You to Do…</title> + <title>To Do…</title> <sect3> <title>Use General Entities to Include Files</title> @@ -1206,10 +1190,9 @@ example.xml:5: element head: validity error : Element head content does not foll <filename>para2.xml</filename>, and <filename>para3.xml</filename>.</para> - <para>Put content similar to the following in each - file:</para> + <para>Put content like this in each file:</para> - <programlisting><![CDATA[<p>This is the first paragraph.</p>]]></programlisting> + <programlisting><sgmltag class="starttag">p</sgmltag>This is the first paragraph.<sgmltag class="endtag">p</sgmltag></programlisting> </step> <step> @@ -1224,19 +1207,19 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY para3 SYSTEM "para3.xml"> ]> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>An Example XHTML File</title> - </head> +<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> - <body> - <p>The current version of this document is: &version;</p> + <sgmltag class="starttag">body</sgmltag> + <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag> &para1; &para2; &para3; - </body> -</html></programlisting> + <sgmltag class="endtag">body</sgmltag> +<sgmltag class="endtag">html</sgmltag></programlisting> </step> <step> @@ -1247,8 +1230,8 @@ example.xml:5: element head: validity error : Element head content does not foll </step> <step> - <para>Load <filename>example.html</filename> into your web - browser, and confirm that the + <para>Load <filename>example.html</filename> into the web + browser and confirm that the <filename>para<replaceable>n</replaceable>.xml</filename> files have been included in <filename>example.html</filename>.</para> @@ -1260,7 +1243,8 @@ example.xml:5: element head: validity error : Element head content does not foll <title>Use Parameter Entities to Include Files</title> <note> - <para>You must have taken the previous steps first.</para> + <para>The previous steps must have completed before this + step.</para> </note> <procedure> @@ -1273,30 +1257,30 @@ example.xml:5: element head: validity error : Element head content does not foll <!ENTITY % entities SYSTEM "entities.ent"> %entities; ]> -<html xmlns="http://www.w3.org/1999/xhtml"> - <head> - <title>An Example XHTML File</title> - </head> +<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> - <body> - <p>The current version of this document is: &version;</p> + <sgmltag class="starttag">body</sgmltag> + <sgmltag class="starttag">p</sgmltag>The current version of this document is: &version;<sgmltag class="endtag">p</sgmltag> &para1; &para2; &para3; - </body> -</html></programlisting> + <sgmltag class="endtag">body</sgmltag> +<sgmltag class="endtag">html</sgmltag></programlisting> </step> <step> - <para>Create a new file, - <filename>entities.ent</filename>, with this + <para>Create a new file called + <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> + <programlisting><!ENTITY version "1.1"> +<!ENTITY para1 SYSTEM "para1.xml"> +<!ENTITY para2 SYSTEM "para2.xml"> +<!ENTITY para3 SYSTEM "para3.xml"></programlisting> </step> <step> @@ -1307,8 +1291,8 @@ example.xml:5: element head: validity error : Element head content does not foll </step> <step> - <para>Load <filename>example.html</filename> into your web - browser, and confirm that the + <para>Load <filename>example.html</filename> into the web + browser and confirm that the <filename>para<replaceable>n</replaceable>.xml</filename> files have been included in <filename>example.html</filename>.</para> @@ -1321,114 +1305,106 @@ example.xml:5: element head: validity error : Element head content does not foll <sect1 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> + <para><acronym>XML</acronym> provides a mechanism to indicate that + particular pieces of the document should be processed in a + special way. These are called + <quote>marked sections</quote>.</para> <example> - <title>Structure of A Marked Section</title> + <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 + <para>As expected of an <acronym>XML</acronym> construct, a marked section starts with <literal><!</literal>.</para> - <para>The first square bracket begins to delimit the marked - section.</para> + <para>The first square bracket begins the marked section.</para> <para><replaceable>KEYWORD</replaceable> describes how this marked - section should be processed by the parser.</para> + section is to be processed by the parser.</para> - <para>The second square bracket indicates that the content of the - marked section starts here.</para> + <para>The second square bracket indicates the start of the + marked section's content.</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> + <acronym>XML</acronym> context with + <literal>></literal>.</para> - <sect2> + <sect2 id="xml-primer-marked-section-keywords"> <title>Marked Section Keywords</title> - <sect3> + <sect3 id="xml-primer-cdata"> <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>When an <acronym>XML</acronym> parser is processing a + document, it keeps track of 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 describes the + content the parser is expecting to see and what it will do + with that content.</para> - <para>The content model you will probably find most - useful is <literal>CDATA</literal>.</para> + <para>The <literal>CDATA</literal> content model is one of the + most useful.</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 + <para><literal>CDATA</literal> is for + <quote>Character Data</quote>. When the parser is in this + content model, it expects to see only characters. 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> + <para>When using <literal>CDATA</literal> in examples of + text marked up in <acronym>XML</acronym>, remember that + the content of <literal>CDATA</literal> is not validated. + The included text must be check with other means. For + example, the content could be written in another document, + validated, and then pasted into the + <literal>CDATA</literal> section.</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> + <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> + 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> + +<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 + 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> + + <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> + + <sgmltag class="starttag">p</sgmltag>This is the end of the example.<sgmltag class="endtag">p</sgmltag>]]><sgmltag class="endtag">programlisting</sgmltag></programlisting> </example> </sect3> - <sect3> + <sect3 id="xml-primer-include-ignore"> <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 + <para>When the keyword is <literal>INCLUDE</literal>, then the + contents of the marked section will be processed. When the + keyword is <literal>IGNORE</literal>, the marked section is ignored and will not be processed. It will not appear in the output.</para> @@ -1445,50 +1421,47 @@ example.xml:5: element head: validity error : Element head content does not foll ]]></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>By itself, this is not too useful. Text to be + removed from the document could be cut out, or wrapped + in comments.</para> - <para>It becomes more useful when you realize you can use + <para>It becomes more useful when controlled by <link linkend="xml-primer-parameter-entities">parameter - entities</link> to control this, yet this usage is limited + entities</link>, 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>For example, suppose that documentation was produced in + a hard-copy version and an electronic version. Some extra + text is desired in the electronic version 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 + <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> + 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 the first definition + always takes effect. So the inclusion of the chapter is + controlled with the corresponding parameter entity. Set to + <literal>INCLUDE</literal>, the first general entity + definition will be read and the second one will be ignored. + Set 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 + <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"> ]]> -<!ENTITY chap.preface ""> -</programlisting> +<!ENTITY chap.preface ""></programlisting> <para>When producing the hard-copy version, change the parameter entity's definition to:</para> @@ -1499,12 +1472,12 @@ example.xml:5: element head: validity error : Element head content does not foll </sect2> <sect2> - <title>For You to Do…</title> + <title>To Do…</title> <procedure> <step> - <para>Modify the <filename>entities.ent</filename> file to contain - the following:</para> + <para>Modify <filename>entities.ent</filename> to + contain the following:</para> <programlisting><!ENTITY version "1.1"> <!ENTITY % conditional.text "IGNORE"> @@ -1520,13 +1493,15 @@ example.xml:5: element head: validity error : Element head content does not foll </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> + <para>Normalize <filename>example.xml</filename> + and notice that the conditional text is not present in the + output document. Set the parameter entity + guard to <literal>INCLUDE</literal> and regenerate the + normalized document and the text will appear again. + This method makes sense if there are more + conditional chunks depending on the same condition. For + example, to control generating printed or online + text.</para> </step> </procedure> </sect2> @@ -1535,10 +1510,11 @@ example.xml:5: element head: validity error : Element head content does not foll <sect1 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 + <para>That is the conclusion of this <acronym>XML</acronym> + primer. For reasons of space and complexity, several things + have not been covered in depth (or at all). However, the + previous sections cover enough <acronym>XML</acronym> to + introduce the organization of the <acronym>FDP</acronym> documentation.</para> </sect1> </chapter> diff --git a/en_US.ISO8859-1/books/handbook/boot/chapter.xml b/en_US.ISO8859-1/books/handbook/boot/chapter.xml index c13bec3bbb..1af00bc7cc 100644 --- a/en_US.ISO8859-1/books/handbook/boot/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/boot/chapter.xml @@ -65,20 +65,18 @@ operating system, and the operating system programs are on the disk, how is the operating system started?</para> - <para>This problem parallels one in the book <citetitle>The - Adventures of Baron Munchausen</citetitle>. A character had - fallen part way down a manhole, and pulled himself out by - grabbing his bootstraps, and lifting. In the early days of - computing the term <firstterm>bootstrap</firstterm> was applied - to the mechanism used to load the operating system, which has - become shortened to <quote>booting</quote>.</para> + <para>This problem parallels one in the book + <citetitle>The Adventures of Baron Munchausen</citetitle>. A + character had fallen part way down a manhole, and pulled himself + out by grabbing his bootstraps, and lifting. In the early days + of computing the term <firstterm>bootstrap</firstterm> was + applied to the mechanism used to load the operating system, + which has become shortened to <quote>booting</quote>.</para> <indexterm><primary><acronym>BIOS</acronym></primary></indexterm> - <indexterm> - <primary>Basic Input/Output System</primary> - <see><acronym>BIOS</acronym></see> - </indexterm> + <indexterm><primary>Basic Input/Output + System</primary><see><acronym>BIOS</acronym></see></indexterm> <para>On x86 hardware the Basic Input/Output System (<acronym>BIOS</acronym>) is responsible for loading the @@ -340,7 +338,7 @@ boot:</screen> <para>Finally, by default, the loader issues a 10 second wait for key presses, and boots the kernel if it is not - interrupted. If interrupted, the user is presented with a + interrupted. If interrupted, the user is presented with a prompt which understands the command set, where the user may adjust variables, unload all modules, load modules, and then finally boot or reboot.</para> @@ -504,10 +502,10 @@ boot:</screen> <para>Here are some practical examples of loader usage:</para> <itemizedlist> - <indexterm><primary>single-user mode</primary></indexterm> - <listitem> - <para>To boot the usual kernel in single-user mode:</para> + <para>To boot the usual kernel in single-user + mode<indexterm><primary>single-user + mode</primary></indexterm>:</para> <screen><userinput>boot -s</userinput></screen> </listitem> @@ -516,18 +514,16 @@ boot:</screen> <para>To unload the usual kernel and modules, and then load the previous or another kernel:</para> - <indexterm> - <primary><filename>kernel.old</filename></primary> - </indexterm> - <screen><userinput>unload</userinput> <userinput>load <replaceable>kernel.old</replaceable></userinput></screen> <para>Use <filename>kernel.GENERIC</filename> to refer to the default kernel that comes with an installation, or - <filename>kernel.old</filename> to refer to the - previously installed kernel before a system upgrade or - before configuring a custom kernel.</para> + <filename>kernel.old</filename><indexterm> + <primary><filename>kernel.old</filename></primary></indexterm> + to refer to the previously installed kernel before a + system upgrade or before configuring a custom + kernel.</para> <note> <para>Use the following to load the usual modules with @@ -793,6 +789,7 @@ bitmap_name="<replaceable>/boot/splash.bin</replaceable>"</programlisting> <para> </para> </sect2> --> + </sect1> <sect1 id="device-hints"> 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 4be1c5afae..03aa4ce849 100644 --- a/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/cutting-edge/chapter.xml @@ -1288,9 +1288,9 @@ Fetching 133 new ports or files... done.</screen> </listitem> <listitem> - <para>A quick way of getting bug fixes. Any given commit is - just as likely to introduce new bugs as to fix existing - ones.</para> + <para>A quick way of getting bug fixes. Any given commit + is just as likely to introduce new bugs as to fix + existing ones.</para> </listitem> <listitem> @@ -1333,50 +1333,37 @@ Fetching 133 new ports or files... done.</screen> one of the following methods:</para> <orderedlist> - <indexterm> - <primary>Subversion</primary> - </indexterm> - <indexterm> - <primary><command>cron</command></primary> - </indexterm> - <indexterm> - <primary>-CURRENT</primary> - <secondary>Syncing with - <application>Subversion</application> - </secondary> - </indexterm> - <indexterm> - <primary>-CURRENT</primary> - <secondary>Syncing with - <application>CTM</application> - </secondary> - </indexterm> - <listitem> - <para>Use <link linkend="svn">svn</link> to check out - the desired development or release 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 + <para>Use <link + linkend="svn">svn</link><indexterm> + <primary>Subversion</primary> + </indexterm> + <indexterm> + <primary>-CURRENT</primary> + <secondary>Syncing with + <application>Subversion</application></secondary> + </indexterm> + to check out the desired development or release + 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 sites</link>. Due to the size of the repository, it is recommended that only desired subtrees be checked out.</para> </listitem> <listitem> - <indexterm> - <primary>-CURRENT</primary> - <secondary>Syncing with CTM</secondary> - </indexterm> - <para>Use the <application><link - linkend="ctm">CTM</link></application> facility. - If you have bad connectivity such as high price - connections or only email access, + linkend="ctm">CTM</link></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>. + is not as reliable as <application> + <link linkend="svn">Subversion</link></application>. For this reason, <application><link linkend="svn">Subversion</link></application> is the recommended method for any system with @@ -1393,11 +1380,11 @@ Fetching 133 new ports or files... done.</screen> compile just a subset is almost guaranteed to cause problems.</para> - <indexterm> - <primary>-CURRENT</primary> - <secondary>compiling</secondary> - </indexterm> - <para>Before compiling &os.current;, read + <para>Before compiling + &os.current;<indexterm> + <primary>-CURRENT</primary> + <secondary>compiling</secondary> + </indexterm>, read <filename>/usr/src/Makefile</filename> very carefully. <link linkend="makeworld">Install a new kernel and rebuild the world</link> the first time through as part @@ -1524,27 +1511,22 @@ Fetching 133 new ports or files... done.</screen> already running a previous release of &os;:</para> <orderedlist> - <indexterm> - <primary>Subversion</primary> - </indexterm> - <indexterm> - <primary><command>cron</command></primary> - </indexterm> - <indexterm> - <primary>-STABLE</primary> - <secondary>syncing with - <application>Subversion</application></secondary> - </indexterm> - <listitem> - <para>Use <link linkend="svn">svn</link> to check out - the desired development or release branch. This is - the recommended method, 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 <literal>stable/9</literal> + <para>Use <link linkend="svn">svn</link><indexterm> + <primary>Subversion</primary> + + </indexterm> to check out the desired development or + release branch. This is the recommended method, + 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 + <literal>stable/9</literal><indexterm> + <primary>-STABLE</primary> + <secondary>syncing with + <application>Subversion</application></secondary> + </indexterm> or <literal>releng/9.0</literal>. URL prefixes for <application>Subversion</application> checkout of the base system are shown in <link @@ -1556,29 +1538,25 @@ Fetching 133 new ports or files... done.</screen> </listitem> <listitem> - <indexterm> - <primary>-STABLE</primary> - <secondary>syncing with CTM</secondary> - </indexterm> - <para>Consider using <application><link - linkend="ctm">CTM</link></application> if you do - not have a fast connection to the Internet.</para> + linkend="ctm">CTM</link></application><indexterm> + <primary>-STABLE</primary> + <secondary>syncing with CTM</secondary> + </indexterm> if you do not have a fast connection to + the Internet.</para> </listitem> </orderedlist> </listitem> <listitem> - <indexterm> - <primary>-STABLE</primary> - <secondary>compiling</secondary> - </indexterm> - - <para>Before compiling &os.stable;, read - <filename>/usr/src/Makefile</filename> carefully. <link - linkend="makeworld">Install a new kernel and rebuild - the world</link> the first time through as part of the - upgrading process. Read &a.stable; and + <para>Before compiling &os.stable;<indexterm> + <primary>-STABLE</primary> + <secondary>compiling</secondary> + </indexterm>, read + <filename>/usr/src/Makefile</filename> carefully. + <link linkend="makeworld">Install a new kernel and + rebuild the world</link> the first time through as part + of the upgrading process. Read &a.stable; and <filename>/usr/src/UPDATING</filename> to keep up-to-date on other bootstrapping procedures that sometimes become necessary on the road to the next @@ -1732,12 +1710,12 @@ Fetching 133 new ports or files... done.</screen> help about synchronizing to a newer version.</para> <para>Updating the system from source is a more subtle process - than it might initially seem to be, and the &os; developers have - found it necessary over the years to change the recommended - approach fairly dramatically as new kinds of unavoidable - dependencies come to light. The rest of this section - describes the rationale behind the currently recommended - upgrade sequence.</para> + than it might initially seem to be, and the &os; developers + have found it necessary over the years to change the + recommended approach fairly dramatically as new kinds of + unavoidable dependencies come to light. The rest of this + section describes the rationale behind the currently + recommended upgrade sequence.</para> <para>Any successful update sequence must deal with the following issues:</para> @@ -1871,11 +1849,12 @@ Fetching 133 new ports or files... done.</screen> <para><command>make <maketarget>delete-old</maketarget></command></para> - <para>This target deletes old (obsolete) files. This is important - because sometimes they cause problems if left on the disk, for - example the presence of the old <filename>utmp.h</filename> - causes problems in some ports when the new - <filename>utmpx.h</filename> is installed.</para> + <para>This target deletes old (obsolete) files. This is + important because sometimes they cause problems if left on + the disk, for example the presence of the old + <filename>utmp.h</filename> causes problems in some ports + when the new <filename>utmpx.h</filename> is + installed.</para> </listitem> <listitem> @@ -1886,10 +1865,11 @@ Fetching 133 new ports or files... done.</screen> </listitem> <listitem> - <para><command>make <maketarget>delete-old-libs</maketarget></command></para> + <para><command>make + <maketarget>delete-old-libs</maketarget></command></para> - <para>Remove any obsolete libraries to avoid conflicts with newer - ones. Make sure that all ports have been rebuilt + <para>Remove any obsolete libraries to avoid conflicts with + newer ones. Make sure that all ports have been rebuilt before old libraries are removed.</para> </listitem> </orderedlist> @@ -2660,27 +2640,28 @@ Script done, …</screen> <primary>Deleting obsolete files and directories</primary> </indexterm> - <para>As a part of the &os; development lifecycle, files and their - contents occasionally become obsolete. This may be because - functionality is implemented elsewhere, the version number of - the library has changed, or it was removed from the system - entirely. This includes old files, libraries, and directories, - which should be removed when updating the system. The benefit - is that the system is not cluttered with old files which take up - unnecessary space on the storage and backup media. - Additionally, if the old library has a security or stability - issue, the system should be updated to the newer library to keep - it safe and to prevent crashes caused by the old library. - Files, directories, and libraries which are considered obsolete - are listed in <filename>/usr/src/ObsoleteFiles.inc</filename>. - The following instructions should be used to remove obsolete - files during the system upgrade process.</para> - - <para>After the <command>make - <maketarget>installworld</maketarget></command> - and the subsequent <command>mergemaster</command> have finished - successfully, check for obsolete files and libraries as - follows:</para> + <para>As a part of the &os; development lifecycle, files and + their contents occasionally become obsolete. This may be + because functionality is implemented elsewhere, the version + number of the library has changed, or it was removed from the + system entirely. This includes old files, libraries, and + directories, which should be removed when updating the system. + The benefit is that the system is not cluttered with old files + which take up unnecessary space on the storage and backup + media. Additionally, if the old library has a security or + stability issue, the system should be updated to the newer + library to keep it safe and to prevent crashes caused by the + old library. Files, directories, and libraries which are + considered obsolete are listed in + <filename>/usr/src/ObsoleteFiles.inc</filename>. The + following instructions should be used to remove obsolete files + during the system upgrade process.</para> + + <para>After the + <command>make <maketarget>installworld</maketarget></command> + and the subsequent <command>mergemaster</command> have + finished successfully, check for obsolete files and libraries + as follows:</para> <screen>&prompt.root; <userinput>cd /usr/src</userinput> &prompt.root; <userinput>make check-old</userinput></screen> @@ -2724,9 +2705,9 @@ Script done, …</screen> <title>Warning</title> <para>Deleting obsolete files will break applications that - still depend on those obsolete files. This is especially true - for old libraries. In most cases, the programs, ports, or - libraries that used the old library need to be recompiled + still depend on those obsolete files. This is especially + 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 executed.</para> @@ -2734,28 +2715,29 @@ Script done, …</screen> <para>Utilities for checking shared library dependencies are available from the Ports Collection in - <filename role="package">sysutils/libchk</filename> or <filename + <filename role="package">sysutils/libchk</filename> or + <filename role="package">sysutils/bsdadminscripts</filename>.</para> - <para>Obsolete shared libraries can conflict with newer libraries, - causing messages like these:</para> + <para>Obsolete shared libraries can conflict with newer + libraries, causing messages like these:</para> <screen>/usr/bin/ld: warning: libz.so.4, needed by /usr/local/lib/libtiff.so, may conflict with libz.so.5 /usr/bin/ld: warning: librpcsvc.so.4, needed by /usr/local/lib/libXext.so, may conflict with librpcsvc.so.5</screen> - <para>To solve these problems, determine which port installed the - library:</para> + <para>To solve these problems, determine which port installed + the library:</para> <screen>&prompt.root; <userinput>pkg_info -W /usr/local/lib/libtiff.so</userinput> /usr/local/lib/libtiff.so was installed by package tiff-3.9.4 &prompt.root; <userinput>pkg_info -W /usr/local/lib/libXext.so</userinput> /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 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> + <para>Then deinstall, rebuild and reinstall the port. + <filename role="package">ports-mgmt/portmaster</filename> 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> <screen>&prompt.root; <userinput>make delete-old-libs</userinput></screen> @@ -2818,7 +2800,9 @@ Script done, …</screen> <qandaentry> <question> <para>My compile failed with lots of - signal 11<indexterm><primary>signal 11</primary></indexterm> + signal 11<indexterm> + <primary>signal 11</primary> + </indexterm> (or other signal number) errors. What happened?</para> </question> diff --git a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml index 8af87cf8cc..0b4e63fbb2 100644 --- a/en_US.ISO8859-1/books/handbook/eresources/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/eresources/chapter.xml @@ -398,12 +398,6 @@ </row> <row> - <entry>&a.mozilla.name;</entry> - <entry>Porting <application>Mozilla</application> to - &os;</entry> - </row> - - <row> <entry>&a.multimedia.name;</entry> <entry>Multimedia applications</entry> </row> @@ -450,6 +444,11 @@ </row> <row> + <entry>&a.pkg-fallout.name;</entry> + <entry>Fallout logs from package building</entry> + </row> + + <row> <entry>&a.platforms.name;</entry> <entry>Concerning ports to non &intel; architecture platforms</entry> @@ -1620,6 +1619,18 @@ </varlistentry> <varlistentry> + <term>&a.pkg-fallout.name;</term> + + <listitem> + <para><emphasis>Fallout logs from package building</emphasis></para> + + <para>All packages building failures logs from the package building + clusters</para> + + </listitem> + </varlistentry> + + <varlistentry> <term>&a.platforms.name;</term> <listitem> diff --git a/en_US.ISO8859-1/books/handbook/install/chapter.xml b/en_US.ISO8859-1/books/handbook/install/chapter.xml index 333118b3a0..179ae911c4 100644 --- a/en_US.ISO8859-1/books/handbook/install/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/install/chapter.xml @@ -2292,55 +2292,47 @@ Mounting root from ufs:/dev/md0c firewall</guimenuitem></term> <listitem> - <indexterm> - <primary>FTP</primary> - <secondary>passive mode</secondary> - </indexterm> - - <para>This option instructs &man.sysinstall.8; - to use passive mode for all FTP - operations. - This allows the user to pass through firewalls - that do not allow incoming connections on random TCP ports. + <para>This option instructs &man.sysinstall.8; to use + passive mode<indexterm> + <primary>FTP</primary> + <secondary>passive mode</secondary> + </indexterm> for all FTP operations. This allows the + user to pass through firewalls that do not allow + incoming connections on random TCP ports. </para> </listitem> </varlistentry> <varlistentry> - <term>FTP via a HTTP proxy: <guimenuitem>Install from an FTP server - through a http proxy</guimenuitem></term> + <term>FTP via a HTTP proxy: <guimenuitem>Install from an FTP + server through a http proxy</guimenuitem></term> <listitem> - <indexterm> - <primary>FTP</primary> - <secondary>via a HTTP proxy</secondary> - </indexterm> - - <para>This option instructs &man.sysinstall.8; - to use the HTTP - protocol to connect to a proxy - for all FTP operations. The proxy will translate - the requests and send them to the FTP server. - This allows the user to pass through firewalls - that do not allow FTP, but offer a HTTP - proxy. - In this case, specify the proxy in + <para>This option instructs &man.sysinstall.8; to use the + HTTP protocol to connect to a proxy for all FTP + operations. The proxy will translate the requests and + send them to the FTP server. This allows the user to + pass through firewalls that do not allow FTP, but offer + a HTTP proxy<indexterm> + <primary>FTP</primary> + <secondary>via a HTTP proxy</secondary> + </indexterm>. In this case, specify the proxy in addition to the FTP server.</para> </listitem> </varlistentry> </variablelist> - <para>For a proxy FTP server, give the name of the - server as 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>, 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, specify FTP (or - passive FTP, if the proxy supports it), and the URL + <para>For a proxy FTP server, give the name of the server as + 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>, + 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, + specify FTP (or passive FTP, if the proxy supports it), and + the URL <literal>ftp://foo.example.com:1234/pub/FreeBSD</literal>.</para> <para>Since <filename class="directory">/pub/FreeBSD</filename> diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml index 1645494198..92da225d1a 100644 --- a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml @@ -78,84 +78,81 @@ <itemizedlist> <listitem> - <indexterm><primary>preemptive - multitasking</primary></indexterm> - - <para><emphasis>Preemptive multitasking</emphasis> with - dynamic priority adjustment to ensure smooth and fair - sharing of the computer between applications and users, - even under the heaviest of loads.</para> + <para><emphasis>Preemptive + multitasking</emphasis><indexterm> + <primary>preemptive multitasking</primary> + </indexterm> with dynamic priority adjustment to ensure + smooth and fair sharing of the computer between + applications and users, even under the heaviest of + loads.</para> </listitem> <listitem> - <indexterm><primary>multi-user - facilities</primary></indexterm> - - <para><emphasis>Multi-user facilities</emphasis> which allow - many people to use a &os; system simultaneously for a - variety of things. This means, for example, that system - peripherals such as printers and tape drives are properly - shared between all users on the system or the network and - that individual resource limits can be placed on users or - groups of users, protecting critical system resources from - over-use.</para> + <para><emphasis>Multi-user facilities</emphasis><indexterm> + <primary>multi-user facilities</primary> + </indexterm> which allow many people to use a &os; system + simultaneously for a variety of things. This means, for + example, that system peripherals such as printers and tape + drives are properly shared between all users on the system + or the network and that individual resource limits can be + placed on users or groups of users, protecting critical + system resources from over-use.</para> </listitem> - <listitem> - <indexterm><primary>TCP/IP networking</primary></indexterm> - <para>Strong <emphasis>TCP/IP networking</emphasis> with - support for industry standards such as SCTP, DHCP, NFS, - NIS, PPP, SLIP, IPsec, and IPv6. This means that your - &os; machine can interoperate easily with other systems as - well as act as an enterprise server, providing vital - functions such as NFS (remote file access) and email - services or putting your organization on the Internet with - WWW, FTP, routing and firewall (security) services.</para> + <listitem> + <para>Strong <emphasis>TCP/IP + networking</emphasis><indexterm> + <primary>TCP/IP networking</primary> + </indexterm> with support for industry standards such as + SCTP, DHCP, NFS, NIS, PPP, SLIP, IPsec, and IPv6. This + means that your &os; machine can interoperate easily with + other systems as well as act as an enterprise server, + providing vital functions such as NFS (remote file access) + and email services or putting your organization on the + Internet with WWW, FTP, routing and firewall (security) + services.</para> </listitem> <listitem> - <indexterm><primary>memory protection</primary></indexterm> - - <para><emphasis>Memory protection</emphasis> ensures that - applications (or users) cannot interfere with each other. - One application crashing will not affect others in any - way.</para> + <para><emphasis>Memory protection</emphasis><indexterm> + <primary>memory protection</primary> + </indexterm> ensures that applications (or users) cannot + interfere with each other. One application crashing will + not affect others in any way.</para> </listitem> <listitem> - <indexterm> - <primary>X Window System</primary> - </indexterm> - <para>The industry standard <emphasis>X Window - System</emphasis> (X11R7) provides a graphical user - interface (GUI) for the cost of a common VGA card and - monitor and comes with full sources.</para> - </listitem> - - <listitem> - <indexterm> - <primary>binary compatibility</primary> - <secondary>Linux</secondary> - </indexterm> - <indexterm> - <primary>binary compatibility</primary> - <secondary>SCO</secondary> - </indexterm> - <indexterm> - <primary>binary compatibility</primary> - <secondary>SVR4</secondary> - </indexterm> - <indexterm> - <primary>binary compatibility</primary> - <secondary>BSD/OS</secondary> - </indexterm> - <indexterm> - <primary>binary compatibility</primary> - <secondary>NetBSD</secondary> - </indexterm> - - <para><emphasis>Binary compatibility</emphasis> with many + System</emphasis><indexterm> + <primary>X Window System</primary> + </indexterm> (X11R7) provides a graphical user interface + (GUI) for the cost of a common VGA card and monitor and + comes with full sources.</para> + </listitem> + + <listitem> + <para> + <indexterm> + <primary>binary compatibility</primary> + <secondary>Linux</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>SCO</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>SVR4</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>BSD/OS</secondary> + </indexterm> + <indexterm> + <primary>binary compatibility</primary> + <secondary>NetBSD</secondary> + </indexterm> + <emphasis>Binary compatibility</emphasis> with many programs built for Linux, SCO, SVR4, BSDI and NetBSD.</para> </listitem> @@ -177,35 +174,34 @@ compile.</para> </listitem> <listitem> - <indexterm><primary>virtual memory</primary></indexterm> - - <para>Demand paged <emphasis>virtual memory</emphasis> and - <quote>merged VM/buffer cache</quote> design efficiently - satisfies applications with large appetites for memory - while still maintaining interactive response to other - users.</para> + <para>Demand paged <emphasis>virtual + memory</emphasis><indexterm> + <primary>virtual memory</primary> + </indexterm> and <quote>merged VM/buffer cache</quote> + design efficiently satisfies applications with large + appetites for memory while still maintaining interactive + response to other users.</para> </listitem> <listitem> - <indexterm> - <primary>Symmetric Multi-Processing (SMP)</primary> - </indexterm> - - <para><emphasis>SMP</emphasis> support for machines with - multiple CPUs.</para> + <para><emphasis>SMP</emphasis><indexterm> + <primary>Symmetric Multi-Processing + (SMP)</primary> + </indexterm> support for machines with multiple + CPUs.</para> </listitem> <listitem> - <indexterm> - <primary>compilers</primary> - <secondary>C</secondary> - </indexterm> - <indexterm> - <primary>compilers</primary> - <secondary>C++</secondary> - </indexterm> - - <para>A full complement of <emphasis>C</emphasis> + <para> + <indexterm> + <primary>compilers</primary> + <secondary>C</secondary> + </indexterm> + <indexterm> + <primary>compilers</primary> + <secondary>C++</secondary> + </indexterm> + A full complement of <emphasis>C</emphasis> and <emphasis>C++</emphasis> development tools. Many additional languages for advanced research @@ -214,13 +210,12 @@ </listitem> <listitem> - <indexterm><primary>source code</primary></indexterm> - - <para><emphasis>Source code</emphasis> for the entire system - means you have the greatest degree of control over your - environment. Why be locked into a proprietary solution - at the mercy of your vendor when you can have a truly open - system?</para> + <para><emphasis>Source code</emphasis><indexterm> + <primary>source code</primary> + </indexterm> for the entire system means you have the + greatest degree of control over your environment. Why be + locked into a proprietary solution at the mercy of your + vendor when you can have a truly open system?</para> </listitem> <listitem> @@ -233,21 +228,20 @@ </listitem> </itemizedlist> - <indexterm><primary>4.4BSD-Lite</primary></indexterm> - <indexterm> - <primary>Computer Systems Research Group (CSRG)</primary> - </indexterm> - <indexterm><primary>U.C. Berkeley</primary></indexterm> - <para>&os; is based on the 4.4BSD-Lite release from Computer - Systems Research Group (CSRG) at the University of California - at Berkeley, and carries on the distinguished tradition of BSD - systems development. In addition to the fine work provided by - CSRG, the &os; Project has put in many thousands of hours - in fine tuning the system for maximum performance and - reliability in real-life load situations. As many of the - commercial giants struggle to field PC operating systems with - such features, performance and reliability, &os; can offer - them <emphasis>now</emphasis>!</para> + <para>&os; is based on the 4.4BSD-Lite<indexterm> + <primary>4.4BSD-Lite</primary> + </indexterm> release from Computer + Systems Research Group (CSRG)<indexterm> + <primary>Computer Systems Research Group (CSRG)</primary> + </indexterm> at the University of California at Berkeley, and + carries on the distinguished tradition of BSD systems + development. In addition to the fine work provided by CSRG, + the &os; Project has put in many thousands of hours in + fine tuning the system for maximum performance and reliability + in real-life load situations. As many of the commercial + giants struggle to field PC operating systems with such + features, performance and reliability, &os; can offer them + <emphasis>now</emphasis>!</para> <para>The applications to which &os; can be put are truly limited only by your own imagination. From software @@ -278,16 +272,16 @@ <itemizedlist> <listitem> - <indexterm><primary>FTP servers</primary></indexterm> - - <para>FTP servers</para> + <para>FTP servers<indexterm> + <primary>FTP servers</primary> + </indexterm></para> </listitem> <listitem> - <indexterm><primary>web servers</primary></indexterm> - - <para>World Wide Web servers (standard or secure - [SSL])</para> + <para>World Wide Web servers<indexterm> + <primary>web servers</primary> + </indexterm> + (standard or secure [SSL])</para> </listitem> <listitem> @@ -295,30 +289,32 @@ </listitem> <listitem> - <indexterm><primary>firewall</primary></indexterm> - - <indexterm><primary>NAT</primary></indexterm> - - <para>Firewalls and NAT (<quote>IP masquerading</quote>) - gateways</para> + <para>Firewalls<indexterm> + <primary>firewall</primary> + </indexterm> + and NAT<indexterm> + <primary>NAT</primary> + </indexterm> + (<quote>IP masquerading</quote>) gateways</para> </listitem> <listitem> - <indexterm> - <primary>electronic mail</primary> - <see>email</see> - </indexterm> - <indexterm> - <primary>email</primary> - </indexterm> - - <para>Electronic Mail servers</para> + <para> + <indexterm> + <primary>electronic mail</primary> + <see>email</see> + </indexterm> + <indexterm> + <primary>email</primary> + </indexterm> + Electronic Mail servers</para> </listitem> <listitem> - <indexterm><primary>USENET</primary></indexterm> - - <para>USENET News or Bulletin Board Systems</para> + <para>USENET<indexterm> + <primary>USENET</primary> + </indexterm> + News or Bulletin Board Systems</para> </listitem> <listitem> @@ -356,27 +352,27 @@ </listitem> <listitem> - <indexterm><primary>router</primary></indexterm> - - <indexterm><primary>DNS Server</primary></indexterm> - - <para><emphasis>Networking:</emphasis> Need a new router? - A name server (DNS)? A firewall to keep people out of your + <para><emphasis>Networking:</emphasis> Need a new + router?<indexterm> + <primary>router</primary> + </indexterm> A name server (DNS)?<indexterm> + <primary>DNS Server</primary> + </indexterm> A firewall to keep people out of your internal network? &os; can easily turn that unused 386 or 486 PC sitting in the corner into an advanced router with sophisticated packet-filtering capabilities.</para> </listitem> <listitem> - <indexterm> - <primary>X Window System</primary> - </indexterm> - <indexterm> - <primary>X Window System</primary> - <secondary>Accelerated-X</secondary> - </indexterm> - - <para><emphasis>X Window workstation:</emphasis> &os; is a + <para> + <indexterm> + <primary>X Window System</primary> + </indexterm> + <indexterm> + <primary>X Window System</primary> + <secondary>Accelerated-X</secondary> + </indexterm> + <emphasis>X Window workstation:</emphasis> &os; is a fine choice for an inexpensive X terminal solution, using the freely available X11 server. Unlike an X terminal, &os; allows many applications to @@ -387,13 +383,13 @@ </listitem> <listitem> - <indexterm><primary>GNU Compiler - Collection</primary></indexterm> - <para><emphasis>Software Development:</emphasis> The basic &os; system comes with a full complement of development - tools including the renowned GNU C/C++ compiler and - debugger.</para> + tools including the renowned GNU + C/C++<indexterm> + <primary>GNU Compiler Collection</primary> + </indexterm> + compiler and debugger.</para> </listitem> </itemizedlist> @@ -416,15 +412,15 @@ <itemizedlist> <listitem> - <indexterm><primary>Apple</primary></indexterm> <para><ulink - url="http://www.apple.com/">Apple</ulink></para> + url="http://www.apple.com/">Apple</ulink><indexterm> + <primary>Apple</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Cisco</primary></indexterm> <para><ulink - url="http://www.cisco.com/">Cisco</ulink></para> + url="http://www.cisco.com/">Cisco</ulink><indexterm> + <primary>Cisco</primary></indexterm></para> </listitem> <listitem> @@ -433,9 +429,9 @@ </listitem> <listitem> - <indexterm><primary>NetApp</primary></indexterm> <para><ulink - url="http://www.netapp.com/">NetApp</ulink></para> + url="http://www.netapp.com/">NetApp</ulink><indexterm> + <primary>NetApp</primary></indexterm></para> </listitem> </itemizedlist> @@ -444,81 +440,78 @@ <itemizedlist> <listitem> - <indexterm><primary>Yahoo!</primary></indexterm> <para><ulink - url="http://www.yahoo.com/">Yahoo!</ulink></para> + url="http://www.yahoo.com/">Yahoo!</ulink><indexterm> + <primary>Yahoo!</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Yandex</primary></indexterm> <para><ulink - url="http://www.yandex.ru/">Yandex</ulink></para> + url="http://www.yandex.ru/">Yandex</ulink><indexterm> + <primary>Yandex</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Apache</primary></indexterm> <para><ulink - url="http://www.apache.org/">Apache</ulink></para> + url="http://www.apache.org/">Apache</ulink><indexterm> + <primary>Apache</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Rambler</primary></indexterm> <para><ulink - url="http://www.rambler.ru/">Rambler</ulink></para> + url="http://www.rambler.ru/">Rambler</ulink><indexterm> + <primary>Rambler</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Sina</primary></indexterm> - <para><ulink url="http://www.sina.com/">Sina</ulink></para> + <para><ulink + url="http://www.sina.com/">Sina</ulink><indexterm> + <primary>Sina</primary> + </indexterm></para> </listitem> <listitem> - <indexterm><primary>Pair Networks</primary></indexterm> - - <para><ulink - url="http://www.pair.com/">Pair Networks</ulink></para> + <para><ulink url="http://www.pair.com/">Pair + Networks</ulink><indexterm> + <primary>Pair Networks</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Sony Japan</primary></indexterm> - - <para><ulink - url="http://www.sony.co.jp/">Sony Japan</ulink></para> + <para><ulink url="http://www.sony.co.jp/">Sony + Japan</ulink><indexterm> + <primary>Sony Japan</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Netcraft</primary></indexterm> - <para><ulink - url="http://www.netcraft.com/">Netcraft</ulink></para> + url="http://www.netcraft.com/">Netcraft</ulink><indexterm> + <primary>Netcraft</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>NetEase</primary></indexterm> - <para><ulink - url="http://www.163.com/">NetEase</ulink></para> + url="http://www.163.com/">NetEase</ulink><indexterm> + <primary>NetEase</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>Weathernews</primary></indexterm> - <para><ulink - url="http://www.weathernews.com/">Weathernews</ulink></para> + url="http://www.weathernews.com/">Weathernews</ulink><indexterm> + <primary>Weathernews</primary></indexterm></para> </listitem> <listitem> - <indexterm><primary>TELEHOUSE America</primary></indexterm> - <para><ulink url="http://www.telehouse.com/">TELEHOUSE - America</ulink></para> + America</ulink><indexterm> + <primary>TELEHOUSE America</primary> + </indexterm></para> </listitem> <listitem> - <indexterm><primary>Experts Exchange</primary></indexterm> - <para><ulink url="http://www.experts-exchange.com/">Experts - Exchange</ulink></para> + Exchange</ulink><indexterm> + <primary>Experts Exchange</primary> + </indexterm></para> </listitem> </itemizedlist> @@ -572,11 +565,11 @@ <indexterm><primary>Greenman, David</primary></indexterm> <indexterm><primary>Walnut Creek CDROM</primary></indexterm> <para>The trio thought that the goal remained - worthwhile, even without Bill's support, and so they adopted the - name "&os;" coined by David Greenman. The - initial objectives were set after consulting with the system's - current users and, once it became clear that the project was - on the road to perhaps even becoming a reality, Jordan contacted + worthwhile, even without Bill's support, and so they adopted + the name "&os;" coined by David Greenman. The initial + objectives were set after consulting with the system's current + users and, once it became clear that the project was on the + road to perhaps even becoming a reality, Jordan contacted Walnut Creek CDROM with an eye toward improving &os;'s distribution channels for those many unfortunates without easy access to the Internet. Walnut Creek CDROM not only supported @@ -734,33 +727,33 @@ <term>The SVN repositories<anchor id="development-cvs-repository"/></term> <listitem> - <indexterm> - <primary>CVS</primary> - </indexterm> - - <indexterm> - <primary>CVS Repository</primary> - </indexterm> + <para> + <indexterm> + <primary>CVS</primary> + </indexterm> - <indexterm> - <primary>Concurrent Versions System</primary> - <see>CVS</see> - </indexterm> + <indexterm> + <primary>CVS Repository</primary> + </indexterm> - <indexterm> - <primary>Subversion</primary> - </indexterm> + <indexterm> + <primary>Concurrent Versions System</primary> + <see>CVS</see> + </indexterm> - <indexterm> - <primary>Subversion Repository</primary> - </indexterm> + <indexterm> + <primary>Subversion</primary> + </indexterm> - <indexterm> - <primary>SVN</primary> - <see>Subversion</see> - </indexterm> + <indexterm> + <primary>Subversion Repository</primary> + </indexterm> - <para>For several years, the central source tree for &os; + <indexterm> + <primary>SVN</primary> + <see>Subversion</see> + </indexterm> + For several years, the central source tree for &os; was maintained by <ulink url="http://www.nongnu.org/cvs/">CVS</ulink> (Concurrent Versions System), a freely available source @@ -780,7 +773,7 @@ your source tree</link> section for more information on obtaining the &os; <literal>src/</literal> repository and <link linkend="ports-using">Using the Ports - Collection</link> for details on obtaining the &os; + Collection</link> for details on obtaining the &os; Ports Collection.</para> </listitem> </varlistentry> @@ -790,9 +783,8 @@ id="development-committers"/></term> <listitem> - <indexterm><primary>committers</primary></indexterm> - - <para>The <firstterm>committers</firstterm> + <para>The <firstterm>committers</firstterm><indexterm> + <primary>committers</primary></indexterm> are the people who have <emphasis>write</emphasis> access to the Subversion tree, and are authorized to make modifications to the &os; source (the term @@ -811,19 +803,19 @@ id="development-core"/></term> <listitem> - <indexterm><primary>core team</primary></indexterm> - - <para>The <firstterm>&os; core team</firstterm> - would be equivalent to the board of directors if the - &os; Project were a company. The primary task of - the core team is to make sure the project, as a whole, - is in good shape and is heading in the right directions. - Inviting dedicated and responsible developers to join - our group of committers is one of the functions of the - core team, as is the recruitment of new core team - members as others move on. The current core team was - elected from a pool of committer candidates in July - 2012. Elections are held every 2 years.</para> + <para>The <firstterm>&os; core team</firstterm><indexterm> + <primary>core team</primary> + </indexterm> would be equivalent to the board of + directors if the &os; Project were a company. The + primary task of the core team is to make sure the + project, as a whole, is in good shape and is heading in + the right directions. Inviting dedicated and + responsible developers to join our group of committers + is one of the functions of the core team, as is the + recruitment of new core team members as others move on. + The current core team was elected from a pool of + committer candidates in July 2012. Elections are held + every 2 years.</para> <para>Some core team members also have specific areas of responsibility, meaning that they are committed to @@ -851,8 +843,6 @@ <term>Outside contributors</term> <listitem> - <indexterm><primary>contributors</primary></indexterm> - <para>Last, but definitely not least, the largest group of developers are the users themselves who provide feedback and bug fixes to us on an almost constant basis. The @@ -864,7 +854,8 @@ <para><citetitle><ulink url="&url.articles.contributors;/article.html">The - &os; Contributors List</ulink></citetitle> is a long + &os; Contributors List</ulink></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> @@ -901,18 +892,18 @@ were over &os.numports; ports! The list of ports ranges from http servers, to games, languages, editors, and almost everything in between. The entire Ports Collection requires - approximately &ports.size;. To compile a port, you simply change - to the directory of the program you wish to install, type - <command>make install</command>, and let the system do the - rest. The full original distribution for each port you build - is retrieved dynamically - so you need only enough disk space to build the ports you - want. Almost every port is also provided as a pre-compiled - <quote>package</quote>, which can be installed with a simple - command (<command>pkg_add</command>) by those who do not wish - to compile their own ports from source. More information on - packages and ports can be found in <xref - linkend="ports"/>.</para> + approximately &ports.size;. To compile a port, you simply + change to the directory of the program you wish to install, + type <command>make install</command>, and let the system do + the rest. The full original distribution for each port you + build is retrieved dynamically so you need only enough disk + space to build the ports you want. Almost every port is also + provided as a pre-compiled <quote>package</quote>, which can + be installed with a simple command + (<command>pkg_add</command>) by those who do not wish to + compile their own ports from source. More information on + packages and ports can be found in + <xref linkend="ports"/>.</para> </sect2> <sect2> diff --git a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml index 1fbe10fc99..544c8b7f91 100644 --- a/en_US.ISO8859-1/books/handbook/l10n/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/l10n/chapter.xml @@ -253,10 +253,11 @@ variables in their configuration files:</para> <itemizedlist> - <indexterm><primary>POSIX</primary></indexterm> <listitem> - <para><envar>LANG</envar> for &posix; &man.setlocale.3; - family functions</para> + <para><envar>LANG</envar> for &posix;<indexterm> + <primary>POSIX</primary> + </indexterm> + &man.setlocale.3; family functions</para> </listitem> <listitem> diff --git a/en_US.ISO8859-1/books/handbook/mail/chapter.xml b/en_US.ISO8859-1/books/handbook/mail/chapter.xml index 12ff246e7b..6a5a690e83 100644 --- a/en_US.ISO8859-1/books/handbook/mail/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mail/chapter.xml @@ -1102,10 +1102,9 @@ www.example.org</programlisting> a host, one of these two must be configured:</para> <itemizedlist> - <indexterm><primary>MX record</primary></indexterm> <listitem> <para>Make sure that the lowest-numbered - <acronym>MX</acronym> record in + <acronym>MX</acronym><indexterm><primary>MX record</primary></indexterm> record in <acronym>DNS</acronym> points to the host's static IP address.</para> </listitem> diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml index 5e208e638f..9f10c154fd 100644 --- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml @@ -746,13 +746,28 @@ <entry>svn, <ulink url="http://svn0.us-east.FreeBSD.org/">http</ulink>, <ulink - url="https://svn0.us-east.FreeBSD.org/">https</ulink></entry> + url="https://svn0.us-east.FreeBSD.org/">https</ulink>, rsync</entry> <entry>USA, New Jersey</entry> <entry>SHA1 <literal>06:D1:23:DE:5E:7A:F7:2B:7A:7E:74:95:5F:54:8D:5C:B0:D6:2E:8F</literal></entry> </row> + + <row> + <entry><hostid + role="fqdn">svn0.eu.FreeBSD.org</hostid></entry> + + <entry>svn, <ulink + url="http://svn0.eu.FreeBSD.org/">http</ulink>, + <ulink + url="https://svn0.eu.FreeBSD.org/">https</ulink>, rsync</entry> + + <entry>Europe, UK</entry> + + <entry>SHA1 + <literal>39:B0:53:35:CE:60:C7:BB:00:54:96:96:71:10:94:BB:CE:1C:07:A7</literal></entry> + </row> </tbody> </tgroup> </informaltable> 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 98d96ed097..b938aca64e 100644 --- a/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/network-servers/chapter.xml @@ -185,7 +185,8 @@ <screen>&prompt.root; <userinput>service inetd rcvar</userinput></screen> - <para>can be run to display the current effective setting.</para> + <para>can be run to display the current effective + setting.</para> <para>Additionally, different command-line options can be passed to <application>inetd</application> via the @@ -1332,51 +1333,49 @@ Exports list on foobar: <title>Machine Types</title> <itemizedlist> - <indexterm> - <primary>NIS</primary> - <secondary>master server</secondary> - </indexterm> <listitem> - <para>A <emphasis>NIS master server</emphasis>. This - server, analogous to a &windowsnt; primary domain + <para>A <emphasis>NIS master server</emphasis><indexterm> + <primary>NIS</primary> + <secondary>master server</secondary> + </indexterm>. + This server, analogous to a &windowsnt; primary domain controller, maintains the files used by all of the NIS clients. The <filename>passwd</filename>, <filename>group</filename>, and other various files used by the NIS clients live on the master server.</para> - <note><para>It is possible for one machine to be an NIS - master server for more than one NIS domain. However, - this will not be covered in this introduction, which - assumes a relatively small-scale NIS - environment.</para></note> + <note> + <para>It is possible for one machine to be an NIS master + server for more than one NIS domain. However, this + will not be covered in this introduction, which + assumes a relatively small-scale NIS + environment.</para> + </note> </listitem> <listitem> - <indexterm> - <primary>NIS</primary> - <secondary>slave server</secondary> - </indexterm> - - <para><emphasis>NIS slave servers</emphasis>. Similar to - the &windowsnt; backup domain controllers, NIS slave - servers maintain copies of the NIS master's data files. - NIS slave servers provide the redundancy, which is - needed in important environments. They also help to - balance the load of the master server: NIS Clients - always attach to the NIS server whose response they get - first, and this includes slave-server-replies.</para> + <para><emphasis>NIS slave servers</emphasis><indexterm> + <primary>NIS</primary> + <secondary>slave server</secondary> + </indexterm>. Similar to the &windowsnt; backup domain + controllers, NIS slave servers maintain copies of the + NIS master's data files. NIS slave servers provide the + redundancy, which is needed in important environments. + They also help to balance the load of the master server: + NIS Clients always attach to the NIS server whose + response they get first, and this includes + slave-server-replies.</para> </listitem> <listitem> - <indexterm> - <primary>NIS</primary> - <secondary>client</secondary> - </indexterm> - - <para><emphasis>NIS clients</emphasis>. NIS clients, like - most &windowsnt; workstations, authenticate against the - NIS server (or the &windowsnt; domain controller in the - &windowsnt; workstations case) to log on.</para> + <para><emphasis>NIS clients</emphasis><indexterm> + <primary>NIS</primary> + <secondary>client</secondary> + </indexterm>. + NIS clients, like most &windowsnt; workstations, + authenticate against the NIS server (or the &windowsnt; + domain controller in the &windowsnt; workstations case) + to log on.</para> </listitem> </itemizedlist> </sect3> @@ -1450,10 +1449,11 @@ Exports list on foobar: </tgroup> </informaltable> - <para>If this is the first time a <acronym>NIS</acronym> scheme - is being developed, it should be thoroughly planned ahead of - time. Regardless of network size, several decisions need to - be made as part of the planning process.</para> + <para>If this is the first time a <acronym>NIS</acronym> + scheme is being developed, it should be thoroughly planned + ahead of time. Regardless of network size, several + decisions need to be made as part of the planning + process.</para> <sect4> <title>Choosing a NIS Domain Name</title> @@ -1500,14 +1500,14 @@ Exports list on foobar: for its NIS domain, very often the machine becomes unusable. The lack of user and group information causes most systems to temporarily freeze up. With this in mind - be sure to choose a machine that will not be - prone to being rebooted frequently, or one that might be - used for development. The NIS server should ideally be a - stand alone machine whose sole purpose in life is to be an - NIS server. If the network is not very - heavily used, it is acceptable to put the NIS server on a - machine running other services, however; if - the NIS server becomes unavailable, it will adversely affect + be sure to choose a machine that will not be prone to + being rebooted frequently, or one that might be used for + development. The NIS server should ideally be a stand + alone machine whose sole purpose in life is to be an NIS + server. If the network is not very heavily used, it is + acceptable to put the NIS server on a machine running + other services, however; if the NIS server becomes + unavailable, it will adversely affect <emphasis>all</emphasis> NIS clients.</para> </sect4> </sect3> @@ -1544,8 +1544,8 @@ Exports list on foobar: </indexterm> <para>Setting up a master NIS server can be relatively straight forward, depending on environmental needs. &os; - comes with support for NIS out-of-the-box. It only needs to - be enabled by adding the following lines to + comes with support for NIS out-of-the-box. It only needs + to be enabled by adding the following lines to <filename>/etc/rc.conf</filename>:</para> <procedure> @@ -1604,13 +1604,13 @@ Exports list on foobar: that are kept in the <filename>/var/yp</filename> directory. They are generated from configuration files in the <filename>/etc</filename> directory of the NIS master, - with one exception: <filename>/etc/master.passwd</filename>. - This is for - a good reason, never propagate passwords for + with one exception: + <filename>/etc/master.passwd</filename>. This is for a + good reason, never propagate passwords for <username>root</username> and other administrative accounts to all the servers in the NIS domain. Therefore, - before the the NIS maps are initialized, configure the primary - password files:</para> + before the the NIS maps are initialized, configure the + primary password files:</para> <screen>&prompt.root; <userinput>cp /etc/master.passwd /var/yp/master.passwd</userinput> &prompt.root; <userinput>cd /var/yp</userinput> @@ -1760,10 +1760,10 @@ Don't forget to update map ypservers on ellington.</screen> <para>There should be a directory called <filename>/var/yp/test-domain</filename>. Copies of the - NIS master server's maps should be in this directory. These - files must always be up to date. The - following <filename>/etc/crontab</filename> entries on - the slave servers should do the job:</para> + NIS master server's maps should be in this directory. + These files must always be up to date. The following + <filename>/etc/crontab</filename> entries on the slave + servers should do the job:</para> <programlisting>20 * * * * root /usr/libexec/ypxfr passwd.byname 21 * * * * root /usr/libexec/ypxfr passwd.byuid</programlisting> @@ -1788,25 +1788,25 @@ Don't forget to update map ypservers on ellington.</screen> <title>NIS Clients</title> <para>An NIS client establishes what is called a binding to a - particular NIS server using the - <command>ypbind</command> daemon. The - <command>ypbind</command> command checks the system's default - domain (as set by the <command>domainname</command> - command), and begins broadcasting RPC requests on the local - network. These requests specify the name of the domain for - which <command>ypbind</command> is attempting to establish a + particular NIS server using the <command>ypbind</command> + daemon. The <command>ypbind</command> command checks the + system's default domain (as set by the + <command>domainname</command> command), and begins + broadcasting RPC requests on the local network. These + requests specify the name of the domain for which + <command>ypbind</command> is attempting to establish a binding. If a server that has been configured to serve the requested domain receives one of the broadcasts, it will - respond to <command>ypbind</command>, which will record the + respond to <command>ypbind</command>, which will record the server's address. If there are several servers available (a master and several slaves, for example), <command>ypbind</command> will use the address of the first one to respond. From that point on, the client system will - direct all of its NIS requests to - that server. <command>ypbind</command> will - occasionally <quote>ping</quote> the server to make sure it - is still up and running. If it fails to receive a reply to - one of its pings within a reasonable amount of time, + direct all of its NIS requests to that server. + <command>ypbind</command> will occasionally + <quote>ping</quote> the server to make sure it is still up + and running. If it fails to receive a reply to one of its + pings within a reasonable amount of time, <command>ypbind</command> will mark the domain as unbound and begin broadcasting again in the hopes of locating another server.</para> @@ -1815,9 +1815,10 @@ Don't forget to update map ypservers on ellington.</screen> <title>Setting Up a NIS Client</title> <indexterm> - <primary>NIS</primary> <secondary>client - configuration</secondary> - </indexterm> <para>Setting up a FreeBSD machine to be a NIS + <primary>NIS</primary> + <secondary>client configuration</secondary> + </indexterm> + <para>Setting up a FreeBSD machine to be a NIS client is fairly straightforward.</para> <procedure> @@ -1853,8 +1854,8 @@ nis_client_enable="YES"</programlisting> </note> <note> - <para>Keep in mind that at least one local account (i.e. - not imported via NIS) must exist in + <para>Keep in mind that at least one local account + (i.e. not imported via NIS) must exist in <filename>/etc/master.passwd</filename> and this account should also be a member of the group <groupname>wheel</groupname>. If there is something @@ -2160,12 +2161,12 @@ basie&prompt.root;</screen> <para>An attempt to implement these restrictions by separately blocking each user, would require the addition of the <literal>-<replaceable>user</replaceable></literal> line to - each system's <filename>passwd</filename>. One line for each user - who is not allowed to login onto that system. Forgetting just one - entry could cause significant trouble. It may be feasible to - do this correctly during the initial setup; however, eventually - someone will forget to add these lines - for new users.</para> + each system's <filename>passwd</filename>. One line for each + user who is not allowed to login onto that system. Forgetting + just one entry could cause significant trouble. It may be + feasible to do this correctly during the initial setup; + however, eventually someone will forget to add these lines for + new users.</para> <para>Handling this situation with netgroups offers several advantages. Each user need not be handled separately; they @@ -2322,11 +2323,11 @@ ellington&prompt.user; <userinput>ypcat -k netgroup.byuser</userinput></screen> </warning> <para>After this change, the NIS map will only need modification - when a new employee joins the IT department. A similar approach - for the less important servers may be used by replacing - the old <literal>+:::::::::</literal> in their local version - of <filename>/etc/master.passwd</filename> with something like - this:</para> + when a new employee joins the IT department. A similar + approach for the less important servers may be used by + replacing the old <literal>+:::::::::</literal> in their local + version of <filename>/etc/master.passwd</filename> with + something like this:</para> <programlisting>+@IT_EMP::::::::: +@IT_APP::::::::: @@ -2368,9 +2369,9 @@ SMALLSRV IT_EMP IT_APP ITINTERN USERBOX IT_EMP ITINTERN USERS</programlisting> <para>This method of defining login restrictions works - reasonably well when it is possible to define groups of machines - with identical restrictions. Unfortunately, this is the - exception and not the rule. Most of the time, the ability + reasonably well when it is possible to define groups of + machines with identical restrictions. Unfortunately, this is + the exception and not the rule. Most of the time, the ability to define login restrictions on a per-machine basis is required.</para> @@ -2437,11 +2438,11 @@ TWO (,hotel,test-domain) will automatically have access to the boxes.</para> <para>One last word of caution: It may not always be advisable - to use machine-based netgroups. When deploying a couple - of dozen or even hundreds of identical machines for student - labs, role-based netgroups instead of - machine-based netgroups may be used to keep the size of the NIS - map within reasonable limits.</para> + to use machine-based netgroups. When deploying a couple of + dozen or even hundreds of identical machines for student labs, + role-based netgroups instead of machine-based netgroups may be + used to keep the size of the NIS map within reasonable + limits.</para> </sect2> <sect2> @@ -2454,9 +2455,9 @@ TWO (,hotel,test-domain) <itemizedlist> <listitem> <para>Every time a new user is added to the lab, they - must be added to the master NIS server - and the <acronym>NIS</acronym> maps will need rebuilt. If - this step is omitted, the new user will not be able to login + must be added to the master NIS server and the + <acronym>NIS</acronym> maps will need rebuilt. If this + step is omitted, the new user will not be able to login anywhere except on the NIS master. For example, if we needed to add a new user <username>jsmith</username> to the lab, we would:</para> @@ -2496,22 +2497,22 @@ TWO (,hotel,test-domain) <sect2> <title>NIS v1 Compatibility</title> - <para>&os;'s <application>ypserv</application> has some - support for serving NIS v1 clients. &os;'s NIS - implementation only uses the NIS v2 protocol; however, other - implementations include support for the v1 protocol for - backwards compatibility with older systems. The + <para>&os;'s <application>ypserv</application> has some support + for serving NIS v1 clients. &os;'s NIS implementation only + uses the NIS v2 protocol; however, other implementations + include support for the v1 protocol for backwards + compatibility with older systems. The <application>ypbind</application> daemons supplied with these - systems will attempt to establish a binding to an NIS v1 server - even though they may never actually need it (and they may - persist in broadcasting in search of one even after they + systems will attempt to establish a binding to an NIS v1 + server even though they may never actually need it (and they + may persist in broadcasting in search of one even after they receive a response from a v2 server). Note that while support for normal client calls is provided, this version of <application>ypserv</application> does not handle v1 map - transfer requests. Additionally, it cannot be used as a master - or slave in conjunction with older NIS servers that only - support the v1 protocol. Fortunately, there probably are not - any such servers still in use today.</para> + transfer requests. Additionally, it cannot be used as a + master or slave in conjunction with older NIS servers that + only support the v1 protocol. Fortunately, there probably are + not any such servers still in use today.</para> </sect2> <sect2 id="network-nis-server-is-client"> @@ -2624,20 +2625,20 @@ nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</ <para><acronym>LDAP</acronym>, the Lightweight Directory Access Protocol, is an application layer protocol used to access, modify, and authenticate (bind) using a distributed directory - information service. Think of it as a phone or record book which - stores several levels of hierarchical, homogeneous information. - It is often used in networks where users often need access to - several levels of internal information utilizing a single - account. For example, email authentication, pulling employee - contact information, and internal website authentication might - all make use of a single user in the <acronym>LDAP</acronym> - server's record base.</para> - - <para>This section will not provide a history or the implementation - details of the protocol. These sections were authored to get an - <acronym>LDAP</acronym> server and/or client configured both - quickly and securely; however, any information base requires - planning and this is no exception.</para> + information service. Think of it as a phone or record book + which stores several levels of hierarchical, homogeneous + information. It is often used in networks where users often + need access to several levels of internal information utilizing + a single account. For example, email authentication, pulling + employee contact information, and internal website + authentication might all make use of a single user in the + <acronym>LDAP</acronym> server's record base.</para> + + <para>This section will not provide a history or the + implementation details of the protocol. These sections were + authored to get an <acronym>LDAP</acronym> server and/or client + configured both quickly and securely; however, any information + base requires planning and this is no exception.</para> <para>Planning should include what type of information will be stored, what that information will be used for, whom should @@ -2647,25 +2648,25 @@ nis_client_flags="-S <replaceable>NIS domain</replaceable>,<replaceable>server</ <sect2> <title><acronym>LDAP</acronym> Terminology and Structure</title> - <para>Before continuing, several parts of <acronym>LDAP</acronym> - must be explained to prevent confusion. And confusion with - this configuration is relatively simple. To begin, all - directory entries consist of a group of - <emphasis>attributes</emphasis>. Each of these attribute sets - contain a name, a unique identifier known as a - <acronym>DN</acronym> or distinguished name normally built from - several other attributes such as the <acronym>RDN</acronym>. - The <acronym>RDN</acronym> or relative distinguished name, is - a more common name for the attribute. Like directories have - absolute and relative paths, consider a <acronym>DN</acronym> - as an absolute path and the <acronym>RDN</acronym> as the - relative path.</para> + <para>Before continuing, several parts of + <acronym>LDAP</acronym> must be explained to prevent + confusion. And confusion with this configuration is + relatively simple. To begin, all directory entries consist of + a group of <emphasis>attributes</emphasis>. Each of these + attribute sets contain a name, a unique identifier known as a + <acronym>DN</acronym> or distinguished name normally built + from several other attributes such as the + <acronym>RDN</acronym>. The <acronym>RDN</acronym> or + relative distinguished name, is a more common name for the + attribute. Like directories have absolute and relative paths, + consider a <acronym>DN</acronym> as an absolute path and the + <acronym>RDN</acronym> as the relative path.</para> <para>As an example, an entry might look like the - following:</para> + following:</para> <screen>&prompt.user; ldapsearch -xb "uid=trhodes,ou=users,o=example.com"</screen> - + <programlisting># extended LDIF # # LDAPv3 @@ -2690,11 +2691,11 @@ result: 0 Success <para>In this example, it is very obvious what the various attributes are; however, the <acronym>cn</acronym> attribute - should be noticed. This is the <acronym>RDN</acronym> discussed - previously. In addition, there is a unique user id provided - here. It is common practice to have specific uid or uuids for - entries to ease in any future migration.</para> - </sect2> + should be noticed. This is the <acronym>RDN</acronym> + discussed previously. In addition, there is a unique user id + provided here. It is common practice to have specific uid or + uuids for entries to ease in any future migration.</para> + </sect2> <sect2> <title>Configuring an <acronym>LDAP</acronym> Server</title> @@ -2713,7 +2714,7 @@ result: 0 Success needed.</para> <para>A few directories will be required from this point on, - at minimal, a data directory and a directory to store the + at minimal, a data directory and a directory to store the certificates in. Create them both with the following commands:</para> @@ -2724,7 +2725,7 @@ result: 0 Success <para>Copy over the database configuration file:</para> <screen>&prompt.root; <userinput>cp /usr/local/etc/openldap/DB_CONFIG.example /var/db/openldap-data/DB_CONFIG</userinput></screen> - + <para>The next phase is to configure the <acronym>SSL</acronym> certificates. While creating certificates is discussed in the <link linkend="openssl">OpenSSL</link> section in this @@ -2736,9 +2737,10 @@ result: 0 Success <para>The following commands must be executed in the <filename class="directory"> /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 following commands.</para> + 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 following + commands.</para> <screen>&prompt.root; <userinput>openssl req -days 365 -nodes -new -x509 -keyout ca.key -out ../ca.crt</userinput></screen> @@ -2752,7 +2754,7 @@ result: 0 Success <acronym>CA</acronym> for certificate authority.</para> <para>The next task is to create a certificate signing request - and a private key. To do this, issue the following + and a private key. To do this, issue the following commands:</para> <screen>&prompt.root; <userinput>openssl req -days 365 -nodes -new -keyout server.key -out server.csr</userinput></screen> @@ -2770,13 +2772,13 @@ result: 0 Success <screen>&prompt.root; <userinput>openssl x509 -req -days 3650 -in client.csr -out ../client.crt -CA ../ca.crt -CAkey ca.key</userinput></screen> - <para>Remember, again, to respect the common name attribute. This - is a common cause for confusion during the first attempt to - configure <acronym>LDAP</acronym>. In addition, ensure that - a total of eight (8) new files have been generated through - the proceeding commands. If so, the next step is to edit - <filename>/usr/local/etc/openldap/slapd.conf</filename> and add - the following options:</para> + <para>Remember, again, to respect the common name attribute. + This is a common cause for confusion during the first attempt + to configure <acronym>LDAP</acronym>. In addition, ensure + that a total of eight (8) new files have been generated + through the proceeding commands. If so, the next step is to + edit <filename>/usr/local/etc/openldap/slapd.conf</filename> + and add the following options:</para> <programlisting>TLSCipherSuite HIGH:MEDIUM:+SSLv3 TLSCertificateFile /usr/local/etc/openldap/server.crt @@ -2790,12 +2792,12 @@ TLSCACertificateFile /usr/local/etc/openldap/ca.crt</programlisting> <programlisting>TLS_CACERT /usr/local/etc/openldap/ca.crt TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting> - <para>While editing these this file, set the <option>BASE</option> - to the desired values, and uncomment all three of the - <option>URI</option>, <option>SIZELIMIT</option> and - <option>TIMELIMIT</option> options. In addition, set the - <option>URI</option> to contain <option>ldap://</option> - and <option>ldaps://</option>.</para> + <para>While editing these this file, set the + <option>BASE</option> to the desired values, and uncomment all + three of the <option>URI</option>, <option>SIZELIMIT</option> + and <option>TIMELIMIT</option> options. In addition, set the + <option>URI</option> to contain <option>ldap://</option> and + <option>ldaps://</option>.</para> <para>The resulting file should look similar to the following shown here:</para> @@ -2823,16 +2825,17 @@ TLS_CIPHER_SUITE HIGH:MEDIUM:+SSLv3</programlisting> <command>slappasswd</command> understands several hashing formats, refer to the manual page for more information.</para> - <para>Edit <filename>/usr/local/etc/openldap/slapd.conf</filename> - and add the following lines:</para> + <para>Edit + <filename>/usr/local/etc/openldap/slapd.conf</filename> and + add the following lines:</para> <programlisting>password-hash {sha} allow bind_v2</programlisting> <para>In addition, the <option>suffix</option> in this file must - be updated to match the <option>BASE</option> from the previous - configuration. The <option>rootdn</option> option should - also be set. A good recommendation is something like + be updated to match the <option>BASE</option> from the + previous configuration. The <option>rootdn</option> option + should also be set. A good recommendation is something like <option>cn=Manager</option>. Before saving this file, place the <option>rootpw</option> option in front of the password output from the <command>slappasswd</command> and delete the @@ -2913,8 +2916,8 @@ cn: Manager</programlisting> <screen>&prompt.root; <userinput>ldapadd -Z -D "cn=Manager,dc=example,dc=com" -W -f <replaceable>import.ldif</replaceable></userinput></screen> - <para>There will be a request for the password specified earlier, - and the output should look like this:</para> + <para>There will be a request for the password specified + earlier, and the output should look like this:</para> <screen>Enter LDAP Password: adding new entry "dc=example,dc=com" @@ -3064,14 +3067,16 @@ result: 0 Success device is compiled into the kernel. To do this, add <literal>device bpf</literal> to the kernel configuration file, and rebuild the kernel. For more - information about building kernels, see <xref - linkend="kernelconfig"/>.</para> <para>The - <devicename>bpf</devicename> device is already part of - the <filename>GENERIC</filename> kernel that is supplied - with &os;, thus there is no need to build a custom kernel - for <acronym>DHCP</acronym>. In the case of a custom - kernel configuration file, this device must be present - for <acronym>DHCP</acronym> to function properly.</para> + information about building kernels, see + <xref linkend="kernelconfig"/>.</para> + + <para>The <devicename>bpf</devicename> device is already + part of the <filename>GENERIC</filename> kernel that is + supplied with &os;, thus there is no need to build a + custom kernel for <acronym>DHCP</acronym>. In the case + of a custom kernel configuration file, this device must + be present for <acronym>DHCP</acronym> to function + properly.</para> <note> <para>For those who are particularly security conscious, @@ -3209,12 +3214,11 @@ dhclient_flags=""</programlisting> (Internet Systems Consortium) implementation of the DHCP server.</para> - <para>The server is not provided as part of &os;, and so - the <filename - role="package">net/isc-dhcp42-server</filename> port must - be installed to provide this service. - See <xref linkend="ports"/> for - more information on using the Ports Collection.</para> + <para>The server is not provided as part of &os;, and so the + <filename role="package">net/isc-dhcp42-server</filename> + port must be installed to provide this service. See + <xref linkend="ports"/> for more information on using the + Ports Collection.</para> </sect3> <sect3> @@ -3225,12 +3229,12 @@ dhclient_flags=""</programlisting> <secondary>installation</secondary> </indexterm> <para>In order to configure the &os; system as a DHCP - server, first ensure that the &man.bpf.4; - device is compiled into the kernel. To do this, add - <literal>device bpf</literal> to the kernel - configuration file, and rebuild the kernel. For more - information about building kernels, see <xref - linkend="kernelconfig"/>.</para> + server, first ensure that the &man.bpf.4; device is + compiled into the kernel. To do this, add + <literal>device bpf</literal> to the kernel configuration + file, and rebuild the kernel. For more information about + building kernels, see + <xref linkend="kernelconfig"/>.</para> <para>The <devicename>bpf</devicename> device is already part of the <filename>GENERIC</filename> kernel that is @@ -3245,11 +3249,10 @@ dhclient_flags=""</programlisting> correctly (although such programs still need privileged access). The <devicename>bpf</devicename> device <emphasis>is</emphasis> required to use DHCP, but - if the sensitivity of the system's security is high, this - device should not be included in - the kernel purely because the use of - <acronym>DHCP</acronym> may, at - some point in the future, be desired.</para> + if the sensitivity of the system's security is high, + this device should not be included in the kernel purely + because the use of <acronym>DHCP</acronym> may, at some + point in the future, be desired.</para> </note> <para>The next thing that is needed is to edit the @@ -4398,20 +4401,19 @@ mail IN A 192.168.1.5</programlisting> 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 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>. 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 securing the - Internet in general. For more in-depth details of how - <acronym>DNSSEC</acronym> works, the relevant + 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 + 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>. + 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 + securing the Internet in general. For more in-depth details + of how <acronym>DNSSEC</acronym> works, the relevant <acronym>RFC</acronym>s are a good place to start. See the list in <xref linkend="dns-read"/>.</para> @@ -4955,12 +4957,12 @@ $include Kexample.com.+005+nnnnn.ZSK.key ; ZSK</programlisting> <term><literal>ServerName www.example.com</literal></term> <listitem> - <para><literal>ServerName</literal> allows an administrator - to set a host name which is sent back to clients for the - server. This is useful if the host is different than the - one that it is configured with (i.e., use - <hostid>www</hostid> instead - of the host's real name).</para> + <para><literal>ServerName</literal> allows an + administrator to set a host name which is sent back to + clients for the server. This is useful if the host is + different than the one that it is configured with (i.e., + use <hostid>www</hostid> instead of the host's real + name).</para> </listitem> </varlistentry> @@ -5397,12 +5399,12 @@ DocumentRoot /www/someotherdomain.tld FTP.</para> <para>In some cases it may be desirable to restrict the access - of some users without - preventing them completely from using FTP. This can be - accomplished with the <filename>/etc/ftpchroot</filename> - file. This file lists users and groups subject to FTP access - restrictions. The &man.ftpchroot.5; manual page has all of - the details so it will not be described in detail here.</para> + of some users without preventing them completely from using + FTP. This can be accomplished with the + <filename>/etc/ftpchroot</filename> file. This file lists + users and groups subject to FTP access restrictions. The + &man.ftpchroot.5; manual page has all of the details so it + will not be described in detail here.</para> <indexterm> <primary>FTP</primary> @@ -5533,10 +5535,11 @@ DocumentRoot /www/someotherdomain.tld &os; printers as if they were local printers.</para> <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 package.</para> + 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 + package.</para> <!-- mention LDAP, Active Directory, WinBIND, ACL, Quotas, PAM, .. --> @@ -5581,12 +5584,12 @@ DocumentRoot /www/someotherdomain.tld reloaded after this configuration file is changed.</para> <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 must be used.</para> + <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 + must be used.</para> -<!-- XXX screenshots go here, loader is creating them +<!-- XXX screenshots go here, loader is creating them XXXTR: I'll believe it when I see it. --> <para>Once successfully logging on to the main @@ -5666,8 +5669,8 @@ DocumentRoot /www/someotherdomain.tld requires clients to first log on before they can access shared resources.</para> - <para>In share level security, clients do not need to log - onto the server with a valid username and password + <para>In share level security, clients do not need to + log onto the server with a valid username and password before attempting to connect to a shared resource. This was the default security model for older versions of <application>Samba</application>.</para> @@ -5710,18 +5713,17 @@ DocumentRoot /www/someotherdomain.tld <screen>&prompt.root; <userinput><command>pdbedit <option>-a</option> <option>-u</option> <replaceable>username</replaceable></command></userinput></screen> </note> - <para>Please see the - <ulink + <para>Please see the <ulink url="http://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/">Official - Samba HOWTO</ulink> - for additional information about configuration - options. With the basics outlined here, the minimal required - start running <application>Samba</application> will - be explained. Other documentation should be consulted in - addition to the information here.</para> + Samba HOWTO</ulink> for additional information about + configuration options. With the basics outlined here, the + minimal required start running + <application>Samba</application> will be explained. Other + documentation should be consulted in addition to the + information here.</para> </sect3> - </sect2> + <sect2> <title>Starting <application>Samba</application></title> @@ -5767,8 +5769,8 @@ Starting smbd.</screen> the <application>winbindd</application> daemon will be started as well.</para> - <para><application>Samba</application> may be stopped at any time - by typing:</para> + <para><application>Samba</application> may be stopped at any + time by typing:</para> <screen>&prompt.root; <userinput>service samba stop</userinput></screen> @@ -5833,16 +5835,15 @@ Starting smbd.</screen> </indexterm> <para>In order to synchronize the clock, one or more - <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 - 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> + <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 + 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> <para>Choosing several unconnected NTP servers is a good idea in case one of the servers being used becomes unreachable or @@ -5945,9 +5946,9 @@ driftfile /var/db/ntp.drift</programlisting> <programlisting>restrict default ignore</programlisting> <note> - <para>This will also prevent access from the server to - any servers listed in the local configuration. If there is - a need to synchronise the NTP server with an external NTP + <para>This will also prevent access from the server to any + servers listed in the local configuration. If there is a + need to synchronise the NTP server with an external NTP server, allow only that specific server. See the &man.ntp.conf.5; manual for more information.</para> </note> 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 86d0c65702..7fcceb544a 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 @@ -148,15 +148,9 @@ <para>This document assumes you have the following:</para> <itemizedlist> - <indexterm id="ppp-isp"> - <primary>ISP</primary> - </indexterm> - <indexterm id="ppp-ppp2"> - <primary>PPP</primary> - </indexterm> <listitem> - <para>An account with an Internet Service Provider (ISP) - which you connect to using PPP.</para> + <para>An account with an Internet Service Provider (ISP)<indexterm id="ppp-isp"><primary>ISP</primary></indexterm> + which you connect to using PPP<indexterm id="ppp-ppp2"><primary>PPP</primary></indexterm>.</para> </listitem> <listitem> @@ -170,32 +164,13 @@ </listitem> <listitem> - <indexterm id="ppp-pap"> - <primary>PAP</primary> - </indexterm> - <indexterm id="ppp-chap"> - <primary>CHAP</primary> - </indexterm> - <indexterm id="ppp-unix"> - <primary>UNIX</primary> - </indexterm> - <indexterm id="ppp-login"> - <primary>login name</primary> - </indexterm> - <indexterm id="ppp-password"> - <primary>password</primary> - </indexterm> - <para>Your login name and password. (Either a - regular &unix; style login and password pair, or a PAP - or CHAP login and password pair).</para> + <para>Your login name<indexterm id="ppp-login"><primary>login name</primary></indexterm> and password<indexterm id="ppp-password"><primary>password</primary></indexterm>. (Either a + regular &unix;<indexterm id="ppp-unix"><primary>UNIX</primary></indexterm> style login and password pair, or a PAP<indexterm id="ppp-pap"><primary>PAP</primary></indexterm> + or CHAP<indexterm id="ppp-chap"><primary>CHAP</primary></indexterm> login and password pair).</para> </listitem> <listitem> - <indexterm id="ppp-nameserver"> - <primary>nameserver</primary> - </indexterm> - - <para>The IP address of one or more name servers. + <para>The IP address of one or more name servers<indexterm id="ppp-nameserver"><primary>nameserver</primary></indexterm>. Normally, you will be given two IP addresses by your ISP to use for this. If they have not given you at least one, then you can use the <command>enable @@ -384,12 +359,7 @@ <term>Line 6 & 7:</term> <listitem> - <indexterm> - <primary>PPP</primary> - <secondary>user PPP</secondary> - </indexterm> - - <para>The dial string. User PPP uses an expect-send + <para>The dial string. User PPP<indexterm><primary>PPP</primary><secondary>user PPP</secondary></indexterm> uses an expect-send syntax similar to the &man.chat.8; program. Refer to the manual page for information on the features of this language.</para> @@ -484,9 +454,7 @@ <term>Line 15:</term> <listitem> - <indexterm><primary>PAP</primary></indexterm> - <indexterm><primary>CHAP</primary></indexterm> - <para>If you are using PAP or CHAP, there will be no + <para>If you are using PAP<indexterm><primary>PAP</primary></indexterm> or CHAP<indexterm><primary>CHAP</primary></indexterm>, there will be no login at this point, and this line should be commented out or removed. See <link linkend="userppp-PAPnCHAP">PAP and CHAP @@ -514,9 +482,7 @@ protocol: ppp</screen> <term>Line 16:</term> <listitem> - <indexterm><primary>timeout</primary></indexterm> - - <para>Sets the default idle timeout (in seconds) for + <para>Sets the default idle timeout<indexterm><primary>timeout</primary></indexterm> (in seconds) for the connection. Here, the connection will be closed automatically after 300 seconds of inactivity. If you never want to timeout, set this value to zero @@ -528,11 +494,9 @@ protocol: ppp</screen> <varlistentry> <term>Line 17:</term> <listitem> - <indexterm><primary>ISP</primary></indexterm> - <para>Sets the interface addresses. The string <replaceable>x.x.x.x</replaceable> should be - replaced by the IP address that your provider has + replaced by the IP address that your provider<indexterm><primary>ISP</primary></indexterm> has allocated to you. The string <replaceable>y.y.y.y</replaceable> should be replaced by the IP address that your ISP indicated @@ -1063,9 +1027,7 @@ set nbns 203.14.100.5</programlisting> <varlistentry> <term>Line 14:</term> <listitem> - <indexterm><primary>password</primary></indexterm> - - <para>This line specifies your PAP/CHAP password. + <para>This line specifies your PAP/CHAP password<indexterm><primary>password</primary></indexterm>. You will need to insert the correct value for <replaceable>MyPassword</replaceable>. You may want to add an additional line, such as:</para> diff --git a/en_US.ISO8859-1/books/handbook/printing/chapter.xml b/en_US.ISO8859-1/books/handbook/printing/chapter.xml index a368f5ad9a..caf27d4416 100644 --- a/en_US.ISO8859-1/books/handbook/printing/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/printing/chapter.xml @@ -128,10 +128,8 @@ </listitem> <listitem> - <indexterm><primary>print jobs</primary></indexterm> - <para>It enables users to submit files to be printed; these - submissions are known as <emphasis>jobs</emphasis>.</para> + submissions are known as <emphasis>jobs</emphasis><indexterm><primary>print jobs</primary></indexterm>.</para> </listitem> <listitem> @@ -189,11 +187,9 @@ </listitem> <listitem> - <indexterm><primary>&tex;</primary></indexterm> - <para><application>LPD</application> can conveniently run a job to be printed through filters to add date/time - headers or convert a special file format (such as a &tex; + headers or convert a special file format (such as a &tex;<indexterm><primary>&tex;</primary></indexterm> DVI file) into a format the printer will understand. You will not have to do these steps manually.</para> </listitem> @@ -290,12 +286,7 @@ <itemizedlist> <listitem> - <indexterm> - <primary>printers</primary> - <secondary>serial</secondary> - </indexterm> - - <para><emphasis>Serial</emphasis> interfaces, also known + <para><emphasis>Serial</emphasis><indexterm><primary>printers</primary><secondary>serial</secondary></indexterm> interfaces, also known as RS-232 or COM ports, use a serial port on your computer to send data to the printer. Serial interfaces are common in the computer industry and @@ -309,12 +300,7 @@ </listitem> <listitem> - <indexterm> - <primary>printers</primary> - <secondary>parallel</secondary> - </indexterm> - - <para><emphasis>Parallel</emphasis> interfaces use a + <para><emphasis>Parallel</emphasis><indexterm><primary>printers</primary><secondary>parallel</secondary></indexterm> interfaces use a parallel port on your computer to send data to the printer. Parallel interfaces are common in the PC market and are faster than RS-232 serial. Cables are @@ -323,22 +309,13 @@ with parallel interfaces, making their configuration exceedingly simple.</para> - <indexterm> - <primary>centronics</primary> - <see>parallel printers</see> - </indexterm> <para>Parallel interfaces are sometimes known as - <quote>Centronics</quote> interfaces, named after the + <quote>Centronics</quote><indexterm><primary>centronics</primary><see>parallel printers</see></indexterm> interfaces, named after the connector type on the printer.</para> </listitem> <listitem> - <indexterm> - <primary>printers</primary> - <secondary>USB</secondary> - </indexterm> - - <para>USB interfaces, named for the Universal Serial + <para>USB<indexterm><primary>printers</primary><secondary>USB</secondary></indexterm> interfaces, named for the Universal Serial Bus, can run at even faster speeds than parallel or RS-232 serial interfaces. Cables are simple and cheap. USB is superior to RS-232 Serial and to @@ -423,10 +400,7 @@ </listitem> <listitem> - <indexterm><primary>null-modem - cable</primary></indexterm> - - <para>A <emphasis>null-modem</emphasis> cable connects + <para>A <emphasis>null-modem</emphasis> cable<indexterm><primary>null-modem cable</primary></indexterm> connects some pins straight through, swaps others (send data to receive data, for example), and shorts some internally in each connector hood. This type of cable is also @@ -714,12 +688,8 @@ showpage</programlisting> <sect4 id="printing-checking-parallel"> <title>Checking a Parallel Printer</title> - <indexterm> - <primary>printers</primary> - <secondary>parallel</secondary> - </indexterm> <para>This section tells you how to check if &os; can - communicate with a printer connected to a parallel + communicate with a printer connected to a parallel<indexterm><primary>printers</primary><secondary>parallel</secondary></indexterm> port.</para> <para><emphasis>To test a printer on a parallel @@ -926,9 +896,7 @@ showpage</programlisting> </step> <step> - <indexterm><primary>header pages</primary></indexterm> - - <para>Turn off header pages (which are on by default) by + <para>Turn off header pages<indexterm><primary>header pages</primary></indexterm> (which are on by default) by inserting the <literal>sh</literal> capability; see the <link linkend="printing-no-header-pages">Suppressing Header Pages</link> section for more @@ -1730,12 +1698,7 @@ $%&'()*+,-./01234567 </listitem> <listitem> - <indexterm> - <primary>printing</primary> - <secondary>filters</secondary> - </indexterm> - - <para>A <emphasis>conversion filter</emphasis> converts + <para>A <emphasis>conversion filter</emphasis><indexterm><primary>printing</primary><secondary>filters</secondary></indexterm> converts a specific file format into one the printer can render onto paper. For example, ditroff typesetting data cannot be directly printed, but you can install a @@ -4808,9 +4771,7 @@ cfA013rose dequeued</screen> <term>LPRng</term> <listitem> - <indexterm><primary>LPRng</primary></indexterm> - - <para><application>LPRng</application>, which purportedly + <para><application>LPRng</application><indexterm><primary>LPRng</primary></indexterm>, which purportedly means <quote>LPR: the Next Generation</quote> is a complete rewrite of PLP. Patrick Powell and Justin Mason (the principal maintainer of PLP) collaborated to make @@ -4824,9 +4785,7 @@ cfA013rose dequeued</screen> <term>CUPS</term> <listitem> - <indexterm><primary>CUPS</primary></indexterm> - - <para><application>CUPS</application>, the Common UNIX + <para><application>CUPS</application><indexterm><primary>CUPS</primary></indexterm>, the Common UNIX Printing System, provides a portable printing layer for &unix;-based operating systems. It has been developed by Easy Software Products to promote a standard printing @@ -4852,9 +4811,7 @@ cfA013rose dequeued</screen> <term>HPLIP</term> <listitem> - <indexterm><primary>HPLIP</primary></indexterm> - - <para><application>HPLIP</application>, the HP &linux; + <para><application>HPLIP</application><indexterm><primary>HPLIP</primary></indexterm>, the HP &linux; Imaging and Printing system, is an HP-developed suite of programs that supports printing, scanning and fax facilities for HP appliances. This suite of programs @@ -4926,15 +4883,12 @@ exit 2</programlisting> "#$%&'()*+,-./012345 #$%&'()*+,-./0123456</screen> - <indexterm><primary>MS-DOS</primary></indexterm> - <indexterm><primary>OS/2</primary></indexterm> - <indexterm><primary>ASCII</primary></indexterm> <para>You have become another victim of the <emphasis>staircase effect</emphasis>, caused by conflicting interpretations of what characters should indicate a new line. &unix; style operating systems use a - single character: ASCII code 10, the line feed (LF). - &ms-dos;, &os2;, and others uses a pair of characters, + single character: ASCII<indexterm><primary>ASCII</primary></indexterm> code 10, the line feed (LF). + &ms-dos;<indexterm><primary>MS-DOS</primary></indexterm>, &os2;<indexterm><primary>OS/2</primary></indexterm>, and others uses a pair of characters, ASCII code 10 <emphasis>and</emphasis> ASCII code 13 (the carriage return or CR). Many printers use the &ms-dos; convention for representing new-lines.</para> diff --git a/en_US.ISO8859-1/books/handbook/security/chapter.xml b/en_US.ISO8859-1/books/handbook/security/chapter.xml index df1fa9b1d0..3c47c57dbe 100644 --- a/en_US.ISO8859-1/books/handbook/security/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/security/chapter.xml @@ -1748,15 +1748,10 @@ jdoe@example.org</screen> Troubleshooting</title> <itemizedlist> - <indexterm> - <primary>Kerberos5</primary> - <secondary>troubleshooting</secondary> - </indexterm> - <listitem> <para>When using either the Heimdal or <acronym>MIT</acronym> - <application>Kerberos</application> ports, ensure that + <application>Kerberos</application><indexterm><primary>Kerberos5</primary><secondary>troubleshooting</secondary></indexterm> ports, ensure that the <envar>PATH</envar> lists the <application>Kerberos</application> versions of the client applications before the system versions.</para> @@ -2444,57 +2439,57 @@ device crypto</screen> </listitem> </itemizedlist> - <sect3> - <sect3info> - <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <affiliation> - <address><email>trhodes@FreeBSD.org</email></address> - </affiliation> - <contrib>Written by </contrib> - </author> - </authorgroup> - </sect3info> - - <title>Configuring IPsec on &os;</title> - - <para>To begin, - <filename role="package">security/ipsec-tools</filename> - must be installed from the Ports Collection. This software - provides a number of applications which support the - configuration.</para> - - <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, - replacing <replaceable>internal</replaceable> and - <replaceable>external</replaceable> with the real IP - addresses of the internal and external interfaces of the two - gateways:</para> - - <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 tunnel <replaceable>external1 external2</replaceable></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 - <acronym>IP</acronym> address is <hostid - role="ipaddr">10.246.38.1</hostid>. The home - <acronym>LAN</acronym>'s external <acronym>IP</acronym> - address is <hostid role="ipaddr">192.168.1.12</hostid> and its - internal private <acronym>IP</acronym> address is <hostid - role="ipaddr">10.0.0.5</hostid>.</para> - - <para>If this is confusing, review the following example output - from &man.ifconfig.8;:</para> - - <programlisting>Gateway 1: + <sect3> + <sect3info> + <authorgroup> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <affiliation> + <address><email>trhodes@FreeBSD.org</email></address> + </affiliation> + <contrib>Written by </contrib> + </author> + </authorgroup> + </sect3info> + + <title>Configuring IPsec on &os;</title> + + <para>To begin, + <filename role="package">security/ipsec-tools</filename> + must be installed from the Ports Collection. This software + provides a number of applications which support the + configuration.</para> + + <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, + replacing <replaceable>internal</replaceable> and + <replaceable>external</replaceable> with the real IP + addresses of the internal and external interfaces of the two + gateways:</para> + + <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 tunnel <replaceable>external1 external2</replaceable></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 + <acronym>IP</acronym> address is + <hostid role="ipaddr">10.246.38.1</hostid>. The home + <acronym>LAN</acronym>'s external <acronym>IP</acronym> + address is <hostid role="ipaddr">192.168.1.12</hostid> and + its internal private <acronym>IP</acronym> address is + <hostid role="ipaddr">10.0.0.5</hostid>.</para> + + <para>If this is confusing, review the following example + output from &man.ifconfig.8;:</para> + + <programlisting>Gateway 1: gif0: flags=8051 mtu 1280 tunnel inet 172.16.5.4 --> 192.168.1.12 @@ -2508,10 +2503,10 @@ tunnel inet 192.168.1.12 --> 172.16.5.4 inet 10.0.0.5 --> 10.246.38.1 netmask 0xffffff00 inet6 fe80::250:bfff:fe3a:c1f%gif0 prefixlen 64 scopeid 0x4</programlisting> - <para>Once complete, both internal <acronym>IP</acronym> - addresses should be reachable using &man.ping.8;:</para> + <para>Once complete, both internal <acronym>IP</acronym> + addresses should be reachable using &man.ping.8;:</para> - <programlisting>priv-net# ping 10.0.0.5 + <programlisting>priv-net# ping 10.0.0.5 PING 10.0.0.5 (10.0.0.5): 56 data bytes 64 bytes from 10.0.0.5: icmp_seq=0 ttl=64 time=42.786 ms 64 bytes from 10.0.0.5: icmp_seq=1 ttl=64 time=19.255 ms @@ -2532,26 +2527,26 @@ PING 10.246.38.1 (10.246.38.1): 56 data bytes 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 28.106/94.594/154.524/49.814 ms</programlisting> - <para>As expected, both sides have the ability to send and - receive <acronym>ICMP</acronym> packets from the privately - configured addresses. Next, both gateways must be told how - to route packets in order to correctly send traffic from - either network. The following command will achieve this - goal:</para> + <para>As expected, both sides have the ability to send and + receive <acronym>ICMP</acronym> packets from the privately + configured addresses. Next, both gateways must be told how + to route packets in order to correctly send traffic from + 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 <replaceable>10.0.0.0 10.0.0.5 255.255.255.0</replaceable></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 <replaceable>10.0.0.0: gateway 10.0.0.5</replaceable></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 <replaceable>10.246.38.0 10.246.38.1 255.255.255.0</replaceable></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 <replaceable>10.246.38.0: gateway 10.246.38.1</replaceable></userinput></screen> - <para>At this point, internal machines should be reachable - from each gateway as well as from machines behind the - gateways. Again, use &man.ping.8; to confirm:</para> + <para>At this point, internal machines should be reachable + from each gateway as well as from machines behind the + gateways. Again, use &man.ping.8; to confirm:</para> - <programlisting>corp-net# ping 10.0.0.8 + <programlisting>corp-net# ping 10.0.0.8 PING 10.0.0.8 (10.0.0.8): 56 data bytes 64 bytes from 10.0.0.8: icmp_seq=0 ttl=63 time=92.391 ms 64 bytes from 10.0.0.8: icmp_seq=1 ttl=63 time=21.870 ms @@ -2573,15 +2568,15 @@ PING 10.246.38.1 (10.246.38.107): 56 data bytes 5 packets transmitted, 5 packets received, 0% packet loss round-trip min/avg/max/stddev = 21.145/31.721/53.491/12.179 ms</programlisting> - <para>Setting up the tunnels is the easy part. Configuring a - secure link is a more in depth process. The following - configuration uses pre-shared (<acronym>PSK</acronym>) - <acronym>RSA</acronym> keys. Other than the - <acronym>IP</acronym> addresses, the - <filename>/usr/local/etc/racoon/racoon.conf</filename> on - both gateways will be identical and look similar to:</para> + <para>Setting up the tunnels is the easy part. Configuring a + secure link is a more in depth process. The following + configuration uses pre-shared (<acronym>PSK</acronym>) + <acronym>RSA</acronym> keys. Other than the + <acronym>IP</acronym> addresses, the + <filename>/usr/local/etc/racoon/racoon.conf</filename> on + both gateways will be identical and look similar to:</para> - <programlisting>path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file + <programlisting>path pre_shared_key "/usr/local/etc/racoon/psk.txt"; #location of pre-shared key file log debug; #log verbosity setting: set to 'notify' when testing and debugging is complete padding # options are not to be changed @@ -2639,33 +2634,33 @@ sainfo (address 10.246.38.0/24 any address 10.0.0.0/24 any) # address $network/ compression_algorithm deflate; }</programlisting> - <para>For descriptions of each available option, refer to the - manual page for <filename>racoon.conf</filename>.</para> + <para>For descriptions of each available option, refer to the + manual page for <filename>racoon.conf</filename>.</para> - <para>The Security Policy Database (<acronym>SPD</acronym>) - needs to be configured so that &os; and - <application>racoon</application> are able to encrypt and - decrypt network traffic between the hosts.</para> + <para>The Security Policy Database (<acronym>SPD</acronym>) + needs to be configured so that &os; and + <application>racoon</application> are able to encrypt and + decrypt network traffic between the hosts.</para> - <para>This can be achieved with a shell script, similar to the - following, on the corporate gateway. This file will be used - during system initialization and should be saved as - <filename>/usr/local/etc/racoon/setkey.conf</filename>.</para> + <para>This can be achieved with a shell script, similar to the + following, on the corporate gateway. This file will be used + during system initialization and should be saved as + <filename>/usr/local/etc/racoon/setkey.conf</filename>.</para> - <programlisting>flush; + <programlisting>flush; spdflush; # To the home network spdadd 10.246.38.0/24 10.0.0.0/24 any -P out ipsec esp/tunnel/172.16.5.4-192.168.1.12/use; spdadd 10.0.0.0/24 10.246.38.0/24 any -P in ipsec esp/tunnel/192.168.1.12-172.16.5.4/use;</programlisting> - <para>Once in place, <application>racoon</application> may be - started on both gateways using the following command:</para> + <para>Once in place, <application>racoon</application> may be + started on both gateways using the following command:</para> - <screen>&prompt.root; <userinput>/usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log</userinput></screen> + <screen>&prompt.root; <userinput>/usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf -l /var/log/racoon.log</userinput></screen> - <para>The output should be similar to the following:</para> + <para>The output should be similar to the following:</para> - <programlisting>corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf + <programlisting>corp-net# /usr/local/sbin/racoon -F -f /usr/local/etc/racoon/racoon.conf Foreground mode. 2006-01-30 01:35:47: INFO: begin Identity Protection mode. 2006-01-30 01:35:48: INFO: received Vendor ID: KAME/racoon @@ -2678,43 +2673,43 @@ Foreground mode. 2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 192.168.1.12[0]->172.16.5.4[0] spi=124397467(0x76a279b) 2006-01-30 01:36:18: INFO: IPsec-SA established: ESP/Tunnel 172.16.5.4[0]->192.168.1.12[0] spi=175852902(0xa7b4d66)</programlisting> - <para>To ensure the tunnel is working properly, switch to - another console and use &man.tcpdump.1; to view network - traffic using the following command. Replace - <literal>em0</literal> with the network interface card as - required:</para> + <para>To ensure the tunnel is working properly, switch to + another console and use &man.tcpdump.1; to view network + traffic using the following command. Replace + <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 <replaceable>172.16.5.4 and dst 192.168.1.12</replaceable></userinput></screen> - <para>Data similar to the following should appear on the - console. If not, there is an issue and debugging the - returned data will be required.</para> + <para>Data similar to the following should appear on the + console. If not, there is an issue and debugging the + returned data will be required.</para> - <programlisting>01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa) + <programlisting>01:47:32.021683 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xa) 01:47:33.022442 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xb) 01:47:34.024218 IP corporatenetwork.com > 192.168.1.12.privatenetwork.com: ESP(spi=0x02acbf9f,seq=0xc)</programlisting> - <para>At this point, both networks should be available and - seem to be part of the same network. Most likely both - networks are protected by a firewall. To allow traffic to - flow between them, rules need to be added to pass packets. - For the &man.ipfw.8; firewall, add the following lines to the - firewall configuration file:</para> + <para>At this point, both networks should be available and + seem to be part of the same network. Most likely both + networks are protected by a firewall. To allow traffic to + flow between them, rules need to be added to pass packets. + For the &man.ipfw.8; firewall, add the following lines to + the firewall configuration file:</para> - <programlisting>ipfw add 00201 allow log esp from any to any + <programlisting>ipfw add 00201 allow log esp from any to any ipfw add 00202 allow log ah from any to any ipfw add 00203 allow log ipencap from any to any ipfw add 00204 allow log udp from any 500 to any</programlisting> - <note> - <para>The rule numbers may need to be altered depending on - the current host configuration.</para> - </note> + <note> + <para>The rule numbers may need to be altered depending on + the current host configuration.</para> + </note> - <para>For users of &man.pf.4; or &man.ipf.8;, the following - rules should do the trick:</para> + <para>For users of &man.pf.4; or &man.ipf.8;, the following + rules should do the trick:</para> - <programlisting>pass in quick proto esp from any to any + <programlisting>pass in quick proto esp from any to any pass in quick proto ah from any to any pass in quick proto ipencap from any to any pass in quick proto udp from any port = 500 to any port = 500 @@ -2725,16 +2720,16 @@ pass out quick proto ipencap from any to any pass out quick proto udp from any port = 500 to any port = 500 pass out quick on gif0 from any to any</programlisting> - <para>Finally, to allow the machine to start support for the - <acronym>VPN</acronym> during system initialization, add the - following lines to <filename>/etc/rc.conf</filename>:</para> + <para>Finally, to allow the machine to start support for the + <acronym>VPN</acronym> during system initialization, add the + following lines to <filename>/etc/rc.conf</filename>:</para> - <programlisting>ipsec_enable="YES" + <programlisting>ipsec_enable="YES" ipsec_program="/usr/local/sbin/setkey" ipsec_file="/usr/local/etc/racoon/setkey.conf" # allows setting up spd policies on boot racoon_enable="yes"</programlisting> - </sect3> - </sect2> + </sect3> + </sect2> </sect1> <sect1 id="openssh"> @@ -2783,7 +2778,7 @@ racoon_enable="yes"</programlisting> </sect2> <sect2> - <title>Enabling The SSH Server</title> + <title>Enabling the SSH Server</title> <indexterm> <primary>OpenSSH</primary> @@ -2918,8 +2913,8 @@ bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</screen> is stored in <filename>~/.ssh/id_dsa.pub</filename> or <filename>~/.ssh/id_rsa.pub</filename>, respectively for the <acronym>DSA</acronym> and <acronym>RSA</acronym> key types. - The public key must be placed in the - <filename>~/.ssh/authorized_keys</filename> file of the + The public key must be placed in + <filename>~/.ssh/authorized_keys</filename> on the remote machine for both <acronym>RSA</acronym> or <acronym>DSA</acronym> keys in order for the setup to work.</para> @@ -2960,7 +2955,7 @@ bb:48:db:f2:93:57:80:b6:aa:bc:f5:d5:ba:8f:79:17 user@host.example.com</screen> </sect2> <sect2 id="security-ssh-agent"> - <title>Using SSH Agent To Cache Keys</title> + <title>Using SSH Agent to Cache Keys</title> <para>To load <acronym>SSH</acronym> keys into memory for use, without needing to type the passphrase each time, use @@ -2990,7 +2985,7 @@ Identity added: /home/user/.ssh/id_dsa (/home/user/.ssh/id_dsa) needs to be placed in <filename>~/.xinitrc</filename>. This provides the &man.ssh-agent.1; services to all programs launched in <application>&xorg;</application>. An example - <filename>~/.xinitrc</filename> file might look like + <filename>~/.xinitrc</filename> might look like this:</para> <programlisting>exec ssh-agent <replaceable>startxfce4</replaceable></programlisting> @@ -3217,7 +3212,7 @@ user@unfirewalled-system.example.org's password: <userinput>*******</userinput>< </sect1info> <title>Filesystem Access Control Lists - (<acronym>ACL</acronym>s)</title> + (<acronym>ACL</acronym>)s</title> <indexterm> <primary>ACL</primary> @@ -3719,11 +3714,11 @@ VII. References <co id="co-ref"/></programlisting> <sect1 id="security-resourcelimits"> <sect1info> <authorgroup> - <author> - <firstname>Tom</firstname> - <surname>Rhodes</surname> - <contrib>Contributed by </contrib> - </author> + <author> + <firstname>Tom</firstname> + <surname>Rhodes</surname> + <contrib>Contributed by </contrib> + </author> </authorgroup> </sect1info> @@ -3742,9 +3737,9 @@ VII. References <co id="co-ref"/></programlisting> group labels known as classes, which require changes not only to this flat file but also the password database. Potentially a single, more constrained user would require - an additional label added, the resource database needs to be - built using <command>cap_mkdb</command>, edits made to - the <filename>/etc/master.passwd</filename> file. In + an additional label to be added, the resource database + rebuilt using <command>cap_mkdb</command>, and edits made to + <filename>/etc/master.passwd</filename>. In addition, the password database must be rebuilt using <command>pwd_mkdb</command>. This multi-step process could be very time consuming depending on how many users must be @@ -3767,35 +3762,37 @@ VII. References <co id="co-ref"/></programlisting> <programlisting>options RACCT options RCTL</programlisting> - <para>The entire system will need rebuilt. See <xref - linkend="kernelconfig"/>, which will provide instructions for - the process. Once this is complete, the <command>rctl</command> - may be used to set rules for the system.</para> + <para>The entire system will need rebuilt. See + <xref linkend="kernelconfig"/>, which will provide instructions + for the process. Once this is complete, the + <command>rctl</command> may be used to set rules for the + system.</para> <para>Rule syntax is simple, controlled through the use of - a <emphasis>subject</emphasis>, a <emphasis>subject-id</emphasis>, - <emphasis>resource</emphasis>, and <emphasis>action</emphasis>. - Take the following example rule:</para> + a <emphasis>subject</emphasis>, a + <emphasis>subject-id</emphasis>, <emphasis>resource</emphasis>, + and <emphasis>action</emphasis>. Take the following example + rule:</para> <programlisting>user:trhodes:<literal>maxproc</literal>:<literal>deny</literal>=10/user</programlisting> - <para>This rule shows a basic premise of a rule, here the - subject is <literal>user</literal> and the subject-id - is <literal>trhodes</literal>. The maxproc is, of course, - max number of processes, which is considered the action. - The action here is set to <literal>deny</literal>, which blocks - any new processes from being created. In the previous example, - the user, <literal>trhodes</literal> will be constrained - to <literal>10</literal> (ten) processes and no greater. - Other actions are available and could be log to the console, - pass a notification to &man.devd.8;, or - send a sigterm to the process.</para> + <para>This rule shows a basic premise of a rule, here the subject + is <literal>user</literal> and the subject-id is + <literal>trhodes</literal>. The maxproc is, of course, max + number of processes, which is considered the resource. The + action here is set to <literal>deny</literal>, which blocks any + new processes from being created. In the previous example, the + user, <literal>trhodes</literal> will be constrained to + <literal>10</literal> (ten) processes and no greater. Other + actions are available and could be log to the console, pass a + notification to &man.devd.8;, or send a sigterm to the + process.</para> <para>Some care must be taken while adding rules. The one above - will unfortunately block my user from doing the most simple tasks - after I have logged in and executed a <command>screen</command> - session. When a resource limit has been hit, an error will - be printed, as in this example:</para> + will unfortunately block my user from doing the most simple + tasks after I have logged in and executed a + <command>screen</command> session. When a resource limit has + been hit, an error will be printed, as in this example:</para> <screen>&prompt.user; <userinput>man test</userinput> /usr/bin/man: Cannot fork: Resource temporarily unavailable @@ -3808,9 +3805,9 @@ eval: Cannot fork: Resource temporarily unavailable</screen> <screen>&prompt.root; <userinput>rctl -a jail:httpd:memoryuse:deny=2G/jail</userinput></screen> <para>Rules may also persist across reboots if they have been - added to <filename>/etc/rctl.conf</filename> file. The - format is a rule, without the preceding command. For example, - the previous rule could be added like the following:</para> + added to <filename>/etc/rctl.conf</filename>. The format is a + rule, without the preceding command. For example, the previous + rule could be added like the following:</para> <programlisting># Block jail from using more than 2G memory: jail:httpd:memoryuse:deny=2G/jail</programlisting> @@ -3826,7 +3823,7 @@ jail:httpd:memoryuse:deny=2G/jail</programlisting> <screen>&prompt.root; <userinput>rctl -r user:trhodes</userinput></screen> - <para>Many other resources exist which can be used to excert + <para>Many other resources exist which can be used to exert additional control over various <literal>subjects</literal>. See &man.rctl.8; to learn about them.</para> </sect1> diff --git a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml index 86436fe80a..fd92268b25 100644 --- a/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/serialcomms/chapter.xml @@ -65,11 +65,10 @@ <title>Terminology</title> <variablelist> - <indexterm><primary>bits-per-second</primary></indexterm> <varlistentry> <term><acronym>bps</acronym></term> <listitem> - <para>Bits per Second (<acronym>bps</acronym>) is the rate + <para>Bits per Second<indexterm><primary>bits-per-second</primary></indexterm> (<acronym>bps</acronym>) is the rate at which data is transmitted.</para> </listitem> </varlistentry> @@ -77,9 +76,7 @@ <varlistentry> <term><acronym>DTE</acronym></term> <listitem> - <indexterm><primary>DTE</primary></indexterm> - - <para>An example of a Data Terminal Equipment + <para>An example of a Data Terminal Equipment<indexterm><primary>DTE</primary></indexterm> (<acronym>DTE</acronym>) is a computer.</para> </listitem> </varlistentry> @@ -87,9 +84,7 @@ <varlistentry> <term><acronym>DCE</acronym></term> <listitem> - <indexterm><primary>DCE</primary></indexterm> - - <para>An example of a Data Communications Equipment + <para>An example of a Data Communications Equipment<indexterm><primary>DCE</primary></indexterm> (<acronym>DTE</acronym>) is a modem.</para> </listitem> </varlistentry> @@ -98,11 +93,9 @@ <term>RS-232</term> <listitem> - <indexterm><primary>RS-232C cables</primary></indexterm> - <para>The original standard for hardware serial communications. It is now usually referred to as - <acronym>TIA</acronym>-232</para> + <acronym>TIA</acronym>-232<indexterm><primary>RS-232C cables</primary></indexterm>.</para> </listitem> </varlistentry> </variablelist> diff --git a/en_US.ISO8859-1/books/handbook/users/chapter.xml b/en_US.ISO8859-1/books/handbook/users/chapter.xml index 4ac3616b48..39f145021d 100644 --- a/en_US.ISO8859-1/books/handbook/users/chapter.xml +++ b/en_US.ISO8859-1/books/handbook/users/chapter.xml @@ -741,12 +741,8 @@ passwd: done</screen> <term><literal>coredumpsize</literal></term> <listitem> - <indexterm><primary>coredumpsize</primary></indexterm> - <indexterm><primary>limiting users</primary> - <secondary>coredumpsize</secondary> - </indexterm> - <para>The limit on the size of a core file generated by a - program is subordinate to other limits on disk usage, such + <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 @@ -760,12 +756,7 @@ passwd: done</screen> <term><literal>cputime</literal></term> <listitem> - <indexterm><primary>cputime</primary></indexterm> - <indexterm> - <primary>limiting users</primary> - <secondary>cputime</secondary> - </indexterm> - <para>The maximum amount of CPU time a user's process may + <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> @@ -781,12 +772,7 @@ passwd: done</screen> <term><literal>filesize</literal></term> <listitem> - <indexterm><primary>filesize</primary></indexterm> - <indexterm> - <primary>limiting users</primary> - <secondary>filesize</secondary> - </indexterm> - <para>The maximum size of a file the user may own. Unlike + <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> @@ -797,12 +783,7 @@ passwd: done</screen> <term><literal>maxproc</literal></term> <listitem> - <indexterm><primary>maxproc</primary></indexterm> - <indexterm> - <primary>limiting users</primary> - <secondary>maxproc</secondary> - </indexterm> - <para>The maximum number of processes a user can run. This + <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 @@ -818,12 +799,7 @@ passwd: done</screen> <term><literal>memorylocked</literal></term> <listitem> - <indexterm><primary>memorylocked</primary></indexterm> - <indexterm> - <primary>limiting users</primary> - <secondary>memorylocked</secondary> - </indexterm> - <para>The maximum amount of memory a process may request + <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 @@ -835,10 +811,7 @@ passwd: done</screen> <term><literal>memoryuse</literal></term> <listitem> - <indexterm><primary>memoryuse</primary></indexterm> - <indexterm><primary>limiting users</primary> - <secondary>memoryuse</secondary></indexterm> - <para>The maximum amount of memory a process may consume at + <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> @@ -849,11 +822,7 @@ passwd: done</screen> <term><literal>openfiles</literal></term> <listitem> - <indexterm><primary>openfiles</primary></indexterm> - <indexterm><primary>limiting users</primary> - <secondary>openfiles</secondary> - </indexterm> - <para>The maximum number of files a process may have open. + <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 @@ -865,12 +834,8 @@ passwd: done</screen> <term><literal>sbsize</literal></term> <listitem> - <indexterm><primary>sbsize</primary></indexterm> - <indexterm><primary>limiting users</primary> - <secondary>sbsize</secondary> - </indexterm> <para>The limit on the amount of network memory, and - thus mbufs, a user may consume in order to limit network + 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> @@ -879,11 +844,7 @@ passwd: done</screen> <term><literal>stacksize</literal></term> <listitem> - <indexterm><primary>stacksize</primary></indexterm> - <indexterm><primary>limiting users</primary> - <secondary>stacksize</secondary> - </indexterm> - <para>The maximum size of a process stack. This alone is + <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> |