os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Re-write the three questions dealing with accessing the documentation

Browse source 
in other formats, including the obsolete information about needing to
do "col -b" and so on.

PR:             docs/13815
Submitted by:   wosch
This commit is contained in:
Nik Clayton 2000-05-23 00:44:07 +00:00
parent 22ac8a6302
commit 37898e6f64
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=7239
2 changed files with 542 additions and 138 deletions
en_US.ISO8859-1/books/faq
book.sgml
en_US.ISO_8859-1/books/faq
book.sgml

340
en_US.ISO8859-1/books/faq/book.sgml
View file

@ -13,7 +13,7 @@
</author>
</authorgroup>
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/faq/book.sgml,v 1.53 2000/05/07 16:35:23 joe Exp $</pubdate>
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/faq/book.sgml,v 1.54 2000/05/07 16:48:51 joe Exp $</pubdate>
<abstract>
<para>This is the FAQ for FreeBSD versions 2.X, 3.X, and 4.X. All entries
@ -708,98 +708,300 @@
<qandaentry>
<question>
<para>Where can I get ASCII/PostScript versions of the
FAQ?</para>
<para>Is the documentation available in other formats, such as plain
text (ASCII), or Postscript?</para>
</question>
<answer>
<para>The up-to-date FAQ is available from the FreeBSD Web
Server or any mirror as PostScript and plain text (7 bit ASCII
and 8-bit Latin1).</para>
<para>Yes. The documentation is available in a number of different
formats and compression schemes on the FreeBSD FTP site, in the
<ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</ulink> directory.</para>
<para>As PostScript (about 370KB):
<para>The documentation is categorised in a number of different
ways. These include:</para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/FAQ/FAQ.ps">http://www.FreeBSD.org/FAQ/FAQ.ps</ulink></para>
<para>The document's name, such as <literal>faq</literal>, or
<literal>handbook</literal>.</para>
</listitem>
</itemizedlist></para>
<para>As ASCII text (about 220KB):
<itemizedlist>
<listitem>
<para><ulink URL="http://www.FreeBSD.org/FAQ/FAQ.ascii">http://www.FreeBSD.org/FAQ/FAQ.ascii</ulink></para>
<para>The document's language and encoding. These are based on
the locale names you will find under
<filename>/usr/share/locale</filename> on your FreeBSD
system. The current languages and encodings that we have for
documentation are as follows:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>en_US.ISO_8859-1</literal></entry>
<entry>US English</entry>
</row>
<row>
<entry><literal>es_ES.ISO_8859-1</literal></entry>
<entry>Spanish</entry>
</row>
<row>
<entry><literal>fr_FR.ISO_8859-1</literal></entry>
<entry>French</entry>
</row>
<row>
<entry><literal>ja_JP.eucJP</literal></entry>
<entry>Japanese (EUC encoding)</entry>
</row>
<row>
<entry><literal>ru_RU.KOI8-R</literal></entry>
<entry>Russian</entry>
</row>
<row>
<entry><literal>zh_TW.Big5</literal></entry>
<entry>Chinese (Big5 encoding)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note>
<para>Some documents may not be available in all
languages.</para>
</note>
</listitem>
</itemizedlist></para>
<para>As ISO 8859-1 text (about 220KB):
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/FAQ/FAQ.latin1">http://www.FreeBSD.org/FAQ/FAQ.latin1</ulink></para>
<para>The document's format. We produce the documentation in a
number of different output formats to try and make it as
flexible as possible. The current formats are;</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Format</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>html-split</literal></entry>
<entry>A collection of small, linked, HTML
files.</entry>
</row>
<row>
<entry><literal>html</literal></entry>
<entry>One large HTML file containing the entire
document</entry>
</row>
<row>
<entry><literal>pdb</literal></entry>
<entry>Palm Pilot database format, for use with the
<ulink url="http://www.iSilo.com/">iSilo</ulink>
reader.</entry>
</row>
<row>
<entry><literal>pdf</literal></entry>
<entry>Adobe's Portable Document Format</entry>
</row>
<row>
<entry><literal>ps</literal></entry>
<entry>Postscript</entry>
</row>
<row>
<entry><literal>rtf</literal></entry>
<entry>Microsoft's Rich Text Format<footnote>
<para>Page numbers are not automatically updated
when loading this format in to Word. Press
<keycap>CTRL</keycap>+<keycap>A</keycap>,
<keycap>CTRL</keycap>+<keycap>END</keycap>,
<keycap>F9</keycap> after loading the document, to
update the page numbers.</para>
</footnote>
</entry>
</row>
<row>
<entry><literal>txt</literal></entry>
<entry>Plain text</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</itemizedlist></para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Where can I get ASCII/PostScript versions of the
Handbook?</para>
</question>
<answer>
<para>The up-to-date Handbook is available from the FreeBSD Web
Server or any mirror as PostScript and plain text (7 bit ASCII
and 8-bit Latin1).</para>
<para>As PostScript (about 1.7MB):
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/handbook/handbook.ps">http://www.FreeBSD.org/handbook/handbook.ps</ulink></para>
<para>The compression and packaging scheme. There are three of
these currently in use.</para>
<orderedlist>
<listitem>
<para>Where the format is <literal>html-split</literal>, the
files are bundled up using &man.tar.1;. The resulting
<filename>.tar</filename> file is then compressed using
the compression schemes detailed in the next point.</para>
</listitem>
<listitem>
<para>All the other formats generate one file, called
<filename>book.<replaceable>format</replaceable></filename>
(i.e., <filename>book.pdb</filename>,
<filename>book.html</filename>, and so on).</para>
<para>These files are then compressed using three
compression schemes.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Scheme</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>zip</literal></entry>
<entry>The Zip format. If you want to uncompress
this on FreeBSD you will need to install the
<filename>archivers/unzip</filename> port
first.</entry>
</row>
<row>
<entry><literal>gz</literal></entry>
<entry>The GNU Zip format. Use &man.gunzip.1; to
uncompress these files, which is part of
FreeBSD.</entry>
</row>
<row>
<entry><literal>bz2</literal></entry>
<entry>The BZip2 format. Less widespread than the
others, but generally gives smaller files.
Install the <filename>archivers/bzip2</filename>
port to uncompress these files.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>So the Postscript version of the Handbook, compressed
using BZip2 will be stored in a file called
<filename>book.sgml.bz2</filename> in the
<filename>handbook/</filename> directory.</para>
</listitem>
<listitem>
<para>The formatted documentation is also available as a
FreeBSD package, of which more later.</para>
</listitem>
</orderedlist>
</listitem>
</itemizedlist></para>
</itemizedlist>
<para>As ASCII text (about 1080KB):
<para>After choosing the format and compression mechanism that you
want to download, you must then decide whether or not you want to
download the document as a FreeBSD
<emphasis>package</emphasis>.</para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/handbook/handbook.ascii">http://www.FreeBSD.org/handbook/handbook.ascii</ulink></para>
</listitem>
</itemizedlist></para>
<para>The advantage of downloading and installing the package is
that the documentation can then be managed using the normal
FreeBSD package management comments, such as &man.pkg.add.1; and
&man.pkg.delete.1;.</para>
<para>As ISO 8859-1 text (about 1080KB):
<para>If you decide to download and install the package then you
must know the filename to download. The documentation-as-packages
files are stored in a directory called
<filename>packages</filename>. Each package file looks like
<filename><replaceable>document-name</replaceable>.<replaceable>lang</replaceable>.<replaceable>encoding</replaceable>.<replaceable>format</replaceable>.tgz</filename>.</para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/handbook/handbook.latin1">http://www.FreeBSD.org/handbook/handbook.latin1</ulink></para>
</listitem>
</itemizedlist></para>
</answer>
</qandaentry>
<para>For example, the FAQ, in English, formatted as PDF, is in the
package called
<filename>faq.en_US.ISO_8859-1.pdf.tgz</filename>.</para>
<qandaentry>
<question>
<para>The ASCII handbook isn't plain text!</para>
</question>
<para>Knowing this, you can use the following command to install the
English PDF FAQ package.</para>
<answer>
<para>True, the ASCII and Latin1 versions of the FAQ and
Handbook aren't strictly plaintext; they contain underlines
and overprints that assume the output is going directly to a
dot matrix printer. If you need to reformat them to be
human-readable, run the file through col:</para>
<screen>&prompt.root; <userinput>pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO_8859-1.pdf.tgz</userinput></screen>
<para>Having done that, you can use &man.pkg.info.1; to determine
where the file has been installed.</para>
<para>
<literallayout>
$ col -b &lt; inputfile &gt; outputfile</literallayout></para>
<screen>&prompt.root; <userinput>pkg_info -f faq.en_US.ISO_8859-1.pdf</userinput>
Information for faq.en_US.ISO_8859-1.pdf:
Packing list:
Package name: faq.en_US.ISO_8859-1.pdf
CWD to /usr/share/doc/en_US.ISO_8859-1/books/faq
File: book.pdf
CWD to .
File: +COMMENT (ignored)
File: +DESC (ignored)</screen>
<para>As you can see, <filename>book.pdf</filename> will have been
installed in to
<filename>/usr/share/doc/en_US.ISO_8859-1/books/faq</filename>.</para>
<para>If you do not want to use the packages then you will have to
download the compressed files yourself, uncompress them, and then
copy the appropriate documents in to place.</para>
<para>For example, the split HTML version of the FAQ, compressed
using &man.gzip.1;, can be found in the
<filename>en_US.ISO_8859-1/books/faq/book.html-split.tar.gz</filename>
file. To download and uncompress that file you would have to do
this.</para>
<screen>&prompt.root; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO_8859-1/books/faq/book.html-split.tar.gz</userinput>
&prompt.root; <userinput>gzip -d book.html-split.tar.gz</userinput>
&prompt.root; <userinput>tar xvf book.html-split.tar</userinput></screen>
<para>You will be left with a collection of
<filename>.html</filename> files. The main one is called
<filename>index.html</filename>, which will contain the table of
contents, introductory material, and links to the other parts of
the document. You can then copy or move these to their final
location as necessary.</para>
</answer>
</qandaentry>

