From 97fe3901a977c8a3195862a2c2b6b5053632d0b0 Mon Sep 17 00:00:00 2001 From: Nik Clayton Date: Fri, 3 Sep 1999 17:16:06 +0000 Subject: Miscellaneous small changes. Includes reformatting white space in some of the example HTML and DocBook fragments, which are significant. Explain where to find the FreeBSD DTD that extends DocBook. Add a section explaining about books and articles, and the differences between them. Added an example of . Be consistent with the white space inside . Make sure that content starts immediately after the opening tag. Shouldn't make a great deal of difference, but we should practice what we preach. Remove the information about , as it seems to be redundant, and we don't use it anymore. Correct an error ("]]", should be "]") in the example of including the manual page reference entities. --- .../books/fdp-primer/sgml-markup/chapter.sgml | 344 ++++++++++++--------- 1 file changed, 195 insertions(+), 149 deletions(-) (limited to 'en_US.ISO_8859-1/books') diff --git a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml index 2d74c89f07..71959ba6a4 100644 --- a/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml +++ b/en_US.ISO_8859-1/books/fdp-primer/sgml-markup/chapter.sgml @@ -27,7 +27,7 @@ ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. - $Id: chapter.sgml,v 1.7 1999-08-30 11:53:03 jhb Exp $ + $Id: chapter.sgml,v 1.8 1999-09-03 17:16:06 nik Exp $ --> @@ -93,8 +93,7 @@ The majority of HTML documents on the FreeBSD web site comply with the loose version of HTML 4.0. - -PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" @@ -114,8 +113,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Normal HTML document structure - -<html> + <html> <head> <title>The document's title</title> </head> @@ -149,8 +147,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -First section + First section @@ -181,8 +178,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -First section + First section @@ -203,8 +199,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -This is a paragraph. It can contain just about any + This is a paragraph. It can contain just about any other element.

]]> @@ -220,8 +215,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -A small excerpt from the US Constitution;

