diff --git a/en/tutorials/docproj-primer/tools/chapter.sgml b/en/tutorials/docproj-primer/tools/chapter.sgml
index 2080134fad..92c310a37e 100644
--- a/en/tutorials/docproj-primer/tools/chapter.sgml
+++ b/en/tutorials/docproj-primer/tools/chapter.sgml
@@ -1,9 +1,48 @@
+
+
- * Tools
+ Tools
- The Documentation Project uses a number of tools to assist in the
- production of documentation. You will need to install some or all of these
- tools before you will be able to make changes.
+ 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.
+
+ All these tools are available as FreeBSD Ports and Packages,
+ greatly simplifying the work you have to do to install
+ them.
+
+ 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 these later chapters.
Use <filename>textproc/docproj</filename> if possible
@@ -33,168 +72,201 @@
as necessary.
-
+
- Software
-
- The project uses the following applications;
-
-
-
- Jade and
- SP
-
-
- These are two application suites by James Clark, who has
- produced many useful SGML-processing applications.
- Jade is “James' DSSSL
- Engine”, a system that takes SGML documentation and a DSSSL
- stylesheet and produces converted output.
- SP contains a number of useful
- applications to manipulate, normalise, and interrogate SGML
- documents.
+ Mandatory tools
- Don't be concerned if these terms are unfamliar to you.
-
- They can be found in the ports system as
- textproc/jade and
- textproc/sp respectively.
-
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
- teTeX
-
-
- teTeX is a distrubution of the TeX
- typesetting system, and is used (in conjunction with Jade) to
- produce the Postscript and PDF output formats.
-
- v0.9 of teTeX is required, which is
- currently in the ports collection as
- print/teTeX-beta.
-
-
- Might be installed as part of
- textproc/docproj, depending on the
- JADETEX setting.
-
-
-
+
+ Software
-
- Emacs or
- Xemacs
+ These programs are required before you can usefully work with
+ the FreeBSD documentation. They are all included in
+ textproc/docproj.
+
+
+
+ SP
+ (textproc/sp)
-
- Neither of these programs is required. However, both of them
- feature PSGML-MODE, a useful extension when dealing with SGML
- documents that can reduce the amount of typing you need to do, and
- remove some of the more obvious errors.
+
+ A suite of applications, including a validating SGML parser,
+ and an SGML normaliser.
+
+
+
+
+ Jade
+ (textproc/jade)
+
+
+ A DSSSL implementation. Used for converting marked up
+ documents to other formats, including HTML and TeX.
+
+
+
+
+ Tidy
+ (www/tidy)
+
+
+ An HTML 'pretty printer', used to reformat some of the
+ automatically generated HTML so that it is easier to
+ follow.
+
+
+
+
+ Lynx
+ (www/lynx-current)
+
+
+ A text-mode WWW browser, &man.lynx.1; can also convert
+ HTML files to plain text.
+
+
+
+
- They can be found in editor/emacs20 and
- editor/xemacs20.
+
+ DTDs and Entities
-
- Not installed as part of
- textproc/docproj.
-
-
-
-
+ 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.
+
+
+
+ HTML DTD (textproc/html)
+
+
+ HTML is the markup language of choice for the World Wide
+ Web, and is used throughout the FreeBSD web site.
+
+
+
+
+ LinuxDoc DTD (textproc/linuxdoc)
+
+
+ Some FreeBSD documentation is marked up in LinuxDoc. The
+ FDP is actively migrating from LinuxDoc to DocBook.
+
+
+
+
+ DocBook DTD (textproc/docbook)
+
+
+ DocBook is designed for marking up technical documentation,
+ and the FDP is migrating from LinuxDoc to DocBook. At the time
+ of writing, this document, and the FreeBSD Handbook are marked
+ up in DocBook.
+
+
+
+
+ ISO 8879 entities
+ (textproc/iso8879)
+
+
+ 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.
+
+
+
+
+
+
+ Stylesheets
+
+ The stylesheets are used when converting and formatting the
+ documentation for display on screen, printing, and so on.
+
+
+
+ Modular DocBook Stylesheets
+ (textproc/dsssl-docbook-modular)
+
+
+ The Modular DocBook Stylesheets are used when converting
+ documentation marked up in DocBook to other formats, such as
+ HTML, or RTF.
+
+
+
+
- Document Type Definitions (DTDs)
-
- The project uses the following DTDs;
-
-
-
- HTML
-
-
- HTML, the HyperText Markup Language, is the markup language of
- choice on the World Wide Web. More information can be found at
- <URL:http://www.w3.org/>.
+ Optional tools
- HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
- and the latest, 4.0 (available in both strict
- and loose variants).
+ 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.
+
+
+ Software
+
+
+
+ JadeTeX and
+ teTeX
+ (print/jadetex and
+ print/teTeX-beta)
- The HTML DTDs are available from the ports collection in the
- textproc/html category.
+
+ Jade and
+ teTeX are used to convert DocBook
+ documents to DVI, Postscript, and PDF formats. The
+ JadeTeX macros are needed in order to
+ do this.
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
- LinuxDoc
+ If you do not intend to convert your documentation to one of
+ these formats (i.e., HTML, plain text, and RTF are sufficient)
+ then you do not need to install
+ JadeTeX and
+ teTeX. This can be a significant
+ space and time saver, as teTeX is
+ over 30MB in size.
+
+
+ If you decide to install
+ JadeTeX and
+ teTeX then you will need to
+ configure teTeX after
+ JadeTeX has been installed.
+ print/jadetex/pkg/MESSAGE contains
+ detailed instructions explaining what you need to do.
+
+
+
-
- LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
- the Linux Documentation
- Project, and subsequently adopted by the FreeBSD
- Documentation Project.
+
+ Emacs or
+ xemacs
+ (editors/emacs or
+ editors/xemacs)
+
+
+ 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 errors.
- The LinuxDoc DTD contains primarily appearance related markup
- rather than content related markup (i.e., it describes what
- something looks like rather than what it is).
-
- Both the FreeBSD Documentation Project and the Linux
- Documentation Project are migrating from the LinuxDoc DTD to the
- DocBook DTD.
-
- The LinuxDoc DTD is available from the ports collection in the
- textproc/linuxdoc category.
-
-
- Installed as part of
- textproc/docproj.
-
-
-
+ You do not need to use them, any text editor can be used to
+ edit marked up documents. Yoy may find they make you
+ efficient.
+
+
+
-
- DocBook
-
-
- DocBook was designed by the Davenport Group
- to be a DTD for writing technical documentation. As such, it
- contains XXX
-
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
-
-
- DSSSL Stylesheets
-
- The Documentation Project uses a slightly customised version of
- Norm Walsh's modular DocBook stylesheets.
-
- These can be found in
- textproc/dsssl-docbook-modular.
-
-
- Installed as part of textproc/docproj.
-
+ If anyone has recommendations for other software that is useful
+ when manipulating SGML documents, please let Nik Clayton
+ (nik@freebsd.org) know, so they can be added to this
+ list.
+
diff --git a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
index 2080134fad..92c310a37e 100644
--- a/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
+++ b/en_US.ISO8859-1/books/fdp-primer/tools/chapter.sgml
@@ -1,9 +1,48 @@
+
+
- * Tools
+ Tools
- The Documentation Project uses a number of tools to assist in the
- production of documentation. You will need to install some or all of these
- tools before you will be able to make changes.
+ 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.
+
+ All these tools are available as FreeBSD Ports and Packages,
+ greatly simplifying the work you have to do to install
+ them.
+
+ 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 these later chapters.
Use <filename>textproc/docproj</filename> if possible
@@ -33,168 +72,201 @@
as necessary.
-
+
- Software
-
- The project uses the following applications;
-
-
-
- Jade and
- SP
-
-
- These are two application suites by James Clark, who has
- produced many useful SGML-processing applications.
- Jade is “James' DSSSL
- Engine”, a system that takes SGML documentation and a DSSSL
- stylesheet and produces converted output.
- SP contains a number of useful
- applications to manipulate, normalise, and interrogate SGML
- documents.
+ Mandatory tools
- Don't be concerned if these terms are unfamliar to you.
-
- They can be found in the ports system as
- textproc/jade and
- textproc/sp respectively.
-
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
- teTeX
-
-
- teTeX is a distrubution of the TeX
- typesetting system, and is used (in conjunction with Jade) to
- produce the Postscript and PDF output formats.
-
- v0.9 of teTeX is required, which is
- currently in the ports collection as
- print/teTeX-beta.
-
-
- Might be installed as part of
- textproc/docproj, depending on the
- JADETEX setting.
-
-
-
+
+ Software
-
- Emacs or
- Xemacs
+ These programs are required before you can usefully work with
+ the FreeBSD documentation. They are all included in
+ textproc/docproj.
+
+
+
+ SP
+ (textproc/sp)
-
- Neither of these programs is required. However, both of them
- feature PSGML-MODE, a useful extension when dealing with SGML
- documents that can reduce the amount of typing you need to do, and
- remove some of the more obvious errors.
+
+ A suite of applications, including a validating SGML parser,
+ and an SGML normaliser.
+
+
+
+
+ Jade
+ (textproc/jade)
+
+
+ A DSSSL implementation. Used for converting marked up
+ documents to other formats, including HTML and TeX.
+
+
+
+
+ Tidy
+ (www/tidy)
+
+
+ An HTML 'pretty printer', used to reformat some of the
+ automatically generated HTML so that it is easier to
+ follow.
+
+
+
+
+ Lynx
+ (www/lynx-current)
+
+
+ A text-mode WWW browser, &man.lynx.1; can also convert
+ HTML files to plain text.
+
+
+
+
- They can be found in editor/emacs20 and
- editor/xemacs20.
+
+ DTDs and Entities
-
- Not installed as part of
- textproc/docproj.
-
-
-
-
+ 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.
+
+
+
+ HTML DTD (textproc/html)
+
+
+ HTML is the markup language of choice for the World Wide
+ Web, and is used throughout the FreeBSD web site.
+
+
+
+
+ LinuxDoc DTD (textproc/linuxdoc)
+
+
+ Some FreeBSD documentation is marked up in LinuxDoc. The
+ FDP is actively migrating from LinuxDoc to DocBook.
+
+
+
+
+ DocBook DTD (textproc/docbook)
+
+
+ DocBook is designed for marking up technical documentation,
+ and the FDP is migrating from LinuxDoc to DocBook. At the time
+ of writing, this document, and the FreeBSD Handbook are marked
+ up in DocBook.
+
+
+
+
+ ISO 8879 entities
+ (textproc/iso8879)
+
+
+ 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.
+
+
+
+
+
+
+ Stylesheets
+
+ The stylesheets are used when converting and formatting the
+ documentation for display on screen, printing, and so on.
+
+
+
+ Modular DocBook Stylesheets
+ (textproc/dsssl-docbook-modular)
+
+
+ The Modular DocBook Stylesheets are used when converting
+ documentation marked up in DocBook to other formats, such as
+ HTML, or RTF.
+
+
+
+
- Document Type Definitions (DTDs)
-
- The project uses the following DTDs;
-
-
-
- HTML
-
-
- HTML, the HyperText Markup Language, is the markup language of
- choice on the World Wide Web. More information can be found at
- <URL:http://www.w3.org/>.
+ Optional tools
- HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
- and the latest, 4.0 (available in both strict
- and loose variants).
+ 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.
+
+
+ Software
+
+
+
+ JadeTeX and
+ teTeX
+ (print/jadetex and
+ print/teTeX-beta)
- The HTML DTDs are available from the ports collection in the
- textproc/html category.
+
+ Jade and
+ teTeX are used to convert DocBook
+ documents to DVI, Postscript, and PDF formats. The
+ JadeTeX macros are needed in order to
+ do this.
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
- LinuxDoc
+ If you do not intend to convert your documentation to one of
+ these formats (i.e., HTML, plain text, and RTF are sufficient)
+ then you do not need to install
+ JadeTeX and
+ teTeX. This can be a significant
+ space and time saver, as teTeX is
+ over 30MB in size.
+
+
+ If you decide to install
+ JadeTeX and
+ teTeX then you will need to
+ configure teTeX after
+ JadeTeX has been installed.
+ print/jadetex/pkg/MESSAGE contains
+ detailed instructions explaining what you need to do.
+
+
+
-
- LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
- the Linux Documentation
- Project, and subsequently adopted by the FreeBSD
- Documentation Project.
+
+ Emacs or
+ xemacs
+ (editors/emacs or
+ editors/xemacs)
+
+
+ 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 errors.
- The LinuxDoc DTD contains primarily appearance related markup
- rather than content related markup (i.e., it describes what
- something looks like rather than what it is).
-
- Both the FreeBSD Documentation Project and the Linux
- Documentation Project are migrating from the LinuxDoc DTD to the
- DocBook DTD.
-
- The LinuxDoc DTD is available from the ports collection in the
- textproc/linuxdoc category.
-
-
- Installed as part of
- textproc/docproj.
-
-
-
+ You do not need to use them, any text editor can be used to
+ edit marked up documents. Yoy may find they make you
+ efficient.
+
+
+
-
- DocBook
-
-
- DocBook was designed by the Davenport Group
- to be a DTD for writing technical documentation. As such, it
- contains XXX
-
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
-
-
- DSSSL Stylesheets
-
- The Documentation Project uses a slightly customised version of
- Norm Walsh's modular DocBook stylesheets.
-
- These can be found in
- textproc/dsssl-docbook-modular.
-
-
- Installed as part of textproc/docproj.
-
+ If anyone has recommendations for other software that is useful
+ when manipulating SGML documents, please let Nik Clayton
+ (nik@freebsd.org) know, so they can be added to this
+ list.
+
diff --git a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml
index 2080134fad..92c310a37e 100644
--- a/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml
+++ b/en_US.ISO_8859-1/books/fdp-primer/tools/chapter.sgml
@@ -1,9 +1,48 @@
+
+
- * Tools
+ Tools
- The Documentation Project uses a number of tools to assist in the
- production of documentation. You will need to install some or all of these
- tools before you will be able to make changes.
+ 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.
+
+ All these tools are available as FreeBSD Ports and Packages,
+ greatly simplifying the work you have to do to install
+ them.
+
+ 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 these later chapters.
Use <filename>textproc/docproj</filename> if possible
@@ -33,168 +72,201 @@
as necessary.
-
+
- Software
-
- The project uses the following applications;
-
-
-
- Jade and
- SP
-
-
- These are two application suites by James Clark, who has
- produced many useful SGML-processing applications.
- Jade is “James' DSSSL
- Engine”, a system that takes SGML documentation and a DSSSL
- stylesheet and produces converted output.
- SP contains a number of useful
- applications to manipulate, normalise, and interrogate SGML
- documents.
+ Mandatory tools
- Don't be concerned if these terms are unfamliar to you.
-
- They can be found in the ports system as
- textproc/jade and
- textproc/sp respectively.
-
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
- teTeX
-
-
- teTeX is a distrubution of the TeX
- typesetting system, and is used (in conjunction with Jade) to
- produce the Postscript and PDF output formats.
-
- v0.9 of teTeX is required, which is
- currently in the ports collection as
- print/teTeX-beta.
-
-
- Might be installed as part of
- textproc/docproj, depending on the
- JADETEX setting.
-
-
-
+
+ Software
-
- Emacs or
- Xemacs
+ These programs are required before you can usefully work with
+ the FreeBSD documentation. They are all included in
+ textproc/docproj.
+
+
+
+ SP
+ (textproc/sp)
-
- Neither of these programs is required. However, both of them
- feature PSGML-MODE, a useful extension when dealing with SGML
- documents that can reduce the amount of typing you need to do, and
- remove some of the more obvious errors.
+
+ A suite of applications, including a validating SGML parser,
+ and an SGML normaliser.
+
+
+
+
+ Jade
+ (textproc/jade)
+
+
+ A DSSSL implementation. Used for converting marked up
+ documents to other formats, including HTML and TeX.
+
+
+
+
+ Tidy
+ (www/tidy)
+
+
+ An HTML 'pretty printer', used to reformat some of the
+ automatically generated HTML so that it is easier to
+ follow.
+
+
+
+
+ Lynx
+ (www/lynx-current)
+
+
+ A text-mode WWW browser, &man.lynx.1; can also convert
+ HTML files to plain text.
+
+
+
+
- They can be found in editor/emacs20 and
- editor/xemacs20.
+
+ DTDs and Entities
-
- Not installed as part of
- textproc/docproj.
-
-
-
-
+ 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.
+
+
+
+ HTML DTD (textproc/html)
+
+
+ HTML is the markup language of choice for the World Wide
+ Web, and is used throughout the FreeBSD web site.
+
+
+
+
+ LinuxDoc DTD (textproc/linuxdoc)
+
+
+ Some FreeBSD documentation is marked up in LinuxDoc. The
+ FDP is actively migrating from LinuxDoc to DocBook.
+
+
+
+
+ DocBook DTD (textproc/docbook)
+
+
+ DocBook is designed for marking up technical documentation,
+ and the FDP is migrating from LinuxDoc to DocBook. At the time
+ of writing, this document, and the FreeBSD Handbook are marked
+ up in DocBook.
+
+
+
+
+ ISO 8879 entities
+ (textproc/iso8879)
+
+
+ 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.
+
+
+
+
+
+
+ Stylesheets
+
+ The stylesheets are used when converting and formatting the
+ documentation for display on screen, printing, and so on.
+
+
+
+ Modular DocBook Stylesheets
+ (textproc/dsssl-docbook-modular)
+
+
+ The Modular DocBook Stylesheets are used when converting
+ documentation marked up in DocBook to other formats, such as
+ HTML, or RTF.
+
+
+
+
- Document Type Definitions (DTDs)
-
- The project uses the following DTDs;
-
-
-
- HTML
-
-
- HTML, the HyperText Markup Language, is the markup language of
- choice on the World Wide Web. More information can be found at
- <URL:http://www.w3.org/>.
+ Optional tools
- HTML has gone through a number of versions, 1, 2, 3.0, 3.2,
- and the latest, 4.0 (available in both strict
- and loose variants).
+ 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.
+
+
+ Software
+
+
+
+ JadeTeX and
+ teTeX
+ (print/jadetex and
+ print/teTeX-beta)
- The HTML DTDs are available from the ports collection in the
- textproc/html category.
+
+ Jade and
+ teTeX are used to convert DocBook
+ documents to DVI, Postscript, and PDF formats. The
+ JadeTeX macros are needed in order to
+ do this.
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
- LinuxDoc
+ If you do not intend to convert your documentation to one of
+ these formats (i.e., HTML, plain text, and RTF are sufficient)
+ then you do not need to install
+ JadeTeX and
+ teTeX. This can be a significant
+ space and time saver, as teTeX is
+ over 30MB in size.
+
+
+ If you decide to install
+ JadeTeX and
+ teTeX then you will need to
+ configure teTeX after
+ JadeTeX has been installed.
+ print/jadetex/pkg/MESSAGE contains
+ detailed instructions explaining what you need to do.
+
+
+
-
- LinuxDoc is an adaptation of the QWERTZ DTD, first adopted by
- the Linux Documentation
- Project, and subsequently adopted by the FreeBSD
- Documentation Project.
+
+ Emacs or
+ xemacs
+ (editors/emacs or
+ editors/xemacs)
+
+
+ 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 errors.
- The LinuxDoc DTD contains primarily appearance related markup
- rather than content related markup (i.e., it describes what
- something looks like rather than what it is).
-
- Both the FreeBSD Documentation Project and the Linux
- Documentation Project are migrating from the LinuxDoc DTD to the
- DocBook DTD.
-
- The LinuxDoc DTD is available from the ports collection in the
- textproc/linuxdoc category.
-
-
- Installed as part of
- textproc/docproj.
-
-
-
+ You do not need to use them, any text editor can be used to
+ edit marked up documents. Yoy may find they make you
+ efficient.
+
+
+
-
- DocBook
-
-
- DocBook was designed by the Davenport Group
- to be a DTD for writing technical documentation. As such, it
- contains XXX
-
-
- Installed as part of
- textproc/docproj.
-
-
-
-
-
-
-
- DSSSL Stylesheets
-
- The Documentation Project uses a slightly customised version of
- Norm Walsh's modular DocBook stylesheets.
-
- These can be found in
- textproc/dsssl-docbook-modular.
-
-
- Installed as part of textproc/docproj.
-
+ If anyone has recommendations for other software that is useful
+ when manipulating SGML documents, please let Nik Clayton
+ (nik@freebsd.org) know, so they can be added to this
+ list.
+