340
en_US.ISO_8859-1/books/faq/book.sgml
View file

@ -13,7 +13,7 @@
</author>
</authorgroup>
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/faq/book.sgml,v 1.53 2000/05/07 16:35:23 joe Exp $</pubdate>
<pubdate>$FreeBSD: doc/en_US.ISO_8859-1/books/faq/book.sgml,v 1.54 2000/05/07 16:48:51 joe Exp $</pubdate>
<abstract>
<para>This is the FAQ for FreeBSD versions 2.X, 3.X, and 4.X. All entries
@ -708,98 +708,300 @@
<qandaentry>
<question>
<para>Where can I get ASCII/PostScript versions of the
FAQ?</para>
<para>Is the documentation available in other formats, such as plain
text (ASCII), or Postscript?</para>
</question>
<answer>
<para>The up-to-date FAQ is available from the FreeBSD Web
Server or any mirror as PostScript and plain text (7 bit ASCII
and 8-bit Latin1).</para>
<para>Yes. The documentation is available in a number of different
formats and compression schemes on the FreeBSD FTP site, in the
<ulink
url="ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/">/pub/FreeBSD/doc/</ulink> directory.</para>
<para>As PostScript (about 370KB):
<para>The documentation is categorised in a number of different
ways. These include:</para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/FAQ/FAQ.ps">http://www.FreeBSD.org/FAQ/FAQ.ps</ulink></para>
<para>The document's name, such as <literal>faq</literal>, or
<literal>handbook</literal>.</para>
</listitem>
</itemizedlist></para>
<para>As ASCII text (about 220KB):
<itemizedlist>
<listitem>
<para><ulink URL="http://www.FreeBSD.org/FAQ/FAQ.ascii">http://www.FreeBSD.org/FAQ/FAQ.ascii</ulink></para>
<para>The document's language and encoding. These are based on
the locale names you will find under
<filename>/usr/share/locale</filename> on your FreeBSD
system. The current languages and encodings that we have for
documentation are as follows:</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Name</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>en_US.ISO_8859-1</literal></entry>
<entry>US English</entry>
</row>
<row>
<entry><literal>es_ES.ISO_8859-1</literal></entry>
<entry>Spanish</entry>
</row>
<row>
<entry><literal>fr_FR.ISO_8859-1</literal></entry>
<entry>French</entry>
</row>
<row>
<entry><literal>ja_JP.eucJP</literal></entry>
<entry>Japanese (EUC encoding)</entry>
</row>
<row>
<entry><literal>ru_RU.KOI8-R</literal></entry>
<entry>Russian</entry>
</row>
<row>
<entry><literal>zh_TW.Big5</literal></entry>
<entry>Chinese (Big5 encoding)</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<note>
<para>Some documents may not be available in all
languages.</para>
</note>
</listitem>
</itemizedlist></para>
<para>As ISO 8859-1 text (about 220KB):
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/FAQ/FAQ.latin1">http://www.FreeBSD.org/FAQ/FAQ.latin1</ulink></para>
<para>The document's format. We produce the documentation in a
number of different output formats to try and make it as
flexible as possible. The current formats are;</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Format</entry>
<entry>Meaning</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>html-split</literal></entry>
<entry>A collection of small, linked, HTML
files.</entry>
</row>
<row>
<entry><literal>html</literal></entry>
<entry>One large HTML file containing the entire
document</entry>
</row>
<row>
<entry><literal>pdb</literal></entry>
<entry>Palm Pilot database format, for use with the
<ulink url="http://www.iSilo.com/">iSilo</ulink>
reader.</entry>
</row>
<row>
<entry><literal>pdf</literal></entry>
<entry>Adobe's Portable Document Format</entry>
</row>
<row>
<entry><literal>ps</literal></entry>
<entry>Postscript</entry>
</row>
<row>
<entry><literal>rtf</literal></entry>
<entry>Microsoft's Rich Text Format<footnote>
<para>Page numbers are not automatically updated
when loading this format in to Word. Press
<keycap>CTRL</keycap>+<keycap>A</keycap>,
<keycap>CTRL</keycap>+<keycap>END</keycap>,
<keycap>F9</keycap> after loading the document, to
update the page numbers.</para>
</footnote>
</entry>
</row>
<row>
<entry><literal>txt</literal></entry>
<entry>Plain text</entry>
</row>
</tbody>
</tgroup>
</informaltable>
</listitem>
</itemizedlist></para>
</answer>
</qandaentry>
<qandaentry>
<question>
<para>Where can I get ASCII/PostScript versions of the
Handbook?</para>
</question>
<answer>
<para>The up-to-date Handbook is available from the FreeBSD Web
Server or any mirror as PostScript and plain text (7 bit ASCII
and 8-bit Latin1).</para>
<para>As PostScript (about 1.7MB):
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/handbook/handbook.ps">http://www.FreeBSD.org/handbook/handbook.ps</ulink></para>
<para>The compression and packaging scheme. There are three of
these currently in use.</para>
<orderedlist>
<listitem>
<para>Where the format is <literal>html-split</literal>, the
files are bundled up using &man.tar.1;. The resulting
<filename>.tar</filename> file is then compressed using
the compression schemes detailed in the next point.</para>
</listitem>
<listitem>
<para>All the other formats generate one file, called
<filename>book.<replaceable>format</replaceable></filename>
(i.e., <filename>book.pdb</filename>,
<filename>book.html</filename>, and so on).</para>
<para>These files are then compressed using three
compression schemes.</para>
<informaltable frame="none">
<tgroup cols="2">
<thead>
<row>
<entry>Scheme</entry>
<entry>Description</entry>
</row>
</thead>
<tbody>
<row>
<entry><literal>zip</literal></entry>
<entry>The Zip format. If you want to uncompress
this on FreeBSD you will need to install the
<filename>archivers/unzip</filename> port
first.</entry>
</row>
<row>
<entry><literal>gz</literal></entry>
<entry>The GNU Zip format. Use &man.gunzip.1; to
uncompress these files, which is part of
FreeBSD.</entry>
</row>
<row>
<entry><literal>bz2</literal></entry>
<entry>The BZip2 format. Less widespread than the
others, but generally gives smaller files.
Install the <filename>archivers/bzip2</filename>
port to uncompress these files.</entry>
</row>
</tbody>
</tgroup>
</informaltable>
<para>So the Postscript version of the Handbook, compressed
using BZip2 will be stored in a file called
<filename>book.sgml.bz2</filename> in the
<filename>handbook/</filename> directory.</para>
</listitem>
<listitem>
<para>The formatted documentation is also available as a
FreeBSD package, of which more later.</para>
</listitem>
</orderedlist>
</listitem>
</itemizedlist></para>
</itemizedlist>
<para>As ASCII text (about 1080KB):
<para>After choosing the format and compression mechanism that you
want to download, you must then decide whether or not you want to
download the document as a FreeBSD
<emphasis>package</emphasis>.</para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/handbook/handbook.ascii">http://www.FreeBSD.org/handbook/handbook.ascii</ulink></para>
</listitem>
</itemizedlist></para>
<para>The advantage of downloading and installing the package is
that the documentation can then be managed using the normal
FreeBSD package management comments, such as &man.pkg.add.1; and
&man.pkg.delete.1;.</para>
<para>As ISO 8859-1 text (about 1080KB):
<para>If you decide to download and install the package then you
must know the filename to download. The documentation-as-packages
files are stored in a directory called
<filename>packages</filename>. Each package file looks like
<filename><replaceable>document-name</replaceable>.<replaceable>lang</replaceable>.<replaceable>encoding</replaceable>.<replaceable>format</replaceable>.tgz</filename>.</para>
<itemizedlist>
<listitem>
<para><ulink
URL="http://www.FreeBSD.org/handbook/handbook.latin1">http://www.FreeBSD.org/handbook/handbook.latin1</ulink></para>
</listitem>
</itemizedlist></para>
</answer>
</qandaentry>
<para>For example, the FAQ, in English, formatted as PDF, is in the
package called
<filename>faq.en_US.ISO_8859-1.pdf.tgz</filename>.</para>
<qandaentry>
<question>
<para>The ASCII handbook isn't plain text!</para>
</question>
<para>Knowing this, you can use the following command to install the
English PDF FAQ package.</para>
<answer>
<para>True, the ASCII and Latin1 versions of the FAQ and
Handbook aren't strictly plaintext; they contain underlines
and overprints that assume the output is going directly to a
dot matrix printer. If you need to reformat them to be
human-readable, run the file through col:</para>
<screen>&prompt.root; <userinput>pkg_add ftp://ftp.FreeBSD.org/pub/FreeBSD/doc/packages/faq.en_US.ISO_8859-1.pdf.tgz</userinput></screen>
<para>Having done that, you can use &man.pkg.info.1; to determine
where the file has been installed.</para>
<para>
<literallayout>
$ col -b &lt; inputfile &gt; outputfile</literallayout></para>
<screen>&prompt.root; <userinput>pkg_info -f faq.en_US.ISO_8859-1.pdf</userinput>
Information for faq.en_US.ISO_8859-1.pdf:
Packing list:
Package name: faq.en_US.ISO_8859-1.pdf
CWD to /usr/share/doc/en_US.ISO_8859-1/books/faq
File: book.pdf
CWD to .
File: +COMMENT (ignored)
File: +DESC (ignored)</screen>
<para>As you can see, <filename>book.pdf</filename> will have been
installed in to
<filename>/usr/share/doc/en_US.ISO_8859-1/books/faq</filename>.</para>
<para>If you do not want to use the packages then you will have to
download the compressed files yourself, uncompress them, and then
copy the appropriate documents in to place.</para>
<para>For example, the split HTML version of the FAQ, compressed
using &man.gzip.1;, can be found in the
<filename>en_US.ISO_8859-1/books/faq/book.html-split.tar.gz</filename>
file. To download and uncompress that file you would have to do
this.</para>
<screen>&prompt.root; <userinput>fetch ftp://ftp.freebsd.org/pub/FreeBSD/doc/en_US.ISO_8859-1/books/faq/book.html-split.tar.gz</userinput>
&prompt.root; <userinput>gzip -d book.html-split.tar.gz</userinput>
&prompt.root; <userinput>tar xvf book.html-split.tar</userinput></screen>
<para>You will be left with a collection of
<filename>.html</filename> files. The main one is called
<filename>index.html</filename>, which will contain the table of
contents, introductory material, and links to the other parts of
the document. You can then copy or move these to their final
location as necessary.</para>
</answer>
</qandaentry>