+ A small excerpt from the US Constitution;

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic @@ -264,8 +258,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -An unordered list. Listitems will probably be + An unordered list. Listitems will probably be preceeded by bullets.

    @@ -297,8 +290,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - - +
    Term 1

    Paragraph 1 of definition 1.

    @@ -334,9 +326,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"     You could use pre to mark up an e-mail message; - - - From: nik@FreeBSD.org + From: nik@FreeBSD.org To: freebsd-doc@FreeBSD.org Subject: New documentation available @@ -347,8 +337,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Comments appreciated. - N -]]> + N]]>     @@ -376,8 +365,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -This is a simple 2x2 table.

    + This is a simple 2x2 table.

    @@ -403,8 +391,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Use: - -One tall thin cell on the left, two short cells next to + One tall thin cell on the left, two short cells next to it on the right.

    @@ -425,8 +412,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Use: - -One long cell on top, two short cells below it.

    + One long cell on top, two short cells below it.

    @@ -447,8 +433,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Use: - -On a 3x3 grid, the top left block is a 2x2 set of + On a 3x3 grid, the top left block is a 2x2 set of cells merged in to one. The other cells are normal.

    @@ -461,7 +446,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" + right --> @@ -498,8 +483,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Use: - -This has been emphasised, while + This has been emphasised, while this has been strongly emphasised.

    ]]>     @@ -515,8 +499,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"     <sgmltag>b</sgmltag> and <sgmltag>i</sgmltag> - -This is in bold, while this is + This is in bold, while this is in italics.

    ]]>         @@ -533,8 +516,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"Use: - -This document was originally written by + This document was originally written by Nik Clayton, who can be reached by e-mail as nik@FreeBSD.org.

    ]]>     @@ -575,8 +557,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"    The following fragments all do the same thing. - -This text is slightly smaller. But + This text is slightly smaller. But this text is slightly bigger.

    This text is slightly smaller. But @@ -613,8 +594,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" Use: - -More information is available at the + More information is available at the FreeBSD web site.

    ]]>     @@ -638,8 +618,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"    Use: - -This paragraph can be referenced + This paragraph can be referenced in other links with the name para1.

    ]]>     @@ -653,8 +632,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"    Assume that the para1 example resides in a document called foo.html. - -More information can be found in the + More information can be found in the first paragraph of foo.html.

    ]]>     @@ -669,8 +647,7 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"    Assume that the para1 example resides in this document - -More information can be found in the + More information can be found in the first paragraph of this document.

    ]]>     @@ -725,6 +702,11 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"     collaborating on a standard DocBook extension set, please get in touch with Nik Clayton nik@FreeBSD.org. + + The FreeBSD extensions are not (currently) in the ports + collection. It is a part of the Documentation Project source + repository, and can be found in + doc/share/sgml/freebsd.dtd. @@ -734,18 +716,15 @@ PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN" DocBook customisations, the FPI for the FreeBSD extended DocBook DTD is; - -PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" + PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" - - - Sectional elements - DocBook contains a number of elements for marking up the structure - of a book. + + Document structure - Generally, the top level (first) element will be - book. + DocBook allows you to structure your documentation in several + ways. In the FreeBSD Documentation Project we are using two primary + types of DocBook document, the book, and the article. A book is organised into chapters. This is a mandatory requirement. There may be parts between @@ -759,6 +738,27 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Chapters and sections contain the remainder of the content. + An article is simpler than a book, and does not use chapters. + Instead, the content of an article is organised into one or more + sections, using the same sect1 (and + sect2 and so on) elements that are used in + books. + + Obviously, you should consider the nature of the documentation you + are writing in order to decide whether it is best marked up as a book + or an article. Articles are well suited to information that does not + need to be broken down in to several chapters, and that is, relatively + speaking, quite short, at up to 20-25 pages of content. Books are + best suited to information that can be broken up in to several + chapters, possibly with appendices and similar content as well. + + The FreeBSD + tutorials are all marked up as articles, while this + document, the FreeBSD + FAQ, and the FreeBSD Handbook are + all marked up as books. + Starting a book @@ -778,8 +778,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" - -<book> + <book> <bookinfo> <title>Your title here</title> @@ -811,17 +810,67 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" + + Starting an article + + The content of the article is contained within the + article element. As well as containing + structural markup, this element can contain elements that include + additional information about the article. This is either + meta-information, used for reference purposes, or additional content + used to produce a title page. + + This additional information should be contained within + artheader. + + + Boilerplate <sgmltag>article</sgmltag> with + <sgmltag>artheader</sgmltag> + + + <article> + <artheader> + <title>Your title here</title> + + <author> + <firstname>Your first name</firstname> + <surname>Your surname</surname> + <affiliation> + <address><email>Your e-mail address</email></address> + </affiliation> + </author> + + <copyright> + <year>1998</year> + <holder role="mailto:your e-mail address">Your name</holder> + </copyright> + + <pubdate role="rcs">$Date$</pubdate> + + <releaseinfo>$Id$</releaseinfo> + + <abstract> + <para>Include an abstract of the article's contents here.</para> + </abstract> + </bookinfo> + + … + +</article> + + Indicating chapters Use chapter to mark up your chapters. Each - chapter has a mandatory title. + chapter has a mandatory title. Articles do not + contain chapters, they are reserved for books. A simple chapter - - + The chapter's title ... @@ -835,8 +884,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Empty chapters - - + This is an empty chapter @@ -847,10 +895,13 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Sections below chapters - Chapters can be broken up into sections, subsections, and so - on. Use the sectn - element. The n indicates the section - number, which identifies the section level. + In books, chapters may (but do not need to) be broken up into + sections, subsections, and so on. In articles, sections are the + main structural element, and each article must contain at least one + section. Use the + sectn element. The + n indicates the section number, which + identifies the section level. The first sectn is sect1. You can have one or more of these in a @@ -860,8 +911,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Sections in chapters - - + A sample chapter Some text in the chapter. @@ -869,7 +919,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" First section (1.1) - ... + … @@ -881,18 +931,25 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" First sub-sub-section (1.2.1.1) - ... + … Second sub-section (1.2.2) - ... + … ]]> + + + This example includes section numbers in the section titles. + You should not do this in your documents. Adding the section + numbers is carried out the by the stylesheets (of which more + later), and you do not need to manage them yourself. + @@ -900,10 +957,10 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" You can introduce another layer of organisation between book and chapter with one or - more parts. + more parts. This can not be done in an + article. - - + Introduction @@ -948,8 +1005,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Use: - -This is a paragraph. It can contain just about any + This is a paragraph. It can contain just about any other element. ]]> Appearance: @@ -974,8 +1030,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Use: - -A small excerpt from the US Constitution; + A small excerpt from the US Constitution;
    Preamble to the Constitution of the United States @@ -1050,8 +1105,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Use: - - + Installing FreeBSD may make you want to delete Windows from your harddisk. ]]> @@ -1100,8 +1154,7 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" Use: - - + This is the first itemized item. @@ -1119,7 +1172,21 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" This is the second ordered item. -]]> + + + + + Do this. + + + + Then do this. + + + + And now do this. + +]]> Appearance: @@ -1143,6 +1210,22 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" + + + + + + Do this. + + + + Then do this. + + + + And now do this. + + @@ -1154,21 +1237,20 @@ PUBLIC "-//FreeBSD//DTD DocBook V3.1-Based Extension//EN" White space and line breaks within programlisting are - significant. In particular, this means that the closing tag should - appear on the same line as the last line of the output, otherwise a - spurious blank line will be included. + significant. In particular, this means that the opening tag should + appear on the same line as the first line of the output, and the + closing tag should appear on the same line as the last line of the + output, otherwise spurious blank lines may be included. <sgmltag>programlisting</sgmltag> Use: - -When you have finished, your program should look like + When you have finished, your program should look like this; - -#include <stdio.h> +#include <stdio.h> int main(void) @@ -1185,8 +1267,7 @@ main(void) When you have finished, your program should look like this; - -#include <stdio.h> + #include <stdio.h> int main(void) @@ -1234,8 +1315,7 @@ main(void) Use: - - +
    @@ -1332,19 +1412,6 @@ main(void) here. - - informalexample - - - Most of the time these examples will occur - “mid-flow” as it were, and you won't need to put a - title on them. So, most of the time, the outermost element - will be informalexample. For those times - when you do need to include a title on the example, use - example. - - - screen @@ -1397,15 +1464,12 @@ main(void) - <sgmltag>informalexample</sgmltag>, - <sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and + <title><sgmltag>screen</sgmltag>, <sgmltag>prompt</sgmltag>, and <sgmltag>userinput</sgmltag> Use: - - - &prompt.user; ls -1 + &prompt.user; ls -1 foo1 foo2 foo3 @@ -1414,12 +1478,10 @@ foo2 &prompt.user; su Password: &prompt.root; cat foo2 -This is the file called 'foo2' -]]> +This is the file called 'foo2']]> - Appearance: + Appearance: - &prompt.user; ls -1 foo1 foo2 @@ -1430,7 +1492,6 @@ foo2 Password: &prompt.root; cat foo2 This is the file called 'foo2' - @@ -1466,8 +1527,7 @@ This is the file called 'foo2' Use: - -FreeBSD is without doubt the + FreeBSD is without doubt the premiere Unix like operating system for the Intel architecture.]]> Appearance: @@ -1526,7 +1586,7 @@ This is the file called 'foo2' … -]]> +]> Use command when you want to include a command name “in-line” but present it as something the @@ -1543,8 +1603,7 @@ This is the file called 'foo2' Use: - -Sendmail is the most + Sendmail is the most widely used Unix mail application. Sendmail includes the @@ -1603,8 +1662,7 @@ This is the file called 'foo2' Use: - -The SGML source for the Handbook in English can be + The SGML source for the Handbook in English can be found in /usr/doc/en/handbook/. The first file is called handbook.sgml in that directory. You should also see a Makefile @@ -1645,8 +1703,7 @@ This is the file called 'foo2' Use: - -sio is used for serial + sio is used for serial communication in FreeBSD. sio manifests through a number of entries in /dev, including /dev/ttyd0 and /dev/cuaa0. @@ -1761,8 +1818,7 @@ This is the file called 'foo2' Use: - -The local machine can always be referred to by the + The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1. @@ -1823,8 +1879,7 @@ This is the file called 'foo2' Use: - -To carry out most system administration functions you + To carry out most system administration functions you will need to be root.]]> Appearance: @@ -1861,8 +1916,7 @@ This is the file called 'foo2' Use: - -Two common targets in a Makefile + Two common targets in a Makefile are all and clean. Typically, invoking all will rebuild the @@ -1912,8 +1966,7 @@ This is the file called 'foo2' Use: - -The maxusers 10 line in the kernel + The maxusers 10 line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support.]]> @@ -1945,8 +1998,7 @@ This is the file called 'foo2' Use: - - + &prompt.user; man command ]]> @@ -1964,8 +2016,7 @@ This is the file called 'foo2' Use: - -The maxusers n + The maxusers n line in the kernel configuration file determines the size of many system tables, and is a rough guide to how many simultaneous logins the system will support. @@ -2015,8 +2066,7 @@ This is the file called 'foo2' <literal>id on chapters and sections</literal> - - + Introduction This is the introduction. It contains a subsection, @@ -2045,8 +2095,7 @@ This is the file called 'foo2' <sgmltag>anchor</sgmltag> - -This paragraph has an embedded + This paragraph has an embedded link target in it. It won't show up in the document.]]> @@ -2071,8 +2120,7 @@ This is the file called 'foo2' Assume that this fragment appears somewhere in a document that includes the id example; - -More information can be found + More information can be found in . More specific information can be found @@ -2113,8 +2161,7 @@ This is the file called 'foo2' Assume that this fragment appears somewhere in a document that includes the id example. - -More information can be found in + More information can be found in the first chapter. More specific information can be found in @@ -2164,8 +2211,7 @@ This is the file called 'foo2' Use: - -Of course, you could stop reading this document and + Of course, you could stop reading this document and go to the FreeBSD home page instead.]]> -- cgit v1.2.3
    Middle right cell