git: 59733057fc - main - Update FAQ 2.2 with current doc layout and formats.

Go to: [ bottom of page ] [ top of archives ] [ this month ]
From: Pau Amma <pauamma_at_FreeBSD.org>
Date: Mon, 31 Oct 2022 16:33:30 UTC
The branch main has been updated by pauamma:

URL: https://cgit.FreeBSD.org/doc/commit/?id=59733057fc1332d59b669b4e065268f42ede1dfd

commit 59733057fc1332d59b669b4e065268f42ede1dfd
Author:     Pau Amma <pauamma@FreeBSD.org>
AuthorDate: 2022-10-13 02:54:26 +0000
Commit:     Pau Amma <pauamma@FreeBSD.org>
CommitDate: 2022-10-31 16:30:42 +0000

    Update FAQ 2.2 with current doc layout and formats.
    
    Graham Perrin's changes and a few I only spotted now.
    
    Reviewed by:    gjb, grahamperrin
    
    Approved by:    gjb (mentor)
    
    Differential Revision:  https://reviews.freebsd.org/D36976
---
 documentation/content/en/books/faq/_index.adoc | 113 +++++++++++--------------
 1 file changed, 50 insertions(+), 63 deletions(-)

diff --git a/documentation/content/en/books/faq/_index.adoc b/documentation/content/en/books/faq/_index.adoc
index 5ea65360d4..45e849d05b 100644
--- a/documentation/content/en/books/faq/_index.adoc
+++ b/documentation/content/en/books/faq/_index.adoc
@@ -263,16 +263,15 @@ Before submitting a problem report, read extref:{problem-reports}[Writing FreeBS
 The project produces a wide range of documentation, available online from this link: https://www.FreeBSD.org/docs/[https://www.FreeBSD.org/docs/]. 
 
 [[doc-formats]]
-=== Is the documentation available in other formats, such as plain text (ASCII), or PDF?
+=== Is the documentation available in other formats, such as PDF?
 
-Yes. The documentation is available in a number of different formats and compression schemes on the FreeBSD FTP site,
-in the https://download.freebsd.org/doc/[/doc/] directory.
+Yes.
+link:https://download.freebsd.org/doc/[The documentation is also available in several formats] on the FreeBSD download site.
 
-The documentation is categorized in a number of different ways.
-These include:
+Documentation directories are categorized according to:
 
 * The document's name, such as `faq`, or `handbook`.
-* The document's language and encoding. These are based on the locale names found under [.filename]#/usr/share/locale# on a FreeBSD system. The current languages and encodings are as follows:
+* The document's language, based on the locale names found under [.filename]#/usr/share/locale# on a FreeBSD system, with the encodings removed as all documentation now uses UTF-8. The current languages are:
 +
 [.informaltable]
 [cols="1,1", frame="none", options="header"]
@@ -280,62 +279,62 @@ These include:
 | Name
 | Meaning
 
-|`en_US.ISO8859-1`
-|English (United States)
+|`en`
+|English
 
-|`bn_BD.ISO10646-1`
+|`bn-bd`
 |Bengali or Bangla (Bangladesh)
 
-|`da_DK.ISO8859-1`
-|Danish (Denmark)
+|`da`
+|Danish
 
-|`de_DE.ISO8859-1`
-|German (Germany)
+|`de`
+|German
 
-|`el_GR.ISO8859-7`
-|Greek (Greece)
+|`el`
+|Greek
 
-|`es_ES.ISO8859-1`
-|Spanish (Spain)
+|`es`
+|Spanish
 
-|`fr_FR.ISO8859-1`
-|French (France)
+|`fr`
+|French
 
-|`hu_HU.ISO8859-2`
-|Hungarian (Hungary)
+|`hu`
+|Hungarian
 
-|`it_IT.ISO8859-15`
-|Italian (Italy)
+|`it`
+|Italian
 
-|`ja_JP.eucJP`
-|Japanese (Japan, EUC encoding)
+|`ja`
+|Japanese
 
-|`ko_KR.UTF-8`
-|Korean (Korea, UTF-8 encoding)
+|`ko`
+|Korean
 
-|`mn_MN.UTF-8`
-|Mongolian (Mongolia, UTF-8 encoding)
+|`mn`
+|Mongolian
 
-|`nl_NL.ISO8859-1`
-|Dutch (Netherlands)
+|`nl`
+|Dutch
 
-|`pl_PL.ISO8859-2`
-|Polish (Poland)
+|`pl`
+|Polish
 
-|`pt_BR.ISO8859-1`
+|`pt-br`
 |Portuguese (Brazil)
 
-|`ru_RU.KOI8-R`
-|Russian (Russia, KOI8-R encoding)
+|`ru`
+|Russian
 
-|`tr_TR.ISO8859-9`
-|Turkish (Turkey)
+|`tr`
+|Turkish
 
-|`zh_CN.UTF-8`
-|Simplified Chinese (China, UTF-8 encoding)
+|`zh-cn`
+|Simplified Chinese (China)
 
-|`zh_TW.UTF-8`
-|Traditional Chinese (Taiwan, UTF-8 encoding)
+|`zh-tw`
+|Traditional Chinese (Taiwan)
 |===
 +
 [NOTE]
@@ -351,41 +350,29 @@ Some documents may not be available in all languages.
 | Format
 | Meaning
 
-|`html-split`
-|A collection of small, linked, HTML files.
-
 |`html`
-|One large HTML file containing the entire document
+|Depending on the document: one large HTML file containing the entire document or a collection of small linked HTML files, both together with images, stylesheets, and JavaScript
 
 |`pdf`
 |Adobe's Portable Document Format
-
-|`txt`
-|Plain text
 |===
 * The compression and packaging scheme.
-.. Where the format is `html-split`, the files are bundled up using man:tar[1]. The resulting [.filename]#.tar# is then compressed using the compression schemes detailed in the next point.
-.. All the other formats generate one file. For example, [.filename]#article.pdf#, [.filename]#book.html#, and so on.
-+
-These files are then compressed using either the `zip` or `bz2` compression schemes.
-man:tar[1] can be used to uncompress these files.
-+
-So the PDF version of the Handbook, compressed using `bzip2` will be stored in a file called [.filename]#book.pdf.bz2# in the [.filename]#handbook/# directory.
+.. Where the format is `html`, the files are bundled up using man:tar[1]. The resulting [.filename]#.tar# is then compressed using man:gzip[1].
+.. The PDF format generates one file. For example, [.filename]#explaining-bsd_en.pdf#, [.filename]#faq_en.pdf#, and so on.
 
-After choosing the format and compression mechanism, download the compressed files, uncompress them, and then copy the appropriate documents into place.
+After choosing the format, download the files, uncompress them if necessary, then copy the appropriate documents into place.
 
-For example, the split HTML version of the FAQ, compressed using man:bzip2[1],
-can be found in [.filename]#doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2# To download and uncompress that file, type:
+For example, the HTML version of the FAQ can be found in [.filename]#doc/en/books/faq/faq_en.tar.gz# To download and uncompress that file, type:
 
 [source,shell]
 ....
-# fetch https://download.freebsd.org/doc/en_US.ISO8859-1/books/faq/book.html-split.tar.bz2
-# tar xvf book.html-split.tar.bz2
+% fetch https://download.freebsd.org/doc/en/books/faq/faq_en.tar.gz
+% tar xvf faq_en.tar.gz
 ....
 
 If the file is compressed, tar will automatically detect the appropriate format and decompress it correctly,
-resulting in a collection of [.filename]#.html# files.
-The main one is called [.filename]#index.html#, which will contain the table of contents, introductory material, and links to the other parts of the document.
+resulting in a collection of files.
+The main one is called [.filename]#index.html#, which will contain the whole document, starting with the table of contents linking to the other parts of the document.
 
 [[mailing]]
 === Where do I find info on the FreeBSD mailing lists? What FreeBSD news groups are available?