diff --git a/zh_TW.UTF-8/books/fdp-primer/Makefile b/zh_TW.UTF-8/books/fdp-primer/Makefile
index e53528b90e0d..594aaefe3dda 100644
--- a/zh_TW.UTF-8/books/fdp-primer/Makefile
+++ b/zh_TW.UTF-8/books/fdp-primer/Makefile
@@ -28,9 +28,6 @@ IMAGES_LIB+= callouts/3.png
IMAGES_LIB+= callouts/4.png
IMAGES_LIB+= callouts/5.png
-# Entities
-SRCS+= chapters.ent
-
URL_RELPREFIX?= ../../../..
DOC_PREFIX?= ${.CURDIR}/../../..
diff --git a/zh_TW.UTF-8/books/fdp-primer/chapters.ent b/zh_TW.UTF-8/books/fdp-primer/chapters.ent
deleted file mode 100644
index a3d22b4c726b..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/chapters.ent
+++ /dev/null
@@ -1,27 +0,0 @@
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml
deleted file mode 100644
index 993215788178..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/doc-build/chapter.xml
+++ /dev/null
@@ -1,486 +0,0 @@
-
-
-
- The Documentation Build Process
-
- This chapter's main purpose is to clearly explain how
- the documentation build process is organized, and
- how to affect modifications to this process.
-
-
- After you have finished reading this chapter you should:
-
-
-
- Know what you need to build the FDP documentation, in
- addition to those mentioned in the SGML tools chapter.
-
-
-
- Be able to read and understand the
- make instructions that are present in
- each document's Makefiles, as well as an
- overview of the doc.project.mk includes.
-
-
-
- Be able to customize the build process by using
- make variables and
- make targets.
-
-
-
-
- The FreeBSD Documentation Build Toolset
-
- Here are your tools. Use them every way you can.
-
-
-
- The primary build tool you will need is
- make, but specifically
- Berkeley Make.
-
-
-
- Package building is handled by FreeBSD's
- pkg_create. If you are not using
- FreeBSD, you will either have to live without packages, or
- compile the source yourself.
-
-
-
- gzip is needed to create
- compressed versions of the document.
- bzip2 compression and
- zip archives are also supported.
- tar is supported, but package
- building demands it.
-
-
-
- install is the default method
- to install the documentation. There are alternatives,
- however.
-
-
-
-
- It is unlikely you will have any trouble finding these last two, they
- are mentioned for completeness only.
-
-
-
-
- Understanding Makefiles in the Documentation tree
-
- There are three main types of Makefiles
- in the FreeBSD Documentation Project tree.
-
-
-
- Subdirectory
- Makefiles simply pass
- commands to those directories below them.
-
-
-
- Documentation
- Makefiles describe the
- document(s) that should be produced from this directory.
-
-
-
- Make
- includes are the glue that perform the document production,
- and are usually of the form
- doc.xxx.mk.
-
-
-
-
- Subdirectory Makefiles
-
- These Makefiles usually take the form of:
-
- SUBDIR =articles
-SUBDIR+=books
-
-COMPAT_SYMLINK = en
-
-DOC_PREFIX?= ${.CURDIR}/..
-.include "${DOC_PREFIX}/share/mk/doc.project.mk"
-
- In quick summary, the first four non-empty lines define the
- make variables,
- SUBDIR, COMPAT_SYMLINK,
- and DOC_PREFIX.
-
- The first SUBDIR statement, as well as
- the COMPAT_SYMLINK statement, shows how to
- assign a value to a variable, overriding any previous
- value.
-
- The second SUBDIR statement shows how a
- value is appended to the current value of a variable. The
- SUBDIR variable is now articles
- books.
-
- The DOC_PREFIX assignment shows how a
- value is assigned to the variable, but only if it is not already
- defined. This is useful if DOC_PREFIX is not
- where this Makefile thinks it is - the user
- can override this and provide the correct value.
-
- Now what does it all mean? SUBDIR
- mentions which subdirectories below this one the build process
- should pass any work on to.
-
- COMPAT_SYMLINK is specific to
- compatibility symlinks (amazingly enough) for languages to their
- official encoding (doc/en would point to
- en_US.ISO-8859-1).
-
- DOC_PREFIX 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.
- .CURDIR is a make
- builtin variable with the path to the current directory.
-
- The final line includes the FreeBSD Documentation Project's
- project-wide make system file
- doc.project.mk which is the glue which
- converts these variables into build instructions.
-
-
-
- Documentation Makefiles
-
- These Makefiles set a bunch of
- make variables that describe how to
- build the documentation contained in that directory.
-
- Here is an example:
-
- MAINTAINER=nik@FreeBSD.org
-
-DOC?= book
-
-FORMATS?= html-split html
-
-INSTALL_COMPRESSED?= gz
-INSTALL_ONLY_COMPRESSED?=
-
-# SGML content
-SRCS= book.xml
-
-DOC_PREFIX?= ${.CURDIR}/../../..
-
-.include "$(DOC_PREFIX)/share/mk/docproj.docbook.mk"
-
- The MAINTAINER 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
- it.
-
- DOC is the name (sans the
- .xml extension) of the main document
- created by this directory. SRCS lists all
- the individual files that make up the document. This should
- also include important files in which a change should result
- in a rebuild.
-
- FORMATS indicates the default formats
- that should be built for this document.
- INSTALL_COMPRESSED is the default list of
- compression techniques that should be used in the document
- build. INSTALL_ONLY_COMPRESS, empty by
- default, should be non-empty if only compressed documents are
- desired in the build.
-
-
- We covered optional variable assignments in the
- previous section.
-
-
- The DOC_PREFIX and include statements
- should be familiar already.
-
-
-
-
- FreeBSD Documentation Project make includes
-
- This is best explained by inspection of the code. Here are
- the system include files:
-
-
-
- doc.project.mk is the main project
- include file, which includes all the following include files, as
- necessary.
-
-
-
- doc.subdir.mk handles traversing of
- the document tree during the build and install processes.
-
-
-
- doc.install.mk provides variables
- that affect ownership and installation of documents.
-
-
-
- doc.docbook.mk is included if
- DOCFORMAT is docbook
- and DOC is set.
-
-
-
-
- doc.project.mk
-
- By inspection:
-
- DOCFORMAT?= docbook
-MAINTAINER?= doc@FreeBSD.org
-
-PREFIX?= /usr/local
-PRI_LANG?= en_US.ISO8859-1
-
-.if defined(DOC)
-.if ${DOCFORMAT} == "docbook"
-.include "doc.docbook.mk"
-.endif
-.endif
-
-.include "doc.subdir.mk"
-.include "doc.install.mk"
-
-
-
- Variables
-
- DOCFORMAT and MAINTAINER
- are assigned default values, if these are not set by the
- document make file.
-
- PREFIX is the prefix under which the
- documentation building tools are
- installed. For normal package and port installation, this is
- /usr/local.
-
- PRI_LANG should be set to whatever
- language and encoding is natural amongst users these documents are
- being built for. US English is the default.
-
-
- PRI_LANG in no way affects what documents
- can, or even will, be built. Its main use is creating links to
- commonly referenced documents into the FreeBSD documentation
- install root.
-
-
-
-
- Conditionals
-
- The .if defined(DOC) line is an example of
- a make conditional which, like in
- other programs, defines behavior if some condition is true or
- if it is false. defined is a function which
- returns whether the variable given is defined or not.
-
- .if ${DOCFORMAT} == "docbook", next,
- tests whether the DOCFORMAT variable is
- "docbook", and in this case, includes
- doc.docbook.mk.
-
- The two .endifs close the two above
- conditionals, marking the end of their application.
-
-
-
-
- doc.subdir.mk
-
- 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.
-
-
- Variables
-
-
-
- SUBDIR is a list of subdirectories
- that the build process should go further down
- into.
-
-
-
- ROOT_SYMLINKS is the name of
- directories that should be linked to the document
- install root from their actual locations, if the current
- language is the primary language (specified by
- PRI_LANG).
-
-
-
- COMPAT_SYMLINK is described in the
- Subdirectory Makefile
- section.
-
-
-
-
-
- Targets and macros
-
- Dependencies are described by
- target:
- dependency1 dependency2 ...
- tuples, where to build target, you need to build
- the given dependencies first.
-
- After that descriptive tuple, instructions on how to build
- the target may be given, if the conversion process between the
- target and its dependencies are not previously defined, or if
- this particular conversion is not the same as the default
- conversion method.
-
- A special dependency .USE defines
- the equivalent of a macro.
-
-_SUBDIRUSE: .USE
-.for entry in ${SUBDIR}
- @${ECHO} "===> ${DIRPRFX}${entry}"
- @(cd ${.CURDIR}/${entry} && \
- ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
-.endfor
-
- In the above, _SUBDIRUSE is now a
- macro which will execute the given commands when it is listed
- as a dependency.
-
- What sets this macro apart from other targets? Basically,
- it is executed after the instructions
- given in the build procedure it is listed as a dependency to,
- and it does not adjust .TARGET, which is the
- variable which contains the name of the target currently
- being built.
-
-clean: _SUBDIRUSE
- rm -f ${CLEANFILES}
-
- In the above, clean will use the
- _SUBDIRUSE macro after it has
- executed the instruction
- rm -f ${CLEANFILES}. In effect, this causes
- clean to go further and further down
- the directory tree, deleting built files as it goes
- down, not on the way back up.
-
-
- Provided targets
-
-
-
- install and
- package both go down the
- directory tree calling the real versions of themselves
- in the subdirectories
- (realinstall and
- realpackage
- respectively).
-
-
-
- clean removes files created
- by the build process (and goes down the directory tree
- too). cleandir does the same,
- and also removes the object directory, if any.
-
-
-
-
-
-
- More on conditionals
-
-
-
- exists is another condition
- function which returns true if the given file exists.
-
-
-
- empty returns true if the given
- variable is empty.
-
-
-
- target returns true if the given
- target does not already exist.
-
-
-
-
-
- Looping constructs in make (.for)
-
- .for provides a way to repeat a set of
- instructions for each space-separated element in a variable.
- It does this by assigning a variable to contain the current
- element in the list being examined.
-
-_SUBDIRUSE: .USE
-.for entry in ${SUBDIR}
- @${ECHO} "===> ${DIRPRFX}${entry}"
- @(cd ${.CURDIR}/${entry} && \
- ${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )
-.endfor
-
- In the above, if SUBDIR is empty, no
- action is taken; if it has one or more elements, the
- instructions between .for and
- .endfor would repeat for every element,
- with entry being replaced with the value of
- the current element.
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml b/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml
deleted file mode 100644
index 5fc6839c922e..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/examples/appendix.xml
+++ /dev/null
@@ -1,336 +0,0 @@
-
-
-
- 範例
-
- 本附錄收錄一些 SGML 檔範例,以及用來轉換格式的相關指令。
- 若已成功安裝文件計畫工具包的話,那麼就可以直接照下面範例來使用。
-
- 這些例子並不是很詳細 — 並未包括你可能想用的元件,
- 尤其像是你文件的前頁(正文前的書頁,包括扉頁、序言、目錄等)
- 若需參考更多 DocBook 標記語言文件的話,那麼可以透過 CSup、CVSup
- 程式來抓 doc tree 部分,以察看本文件或其他文件的 SGML 原稿。
- 或者,也可以線上瀏覽
- http://www.FreeBSD.org/cgi/cvsweb.cgi/doc/。
-
- 為了避免不必要的困擾,這些例子採用標準的 DocBook 4.1 DTD 而非 FreeBSD 額外的 DTD。
- 同時並採用 Norm Walsh 氏的樣式表(stylesheets),而非 FreeBSD 文件計劃有自行改過的樣式表。
- 在一般使用 DocBook 的例子,這樣子會比較簡化環境,而不會造成額外困擾。
-
-
- DocBook book
-
-
- DocBook book
-
-
-
-
-
- 樣本書的例子
-
-
- 名(first name)
- 姓(surname)
-
- foo@example.com
-
-
-
-
- 2000
- 相關版權字樣
-
-
-
- 該書若有摘要,就寫在這邊。
-
-
-
-
- 序言
-
- 該書若有序言,就放在這邊。
-
-
-
- 第一章
-
- 這是這本書的第一章。
-
-
- 第一節
-
- 這本書的第一節。
-
-
-]]>
-
-
-
-
- DocBook article
-
-
- DocBook article
-
-
-
-
-
- 文章樣本
-
-
- 名(first name)
- 姓(surname)
-
- foo@example.com
-
-
-
-
- 2000
- 相關版權字樣
-
-
-
- 該文章若有摘要,就寫在這邊。
-
-
-
-
- 第一節
-
- 該文章的第一節。
-
-
- 第一小節(sub-section)
-
- 該文章的第一小節(sub-section)
-
-
-]]>
-
-
-
-
- Producing formatted output
-
- 本節有些前提,假設:已經有裝 textproc/docproj
- 上面所安裝各軟體,無論它們是用 port 方式安裝或是手動安裝。
- 此外,假設所裝的軟體都放在 /usr/local/ 下的子目錄,
- 並且所安裝的相關執行檔,都有裝在你的 PATH 環境變數內的目錄。
- 如有必要的話,請依你的系統環境而調整相關路徑。
-
-
- 使用 Jade
-
-
- 轉換 DocBook 為 HTML (完整模式)
-
- &prompt.user; jade -V nochunks \
- -c /usr/local/share/xml/docbook/dsssl/modular/catalog \
- -c /usr/local/share/xml/docbook/catalog \
- -c /usr/local/share/xml/jade/catalog \
- -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \
- -t sgml file.xml > file.html
-
-
-
- Specifies the nochunks parameter to the
- stylesheets, forcing all output to be written to
- STDOUT (using Norm Walsh's stylesheets).
-
-
-
- Specifies the catalogs that Jade 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.
-
-
-
- Specifies the full path to the DSSSL stylesheet that Jade
- will use when processing the document.
-
-
-
- Instructs Jade to perform a
- transformation from one DTD to another. In
- this case, the input is being transformed from the DocBook DTD
- to the HTML DTD.
-
-
-
- Specifies the file that Jade should process, and redirects
- output to the specified .html file.
-
-
-
-
-
- 轉換 DocBook 為 HTML (章節模式)
-
- &prompt.user; jade \
- -c /usr/local/share/xml/docbook/dsssl/modular/catalog \
- -c /usr/local/share/xml/docbook/catalog \
- -c /usr/local/share/xml/jade/catalog \
- -d /usr/local/share/xml/docbook/dsssl/modular/html/docbook.dsl \
- -t sgml file.xml
-
-
-
- Specifies the catalogs that Jade 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.
-
-
-
- Specifies the full path to the DSSSL stylesheet that Jade
- will use when processing the document.
-
-
-
- Instructs Jade to perform a
- transformation from one DTD to another. In
- this case, the input is being transformed from the DocBook DTD
- to the HTML DTD.
-
-
-
- Specifies the file that Jade should process. The
- stylesheets determine how the individual HTML files will be
- named, and the name of the root file (i.e., the
- one that contains the start of the document.
-
-
-
- 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.
-
-
-
- 轉換 DocBook 為 Postscript(PS) 格式
-
- The source SGML file must be converted to a &tex; file.
-
- &prompt.user; jade -Vtex-backend \
- -c /usr/local/share/xml/docbook/dsssl/modular/catalog \
- -c /usr/local/share/xml/docbook/catalog \
- -c /usr/local/share/xml/jade/catalog \
- -d /usr/local/share/xml/docbook/dsssl/modular/print/docbook.dsl \
- -t tex file.xml
-
-
-
- Customizes the stylesheets to use various options
- specific to producing output for &tex;.
-
-
-
- Specifies the catalogs that Jade 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.
-
-
-
- Specifies the full path to the DSSSL stylesheet that
- Jade will use when processing the document.
-
-
-
- Instructs Jade to convert the output to &tex;.
-
-
-
- The generated .tex file must now be run
- through tex, specifying the
- &jadetex macro package.
-
- &prompt.user; tex "&jadetex" file.tex
-
- You have to run texat
- least 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.
-
- Do not be alarmed if you see warning messages such as
- LaTeX Warning: Reference `136' on page 5 undefined on input
- line 728. at this point.
-
- The second run reprocesses the document now that certain pieces
- of information are known (such as the document's page length). This
- allows index entries and other cross-references to be fixed
- up.
-
- The third pass performs any final cleanup necessary.
-
- The output from this stage will be
- file.dvi.
-
- Finally, run dvips to convert the
- .dvi file to Postscript.
-
- &prompt.user; dvips -o file.ps file.dvi
-
-
-
- 轉換 DocBook 為 PDF 格式
-
- The first part of this process is identical to that when
- converting DocBook to Postscript, using the same
- jade command line ().
-
- When the .tex file has been generated you
- run pdfTeX. However, use the &pdfjadetex macro package
- instead.
-
- &prompt.user; pdftex "&pdfjadetex" file.tex
-
- Again, run this command three times.
-
- This will generate
- file.pdf, which does
- not need to be processed any further.
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml
deleted file mode 100644
index d3f24e60efd3..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/overview/chapter.xml
+++ /dev/null
@@ -1,241 +0,0 @@
-
-
-
- 概論
-
- 歡迎參與 FreeBSD 文件計劃。維持優秀質量的文件對 FreeBSD 的成功來說十分重要,
- 而 FreeBSD 文件計劃(以下皆以 FDP 來代表 FreeBSD Documentation Project
- 的縮寫) 則與這些文件撰寫、更新息息相關,因此您的點滴貢獻都是十分寶貴的。
-
- 本文件最主要的目的,就是清楚告訴您:『FDP 的架構有哪些』、『如何撰寫並提交文件給 FDP』、
- 『如何有效運用工具來協助撰稿』。
-
-
- Membership
-
- 我們歡迎每個熱心的志士來加入 FDP 行列。FDP 並不限定每月必須交出多少稿量,才能加入。
- 您唯一須要作的就是訂閱 &a.doc; 。
-
- 讀完本份文件,您將會:
-
-
-
- 瞭解有哪些文件是由 FDP 所維護的。
-
-
-
- 可以看懂 FDP 所維護的 SGML 原始文件。
-
-
-
- 知道如何來對文件作修改。
-
-
-
- 知道如何投稿自己的修改部份,並最後正式進入 FreeBSD 文件內。
-
-
-
-
- FreeBSD 文件的組成部分
-
- FDP 總共負責 FreeBSD 的 4 種類別的文件:
-
-
-
- 線上手冊(manual)
-
-
- 英文版的系統 manual 並不是由 FDP 所撰寫的,因為它們是屬於 base system 的部份。
- 然而,FDP 可以(也曾這麼做過)修改這些文件,來讓這些文件寫得更清楚,甚至是勘正錯誤的地方。
-
- 翻譯團隊負責將系統的線上手冊翻譯為不同的語言。 這些譯本都由 FDP 維護。
-
-
-
-
- FAQ
-
-
- FAQ 主要是收集在各論壇或 newsgroup 會常問到或有可能會問到的 FreeBSD 相關問題與答案 。
- (簡單講,就是『問答集』格式) 通常會擺在這裡面的問答格式,不會放太長的詳細內容。
-
-
-
-
- 使用手冊(Handbook)
-
-
- 使用手冊主要是給 FreeBSD 使用者提供詳盡的線上參考資料。
-
-
-
-
- Web site
-
-
- FreeBSD 主要各項介紹方面的 WWW 部份,歡迎逛逛 http://www.FreeBSD.org/
- 以及許多其他 mirror 站。這網站是許多人第一次接觸 FreeBSD 的地方。
-
-
-
-
- 這四個文件組成部分都可透過 FreeBSD CVS tree 來取得。也就是說,這些文件的修改記錄對於任何人都是公開的,
- 而且無論是誰都可以用像是 CSup, CVSup 或
- CTM 將文件取出來(checkout)並放在自己機器上做備份或副本參考等用途。
-
- 此外,許多人會寫些教學文件或維護有關 FreeBSD 內容的網站。(若作者同意的話)其中有些資料會保存在 FreeBSD 正式
- CVS repository 內。而其他的文件,可能作者不希望被放在 FreeBSD repository 內而另存他處。
- 總之,FDP 會盡力提供這些文件的連結。
-
-
-
- 在開工之前...
-
- 本文假設您已經瞭解:
-
-
-
- 如何從 FreeBSD CVS repository 更新自己電腦上的 FreeBSD 文件部份(以 CVS
- 或 CSup 或 CVSup 或是
- CTM) 或是用
- CVSup 來下載 checked-out 的副本
-
-
-
- 如何用 FreeBSD Ports 套件管理機制或 &man.pkg.add.1; 來下載、安裝軟體。
-
-
-
-
-
- 快速上手篇
-
- 若想先自行試試看,並有信心可以作得到,那麼就照下面步驟吧。
-
-
-
- 安裝 textproc/docproj 這個組合型 port(meta-port)。
-
- &prompt.root; cd /usr/ports/textproc/docproj
-&prompt.root; make JADETEX=no install
-
-
-
- 下載 FreeBSD doc tree 到本機上:
- 無論是用 CSup 或 CVSup 的 checkout 模式,
- 或是複製完整的 CVS repository 到本機上都可以。
-
- 若想在本機上只跑最低限度的 CVS repository 就好,那麼必須要
- checkout 出 doc/share 以及 doc/en_US.ISO8859-1/share
- 這兩個目錄才行。
-
- &prompt.user; cvs checkout doc/share
-&prompt.user; cvs checkout doc/en_US.ISO8859-1/share
-
- 若硬碟空間還算可以的話,那可以把所有語系的 doc 都 check out 出來:
-
- &prompt.user; cvs checkout doc
-
-
-
- 可依需要從 repository 中 checkout 出來你想修改某份現有的書籍或文章內容。
- 若打算撰寫新書或新文章的話,可以參考現有的部分作為實例來做。
-
- 舉例來說,若想寫篇新文章,內容是有關在 FreeBSD 與 Windows 2000 之間建立 VPN 連線,
- 那麼可以照類似下面這樣的作法:
-
-
-
- Check out articles 目錄:
-
- &prompt.user; cvs checkout doc/en_US.ISO8859-1/articles
-
-
-
- 複製現有的文章作為範本。在這個例子中,您打算決定把新文章放在
- vpn-w2k 的目錄下。
-
- &prompt.user; cd doc/en_US.ISO8859-1/articles
-&prompt.user; cp -R committers-guide vpn-w2k
-
-
-
- 若是要修改現有文章,像是 FAQ(擺在 doc/en_US.ISO8859-1/books/faq)
- ,那麼要從 repository 中取出來(check out):
-
- &prompt.user; cvs checkout doc/en_US.ISO8859-1/books/faq
-
-
-
- 以編輯器來編寫 .xml 檔。
-
-
-
- 以 lint 當輔助參數,來快速檢測文件結構及連結有無錯誤,
- 以下這個指令,實際上不會進行耗時的編書過程,只是先測試文件有無錯誤。
-
- &prompt.user; make lint
-
- 當編書的一切都就緒時,這時你可以用 FORMATS
- 變數來指定產生的格式為哪一種。 目前支援的格式共有:
- html, html-split,
- txt, ps,
- pdf, rtf 。
- 所支援的格式列表最新版,可參考
- doc/share/mk/doc.docbook.mk 檔。 請記得:
- 在單一指令中,若要同時產生多種格式的話,應使用引號(quotes)來將這些格式括起來。
-
- 舉例來說,若只要產生
- html 格式就好,那麼就打:
-
- &prompt.user; make FORMATS=html
-
- 但若希望有 html 及 txt 格式的話,
- 你可能要打兩次 &man.make.1; 指令才能完成:
-
- &prompt.user; make FORMATS=html
-&prompt.user; make FORMATS=txt
-
- 其實,也可以用單一指令來完成:
-
- &prompt.user; make FORMATS="html txt"
-
-
-
- 最後,以 &man.send-pr.1; 來提交修改的部份。
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml
deleted file mode 100644
index 6edba25352f5..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/psgml-mode/chapter.xml
+++ /dev/null
@@ -1,165 +0,0 @@
-
-
-
- Using sgml-mode with
- Emacs
-
- Recent versions of Emacs or XEmacs (available from the ports
- collection) contain a very useful package called PSGML. Automatically
- invoked when a file with the .xml extension is loaded,
- or by typing M-x sgml-mode, it is a major mode for
- dealing with SGML files, elements and attributes.
-
- An understanding of some of the commands provided by this mode can
- make working with SGML documents such as the Handbook much easier.
-
-
-
- C-c C-e
-
-
- Runs sgml-insert-element. You will be
- prompted for the name of the element to insert at the current point.
- You can use the TAB key to complete the element. Elements that are
- not valid at the current point will be disallowed.
-
- The start and end tags for the element will be inserted. If the
- element contains other, mandatory, elements then these will be
- inserted as well.
-
-
-
-
- C-c =
-
-
- Runs sgml-change-element-name. Place the
- point within an element and run this command. You will be prompted
- for the name of the element to change to. Both the start and end
- tags of the current element will be changed to the new
- element.
-
-
-
-
- C-c C-r
-
-
- Runs sgml-tag-region. Select some text (move
- to start of text, C-space, move to end of text, C-space) and then
- run this command. You will be prompted for the element to use. This
- element will then be inserted immediately before and after your
- marked region.
-
-
-
-
- C-c -
-
-
- Runs sgml-untag-element. Place the point
- within the start or end tag of an element you want to remove, and
- run this command. The element's start and end tags will be
- removed.
-
-
-
-
- C-c C-q
-
-
- Runs sgml-fill-element. Will recursively fill
- (i.e., reformat) content from the current element in. The filling
- will affect content in which whitespace is
- significant, such as within programlisting
- elements, so run this command with care.
-
-
-
-
- C-c C-a
-
-
- Runs sgml-edit-attributes. Opens a second
- buffer containing a list of all the attributes for the closest
- enclosing element, and their current values. Use TAB to navigate
- between attributes, C-k to remove an existing
- value and replace it with a new one, C-c C-c
- to close this buffer and return to the main document.
-
-
-
-
- C-c C-v
-
-
- Runs sgml-validate. Prompts you to save the
- current document (if necessary) and then runs an SGML validator. The
- output from the validator is captured into a new buffer, and you can
- then navigate from one troublespot to the next, fixing markup errors
- as you go.
-
-
-
-
- C-c /
-
-
- Runs sgml-insert-end-tag. Inserts the
- end tag for the current open element.
-
-
-
-
- Doubtless there are other useful functions of this mode, but those are
- the ones I use most often.
-
- You can also use the following entries in
- .emacs to set proper spacing, indentation,
- and column width for working with the Documentation Project.
-
-
- (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)))
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml
deleted file mode 100644
index 89f409164ef1..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/see-also/chapter.xml
+++ /dev/null
@@ -1,122 +0,0 @@
-
-
-
- 他山之石
-
- This document is deliberately not an exhaustive discussion of SGML,
- the DTDs listed, and the FreeBSD Documentation Project. For more
- information about these, you are encouraged to see the following web
- sites.
-
-
- The FreeBSD Documentation Project
-
-
-
- The FreeBSD
- Documentation Project web pages
-
-
-
- The FreeBSD Handbook
-
-
-
-
-
- SGML
-
-
-
- The SGML/XML web
- page, a comprehensive SGML resource
-
-
-
- Gentle introduction to SGML
-
-
-
-
-
- HTML
-
-
-
- The World Wide Web
- Consortium
-
-
-
- The HTML 4.0
- specification
-
-
-
-
-
- DocBook
-
-
-
- The DocBook
- Technical Committee, maintainers of the DocBook DTD
-
-
-
- DocBook: The Definitive
- Guide, the online documentation for the DocBook
- DTD.
-
-
-
-
- The DocBook Open
- Repository contains DSSSL stylesheets and other resources
- for people using DocBook.
-
-
-
-
-
- The Linux Documentation Project
-
-
-
- The Linux Documentation
- Project web pages
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml
deleted file mode 100644
index 6b0907ff573d..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/sgml-markup/chapter.xml
+++ /dev/null
@@ -1,2682 +0,0 @@
-
-
-
- SGML Markup
-
- This chapter describes the two markup languages you will encounter
- when you contribute to the FreeBSD documentation project. Each section
- describes the markup language, and details the markup that you are likely
- to want to use, or that is already in use.
-
- These markup languages contain a large number of elements, and it can
- be confusing sometimes to know which element to use for a particular
- situation. This section goes through the elements you are most likely to
- need, and gives examples of how you would use them.
-
- This is not an exhaustive list of elements, since
- that would just reiterate the documentation for each language. The aim of
- this section is to list those elements more likely to be useful to you.
- If you have a question about how best to markup a particular piece of
- content, please post it to the &a.doc;.
-
-
- Inline vs. block
-
- In the remainder of this document, when describing elements,
- inline means that the element can occur within a
- block element, and does not cause a line break. A
- block element, by comparison, will cause a line
- break (and other processing) when it is encountered.
-
-
-
- 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/>.
-
- HTML is used to markup pages on the FreeBSD web site. It should not
- (generally) be used to mark up other documentation,
- since DocBook offers a
- far richer set of elements to choose from. Consequently, you will
- normally only encounter HTML pages if you are writing for the web
- site.
-
- 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).
-
- The HTML DTDs are available from the ports collection in the
- textproc/html port. They are automatically
- installed as part of the textproc/docproj
- port.
-
-
- Formal Public Identifier (FPI)
-
- There are a number of HTML FPIs, depending upon the version (also
- known as the level) of HTML that you want to declare your document to
- be compliant with.
-
- 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"
-
-
-
- Sectional elements
-
- An HTML document is normally split into two sections. The first
- section, called the head, 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
- body, contains the content that will be displayed
- to the user.
-
- These sections are indicated with head and
- body elements respectively. These elements are
- contained within the top-level html element.
-
-
- Normal HTML document structure
-
- <html>
- <head>
- <title>The document's title</title>
- </head>
-
- <body>
-
- …
-
- </body>
-</html>
-
-
-
-
- Block elements
-
-
- Headings
-
- HTML allows you to denote headings in your document, at up to
- six different levels.
-
- The largest and most prominent heading is h1,
- then h2, continuing down to
- h6.
-
- The element's content is the text of the heading.
-
-
- h1, h2, etc.
-
- Use:
-
- <h1>First section</h1>
-
-<!‐- Document introduction goes here -‐>
-
-<h2>This is the heading for the first section</h2>
-
-<!‐- Content for the first section goes here -‐>
-
-<h3>This is the heading for the first sub-section</h3>
-
-<!‐- Content for the first sub-section goes here -‐>
-
-<h2>This is the heading for the second section</h2>
-
-<!‐- Content for the second section goes here -‐>
-
-
- Generally, an HTML page should have one first level heading
- (h1). This can contain many second level
- headings (h2), which can in turn contain many
- third level headings. Each
- hn element should have
- the same element, but one further up the hierarchy, preceding it.
- Leaving gaps in the numbering is to be avoided.
-
-
- Bad ordering of
- hn elements
-
- Use:
-
- <h1>First section</h1>
-
-<!‐- Document introduction -‐>
-
-<h3>Sub-section</h3>
-
-<!‐- This is bad, <h2> has been left out -‐>
-
-
-
-
- Paragraphs
-
- HTML supports a single paragraph element,
- p.
-
-
- p
-
- Use:
-
- This is a paragraph. It can contain just about any
- other element.
]]>
-
-
-
-
- Block quotations
-
- A block quotation is an extended quotation from another document
- that should not appear within the current paragraph.
-
-
- blockquote
-
- Use:
-
- 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
- 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.
]]>
-
-
-
-
- Lists
-
- You can present the user with three types of lists, ordered,
- unordered, and definition.
-
- 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.
-
- Ordered lists are indicated by the ol
- element, unordered lists by the ul element, and
- definition lists by the dl element.
-
- Ordered and unordered lists contain listitems, indicated by the
- li element. A listitem can contain textual
- content, or it may be further wrapped in one or more
- p elements.
-
- Definition lists contain definition terms
- (dt) and definition descriptions
- (dd). A definition term can only contain inline
- elements. A definition description can contain other block
- elements.
-
-
- ul and ol
-
- Use:
-
- An unordered list. Listitems will probably be
- preceded by bullets.
-
-
-
First item
-
-
Second item
-
-
Third item
-
-
-
An ordered list, with list items consisting of multiple
- paragraphs. Each item (note: not each paragraph) will be
- numbered.
-
-
-
This is the first item. It only has one paragraph.
-
-
This is the first paragraph of the second item.
-
-
This is the second paragraph of the second item.
-
-
This is the first and only paragraph of the third
- item.
-]]>
-
-
-
-
- Pre-formatted text
-
- You can indicate that text should 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.
-
- In order to do this, wrap the content in the
- pre element.
-
-
- pre
-
- You could use pre to mark up an email
- message:
-
- 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>
-
- Comments appreciated.
-
- N]]>
-
- Keep in mind that < and
- & still are recognized as special
- characters in pre-formatted text. This is why the example
- shown had to use < instead of
- <. For consistency,
- > was used in place of
- >, too. Watch out for the special characters
- that may appear in text copied from a plain-text source,
- e.g., an email message or program code.
-
-
-
-
-
- Tables
-
-
- Most text-mode browsers (such as Lynx) do not render tables
- particularly effectively. If you are relying on the tabular
- display of your content, you should consider using alternative
- markup to prevent confusion.
-
-
- Mark up tabular information using the table
- element. A table consists of one or more table rows
- (tr), each containing one or more cells of table
- data (td). Each cell can contain other block
- elements, such as paragraphs or lists. It can also contain another
- table (this nesting can repeat indefinitely). If the cell only
- contains one paragraph then you do not need to include the
- p element.
-
-
- Simple use of table
-
- Use:
-
- This is a simple 2x2 table.
-
-
-
-
Top left cell
-
-
Top right cell
-
-
-
-
Bottom left cell
-
-
Bottom right cell
-
-
]]>
-
- A cell can span multiple rows and columns. To indicate this,
- add the rowspan and/or colspan
- attributes, with values indicating the number of rows of columns
- that should be spanned.
-
-
- Using rowspan
-
- Use:
-
- One tall thin cell on the left, two short cells next to
- it on the right.
-
-
-
-
Long and thin
-
-
-
-
Top cell
-
-
Bottom cell
-
-
]]>
-
-
-
- Using colspan
-
- Use:
-
- One long cell on top, two short cells below it.
-
-
-
-
Top cell
-
-
-
-
Bottom left cell
-
-
Bottom right cell
-
-
]]>
-
-
-
- Using rowspan and
- colspan together
-
- Use:
-
- On a 3x3 grid, the top left block is a 2x2 set of
- cells merged into one. The other cells are normal.
-
-
-
-
Top left large cell
-
-
Top right cell
-
-
-
-
Middle right cell
-
-
-
-
Bottom left cell
-
-
Bottom middle cell
-
-
Bottom right cell
-
-
]]>
-
-
-
-
-
- In-line elements
-
-
- Emphasizing information
-
- You have two levels of emphasis available in HTML,
- em and strong.
- em is for a normal level of emphasis and
- strong indicates stronger emphasis.
-
- Typically, em is rendered in italic and
- strong is rendered in bold. This is not always
- the case, however, and you should not rely on it.
-
-
- em and strong
-
- Use:
-
- This has been emphasized, while
- this has been strongly emphasized.]]>
-
-
-
-
- Bold and italics
-
- Because HTML includes presentational markup, you can also
- indicate that particular content should be rendered in bold or
- italic. The elements are b and
- i respectively.
-
-
- b and i
-
- This is in bold, while this is
- in italics.]]>
-
-
-
-
- Indicating fixed pitch text
-
- If you have content that should be rendered in a fixed pitch
- (typewriter) typeface, use tt (for
- teletype).
-
-
- tt
-
- Use:
-
- This document was originally written by
- Nik Clayton, who can be reached by email as
- nik@FreeBSD.org.]]>
-
-
-
-
- Content size
-
- You can indicate that content should be shown in a larger or
- smaller font. There are three ways of doing this.
-
-
-
- Use big and small
- around the content you wish to change size. These tags can be
- nested, so <big><big>This is much
- bigger</big></big> is possible.
-
-
-
- Use font with the size
- attribute set to +1 or -1
- respectively. This has the same effect as using
- big or small. However,
- the use of this approach is deprecated.
-
-
-
- Use font with the size
- attribute set to a number between 1 and 7. The default font size
- is 3. This approach is deprecated.
-
-
-
-
- big, small, and
- font
-
- The following fragments all do the same thing.
-
- This text is slightly smaller. But
- this text is slightly bigger.
-
-
This text is slightly smaller. But
- this text is slightly bigger
-
-
This text is slightly smaller. But
- this text is slightly bigger.
]]>
-
-
-
-
-
- Links
-
-
- Links are also in-line elements.
-
-
-
- Linking to other documents on the WWW
-
- In order to include a link to another document on the WWW you
- must know the URL of the document you want to link to.
-
- The link is indicated with a, and the
- href attribute contains the URL of the target
- document. The content of the element becomes the link, and is
- normally indicated to the user in some way (underlining, change of
- color, different mouse cursor when over the link, and so
- on).
-
-
- Using <a href="...">
-
- Use:
-
- More information is available at the
- FreeBSD web site.]]>
-
-
- These links will take the user to the top of the chosen
- document.
-
-
-
- Linking to other parts of documents
-
- Linking to a point within another document (or within the same
- document) requires that the document author include anchors that you
- can link to.
-
- Anchors are indicated with a and the
- name attribute instead of
- href.
-
-
- Using <a name="...">
-
- Use:
-
- This paragraph can be referenced
- in other links with the name para1.]]>
-
-
- To link to a named part of a document, write a normal link to
- that document, but include the name of the anchor after a
- # symbol.
-
-
- Linking to a named part of another document
-
- Assume that the para1 example resides in a
- document called foo.html.
-
- More information can be found in the
- first paragraph of
- foo.html.]]>
-
-
- 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 #).
-
-
- Linking to a named part of the same document
-
- Assume that the para1 example resides in
- this document:
-
- More information can be found in the
- first paragraph of this
- document.]]>
-
-
-
-
-
-
- DocBook
-
- DocBook was originally developed by HaL Computer Systems and O'Reilly
- & Associates to be a DTD for writing technical documentation
- A short history can be found under
- http://www.oasis-open.org/committees/docbook/intro.shtml.
- . Since 1998 it is maintained by the
- DocBook Technical Committee. As such, and unlike LinuxDoc
- and HTML, DocBook is very heavily oriented towards markup that
- describes what something is, rather than describing
- how it should be presented.
-
-
- formal vs. informal
-
- Some elements may exist in two forms, formal
- and informal. Typically, the formal version of
- the element will consist of a title followed by the informal
- version of the element. The informal version will not have a
- title.
-
-
- The DocBook DTD is available from the ports collection in the
- textproc/docbook port. It is automatically
- installed as part of the textproc/docproj
- port.
-
-
- FreeBSD extensions
-
- The FreeBSD Documentation Project has extended the DocBook DTD by
- adding some new elements. These elements serve to make some of the
- markup more precise.
-
- Where a FreeBSD specific element is listed below it is clearly
- marked.
-
- Throughout the rest of this document, the term
- DocBook is used to mean the FreeBSD extended DocBook
- DTD.
-
-
- There is nothing about these extensions that is FreeBSD
- specific, 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 &a.doceng;.
-
-
- The FreeBSD extensions are not (currently) in the ports
- collection. They are stored in the FreeBSD CVS tree, as doc/share/xml/freebsd.dtd.
-
-
-
- Formal Public Identifier (FPI)
-
- In compliance with the DocBook guidelines for writing FPIs for
- DocBook customizations, the FPI for the FreeBSD extended DocBook DTD
- is:
-
- PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN"
-
-
-
- Document structure
-
- 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 organized into chapters. This is a
- mandatory requirement. There may be parts between
- the book and the chapter to provide another layer of organization.
- The Handbook is arranged in this way.
-
- A chapter may (or may not) contain one or more sections. These
- are indicated with the sect1 element. If a section
- contains another section then use the sect2
- element, and so on, up to sect5.
-
- 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 organized 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 into 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 into 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
-
- The content of the book is contained within the
- book element. As well as containing structural
- markup, this element can contain elements that include additional
- information about the book. 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
- bookinfo.
-
-
- Boilerplate book with
- bookinfo
-
-
- <book>
- <bookinfo>
- <title>Your title here</title>
-
- <author>
- <firstname>Your first name</firstname>
- <surname>Your surname</surname>
- <affiliation>
- <address><email>Your email address</email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year>1998</year>
- <holder role="mailto:your email address">Your name</holder>
- </copyright>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <abstract>
- <para>Include an abstract of the book's contents here.</para>
- </abstract>
- </bookinfo>
-
- …
-
-</book>
-
-
-
-
- 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
- articleinfo.
-
-
- Boilerplate article with
- articleinfo
-
-
- <article>
- <articleinfo>
- <title>Your title here</title>
-
- <author>
- <firstname>Your first name</firstname>
- <surname>Your surname</surname>
- <affiliation>
- <address><email>Your email address</email></address>
- </affiliation>
- </author>
-
- <copyright>
- <year>1998</year>
- <holder role="mailto:your email address">Your name</holder>
- </copyright>
-
- <releaseinfo>$FreeBSD$</releaseinfo>
-
- <abstract>
- <para>Include an abstract of the article's contents here.</para>
- </abstract>
- </articleinfo>
-
- …
-
-</article>
-
-
-
- Indicating chapters
-
- Use chapter to mark up your chapters. Each
- chapter has a mandatory title. Articles do not
- contain chapters, they are reserved for books.
-
-
- A simple chapter
-
-
- The chapter's title
-
- ...
-]]>
-
-
- A chapter cannot be empty; it must contain elements in addition
- to title. If you need to include an empty
- chapter then just use an empty paragraph.
-
-
- Empty chapters
-
-
- This is an empty chapter
-
-
-]]>
-
-
-
-
- Sections below chapters
-
- 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
- chapter. They can contain one or more sect2
- elements, and so on, down to sect5.
-
-
- Sections in chapters
-
-
- A sample chapter
-
- Some text in the chapter.
-
-
- First section (1.1)
-
- …
-
-
-
- Second section (1.2)
-
-
- First sub-section (1.2.1)
-
-
- 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 by the stylesheets (of which more
- later), and you do not need to manage them yourself.
-
-
-
-
- Subdividing using parts
-
- You can introduce another layer of organization between
- book and chapter with one or
- more parts. This cannot be done in an
- article.
-
-
- Introduction
-
-
- Overview
-
- ...
-
-
-
- What is FreeBSD?
-
- ...
-
-
-
- History
-
- ...
-
-]]>
-
-
-
-
- Block elements
-
-
- Paragraphs
-
- DocBook supports three types of paragraphs:
- formalpara, para, and
- simpara.
-
- Most of the time you will only need to use
- para. formalpara includes a
- title element, and simpara
- disallows some elements from within para. Stick
- with para.
-
-
- para
-
- Use:
-
- This is a paragraph. It can contain just about any
- other element. ]]>
-
- Appearance:
-
- This is a paragraph. It can contain just about any other
- element.
-
-
-
-
- Block quotations
-
- A block quotation is an extended quotation from another document
- that should not appear within the current paragraph. You will
- probably only need it infrequently.
-
- Blockquotes can optionally contain a title and an attribution
- (or they can be left untitled and unattributed).
-
-
- blockquote
-
- Use:
-
- A small excerpt from the US Constitution:
-
-
- Preamble to the Constitution of the United States
-
- Copied from a web site somewhere
-
- 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.
-
]]>
-
- Appearance:
-
-
- Preamble to the Constitution of the United States
-
- Copied from a web site somewhere
-
- 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.
-
-
-
-
-
- Tips, notes, warnings, cautions, important information and
- sidebars.
-
- You may need to include extra information separate from the
- main body of the text. Typically this is meta
- information that the user should be aware of.
-
- Depending on the nature of the information, one of
- tip, note,
- warning, caution, and
- important should be used. Alternatively, if the
- information is related to the main text but is not one of the above,
- use sidebar.
-
- The circumstances in which to choose one of these elements over
- another is unclear. The DocBook documentation suggests:
-
-
-
- A Note is for information that should be heeded by all
- readers.
-
-
-
- An Important element is a variation on Note.
-
-
-
- A Caution is for information regarding possible data loss
- or software damage.
-
-
-
- A Warning is for information regarding possible hardware
- damage or injury to life or limb.
-
-
-
-
- warning
-
- Use:
-
-
- Installing FreeBSD may make you want to delete Windows from your
- hard disk.
-]]>
-
-
-
-
- Installing FreeBSD may make you want to delete Windows from
- your hard disk.
-
-
-
-
- Lists and procedures
-
- You will often need to list pieces of information to the user,
- or present them with a number of steps that must be carried out in
- order to accomplish a particular goal.
-
- In order to do this, use itemizedlist,
- orderedlist, or
- procedureThere are other types of
- list element in DocBook, but we are not concerned with those at
- the moment.
-
-
-
- itemizedlist and
- orderedlist are similar to their counterparts in
- HTML, ul and ol. Each one
- consists of one or more listitem elements, and
- each listitem contains one or more block
- elements. The listitem elements are analogous to
- HTML's li tags. However, unlike HTML, they are
- required.
-
- procedure is slightly different. It consists
- of steps, which may in turn consists of more
- steps or substeps. Each
- step contains block elements.
-
-
- itemizedlist,
- orderedlist, and
- procedure
-
- Use:
-
-
-
- This is the first itemized item.
-
-
-
- This is the second itemized item.
-
-
-
-
-
- This is the first ordered item.
-
-
-
- This is the second ordered item.
-
-
-
-
-
- Do this.
-
-
-
- Then do this.
-
-
-
- And now do this.
-
-]]>
-
- Appearance:
-
-
-
- This is the first itemized item.
-
-
-
- This is the second itemized item.
-
-
-
-
-
- This is the first ordered item.
-
-
-
- This is the second ordered item.
-
-
-
-
-
-
-
-
- Do this.
-
-
-
- Then do this.
-
-
-
- And now do this.
-
-
-
-
-
- Showing file samples
-
- If you want to show a fragment of a file (or perhaps a complete
- file) to the user, wrap it in the programlisting
- element.
-
- White space and line breaks within
- programlistingare
- 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.
-
-
- programlisting
-
- Use:
-
- When you have finished, your program should look like
- this:
-
-#include <stdio.h>
-
-int
-main(void)
-{
- printf("hello, world\n");
-}]]>
-
- Notice how the angle brackets in the
- #include line need to be referenced by their
- entities instead of being included literally.
-
- Appearance:
-
- When you have finished, your program should look like
- this:
-
- #include <stdio.h>
-
-int
-main(void)
-{
- printf("hello, world\n");
-}
-
-
-
-
- Callouts
-
- A callout is a mechanism for referring back to an earlier piece
- of text or specific position within an earlier example without
- linking to it within the text.
-
- To do this, mark areas of interest in your example
- (programlisting,
- literallayout, or whatever) with the
- co element. Each element must have a unique
- id assigned to it. After the example include a
- calloutlist that refers back to the example and
- provides additional commentary.
-
-
- co and
- calloutlist
-
- When you have finished, your program should look like
- this:
-
-#include <stdio.h>
-
-int
-main(void)
-{
- printf("hello, world\n");
-}
-
-
-
- Includes the standard IO header file.
-
-
-
- Specifies that main() returns an
- int.
-
-
-
- The printf() call that writes
- hello, world to standard output.
-
-]]>
-
- Appearance:
-
- When you have finished, your program should look like
- this:
-
- #include <stdio.h>
-
-int
-main(void)
-{
- printf("hello, world\n");
-}
-
-
-
- Includes the standard IO header file.
-
-
-
- Specifies that main() returns an
- int.
-
-
-
- The printf() call that writes
- hello, world to standard output.
-
-
-
-
-
-
- Tables
-
- Unlike HTML, you do not need to use tables for layout purposes,
- as the stylesheet handles those issues for you. Instead, just use
- tables for marking up tabular data.
-
- In general terms (and see the DocBook documentation for more
- detail) a table (which can be either formal or informal) consists of
- a table element. This contains at least one
- tgroup element, which specifies (as an attribute)
- the number of columns in this table group. Within the tablegroup
- you can then have one thead element, which
- contains elements for the table headings (column headings), and one
- tbody which contains the body of the
- table.
-
- Both tgroup and thead
- contain row elements, which in turn contain
- entry elements. Each entry
- element specifies one cell in the table.
-
-
- informaltable
-
- Use:
-
-
-
-
-
- This is column head 1
- This is column head 2
-
-
-
-
-
- Row 1, column 1
- Row 1, column 2
-
-
-
- Row 2, column 1
- Row 2, column 2
-
-
-
-]]>
-
- Appearance:
-
-
-
-
-
- This is column head 1
- This is column head 2
-
-
-
-
-
- Row 1, column 1
- Row 1, column 2
-
-
-
- Row 2, column 1
- Row 2, column 2
-
-
-
-
-
-
- Always use the pgwide attribute with
- a value of 1 with the
- informaltable element. A bug in Internet
- Explorer can cause the table to render incorrectly if this
- is omitted.
-
- If you do not want a border around the table the
- frame attribute can be added to the
- informaltable element with a value of
- none (i.e., <informaltable
- frame="none">).
-
-
- Tables where frame="none"
-
- Appearance:
-
-
-
-
-
- This is column head 1
- This is column head 2
-
-
-
-
-
- Row 1, column 1
- Row 1, column 2
-
-
-
- Row 2, column 1
- Row 2, column 2
-
-
-
-
-
-
-
-
- Examples for the user to follow
-
- A lot of the time you need to show examples for the user to
- follow. Typically, these will consist of dialogs with the computer;
- the user types in a command, the user gets a response back, they
- type in another command, and so on.
-
- A number of distinct elements and entities come into play
- here.
-
-
-
- screen
-
-
- Everything the user sees in this example will be on the
- computer screen, so the next element is
- screen.
-
- Within screen, white space is
- significant.
-
-
-
-
- prompt,
- &prompt.root; and
- &prompt.user;
-
-
- Some of the things the user will be seeing on the screen
- are prompts from the computer (either from the operating system, command
- shell, or application). These should be marked up using
- prompt.
-
- As a special case, the two shell prompts for the normal
- user and the root user have been provided as entities. Every
- time you want to indicate the user is at a shell prompt, use
- one of &prompt.root; and
- &prompt.user; as necessary. They do
- not need to be inside prompt.
-
-
- &prompt.root; and
- &prompt.user; are FreeBSD
- extensions to DocBook, and are not part of the original
- DTD.
-
-
-
-
-
- userinput
-
-
- When displaying text that the user should type in, wrap it
- in userinput tags. It will probably be
- displayed differently to the user.
-
-
-
-
-
- screen, prompt, and
- userinput
-
- Use:
-
- &prompt.user; ls -1
-foo1
-foo2
-foo3
-&prompt.user; ls -1 | grep foo2
-foo2
-&prompt.user; su
-Password:
-&prompt.root; cat foo2
-This is the file called 'foo2']]>
-
- Appearance:
-
- &prompt.user; ls -1
-foo1
-foo2
-foo3
-&prompt.user; ls -1 | grep foo2
-foo2
-&prompt.user; su
-Password:
-&prompt.root; cat foo2
-This is the file called 'foo2'
-
-
-
- Even though we are displaying the contents of the file
- foo2, it is not marked
- up as programlisting. Reserve
- programlisting for showing fragments of files
- outside the context of user actions.
-
-
-
-
-
- In-line elements
-
-
- Emphasizing information
-
- When you want to emphasize a particular word or phrase, use
- emphasis. This may be presented as italic, or
- bold, or might be spoken differently with a text-to-speech
- system.
-
- There is no way to change the presentation of the emphasis
- within your document, no equivalent of HTML's b
- and i. If the information you are presenting is
- important then consider presenting it in
- important rather than
- emphasis.
-
-
- emphasis
-
- Use:
-
- FreeBSD is without doubt the
- premiere Unix like operating system for the Intel architecture.]]>
-
- Appearance:
-
- FreeBSD is without doubt the premiere Unix
- like operating system for the Intel architecture.
-
-
-
-
- Quotations
-
- To quote text from another document or source, or to denote
- a phrase that is used figuratively, use quote.
- Within a quote tag, you may use most of the
- markup tags available for normal text.
-
-
- Quotations
-
- Use:
-
- However, make sure that the search does not go beyond the
- boundary between local and public administration,
- as RFC 1535 calls it.]]>
-
- Appearance:
-
- However, make sure that the search does not go beyond the
- boundary between local and public administration,
- as RFC 1535 calls it.
-
-
-
-
- Keys, mouse buttons, and combinations
-
- To refer to a specific key on the keyboard, use
- keycap. To refer to a mouse button, use
- mousebutton. And to refer to combinations of key
- presses or mouse clicks, wrap them all in
- keycombo.
-
- keycombo has an attribute called
- action, which may be one of
- click, double-click,
- other, press,
- seq, or simul. The last two
- values denote whether the keys or buttons should be pressed in
- sequence, or simultaneously.
-
- The stylesheets automatically add any connecting symbols, such
- as +, between the key names, when wrapped in
- keycombo.
-
-
- Keys, mouse buttons, and combinations
-
- Use:
-
- To switch to the second virtual terminal, press
- Alt
- F1.
-
-To exit vi without saving your work, type
- Esc:
- q!.
-
-My window manager is configured so that
- Alt
- right
- mouse button is used to move windows.]]>
-
- Appearance:
-
- To switch to the second virtual terminal, press
- Alt
- F1.
-
- To exit vi without saving your work, type
- Esc:
- q!.
-
- My window manager is configured so that
- Alt
- right
- mouse button is used to move windows.
-
-
-
-
- Applications, commands, options, and cites
-
- You will frequently want to refer to both applications and
- commands when writing for the Handbook. The distinction between
- them is simple: an application is the name for a suite (or possibly
- just 1) of programs that fulfil a particular task. A command is the
- name of a program that the user can run.
-
- In addition, you will occasionally need to list one or more of
- the options that a command might take.
-
- Finally, you will often want to list a command with its manual
- section number, in the command(number) format so
- common in Unix manuals.
-
- Mark up application names with
- application.
-
- When you want to list a command with its manual section number
- (which should be most of the time) the DocBook element is
- citerefentry. This will contain a further two
- elements, refentrytitle and
- manvolnum. The content of
- refentrytitle is the name of the command, and the
- content of manvolnum is the manual page
- section.
-
- This can be cumbersome to write, and so a series of general entities
- have been created to make this easier. Each entity takes the form
- &man.manual-page.manual-section;.
-
- The file that contains these entities is in
- doc/share/xml/man-refs.ent, and can be
- referred to using this FPI:
-
- PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN"
-
- Therefore, the introduction to your documentation will probably
- look like this:
-
- <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
-
-<!ENTITY % man PUBLIC "-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN">
-%man;
-
-…
-
-]>
-
- Use command when you want to include a
- command name in-line but present it as something the
- user should type in.
-
- Use option to mark up the options
- which will be passed to a command.
-
- When referring to the same command multiple times in
- close proximity it is preferred to use the
- &man.command.section;
- notation to markup the first reference and use
- command to markup subsequent references.
- This makes the generated output, especially HTML, appear
- visually better.
-
- This can be confusing, and sometimes the choice is not always
- clear. Hopefully this example makes it clearer.
-
-
- Applications, commands, and options.
-
- Use:
-
- Sendmail is the most
- widely used Unix mail application.
-
-Sendmail includes the
-
- sendmail
- 8
- , &man.mailq.8;, and &man.newaliases.8;
- programs.
-
-One of the command line parameters to
- sendmail
- 8
- , , will display the current
- status of messages in the mail queue. Check this on the command
- line by running sendmail -bp.]]>
-
- Appearance:
-
- Sendmail is the most widely used
- Unix mail application.
-
- Sendmail includes the
-
- sendmail
- 8
- ,
- mailq
- 8
- , and
- newaliases
- 8
- programs.
-
- One of the command line parameters to
- sendmail
- 8
- , , will display the current
- status of messages in the mail queue. Check this on the command
- line by running sendmail -bp.
-
-
-
- Notice how the
- &man.command.section; notation is easier to follow.
-
-
-
-
- Files, directories, extensions
-
- Whenever you wish to refer to the name of a file, a directory,
- or a file extension, use filename.
-
-
- filename
-
- Use:
-
- The SGML source for the Handbook in English can be
- found in /usr/doc/en/handbook/. The first
- file is called handbook.xml in that
- directory. You should also see a Makefile
- and a number of files with a .ent
- extension.]]>
-
- Appearance:
-
- The SGML source for the Handbook in English can be found in
- /usr/doc/en/handbook/. The first file is
- called handbook.xml in that directory. You
- should also see a Makefile and a number of
- files with a .ent extension.
-
-
-
-
- The name of ports
-
-
- FreeBSD extension
-
- These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.
-
-
- You might need to include the name of a program from the
- FreeBSD Ports Collection in the documentation. Use the
- filename tag with the role
- attribute set to package to identify these.
- Since ports
- can be installed in any number of locations, only include
- the category and the port name; do not include
- /usr/ports.
-
-
- filename tag with
- package role
-
- Use:
-
- Install the net/ethereal port to view network traffic.]]>
-
- Appearance:
-
- Install the net/ethereal
- port to view network traffic.
-
-
-
-
- Devices
-
-
- FreeBSD extension
-
- These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.
-
-
- When referring to devices you have two choices. You can either
- refer to the device as it appears in /dev, or
- you can use the name of the device as it appears in the kernel. For
- this latter course, use devicename.
-
- Sometimes you will not have a choice. Some devices, such as
- networking cards, do not have entries in /dev,
- or the entries are markedly different from those entries.
-
-
- devicename
-
- Use:
-
- sio is used for serial
- communication in FreeBSD. sio manifests
- through a number of entries in /dev, including
- /dev/ttyd0 and /dev/cuaa0.
-
-By contrast, the networking devices, such as
- ed0 do not appear in /dev.
-
-In MS-DOS, the first floppy drive is referred to as
- a:. In FreeBSD it is
- /dev/fd0.]]>
-
- Appearance:
-
- sio is used for serial communication
- in FreeBSD. sio manifests through a
- number of entries in /dev, including
- /dev/ttyd0 and
- /dev/cuaa0.
-
- By contrast, the networking devices, such as
- ed0 do not appear in
- /dev.
-
- In MS-DOS, the first floppy drive is referred to as
- a:. In FreeBSD it is
- /dev/fd0.
-
-
-
-
- Hosts, domains, IP addresses, and so forth
-
-
- FreeBSD extension
-
- These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.
-
-
- You can markup identification information for networked
- computers (hosts) in several ways, depending on the nature of the
- information. All of them use hostid as the
- element, with the role attribute selecting the
- type of the marked up information.
-
-
-
- No role attribute, or
- role="hostname"
-
-
- With no role attribute (i.e.,
- hostid.../hostid) the
- marked up information is the simple hostname, such as
- freefall or wcarchive.
- You can explicitly specify this with
- role="hostname".
-
-
-
-
- role="domainname"
-
-
- The text is a domain name, such as
- FreeBSD.org or
- ngo.org.uk. There is no hostname
- component.
-
-
-
-
- role="fqdn"
-
-
- The text is a Fully Qualified Domain Name, with both
- hostname and domain name parts.
-
-
-
-
- role="ipaddr"
-
-
- The text is an IP address, probably expressed as a dotted
- quad.
-
-
-
-
- role="ip6addr"
-
-
- The text is an IPv6 address.
-
-
-
-
- role="netmask"
-
-
- The text is a network mask, which might be expressed as a
- dotted quad, a hexadecimal string, or as a
- / followed by a number.
-
-
-
-
- role="mac"
-
-
- The text is an Ethernet MAC address, expressed as a series
- of 2 digit hexadecimal numbers separated by colons.
-
-
-
-
-
- hostid and roles
-
- Use:
-
- The local machine can always be referred to by the
- name localhost, which will have the IP address
- 127.0.0.1.
-
-The FreeBSD.org domain
- contains a number of different hosts, including
- freefall.FreeBSD.org and
- bento.FreeBSD.org.
-
-When adding an IP alias to an interface (using
- ifconfig) always use a
- netmask of 255.255.255.255
- (which can also be expressed as 0xffffffff.
-
-The MAC address uniquely identifies every network card
- in existence. A typical MAC address looks like 08:00:20:87:ef:d0.]]>
-
- Appearance:
-
- The local machine can always be referred to by the name
- localhost, which will have the IP address 127.0.0.1.
-
- The FreeBSD.org domain
- contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org.
-
- When adding an IP alias to an interface (using
- ifconfig) always use a
- netmask of 255.255.255.255 (which
- can also be expressed as 0xffffffff.
-
- The MAC address uniquely identifies every network card in
- existence. A typical MAC address looks like 08:00:20:87:ef:d0.
-
-
-
-
- Usernames
-
-
- FreeBSD extension
-
- These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.
-
-
- When you need to refer to a specific username, such as
- root or bin, use
- username.
-
-
- username
-
- Use:
-
- To carry out most system administration functions you
- will need to be root.]]>
-
- Appearance:
-
- To carry out most system administration functions you will
- need to be root.
-
-
-
-
- Describing Makefiles
-
-
- FreeBSD extension
-
- These elements are part of the FreeBSD extension to DocBook,
- and do not exist in the original DocBook DTD.
-
-
- Two elements exist to describe parts of
- Makefiles, maketarget and
- makevar.
-
- maketarget identifies a build target exported
- by a Makefile that can be given as a parameter
- to make. makevar identifies a
- variable that can be set (in the environment, on the
- make command line, or within the
- Makefile) to influence the process.
-
-
- maketarget and
- makevar
-
- Use:
-
- Two common targets in a Makefile
- are all and clean.
-
-Typically, invoking all will rebuild the
- application, and invoking clean will remove
- the temporary files (.o for example) created by
- the build process.
-
-clean may be controlled by a number of
- variables, including CLOBBER and
- RECURSE.]]>
-
- Appearance:
-
- Two common targets in a Makefile are
- all and
- clean.
-
- Typically, invoking all will rebuild
- the application, and invoking clean will
- remove the temporary files (.o for example)
- created by the build process.
-
- clean may be controlled by a number
- of variables, including CLOBBER and
- RECURSE.
-
-
-
-
- Literal text
-
- You will often need to include literal text in the
- Handbook. This is text that is excerpted from another file, or
- which should be copied from the Handbook into another file
- verbatim.
-
- Some of the time, programlisting will be
- sufficient to denote this text. programlisting
- is not always appropriate, particularly when you want to include a
- portion of a file in-line with the rest of the
- paragraph.
-
- On these occasions, use literal.
-
-
- literal
-
- Use:
-
- 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.]]>
-
- Appearance:
-
- 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.
-
-
-
-
- Showing items that the user must fill
- in
-
- There will often be times when you want to show the user what to
- do, or refer to a file, or command line, or similar, where the user
- cannot simply copy the examples that you provide, but must instead
- include some information themselves.
-
- replaceable is designed for this eventuality.
- Use it inside other elements to indicate parts
- of that element's content that the user must replace.
-
-
- replaceable
-
- Use:
-
-
- &prompt.user; man command
-]]>
-
- Appearance:
-
-
- &prompt.user; man command
-
-
- replaceable can be used in many different
- elements, including literal. This example also
- shows that replaceable should only be wrapped
- around the content that the user is meant to
- provide. The other content should be left alone.
-
- Use:
-
- 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.
-
-For a desktop workstation, 32 is a good value
- for n.]]>
-
- Appearance:
-
- 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.
-
- For a desktop workstation, 32 is a good
- value for n.
-
-
-
-
- Quoting system errors
-
- You might want to show errors generated by FreeBSD.
- Mark these with errorname. This
- indicates the exact error that appears.
-
-
- errorname
-
- Use:
-
- Panic: cannot mount root ]]>
-
-
-
- Appearance:
-
-
- Panic: cannot mount root
-
-
-
-
-
-
- Images
-
-
- Image support in the documentation is currently extremely
- experimental. I think the mechanisms described here are unlikely to
- change, but that is not guaranteed.
-
- You will also need to install the
- graphics/ImageMagick port, which is used to
- convert between the different image formats. This is a big port,
- and most of it is not required. However, while we are working on the
- Makefiles and other infrastructure it makes
- things easier. This port is not in the
- textproc/docproj meta port, you must install it
- by hand.
-
- The best example of what follows in practice is the
- doc/en_US.ISO8859-1/articles/vm-design/ document.
- If you are unsure of the description that follows, take a look at the
- files in that directory to see how everything hangs together.
- Experiment with creating different formatted versions of the
- document to see how the image markup appears in the formatted
- output.
-
-
-
- Image formats
-
- We currently support two formats for images. The format you
- should use will depend on the nature of your image.
-
- For images that are primarily vector based, such as network
- diagrams, time lines, and similar, use Encapsulated Postscript, and
- make sure that your images have the .eps
- extension.
-
- For bitmaps, such as screen captures, use the Portable Network
- Graphic format, and make sure that your images have the
- .png extension.
-
- These are the only formats in which images
- should be committed to the CVS repository.
-
- Use the right format for the right image. It is to be expected
- that your documentation will have a mix of EPS and PNG images. The
- Makefiles ensure that the correct format image
- is chosen depending on the output format that you use for your
- documentation. Do not commit the same image to the
- repository in two different formats.
-
-
- It is anticipated that the Documentation Project will switch to
- using the Scalable Vector Graphic (SVG) format for vector images.
- However, the current state of SVG capable editing tools makes this
- impractical.
-
-
-
-
- Markup
-
- The markup for an image is relatively simple. First, markup a
- mediaobject. The mediaobject
- can contain other, more specific objects. We are concerned with
- two, the imageobject and the
- textobject.
-
- You should include one imageobject, and two
- textobject elements. The
- imageobject will point to the name of the image
- file that will be used (without the extension). The
- textobject elements contain information that will
- be presented to the user as well as, or instead of, the
- image.
-
- There are two circumstances where this can happen.
-
-
-
- When the reader is viewing the documentation in HTML. In
- this case, each image will need to have associated alternate
- text to show the user, typically whilst the image is loading, or
- if they hover the mouse pointer over the image.
-
-
-
- When the reader is viewing the documentation in plain text.
- In this case, each image should have an ASCII art equivalent to
- show the user.
-
-
-
- An example will probably make things easier to understand.
- Suppose you have an image, called fig1.png, that
- you want to include in the document. This image is of a rectangle
- with an A inside it. The markup for this would be as
- follows.
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="fig1">
- </imageobject>
-
- <textobject>
- <literallayout class="monospaced">+---------------+
-| A |
-+---------------+</literallayout>
- </textobject>
-
- <textobject>
- <phrase>A picture</phrase>
- </textobject>
-</mediaobject>
-
-
-
- Include an imagedata element inside the
- imageobject element. The
- fileref attribute should contain the filename
- of the image to include, without the extension. The stylesheets
- will work out which extension should be added to the filename
- automatically.
-
-
-
- The first textobject should contain a
- literallayout element, where the
- class attribute is set to
- monospaced. This is your opportunity to
- demonstrate your ASCII art skills. This content will be used if
- the document is converted to plain text.
-
- Notice how the first and last lines of the content of the
- literallayout element butt up next to the
- element's tags. This ensures no extraneous white space is
- included.
-
-
-
- The second textobject should contain a
- single phrase element. The contents of this
- will become the alt attribute for the image
- when this document is converted to HTML.
-
-
-
-
-
- Makefile entries
-
- Your images must be listed in the
- Makefile in the IMAGES
- variable. This variable should contain the name of all your
- source images. For example, if you have
- created three figures, fig1.eps,
- fig2.png, fig3.png, then
- your Makefile should have lines like this in
- it.
-
- …
-IMAGES= fig1.eps fig2.png fig3.png
-…
-
- or
-
- …
-IMAGES= fig1.eps
-IMAGES+= fig2.png
-IMAGES+= fig3.png
-…
-
- Again, the Makefile will work out the
- complete list of images it needs to build your source document, you
- only need to list the image files you
- provided.
-
-
-
- Images and chapters in subdirectories
-
- You must be careful when you separate your documentation into
- smaller files (see ) in
- different directories.
-
- Suppose you have a book with three chapters, and the chapters
- are stored in their own directories, called
- chapter1/chapter.xml,
- chapter2/chapter.xml, and
- chapter3/chapter.xml. If each chapter has
- images associated with it, I suggest you place those images in each
- chapter's subdirectory (chapter1/,
- chapter2/, and
- chapter3/).
-
- However, if you do this you must include the directory names in
- the IMAGES variable in the
- Makefile, and you must
- include the directory name in the imagedata
- element in your document.
-
- For example, if you have chapter1/fig1.png,
- then chapter1/chapter.xml should
- contain:
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="chapter1/fig1">
- </imageobject>
-
- …
-
-</mediaobject>
-
-
-
- The directory name must be included in the
- fileref attribute.
-
-
-
- The Makefile must contain:
-
- …
-IMAGES= chapter1/fig1.png
-…
-
- Then everything should just work.
-
-
-
-
- Links
-
-
- Links are also in-line elements.
-
-
-
- Linking to other parts of the same document
-
- Linking within the same document requires you to specify
- where you are linking from (i.e., the text the user will click, or
- otherwise indicate, as the source of the link) and where you are
- linking to (the link's destination).
-
- Each element within DocBook has an attribute called
- id. You can place text in this attribute to
- uniquely name the element it is attached to.
-
- This value will be used when you specify the link
- source.
-
- Normally, you will only be linking to chapters or sections, so
- you would add the id attribute to these
- elements.
-
-
- id on chapters and sections
-
-
- Introduction
-
- This is the introduction. It contains a subsection,
- which is identified as well.
-
-
- Sub-sect 1
-
- This is the subsection.
-
-]]>
-
-
- Obviously, you should use more descriptive values. The values
- must be unique within the document (i.e., not just the file, but the
- document the file might be included in as well). Notice how the
- id for the subsection is constructed by appending
- text to the id of the chapter. This helps to
- ensure that they are unique.
-
- If you want to allow the user to jump into a specific portion of
- the document (possibly in the middle of a paragraph or an example),
- use anchor. This element has no content, but
- takes an id attribute.
-
-
- anchor
-
- This paragraph has an embedded
- link target in it. It will not show up in
- the document.]]>
-
-
- When you want to provide the user with a link they can activate
- (probably by clicking) to go to a section of the document that has
- an id attribute, you can use either
- xref or link.
-
- Both of these elements have a linkend
- attribute. The value of this attribute should be the value that you
- have used in a id attribute (it does not matter
- if that value has not yet occurred in your document; this will work
- for forward links as well as backward links).
-
- If you use xref then you have no control over
- the text of the link. It will be generated for you.
-
-
- Using xref
-
- Assume that this fragment appears somewhere in a document that
- includes the id example:
-
- More information can be found
- in .
-
-More specific information can be found
- in .]]>
-
- The text of the link will be generated automatically, and will
- look like (emphasized text indicates the text
- that will be the link):
-
-
- More information can be found in Chapter
- One.
-
- More specific information can be found in the
- section called Sub-sect 1.
-
-
-
- Notice how the text from the link is derived from the section
- title or the chapter number.
-
-
- This means that you cannot use
- xref to link to an id
- attribute on an anchor element. The
- anchor has no content, so the
- xref cannot generate the text for the
- link.
-
-
- If you want to control the text of the link then use
- link. This element wraps content, and the
- content will be used for the link.
-
-
- Using link
-
- Assume that this fragment appears somewhere in a document that
- includes the id example.
-
- More information can be found in
- the first chapter.
-
-More specific information can be found in
- this section.]]>
-
- This will generate the following
- (emphasized text indicates the text that will
- be the link):
-
-
- More information can be found in the first
- chapter.
-
- More specific information can be found in
- this section.
-
-
-
-
- That last one is a bad example. Never use words like
- this or here as the source for the
- link. The reader will need to hunt around the surrounding context
- to see where the link is actually taking them.
-
-
-
- You can use link to
- include a link to an id on an
- anchor element, since the
- link content defines the text that will be used
- for the link.
-
-
-
-
- Linking to documents on the WWW
-
- Linking to external documents is much simpler, as long as you
- know the URL of the document you want to link to. Use
- ulink. The url attribute is
- the URL of the page that the link points to, and the content of the
- element is the text that will be displayed for the user to
- activate.
-
-
- ulink
-
- Use:
-
- Of course, you could stop reading this document and
- go to the FreeBSD
- home page instead.]]>
-
- Appearance:
-
- Of course, you could stop reading this document and go to the
- FreeBSD home page
- instead.
-
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml
deleted file mode 100644
index eb17a7cd91e2..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/sgml-primer/chapter.xml
+++ /dev/null
@@ -1,1543 +0,0 @@
-
-
-
- SGML Primer
-
- FDP 文件幾乎都是以 SGML 相關程式寫的。本章會介紹 SGML 是什麼、
- 如何閱讀、理解這些 SGML 原稿,以及本文件中所運用的各項 SGML 技巧。
-
- 本節部分靈感啟發來自 Mark Galassi 的這篇 Get Going With DocBook。
-
-
- 簡介
-
- 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.
-
- 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 typewriter style
- font for viewing on screen, but as italics when printed,
- or any of a myriad of other options for presentation.
-
- It was once hoped that Artificial Intelligence (AI) would make this
- easy. Your computer would read in 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 text.
-
- More precisely, they need help identifying what is what. You or I
- can look at
-
-
- To remove /tmp/foo use &man.rm.1;.
-
- &prompt.user; rm /tmp/foo
-
-
- and easily see which parts are filenames, which are commands to be typed
- in, which parts are references to manual pages, and so on. But the
- computer processing the document cannot. For this we need
- markup.
-
- Markup is commonly used to describe adding
- value or increasing cost. The term takes on both
- these meanings when applied to text. Markup is additional text included
- in the document, distinguished from the document's content in some way,
- so that programs that process the document can read the markup and use
- it when making decisions about the document. Editors can hide the
- markup from the user, so the user is not distracted by it.
-
- The extra information stored in the markup adds
- value 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 increases the
- cost (i.e., the effort required) to create the
- document.
-
- The previous example is actually represented in this document like
- this:
-
- To remove /tmp/foo use &man.rm.1;.
-
-&prompt.user; rm /tmp/foo]]>
-
- As you can see, the markup is clearly separate from the
- content.
-
- 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.
-
- 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 meta markup
- language.
-
- This is exactly what the Standard Generalized Markup Language (SGML)
- is. Many markup languages have been written in SGML, including the two
- most used by the FDP, HTML and DocBook.
-
- Each language definition is more properly called a Document Type
- Definition (DTD). The DTD 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. A DTD is sometimes
- referred to as an application of SGML.
-
- A DTD is a complete
- 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 SGML
- parser which reads in both the DTD and a document
- which claims to conform to the DTD. The parser can then confirm whether
- or not all the elements required by the DTD are in the document in the
- right order, and whether there are any errors in the markup. This is
- normally referred to as validating the document.
-
-
- This processing simply confirms that the choice of elements, their
- ordering, and so on, conforms to that listed in the DTD. It does
- not check that you have used
- appropriate 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 DTD defines elements for filenames and functions,
- and that they are allowed to appear in the same place).
-
-
- It is likely that most of your contributions to the Documentation
- Project will consist of content marked up in either HTML or DocBook,
- rather than alterations to the DTDs. For this reason this book will
- not touch on how to write a DTD.
-
-
-
- Elements, tags, and attributes
-
- All the DTDs written in SGML share certain characteristics. This is
- hardly surprising, as the philosophy behind SGML will inevitably show
- through. One of the most obvious manifestations of this philosophy is
- that of content and
- elements.
-
- 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.
-
- For example, consider a typical book. At the very top level, the
- book is itself an element. This book element obviously
- contains chapters, which can be considered to be elements in their own
- right. Each chapter will contain more elements, such as paragraphs,
- quotations, and footnotes. Each paragraph might contain further
- elements, identifying content that was direct speech, or the name of a
- character in the story.
-
- You might like to think of this as chunking 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.
-
- Notice how you can make this differentiation between different
- elements of the content without resorting to any SGML 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.
-
- 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 SGML (HTML, DocBook, et al) this is done by
- means of tags.
-
- A tag is used to identify where a particular element starts, and
- where the element ends. The tag is not part of the element
- itself. Because each DTD 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.
-
- For an element called element-name the
- start tag will normally look like
- <element-name>. The
- corresponding closing tag for this element is
- </element-name>.
-
-
- Using an element (start and end tags)
-
- HTML has an element for indicating that the content enclosed by
- the element is a paragraph, called p. This
- element has both start and end tags.
-
- 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.
-
-
This is another paragraph. But this one is much shorter.
]]>
-
-
- Not all elements require an end tag. Some elements have no content.
- For example, in HTML you can indicate that you want a horizontal line to
- appear in the document. Obviously, this line has no content, so just
- the start tag is required for this element.
-
-
- Using an element (start tag only)
-
- HTML has an element for indicating a horizontal rule, called
- hr. This element does not wrap content, so only
- has a start tag.
-
- This is a paragraph.
-
-
-
-
This is another paragraph. A horizontal rule separates this
- from the previous paragraph.
]]>
-
-
- 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.
-
-
- Elements within elements; em
-
- This is a simple paragraph where some
- of the words have been emphasized.]]>
-
-
- The DTD will specify the rules detailing which elements can contain
- other elements, and exactly what they can contain.
-
-
- People often confuse the terms tags and elements, and use the
- terms as if they were interchangeable. They are not.
-
- 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.
-
- When this document (or anyone else knowledgeable about SGML) refers
- to the <p> tag they mean the literal text
- consisting of the three characters <,
- p, and >. But the phrase
- the <p> element refers to the whole
- element.
-
- This distinction is very subtle. But keep it
- in mind.
-
-
- Elements can have attributes. An attribute has a name and a value,
- and is used for adding extra information to the element. This might be
- information that indicates how the content should be rendered, or might
- be something that uniquely identifies that occurrence of the element, or
- it might be something else.
-
- An element's attributes are written inside the
- start tag for that element, and take the form
- attribute-name="attribute-value".
-
- In sufficiently recent versions of HTML, the p
- element has an attribute called align, which suggests
- an alignment (justification) for the paragraph to the program displaying
- the HTML.
-
- The align attribute can take one of four defined
- values, left, center,
- right and justify. If the
- attribute is not specified then the default is
- left.
-
-
- Using an element with an attribute
-
- The inclusion of the align attribute
- on this paragraph was superfluous, since the default is left.
-
-
This may appear in the center.
]]>
-
-
- Some attributes will only take specific values, such as
- left or justify. Others will
- allow you to enter anything you want. If you need to include quotes
- (") within an attribute then use single quotes around
- the attribute value.
-
-
- Single quotes around attributes
-
- I am on the right!]]>
-
-
- Sometimes you do not need to use quotes around attribute values at
- all. However, the rules for doing this are subtle, and it is far
- simpler just to always quote your attribute
- values.
-
- The information on attributes, elements, and tags is stored
- in SGML catalogs. The various Documentation Project tools use
- these catalog files to validate your work. The tools in
- textproc/docproj include a variety of SGML catalog
- files. The FreeBSD Documentation Project includes its own set
- of catalog files. Your tools need to know about both sorts of
- catalog files.
-
-
- For you to do…
-
- 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.
-
-
-
- Download and install textproc/docproj
- from the FreeBSD ports system. This is a
- meta-port that should download and install
- all of the programs and supporting files that are used by the
- Documentation Project.
-
-
-
- Add lines to your shell startup files to set
- SGML_CATALOG_FILES. (If you are not working
- on the English version of the documentation, you will want
- to substitute the correct directory for your
- language.)
-
-
- .profile, for &man.sh.1; and
- &man.bash.1; users
-
- SGML_ROOT=/usr/local/share/xml
-SGML_CATALOG_FILES=${SGML_ROOT}/jade/catalog
-SGML_CATALOG_FILES=${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
-SGML_CATALOG_FILES=${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
-SGML_CATALOG_FILES=${SGML_ROOT}/docbook/4.1/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
-export SGML_CATALOG_FILES
-
-
-
- .cshrc, for &man.csh.1; and
- &man.tcsh.1; users
-
- setenv SGML_ROOT /usr/local/share/xml
-setenv SGML_CATALOG_FILES ${SGML_ROOT}/jade/catalog
-setenv SGML_CATALOG_FILES ${SGML_ROOT}/iso8879/catalog:$SGML_CATALOG_FILES
-setenv SGML_CATALOG_FILES ${SGML_ROOT}/html/catalog:$SGML_CATALOG_FILES
-setenv SGML_CATALOG_FILES ${SGML_ROOT}/docbook/4.1/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
-
-
- Then either log out, and log back in again, or run those
- commands from the command line to set the variable values.
-
-
-
-
-
- Create example.xml, and enter the
- following text:
-
-
-
-
-
- An example HTML file
-
-
-
-
This is a paragraph containing some text.
-
-
This paragraph contains some more text.
-
-
This paragraph might be right-justified.
-
-]]>
-
-
-
- Try to validate this file using an SGML parser.
-
- Part of textproc/docproj is the
- nsgmls validating
- parser. Normally, nsgmls reads in a document
- marked up according to an SGML DTD and returns a copy of the
- document's Element Structure Information Set (ESIS, but that is
- not important right now).
-
- However, when nsgmls is given the
- parameter, nsgmls will suppress its normal output, and
- just print error messages. This makes it a useful way to check to
- see if your document is valid or not.
-
- Use nsgmls to check that your document is
- valid:
-
- &prompt.user; nsgmls -s example.xml
-
- As you will see, nsgmls returns without displaying any
- output. This means that your document validated
- successfully.
-
-
-
- See what happens when required elements are omitted. Try
- removing the title and
- /title tags, and re-run the validation.
-
- &prompt.user; nsgmls -s example.xml
-nsgmls:example.xml:5:4:E: character data is not allowed here
-nsgmls:example.xml:6:8:E: end tag for "HEAD" which is not finished
-
- The error output from nsgmls is organized into
- colon-separated groups, or columns.
-
-
-
-
-
- Column
- Meaning
-
-
-
-
-
- 1
- The name of the program generating the error. This
- will always be nsgmls.
-
-
-
- 2
- The name of the file that contains the error.
-
-
-
- 3
- Line number where the error appears.
-
-
-
- 4
- Column number where the error appears.
-
-
-
- 5
- A one letter code indicating the nature of the
- message. I indicates an informational
- message, W is for warnings, and
- E is for errors
- It is not always the fifth column either.
- nsgmls -sv displays
- nsgmls:I: SP version "1.3"
- (depending on the installed version). As you can see,
- this is an informational message.
- , and X is for
- cross-references. As you can see, these messages are
- errors.
-
-
-
- 6
- The text of the error message.
-
-
-
-
-
- Simply omitting the title tags has
- generated 2 different errors.
-
- The first error indicates that content (in this case,
- characters, rather than the start tag for an element) has occurred
- where the SGML parser was expecting something else. In this case,
- the parser was expecting to see one of the start tags for elements
- that are valid inside head (such as
- title).
-
- The second error is because head elements
- must contain a title
- element. Because it does not nsgmls considers that the
- element has not been properly finished. However, the closing tag
- indicates that the element has been closed before it has been
- finished.
-
-
-
- Put the title element back in.
-
-
-
-
-
-
- The DOCTYPE declaration
-
- The beginning of each document that you write must specify the name
- of the DTD that the document conforms to. This is so that SGML parsers
- can determine the DTD and ensure that the document does conform to
- it.
-
- This information is generally expressed on one line, in the DOCTYPE
- declaration.
-
- A typical declaration for a document written to conform with version
- 4.0 of the HTML DTD looks like this:
-
- ]]>
-
- That line contains a number of different components.
-
-
-
- <!
-
-
- Is the indicator that indicates that this
- is an SGML declaration. This line is declaring the document type.
-
-
-
-
-
- DOCTYPE
-
-
- Shows that this is an SGML declaration for the document
- type.
-
-
-
-
- html
-
-
- Names the first element that
- will appear in the document.
-
-
-
-
- PUBLIC "-//W3C//DTD HTML 4.0//EN"
-
-
- Lists the Formal Public Identifier (FPI)
- Formal Public Identifier
-
- for the DTD that this
- document conforms to. Your SGML parser will use this to find the
- correct DTD when processing this document.
-
- PUBLIC is not a part of the FPI, but
- indicates to the SGML processor how to find the DTD referenced in
- the FPI. Other ways of telling the SGML parser how to find the
- DTD are shown later.
-
-
-
-
- >
-
-
- Returns to the document.
-
-
-
-
-
- Formal Public Identifiers (FPIs)
- Formal Public Identifier
-
-
-
-
- You do not need to know this, but it is useful background, and
- might help you debug problems when your SGML processor can not locate
- the DTD you are using.
-
-
- FPIs must follow a specific syntax. This syntax is as
- follows:
-
- "Owner//KeywordDescription//Language"
-
-
-
- Owner
-
-
- This indicates the owner of the FPI.
-
- If this string starts with ISO then this is an
- ISO owned FPI. For example, the FPI "ISO
- 8879:1986//ENTITIES Greek Symbols//EN" lists
- ISO 8879:1986 as being the owner for the set
- of entities for Greek symbols. ISO 8879:1986 is the ISO number
- for the SGML standard.
-
- Otherwise, this string will either look like
- -//Owner or
- +//Owner (notice
- the only difference is the leading + or
- -).
-
- If the string starts with - then the
- owner information is unregistered, with a +
- it identifies it as being registered.
-
- 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 registration authority could be created in order
- to assign registered names. The ISO council delegated this to
- the American National Standards Institute (ANSI).
-
- Because the FreeBSD Project has not been registered the
- owner string is -//FreeBSD. And as you can
- see, the W3C are not a registered owner either.
-
-
-
-
- Keyword
-
-
- There are several keywords that indicate the type of
- information in the file. Some of the most common keywords are
- DTD, ELEMENT,
- ENTITIES, and TEXT.
- DTD is used only for DTD files,
- ELEMENT is usually used for DTD fragments
- that contain only entity or element declarations.
- TEXT is used for SGML content (text and
- tags).
-
-
-
-
- Description
-
-
- Any description you want to supply for the contents of this
- file. This may include version numbers or any short text that
- is meaningful to you and unique for the SGML system.
-
-
-
-
- Language
-
-
- This is an ISO two-character code that identifies the native
- language for the file. EN is used for
- English.
-
-
-
-
-
- catalog files
-
- If you use the syntax above and process this document
- using an SGML 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.
-
- In order to do this it can use a catalog file. A catalog file
- (typically called catalog) contains lines that
- map FPIs to filenames. For example, if the catalog file contained
- the line:
-
- PUBLIC "-//W3C//DTD HTML 4.0//EN" "4.0/strict.dtd"
-
- The SGML processor would know to look up the DTD from
- strict.dtd in the 4.0
- subdirectory of whichever directory held the
- catalog file that contained that line.
-
- Look at the contents of
- /usr/local/share/xml/html/catalog. This is
- the catalog file for the HTML DTDs that will have been installed as
- part of the textproc/docproj port.
-
-
-
- SGML_CATALOG_FILES
-
- In order to locate a catalog file, your
- SGML processor will need to know where to look. Many of them
- feature command line parameters for specifying the path to one or
- more catalogs.
-
- In addition, you can set SGML_CATALOG_FILES to
- point to the files. This environment variable should consist of a
- colon-separated list of catalog files (including their full
- path).
-
- Typically, you will want to include the following files:
-
-
-
- /usr/local/share/xml/docbook/4.1/catalog
-
-
-
- /usr/local/share/xml/html/catalog
-
-
-
- /usr/local/share/xml/iso8879/catalog
-
-
-
- /usr/local/share/xml/jade/catalog
-
-
-
- You should already have done
- this.
-
-
-
-
- Alternatives to FPIs
-
- 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.
-
- The syntax for this is slightly different:
-
- ]]>
-
- The SYSTEM keyword indicates that the SGML
- processor should locate the DTD in a system specific fashion. This
- typically (but not always) means the DTD will be provided as a
- filename.
-
- 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 SYSTEM identifier then everyone
- would need to keep their DTDs in the same place.
-
-
-
-
- Escaping back to SGML
-
- Earlier in this primer I said that SGML is only used when writing a
- DTD. This is not strictly true. There is certain SGML 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 SGML syntax. Other uses for SGML
- syntax in your document will be shown later too.
-
- Obviously, you need some way of indicating to the SGML processor
- that the following content is not elements within the document, but is
- SGML that the parser should act upon.
-
- These sections are marked by <! ... > in
- your document. Everything between these delimiters is SGML syntax as
- you might find within a DTD.
-
- As you may just have realized, the DOCTYPE declaration
- is an example of SGML syntax that you need to include in your
- document…
-
-
-
- 註解
-
- Comments are an SGML construction, and are normally only valid
- inside a DTD. However, as
- shows, it is possible to use SGML syntax within your document.
-
- The delimiter for SGML comments is the string
- --. The first occurrence of this string
- opens a comment, and the second closes it.
-
-
- SGML generic comment
-
- <!-- 測試註解 -->
-
-
-<!‐- 這是註解 -‐>
-
-<!‐- 這也是註解 -‐>
-
-<!‐- 要寫多行註解的話,
- 這是其中之一的方式 -‐>
-
-<!‐- 要寫多行註解, -‐
- ‐- 也可以這樣子用 -‐>
-
-
- If you have used HTML before you may have been shown different rules
- for comments. In particular, you may think that the string
- <!-- opens a comment, and it is only closed by
- -->.
-
- This is not the case. A lot of web browsers
- have broken HTML parsers, and will accept that as valid. However, the
- SGML parsers used by the Documentation Project are much stricter, and
- will reject documents that make that error.
-
-
- Erroneous SGML comments
-
-
-<!‐- This is in the comment -‐
-
- THIS IS OUTSIDE THE COMMENT!
-
- ‐- back inside the comment -‐>
-
- The SGML parser will treat this as though it were actually:
-
- <!THIS IS OUTSIDE THE COMMENT>
-
- This is not valid SGML, and may give confusing error
- messages.
-
- <!‐‐‐‐‐ This is a very bad idea ‐‐‐‐‐>
-
- As the example suggests, do not write
- comments like that.
-
- <!‐-===================================================-‐>
-
- That is a (slightly) better approach, but it still potentially
- confusing to people new to SGML.
-
-
-
- For you to do…
-
-
-
- Add some comments to example.xml, and
- check that the file still validates using nsgmls.
-
-
-
- Add some invalid comments to
- example.xml, and see the error messages that
- nsgmls gives when it encounters an invalid comment.
-
-
-
-
-
-
- Entities
-
- Entities are a mechanism for assigning names to chunks of content.
- As an SGML parser processes your document, any entities it finds are
- replaced by the content of the entity.
-
- This is a good way to have re-usable, easily changeable chunks of
- content in your SGML documents. It is also the only way to include one
- marked up file inside another using SGML.
-
- There are two types of entities which can be used in two different
- situations; general entities and
- parameter entities.
-
-
- General Entities
-
- You cannot use general entities in an SGML context (although you
- define them in one). They can only be used in your document.
- Contrast this with parameter
- entities.
-
- 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
- &entity-name;. For
- example, suppose you had an entity called
- current.version which expanded to the current
- version number of your product. You could write:
-
- The current version of our product is
- ¤t.version;.]]>
-
- When the version number changes you can simply change the
- definition of the value of the general entity and reprocess your
- document.
-
- You can also use general entities to enter characters that you
- could not otherwise include in an SGML document. For example,
- < and & cannot
- normally appear in an SGML document. When the SGML
- parser sees the <
- symbol it assumes that a tag (either a start tag
- or an end tag) is about to appear, and when it sees the
- & symbol
- it assumes the next text will be the name of an entity.
-
- Fortunately, you can use the two general entities
- < and &
- whenever you need to include one or other of these.
-
- A general entity can only be defined within an SGML context.
- Typically, this is done immediately after the DOCTYPE
- declaration.
-
-
- Defining general entities
-
-
-
-]>]]>
-
- 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.
-
- The square brackets are necessary to indicate that we are
- extending the DTD indicated by the DOCTYPE declaration.
-
-
-
-
- Parameter entities
-
- Like general
- entities, parameter entities are used to assign names to
- reusable chunks of text. However, where as general entities can only
- be used within your document, parameter entities can only be used
- within an SGML
- context.
-
- Parameter entities are defined in a similar way to general
- entities. However, instead of using
- &entity-name; to
- refer to them, use
- %entity-name;
- Parameter entities use the
- Percent symbol.
- . The definition also includes the %
- between the ENTITY keyword and the name of the
- entity.
-
-
- Defining parameter entities
-
-
-
-
-]>]]>
-
-
- This may not seem particularly useful. It will be.
-
-
-
- For you to do…
-
-
-
- Add a general entity to
- example.xml.
-
-
-]>
-
-
-
- An example HTML file
-
-
-
-
This is a paragraph containing some text.
-
-
This paragraph contains some more text.
-
-
This paragraph might be right-justified.
-
-
The current version of this document is: &version;
-
-]]>
-
-
-
- Validate the document using nsgmls.
-
-
-
- Load example.xml into your web browser
- (you may need to copy it to example.html
- before your browser recognizes it as an HTML document).
-
- Unless your browser is very advanced, you will not see the entity
- reference &version; replaced with the
- version number. Most web browsers have very simplistic parsers
- which do not handle proper SGML
- This is a shame. Imagine all the problems and hacks (such
- as Server Side Includes) that could be avoided if they
- did.
- .
-
-
-
- The solution is to normalize your
- document using an SGML normalizer. The normalizer reads in valid
- SGML and outputs equally valid SGML which has been transformed in
- some way. One of the ways in which the normalizer transforms the
- SGML is to expand all the entity references in the document,
- replacing the entities with the text that they represent.
-
- You can use sgmlnorm to do this.
-
- &prompt.user; sgmlnorm example.xml > example.html
-
- You should find a normalized (i.e., entity references
- expanded) copy of your document in
- example.html, ready to load into your web
- browser.
-
-
-
- If you look at the output from sgmlnorm
- you will see that it does not include a DOCTYPE declaration at
- the start. To include this you need to use the
- option:
-
- &prompt.user; sgmlnorm -d example.xml > example.html
-
-
-
-
-
-
- Using entities to include files
-
- Entities (both general and parameter) are
- particularly useful when used to include one file inside another.
-
-
- Using general entities to include files
-
- Suppose you have some content for an SGML book organized into
- files, one file per chapter, called
- chapter1.xml,
- chapter2.xml, and so forth, with a
- book.xml file that will contain these
- chapters.
-
- In order to use the contents of these files as the values for your
- entities, you declare them with the SYSTEM keyword.
- This directs the SGML parser to use the contents of the named file as
- the value of the entity.
-
-
- Using general entities to include files
-
-
-
-
-]>
-
-
-
- &chapter.1;
- &chapter.2;
- &chapter.3;
-]]>
-
-
-
- When using general entities to include other files within a
- document, the files being included
- (chapter1.xml,
- chapter2.xml, and so on) must
- not start with a DOCTYPE declaration. This is a syntax
- error.
-
-
-
-
- Using parameter entities to include files
-
- Recall that parameter entities can only be used inside an SGML
- context. Why then would you want to include a file within an SGML
- context?
-
- You can use this to ensure that you can reuse your general
- entities.
-
- Suppose that you had many chapters in your document, and you
- reused these chapters in two different books, each book organizing the
- chapters in a different fashion.
-
- You could list the entities at the top of each book, but this
- quickly becomes cumbersome to manage.
-
- Instead, place the general entity definitions inside one file,
- and use a parameter entity to include that file within your
- document.
-
-
- Using parameter entities to include files
-
- First, place your entity definitions in a separate file, called
- chapters.ent. This file contains the
- following:
-
-
-
-]]>
-
- Now 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 as before:
-
-
-%chapters;
-]>
-
-
- &chapter.1;
- &chapter.2;
- &chapter.3;
-]]>
-
-
-
-
- For you to do…
-
-
- Use general entities to include files
-
-
-
- Create three files, para1.xml,
- para2.xml, and
- para3.xml.
-
- Put content similar to the following in each file:
-
- This is the first paragraph.]]>
-
-
-
- Edit example.xml so that it looks like
- this:
-
-
-
-
-
-]>
-
-
-
- An example HTML file
-
-
-
-
The current version of this document is: &version;
-
- ¶1;
- ¶2;
- ¶3;
-
-]]>
-
-
-
- Produce example.html by normalizing
- example.xml.
-
- &prompt.user; sgmlnorm -d example.xml > example.html
-
-
-
- Load example.html into your web
- browser, and confirm that the
- paran.xml files
- have been included in example.html.
-
-
-
-
-
- Use parameter entities to include files
-
-
- You must have taken the previous steps first.
-
-
-
-
- Edit example.xml so that it looks like
- this:
-
- %entities;
-]>
-
-
-
- An example HTML file
-
-
-
-
The current version of this document is: &version;
-
- ¶1;
- ¶2;
- ¶3;
-
-]]>
-
-
-
- Create a new file, entities.xml, with
- this content:
-
-
-
-
-]]>
-
-
-
- Produce example.html by normalizing
- example.xml.
-
- &prompt.user; sgmlnorm -d example.xml > example.html
-
-
-
- Load example.html into your web
- browser, and confirm that the
- paran.xml files
- have been included in example.html.
-
-
-
-
-
-
-
- Marked sections
-
- SGML provides a mechanism to indicate that particular pieces of the
- document should be processed in a special way. These are termed
- marked sections.
-
-
- Structure of a marked section
-
- <![ KEYWORD [
- Contents of marked section
-]]>
-
-
- As you would expect, being an SGML construct, a marked section
- starts with <!.
-
- The first square bracket begins to delimit the marked
- section.
-
- KEYWORD describes how this marked
- section should be processed by the parser.
-
- The second square bracket indicates that the content of the marked
- section starts here.
-
- The marked section is finished by closing the two square brackets,
- and then returning to the document context from the SGML context with
- >.
-
-
- Marked section keywords
-
-
- CDATA, RCDATA
-
- These keywords denote the marked sections content
- model, and allow you to change it from the
- default.
-
- When an SGML parser is processing a document it keeps track
- of what is called the content model.
-
- 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.
-
- The two content models you will probably find most useful are
- CDATA and RCDATA.
-
- CDATA is for Character Data.
- If the parser is in this content model then it is expecting to see
- characters, and characters only. In this model the
- < and &
- symbols lose their special status, and will be treated as ordinary
- characters.
-
- RCDATA is for Entity references and
- character data If the parser is in this content model then it
- is expecting to see characters and entities.
- < loses its special status, but
- & will still be treated as
- starting the beginning of a general entity.
-
- This is particularly useful if you are including some verbatim
- text that contains lots of < and
- & characters. While you
- could go through the text ensuring that every
- < is converted to a
- < and every &
- is converted to a &, it can be
- easier to mark the section as only containing CDATA. When the SGML
- parser encounters this it will ignore the
- < and & symbols
- embedded in the content.
-
-
- When you use CDATA or
- RCDATA in examples of text marked up in SGML,
- keep in mind that the content of CDATA is not
- validated. You have to check the included SGML text using other
- means. You could, for example, write the example in another
- document, validate the example code, and then paste it to your
- CDATA content.
-
-
-
-
- Using a CDATA marked section
-
- <para>Here is an example of how you would include some text
- that contained many <literal><</literal>
- and <literal>&</literal> symbols. The sample
- text is a fragment of HTML. The surrounding text (<para> and
- <programlisting>) are from DocBook.</para>
-
-<programlisting>
- <![CDATA[This is a sample that shows you some of the elements within
- HTML. 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.
-
-
-
This is a listitem
-
This is a second listitem
-
This is a third listitem
-
-
-
This is the end of the example.
]]>
- ]]>
-</programlisting>
-
- If you look at the source for this document you will see this
- technique used throughout.
-
-
-
-
- INCLUDE and
- IGNORE
-
- If the keyword is INCLUDE then the contents
- of the marked section will be processed. If the keyword is
- IGNORE then the marked section is ignored and
- will not be processed. It will not appear in the output.
-
-
- Using INCLUDE and
- IGNORE in marked sections
-
- <![ INCLUDE [
- This text will be processed and included.
-]]>
-
-<![ IGNORE [
- This text will not be processed or included.
-]]>
-
-
- 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.
-
- It becomes more useful when you realize you can use parameter entities
- to control this. Remember that parameter entities can only be used
- in SGML contexts, and the keyword of a marked section
- is an SGML context.
-
- 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.
-
- Create a parameter entity, and set its value to
- INCLUDE. Write your document, using marked
- sections to delimit content that should only appear in the
- electronic version. In these marked sections use the parameter
- entity in place of the keyword.
-
- When you want to produce the hard-copy version of the document,
- change the parameter entity's value to IGNORE and
- reprocess the document.
-
-
- Using a parameter entity to control a marked
- section
-
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
-<!ENTITY % electronic.copy "INCLUDE">
-]]>
-
-...
-
-<![ %electronic.copy [
- This content should only appear in the electronic
- version of the document.
-]]>
-
- When producing the hard-copy version, change the entity's
- definition to:
-
- <!ENTITY % electronic.copy "IGNORE">
-
- On reprocessing the document, the marked sections that use
- %electronic.copy as their keyword will be
- ignored.
-
-
-
-
-
- For you to do…
-
-
-
- Create a new file, section.xml, that
- contains the following:
-
- <!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0//EN" [
-<!ENTITY % text.output "INCLUDE">
-]>
-
-<html>
- <head>
- <title>An example using marked sections</title>
- </head>
-
- <body>
- <p>This paragraph <![CDATA[contains many <
- characters (< < < < <) so it is easier
- to wrap it in a CDATA marked section ]]></p>
-
- <![IGNORE[
- <p>This paragraph will definitely not be included in the
- output.</p>
- ]]>
-
- <![ [
- <p>This paragraph might appear in the output, or it
- might not.</p>
-
- <p>Its appearance is controlled by the
- parameter entity.</p>
- ]]>
- </body>
-</html>
-
-
-
- Normalize this file using &man.xmlnorm.1; and examine the
- output. Notice which paragraphs have appeared, which have
- disappeared, and what has happened to the content of the CDATA
- marked section.
-
-
-
- Change the definition of the text.output
- entity from INCLUDE to
- IGNORE. Re-normalize the file, and examine the
- output to see what has changed.
-
-
-
-
-
-
- Conclusion
-
- That is the conclusion of this SGML primer. For reasons of space
- and complexity several things have not been covered in depth (or at
- all). However, the previous sections cover enough SGML for you to be
- able to follow the organization of the FDP documentation.
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml
deleted file mode 100644
index c4feee84cbb0..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/structure/chapter.xml
+++ /dev/null
@@ -1,281 +0,0 @@
-
-
-
- Structuring documents under doc/
-
- The doc/ 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:
-
-
-
- make it easy to automate converting the document to other formats;
-
-
-
- promote consistency between the different documentation
- organizations, to make it easier to switch between working on
- different documents;
-
-
-
- make it easy to decide where in the tree new documentation should
- be placed.
-
-
-
- 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.
-
-
- The top level, doc/
-
- There are two types of directory under doc/,
- each with very specific directory names and meanings.
-
-
- Directory
-
- Meaning
-
-
- share/
-
- 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
- share/mk, while the additional SGML support
- files (such as the FreeBSD extended DocBook DTD) are in
- share/xml.
-
-
-
- lang.encoding/
-
- One directory exists for each available translation and encoding
- of the documentation, for example
- en_US.ISO8859-1/ and
- zh_TW.UTF-8/. 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.
-
-
-
-
-
- The
- lang.encoding/ directories
-
- These directories contain the documents themselves. The
- documentation is split into up to three more categories at this
- level, indicated by the different directory names.
-
-
- Directory
-
- Contents
-
-
- articles
-
- Documentation marked up as a DocBook article
- (or equivalent). Reasonably short, and broken up into sections.
- Normally only available as one HTML file.
-
-
-
- books
-
- Documentation marked up as a DocBook book (or
- equivalent). Book length, and broken up into chapters. Normally
- available as both one large HTML file (for people with fast
- connections, or who want to print it easily from a browser) and
- as a collection of linked, smaller files.
-
-
-
- man
-
- For translations of the system manual pages. This directory will
- contain one or more
- mann directories,
- corresponding to the sections that have been translated.
-
-
-
- Not every
- lang.encoding directory will contain all of these directories. It depends
- on how much translation has been accomplished by that translation
- team.
-
-
-
- Document specific information
-
- This section contains specific notes about particular documents
- managed by the FDP.
-
-
- The Handbook
-
- books/handbook/
-
- The Handbook is written to comply with the FreeBSD DocBook
- extended DTD.
-
- The Handbook is organized as a DocBook book.
- It is then divided into parts, each of which may
- contain several chapters.
- chapters are further subdivided into sections
- (sect1) and subsections (sect2,
- sect3) and so on.
-
-
- Physical organization
-
- There are a number of files and directories within the
- handbook directory.
-
-
- 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;.
-
-
-
- Makefile
-
- The Makefile defines some variables that
- affect how the SGML source is converted to other formats, and
- lists the various source files that make up the Handbook. It then
- includes the standard doc.project.mk file, to
- bring in the rest of the code that handles converting documents
- from one format to another.
-
-
-
- book.xml
-
- This is the top level document in the Handbook. It contains
- the Handbook's DOCTYPE
- declaration, as well as the elements that describe the
- Handbook's structure.
-
- book.xml uses parameter
- entities to load in the files with the
- .ent extension. These files (described later)
- then define general
- entities that are used throughout the rest of the
- Handbook.
-
-
-
- directory/chapter.xml
-
- Each chapter in the Handbook is stored in a file called
- chapter.xml in a separate directory from the
- other chapters. Each directory is named after the value of the
- id attribute on the chapter
- element.
-
- For example, if one of the chapter files contains:
-
-
-...
-]]>
-
- then it will be called chapter.xml in
- the kernelconfiguration directory. In
- general, the entire contents of the chapter will be held in this
- file.
-
- When the HTML version of the Handbook is produced, this will
- yield kernelconfiguration.html. This is
- because of the id value, and is not related to
- the name of the directory.
-
- In earlier versions of the Handbook the files were stored in
- the same directory as book.xml, and named
- after the value of the id attribute on the
- file's chapter element. Moving them into
- separate directories prepares for future plans for the Handbook.
- Specifically, it will soon be possible to include images in each
- chapter. It makes more sense for each image to be stored in a
- directory with the text for the chapter than to try to keep the
- text for all the chapters, and all the images, in one large
- directory. 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.
-
- A brief look will show that there are many directories with
- individual chapter.xml files, including
- basics/chapter.xml,
- introduction/chapter.xml, and
- printing/chapter.xml.
-
-
- 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).
-
-
- Each chapter.xml file will not be a
- complete SGML document. In particular, they will not have their
- own DOCTYPE lines at the start of the files.
-
- This is unfortunate as
- it makes it impossible to treat these as generic SGML
- files and simply convert them to HTML, RTF, PS, and other
- formats in the same way the main Handbook is generated. This
- would force you to rebuild the Handbook
- every time you want to see the effect a change has had on just
- one chapter.
-
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml
deleted file mode 100644
index b1ef0c746027..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/stylesheets/chapter.xml
+++ /dev/null
@@ -1,92 +0,0 @@
-
-
-
- * Stylesheets
-
- SGML 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 DynaText, Panorama, SPICE,
- JSSS, FOSI, CSS, and DSSSL.
-
- For DocBook, we are using stylesheets written in DSSSL. For HTML we
- are using CSS.
-
-
- * DSSSL
-
- The Documentation Project uses a slightly customized version of
- Norm Walsh's modular DocBook stylesheets.
-
- These can be found in
- textproc/dsssl-docbook-modular.
-
- The modified stylesheets are not in the ports system. Instead they
- are part of the Documentation Project source repository, and can be
- found in doc/share/xml/freebsd.dsl. It is well
- commented, and pending completion of this section you are encouraged to
- examine that file to see how some of the available options in the
- standard stylesheets have been configured in order to customize the
- output for the FreeBSD Documentation Project. That file also contains
- examples showing how to extend the elements that the stylesheet
- understands, which is how the FreeBSD specific elements have been
- formatted.
-
-
-
- CSS
-
- Cascading Stylesheets (CSS) are a mechanism for attaching style
- information (font, weight, size, color, and so forth) to elements in an
- HTML document without abusing HTML to do so.
-
-
- The Web site (HTML documents)
-
- The FreeBSD web site does not currently use CSS. Unfortunately,
- the look and feel is constructed using abuses of HTML of varying
- degrees. This should be fixed, and would be a good project for
- someone looking to contribute to the documentation project.
-
-
-
- The DocBook documents
-
- The FreeBSD DSSSL stylesheets include a reference to a stylesheet,
- docbook.css, which is expected to appear in the
- same directory as the HTML files. The project-wide CSS file is copied
- from doc/share/misc/docbook.css when documents
- are converted to HTML, and is installed automatically.
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml
deleted file mode 100644
index 8e2a94ad94d9..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/the-website/chapter.xml
+++ /dev/null
@@ -1,191 +0,0 @@
-
-
-
- 建構 Website
-
-
- 事前準備
-
- 請先準備約 200MB 空間,這些是要用來放 SGML 工具程式、CVS tree、
- 臨時編譯用的空間,以及編譯好的網頁存放空間。若事先已有裝 SGML 工具程式、
- CVS tree 的話,那麼只需頂多約 100MB 空間即可。
-
-
- 請確認一下你的相關文件製作所會用到的 ports 都是最新版!
- 若不清楚所裝的版本為何,那麼就先以 &man.pkg.delete.1; 指令來移除舊版,
- 接著才去裝 port。 舉例來說,若已裝的是 jade-1.1,
- 但是我們目前需要的卻是 jade-1.2,那麼先用下列方式來移除舊版:
-
- &prompt.root; pkg_delete jade-1.1
-
-
- 接著,就是設定 CVS repository。需要至少 www, doc, ports 這三樣
- CVS tree(當然還要加上 CVSROOT)。 請參閱
- CVSup 簡介
- 以瞭解如何來 mirror a CVS tree 或部分 CVS tree。
-
- 最低需求的 cvsup collections 為:www,
- doc-all, cvs-base 以及
- ports-base。
-
- 剛講的這些需要約 105MB 空間。
-
- 而完整的 CVS tree - 包括 src,
- doc, www 以及
- ports - 目前約為 940MB。
-
-
-
- Build the web pages from scratch
-
-
-
- 先建立要編譯的目錄(至少要有 60MB 空間),並切換到該目錄。
-
- &prompt.root; mkdir /var/tmp/webbuild
-&prompt.root; cd /var/tmp/webbuild
-
-
-
- 從 CVS tree 內 checkout 相關的 SGML 檔。
-
- &prompt.root; cvs -R co www doc
-
-
-
- 切到 www/en 目錄,然後打
- &man.make.1; all 來產生網頁。
-
- &prompt.root; cd en
-&prompt.root; make all
-
-
-
-
-
- 在你的網頁伺服器上安裝網頁
-
-
-
- 如果你已經離開 en
- 這個目錄,請切換回這個目錄中。
-
- &prompt.root; cd path/www/en
-
-
-
- 執行 &man.make.1; install ,
- 並將 DESTDIR 設定為你想安裝檔案的目錄名稱。
-
- &prompt.root; make DESTDIR=/usr/local/www install
-
-
-
- 如果你之前已經在相同的目錄中安裝了這些網頁,
- 安裝過程並不會刪除任何既有或過期的網頁。
- 舉例來說,如果你每日建構和安裝新的網頁副本,
- 這個指令將會搜尋並刪除在三天內沒有更新的檔案。
-
- &prompt.root; find /usr/local/www -ctime 3 -print0 | xargs -0 rm
-
-
-
-
-
- 環境變數
-
-
-
- CVSROOT
-
-
- 設定 CVS tree 的位置,此為必備條件。
-
- &prompt.root; CVSROOT=/home/ncvs; export CVSROOT
-
-
-
-
- ENGLISH_ONLY
-
-
- 如果設定這個環境變數,而且值不為空白,
- makefiles 將只會建構和安裝英文文件。
- 所以將會略過其他的各國翻譯。例如:
-
- &prompt.root; make ENGLISH_ONLY=YES all install
-
- 如果你想要取消變數 ENGLISH_ONLY
- 以及建構所有的頁面並包括翻譯,只要將變數 ENGLISH_ONLY
- 的值設定成空白即可。
-
- &prompt.root; make ENGLISH_ONLY="" all install clean
-
-
-
-
- WEB_ONLY
-
-
- 如果有設定這個變數的話,
- makefiles 將只會從 www 目錄建構及安裝 HTML 頁面。
- 所有從 doc 目錄下的文件全部都會被忽略 (Handbook, FAQ, Tutorials)。
- 例如:
-
- &prompt.root; make WEB_ONLY=YES all install
-
-
-
-
- NOPORTSCVS
-
-
- 如果設了這個變數,makefiles 就不會從 ports cvs repository
- 取出檔案。 取而代之會從
- /usr/ports (或是 PORTSBASE
- 所設定的值) 內複製檔案。
-
-
-
-
- CVSROOT 是環境變數。
- 你必須直接使用指令或是在 dot files (如: ~/.profile) 中
- 設定這個環境變數。
-
- WEB_ONLY、ENGLISH_ONLY 及
- NOPORTSCVS 都是 makefile 變數。
- 你可以在 /etc/make.conf、Makefile.inc
- 中設定這些變數,作法就像是用命令列或使用 dot files 來設定環境變數一般。
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml
deleted file mode 100644
index 622e98e1641e..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/tools/chapter.xml
+++ /dev/null
@@ -1,235 +0,0 @@
-
-
-
- 工具
-
- FDP 使用一堆工具來協助管理 FreeBSD 文件、轉換文件格式等等。
- 因此,若要進行 FDP 工作的話,必須要學會這些工具才行。
-
- 這些工具都可以用 Ports 或 Packages 來安裝,以節省許多安裝的工夫。
-
- 您必須安裝這些工具,才能使用接下來各章節會介紹到的例子。 這些工具的用法,會在後續相關章節談到。
-
-
- 建議安裝 textproc/docproj
-
- 裝了
- textproc/docproj 可以更省時省力,它是個
- 組合型的 port(meta-port),本身並非軟體,只是將一些常用工具組合起來而已。
- 裝了這個 port 之後,『應該』就會自動下載、安裝本章所會介紹到的工具了。
- 若要處理中文的話,建議再裝 chinese/docproj 會比較好。
-
- 在這些 packages 當中,你可能會需要使用 JadeTeX 這個 macro 設定,
- 一旦選擇使用該 macro 的話,它會接著去裝 &tex;。由於 &tex; 算是個蠻大的套件,
- 除非你需要輸出 Postscript 或 PDF 格式,否則就不必裝了。
-
- 所以請考慮是否要節省編譯時間、硬碟空間,以判定要不要裝 JadeTeX (以及 &tex;)
- 了。若要一併裝起來的話:
-
- &prompt.root; make JADETEX=yes install
-
- 或是,不裝的話:
-
- &prompt.root; make JADETEX=no install
-
- 或者,也可以選擇 textproc/docproj-jadetex 或是 textproc/docproj-nojadetex 這兩個之一來裝,
- 它們都是已事先設定 JADETEX 變數的 slave ports,
- 都一樣會裝 docproj 差別僅在於有沒有 JadeTeX 而已。
- 請注意:若只要輸出 HTML 或 ASCII 格式文件,那就不用裝 JadeTeX,
- 而若要輸出 PostScript、PDF 格式,就需要裝 &tex; 才行。
-
-
-
- 必備工具
-
-
- 軟體
-
- 這些都是在進行 FreeeBSD 文件計劃時所會需要用上的工具程式,
- 而且可以用來轉換文件為 HTML、plain text以及 RTF 格式。這些相關套件在
- textproc/docproj 都已經全部收錄了。
-
-
-
- Jade
- (textproc/jade)
-
-
- DSSSL 規格的實作程式,可用來把標記語言的文件(marked up)轉換為其他格式,像是:HTML 及 &tex;。
-
-
-
-
- Tidy
- (www/tidy)
-
-
- HTML pretty printer,可用來把自動產生的 HTML 內容整理得更易閱讀、以便日後維護。
-
-
-
-
- Links
- (www/links)
-
-
- 文字操作模式的 WWW 瀏覽器(browser)可以把 HTML 檔轉為 plain text 格式。
-
-
-
-
- peps
- (graphics/peps)
-
-
- 文件中有些圖是存成 EPS 格式的,這些必須要轉為 PNG 格式,
- 才能讓一般瀏覽器可以正常觀看。
-
-
-
-
-
-
- DTD 及 Entity
-
- 由於 FDP 有用到許多 DTD 跟 Entity,因此在開工前,要裝上這些才行。
-
-
-
- HTML DTD (textproc/html)
-
-
- HTML 是用於 WWW 的標記語言,且也是 FreeBSD 網頁所使用的格式。
-
-
-
-
- DocBook DTD (textproc/docbook)
-
-
- DocBook 是專門用來製作技術文件的標示語言版本,
- FreeBSD 全部文件都是以 DocBook 所寫成的。
-
-
-
-
- ISO 8879 entities
- (textproc/iso8879)
-
-
- 在 ISO 8879:1986 之中有 19 個 entity 被許多 DTD 所大量使用,
- 包括了數學符號、拉丁字母符號(尖重音等音節符號也是)以及希臘符號。
-
-
-
-
-
-
- 樣式表(Stylesheets)
-
- 這些樣式表都是用來轉換、重排文件的螢幕顯示、列印等效果處理
-
-
-
- Modular DocBook 樣式表
- (textproc/dsssl-docbook-modular)
-
-
- Modular DocBook 樣式表,是用來把 DocBook 的標記語言文件轉換為其他格式,像是:
- HTML 或 RTF。
-
-
-
-
-
-
-
- 輔助工具
-
- 不一定得裝下列的工具才行,但是,裝了之後會更容易進行各項工作,
- 而且可輸出的格式也更具彈性。
-
-
- 軟體
-
-
-
- JadeTeX 及
- teTeX
- (print/jadetex 及
- print/teTeX)
-
-
- Jade 與
- teTeX 可用來把 DocBook 格式文件轉為
- DVI, Postscript 及 PDF 格式。安裝時請記得加上
- JadeTeX 這個 macro,這樣才會順便裝上這兩個套件。
-
- 若無意把文件轉換更多格式的話(舉例:只要 HTML, plain text, RTF 這些格式就夠的話)
- ,那麼就不用裝
- JadeTeX 與
- teTeX。 如此一來可省下一些的編譯時間、安裝空間,
- 因為 teTeX 大約要至少 30MB 空間。
-
-
- 若決定要裝
- JadeTeX 以及
- teTeX 的話,那麼在裝完 JadeTeX 之後,
- 要記得設定 teTeX 才行。
- print/jadetex/pkg-message 內有詳細介紹相關步驟。
-
-
-
-
-
- Emacs 或
- XEmacs
- (editors/emacs 或
- editors/xemacs)
-
-
- 這兩者編輯器都具有處理 SGML DTD 標記文件的特殊模式。
- 該模式提供一些指令,來簡化所需的打字次數,而且可以減少可能發生的錯誤。
-
- 不過,這些編輯器並不是必備的;任何文字編輯器都可以用來編輯標記語言文件。
- 不過,你可以透過類似上述這樣的編輯器,來讓這些繁瑣作業更輕鬆有效率些。
-
-
-
-
- 若有推薦其他好用的處理 SGML 文件程式,請來信讓 &a.doceng; 知道,
- 如此一來,該軟體就會列入這裡介紹了。
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml
deleted file mode 100644
index 93e331fbe8cc..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/translations/chapter.xml
+++ /dev/null
@@ -1,383 +0,0 @@
-
-
-
- 翻譯時的常見問題
-
- 本章是翻譯 FreeBSD 文件(包含:FAQ, Handbook, tutorials, manual pages等)的常見問題(FAQ)。
-
- 本文件 主要 是以 FreeBSD 德文翻譯計劃的翻譯 FAQ 為母本而來的,
- 原始撰稿者為 Frank Gründer elwood@mc5sys.in-berlin.de ,並由
- Bernd Warken bwarken@mayn.de 再翻譯回英文版。
-
- The FAQ is maintained by the &a.doceng;.
-
-
-
-
- FAQ 的目的是?
-
-
-
- 隨著越來越多人參與 freebsd-doc 郵遞論壇,而且希望將 FreeBSD 文件翻譯為各種語言版本。
- 我們希望這份 FAQ 能儘可能為這些參與翻譯者提供快速的解惑。
-
-
-
-
-
- i18n 跟 l10n 是什麼呢?
-
-
-
- i18n 是
- internationalization 的簡寫,而 l10n
- 則是 localization 的簡寫。這些都是為了書寫方便而用的簡寫。
-
- i18n 就是開頭為 i 後面有 18 個字母,最後接 n。
- 同理,
- l10n 則是開頭為 l 後面有 10 個字母,最後接 n。
-
-
-
-
-
- 有專門給譯者參與討論的 mailing list 嗎?
-
-
-
- 有啊,不同的語系翻譯者都各自有自屬的 mailing lists。這份 翻譯計劃清單
- 有列出各翻譯計劃的詳細 mailing lists 及相關網站。
-
-
-
-
-
- 需要更多人一起參與翻譯嗎?
-
-
-
- 當然囉,越多人參與翻譯,那麼就能夠越快翻完,而且英文版文件若有增減、更新的話,
- 各翻譯版也可以儘快同步囉。
-
- 不一定得是專業譯者,才能參與翻譯的。
-
-
-
-
-
- 有要求哪些語言能力呢?
-
-
-
- 理論上,必須要對英文非常熟稔,而且很明顯地,對想翻譯的語言必須要能運用自如。
-
- 英文並非一定要會的。比如說,可以把西班牙文(Spanish)的 FAQ 翻譯為匈牙利文(Hungarian)。
-
-
-
-
-
- 該學會哪些程式的使用呢?
-
-
-
- 強烈建議在自己機器上也建立 FreeBSD CVS repository 的備份(至少文件部分),可以用
- CTM 或
- CVSup 都可以。Handbook 中的 "更新、升級 FreeBSD"
- 一章內有提到如何使用這些程式。
-
- 此外,需要熟悉 CVS 用法。
- 如此一來,你可以查閱不同版本之間的差異處。
-
- [XXX To Do(尚未撰稿,仍待補充) -- 寫份上手說明(tutorial)來介紹如何以 CVSup
- 取得文件部分,以及察看不同版本之間的差異。]
-
-
-
-
-
- 要怎麼找出來還有誰要跟我一起翻譯的呢?
-
-
-
- 文件計劃的翻譯 這列了目前已知的各翻譯者成果
- ,如果已經有其他人也在做跟你一樣的翻譯工作,那麼請不要重複浪費人力,
- 請與他們聯繫看看還有哪些地方可以幫上忙的。
-
- 若上面並未列出你母語的翻譯,或是也有人要翻譯但還未公開宣布的話,那麼就寄信到 &a.doc; 吧。
-
-
-
-
-
-
- 都沒人翻譯為我所使用的語言,該怎麼辦?
-
-
-
- 恭喜啊,你剛好踏上 FreeBSD
- 你的母語 文件翻譯計劃 的啟程之路,歡迎上船。
-
- 首先呢,先判斷是否有妥善規劃時間,因為你只有一個人在翻而已,
- 因此,相關翻譯成果的公布、與其他可能會幫忙的志工們聯繫這些工作都是你的職責所在。
-
- 寫信到 &a.doc; 向大家宣布你正準備要翻譯,然後文件計劃的翻譯部分就會更新相關資料
-
- 若你的國家已經有人提供 FreeBSD 的 mirror(映設) 服務的話,那麼就先跟他們聯繫,
- 並詢問你是否在上面可以有網頁空間來放相關計劃資料,
- 以及是否可以有提供 email 帳號或 mailing list 服務。
-
- 然後,就開始翻文件囉,一開始翻譯的時候,先找些篇幅較短的文件會比較容易些
- — 像是 FAQ 啦,或是如何上手之類的說明文章。
-
-
-
-
-
- 已經翻好一些文件了,該寄到哪呢?
-
-
-
- 這要看情況而定。 若你是在翻譯團隊內做的話(像是日本、德國),
- 他們會有自己內部流程來決定翻譯文件怎麼送,這些大致流程會在他們網頁上面有寫。
-
- 若你是某語系的唯一翻譯者(或你是負責某翻譯計劃,並想把成果回饋給 FreeBSD 計劃)
- ,那麼你就應該把自己的翻譯成果寄給 FreeBSD 計劃。(細節請看下個問題)
-
-
-
-
-
- 我是該語系的唯一翻譯者,該怎麼把翻譯成果寄出去呢?
-
- 或者
-
- 我們是翻譯團隊,該怎麼把我們成員翻譯成果寄出去呢?
-
-
-
- 首先,請先確定你的翻譯成果組織條理分明,並可正確編譯,也就是說:
- 把它擺到現有文件架構內是可以正確編譯成功的。
-
- 目前,FreeBSD 文件都是放在最上層的 doc/ 目錄內。
- 而該目錄下的則依其語系來做分類命名的,依照 ISO639 定義(/usr/share/misc/iso639
- 的這個 FreeBSD 版本比 1999/01/20 還新)。
-
- 若你這個語系可能會有不同編碼方式(像是:中文)
- 那麼就應該會像下面這樣,來依你所使用的編碼方式細分。
-
- 最後,你應該建立好各文件的目錄了。
-
- 舉例來說,假設有瑞典文(Swedish)版的翻譯,那麼應該會長像:
-
- doc/
- sv_SE.ISO8859-1/
- Makefile
- books/
- faq/
- Makefile
- book.xml
-
- sv_SE.ISO8859-1 是依照
- 語系(lang).編碼(encoding)
- 的規則來建立的譯名。
- 請注意:其中有兩個 Makefiles 檔,它們是用來編書的。
-
- 然後請用 &man.tar.1; 與 &man.gzip.1; 來把你的翻譯文件壓縮起來,並寄到本計劃來。
-
- &prompt.user; cd doc
-&prompt.user; tar cf swedish-docs.tar sv_SE.ISO8859-1
-&prompt.user; gzip -9 swedish-docs.tar
-
- 接著,把 swedish-docs.tar.gz 放到網頁空間上,若你沒有自己網頁空間的話(ISP不提供)
- ,那麼可以該檔寄到 &a.doceng; 來。
-
- 還有,記得用 &man.send-pr.1; 以正式通知大家;你已經寄出翻譯文件了,
- 還有,若有人可以幫忙檢閱、複審文件的話,對翻譯品質較好,
- 因為這也有助於提升翻譯品質的流暢度。
-
- 最後,會有人(可能是文件計劃總管,或是 &a.doceng; 成員)
- 會檢閱你的翻譯文件,並確認是否可正常編譯。此外,他們會特別注意下列幾點:
-
-
-
- 你的檔案是否都有用 RCS tag (像是 "ID" 之類的)?
-
-
-
- sv_SE.ISO8859-1 是否可以順利 make all 編譯呢?
-
-
-
- make install 是否結果有正確?
-
-
-
- 若有問題的話,那麼檢閱者會叮嚀你,來讓這些翻譯成果可以正確使用。
-
- 若沒問題的話,那麼就會很快把你的翻譯成果 commit 進去了。
-
-
-
-
-
- 可以加入某語系或某國家才有的東西到翻譯內容內嗎?
-
-
-
- 我們希望不要這麼做。
-
- 舉例來說,假設你正準備把 Handbook 翻譯為韓文版,
- 並希望把韓國零售處也加到你翻譯的 Handbook 韓文版內。
-
- 我們想不出來有啥原因,為什麼不把這些資訊提供給英文版呢?(或是德文、西班牙文、日文等 …)
- 因為,有可能英語讀者跑去韓國時,會想買 FreeBSD 相關產品。
- 此外,這也可以提升 FreeBSD 的可見度,很顯然的,這並不是件壞事啊。
-
- 若你有某國才有的資料,請(用 &man.send-pr.1; )提供給英文版 Handbook 以作為修訂
- ,然後再把英文版的修訂部分,翻為你要翻譯的 Handbook 吧。
-
- 感恩,謝謝。
-
-
-
-
-
- 要怎麼把該語系特有的字元寫進去翻譯內容呢?
-
-
-
- 文件內所有的非 ASCII(Non-ASCII) 字元,都要使用 SGML entities 才能寫進去。
-
- 簡單來說,長相一開頭會是 & 符號(&),然後是該 entity 名稱,最後接上分號(;)。
-
- 這些 entity 名稱都是 ISO8879 所制訂的,而 port tree 內則在
- textproc/iso8879。
-
- 以下舉一些例子:
-
-
- Entity名稱
-
- 實際樣子
-
- 介紹
-
-
- é
- é
- 小 e,並帶尖、重音(acute accent)
-
-
-
- É
- É
- 大 E,並帶尖、重音(acute accent)
-
-
-
- ü
- ü
- 小 u,並帶日耳曼語系中的母音變化(umlaut)
-
-
-
- 在裝了 iso8879 這個 port 之後,就可以在
- /usr/local/share/xml/iso8879 找到這些的詳細列表。
-
-
-
-
-
- 如何稱呼讀者呢?
-
-
-
- 在英文文件內,讀者都是以 you 來稱呼,而有些語言並沒有正式/非正式的區隔。
-
- 若你所要翻的語言可以區別這些差異,那麼請用該語系在一般技術文件上所使用的稱呼吧。
- 如果容易造成困惑的話,那麼請改用較中性的稱呼來取代。
-
-
-
-
-
-
-
- 翻譯成果內要不要附上一些其他訊息呢?
-
-
-
- 當然要。
-
- 每份英文版原稿的開頭,通常會有像下面的內容:
-
- <!--
- The FreeBSD Documentation Project
-
- $FreeBSD: doc/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.5 2000/07/07 18:38:38 dannyboy Exp $
--->
-
- 實際上的內容可能稍有不同,但每份原稿都會附上 $FreeBSD$ 這一行以及
- The FreeBSD Documentation Project 宣告。
- 請注意:$FreeBSD 開頭的這行是會由 CVS 隨著每次異動而自動更改的,
- 所以,新檔案的話請保持原狀(也就是只要寫 $FreeBSD$ 就好了)。
-
- 翻譯文件中,必須都要有 $FreeBSD$ 這行,並且把
- FreeBSD Documentation Project 這行改為
- The FreeBSD 你的語系
- Documentation Project。
-
- 此外,還必須加上第三行來指出你所翻譯的,到底是以英文版原稿的哪一版本為母本所做的翻譯。
-
- 因此呢,西班牙文版(Spanish)的檔案開頭應該是長像這樣:
-
- <!--
- The FreeBSD Spanish Documentation Project
-
- $FreeBSD: doc/es_ES.ISO8859-1/books/fdp-primer/translations/chapter.xml,v 1.3 1999/06/24 19:12:32 jesusr Exp $
- Original revision: 1.11
--->
-
-
-
-
diff --git a/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml b/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml
deleted file mode 100644
index 158d23202971..000000000000
--- a/zh_TW.UTF-8/books/fdp-primer/writing-style/chapter.xml
+++ /dev/null
@@ -1,440 +0,0 @@
-
-
-
- 文件的撰寫風格
-
- 由於 FreeBSD 文件是由眾多作者所維護的,為了保持寫作風格的一貫性,
- 於是就產生較有共識的寫作規則,請各位記得要遵守。
-
-
-
- 使用美式英語
-
-
- 同一個字在不同種類的英語會有著不同的拼法。
- 遇到拼字不同的情況,請採用美式英語拼法。 像是:
- 請改用 color,而非 colour。
- 請改用 rationalize,而非 rationalise
- 等等類似字彙。
-
-
- 若文章採用英式英語也可以接受,但必須全篇文章都採用同一拼法才行
- 。 而文件的其他部份,像是書、網頁、 manual
- 說明等則必須採用美式英語。
-
-
-
-
-
- 不要用簡寫
-
-
- 請不要簡寫(contraction)。 請務必將完整的字寫出來。 比如:
- Don't use contractions 這句有用到簡寫,就要避免。
-
- 正式書面寫法避免簡寫的原因,乃是因為如此一來字句意思較精準,
- 且對譯者會比較輕鬆些。
-
-
-
-
- 正確使用 serial comma 以及頓號
-
-
- 英文段落通常會逗號(,)作為該句所提到的各項目的語氣區隔。
- 並且會在最後一個提到的項目時,先加上逗號再接上 and,
- 最後才是最後的項目。
-
- 舉個例子,看看下面這句:
-
-
- This is a list of one, two and three items.
-
-
- 那麼這一句到底是有三個項目(one、two
- 、three)呢?或者是只有兩個項目(one、
- two and three)呢?
-
- 因此較妥的方式是以 serial comma 的方式,才能正確表達語意:
-
-