Index: head/nl_NL.ISO8859-1/books/fdp-primer/book.xml =================================================================== --- head/nl_NL.ISO8859-1/books/fdp-primer/book.xml (revision 47758) +++ head/nl_NL.ISO8859-1/books/fdp-primer/book.xml (revision 47759) @@ -1,9029 +1,9003 @@ ]> Overzicht van het FreeBSD Documentatieproject voor nieuwe bijdragers - Het FreeBSD Documentatieroject + Het FreeBSD Documentatieproject 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 DocEng $FreeBSD$ $FreeBSD$ Copyright Herdistributiie en gebruik in bron- (XML DocBook) en 'gecompileerde' vormen (XML, HTML, PDF, PostScript, RTF enzovoorts) met of zonder aanpassingen, is toegestaan gegeven dat aan de volgende voorwaarden is voldaan: Herdistributies van broncode (XML DocBook) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer onveranderd als de eerste regels van dit bestand behouden. Herdistributies in gecompileerde vorm (getransformeerd naar andere DTDs, omgezet naar PDF, PostScript, RTF en andere formaten) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer in de documentatie en/of andere materialen geleverd met de distributie herproduceren. THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Dank u dat u deel bent geworden van het FreeBSD Documentatieproject. Uw bijdrage is zeer waardevol, en we stellen het op prijs. Deze handleidng behandelt details die nodig zijn om te beginnen met bij te dragen aan het FreeBSD Documentatieproject, of FDP, inclusief gereedschappen, softare en de gedachten achter het Documentatieproject. Dit is werk in uitvoering. Correcties en aanvullingen zijn altijd welkom. Inleiding Shellprompts Deze tabel laat de standaard systeemprompt en de prompt van de supergebruiker zien. Deze voorbeelden gebruiken deze prompts om aan te geven welk soort gebruiker het voorbeeld draait. Gebruiker Prompt Gewone gebruiker % root # Typografische aannames Deze tabel beschrijft de typografische aannames die in dit boek gebruikt worden. Betekenis Voorbeelden De naam van commando's. Gebruik ls -l voor een lijst van alle bestanden. De namen van bestanden. Bewerk .login. Uitvoer op het computerscherm. You have mail. Wat de gebruiker typt, in contrast met uitvoer op het computerscherm. % date +"De tijd is %H:%M" De tijd is 09:18 Verwijzing naar handleidingspagina's. Gebruik su1 om van gebruikersidentiteit te veranderen. Gebruiker- en groepnamen. Alleen root kan dit doen. Nadruk. De gebruiker moet dit doen. Tekst die de gebruiker door de eigenlijke tekst dient te vervangen. Gebruik man -ksleutelwoord om naar een sleutelwoord in handleidingspagina's te zoeken. Omgevingsvariabelen. - $HOME is set to the user's home - directory. + $HOME is ingesteld op de thuismap van de gebruiker. - Notes, Tips, Important Information, Warnings, and - Examples + Opmerkingen, tips, belangrijke informatie, waarschuwingen en voorbeelden - Notes, warnings, and examples appear within the - text. + Opmerkingen, waarschuwingen en voorbeelden verschijnen in de tekst. - Notes are represented like this, and contain information - to take note of, as it may affect what the user - does. + Opmerkingen worden zo weergegeven en bevatten informatie waarvan kennis genomen moet worden, aangezien ze kunne beïnvloeden wat de gebruiker doet. - Tips are represented like this, and contain information - helpful to the user, like showing an easier way to do - something. + Tips worden zo weergegeven en bevatten behulpzame informatie voor de gebruiker, zoals een eenvoudigere manier laten zien om iets te doen. - Important information is represented like this. - Typically, these show extra steps the user may need to - take. + Belangrijke informatie wordt zo weergegeven. Typisch laat het extra stappen zien die de gebruiker kan moeten nemen. - Warnings are represented like this, and contain - information warning about possible damage if the - instructions are not followed. This damage may be physical, - to the hardware or the user, or it may be non-physical, such - as the inadvertent deletion of important files. + Waarschuwingen worden zo weergegeven en bevatten informatie die waarschuuwt over mogelijke schade indien de instructies niet worden opgevolgd. Deze schade kan fysiek zijn, aan de hardware of de gebruiker, of het kan niet-fysiek zijn, zoals het onbedoeld verwijderen van belangrijke bestanden. - A Sample Example + Een voorbeeld van een voorbeeld - Examples are represented like this, and typically - contain examples showing a walkthrough, or - the results of a particular action. + Voorbeelden worden zo weergegeven en bevatten typisch een voorbeeld dat een stappenplan of het resultaat van een bepaalde actie laat zien. - Acknowledgments + Erkenningen - My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, - Peter Flynn, and Christopher Maden, who took the time to read - early drafts of this document and offer many valuable comments - and criticisms. + Veel dank aan Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, en Christopher Maden. die te tijd hebben genomen om vroege kladversies van dit document te lezen en veel waardevol commentaar en kritiek hebben geboden. - Overview + Overzicht - Welcome to the FreeBSD Documentation Project - (FDP). Quality documentation is crucial - to the success of FreeBSD, and we value your contributions very - highly. + Welkom bij het FreeBSD Documentatieproject (FDP). Kwaliteitsdocumentatie is cruciaal voor het succes van FreeBSD en we stellen uw bijdragen zeer op prijs. - This document describes how the FDP is - organized, how to write and submit documentation, and how to - effectively use the available tools. + Dit document beschrijft hoe het FDP is georganiseerd, hoe documentatie te schrijven en op te sturen, en hoe effectief van de beschikbare gereedschappen gebruik te maken. - Everyone is welcome to contribute to the - FDP. Willingness to contribute is the only - membership requirement. + Iedereen is welkom om aan het FDP bij te dragen. Bereidheid om bij te dragen is de enige eis voor lidmaatschap. - This primer shows how to: + Deze handleiding laat zien hoe: - Identify which parts of FreeBSD are maintained by the - FDP. + Te identificeren welke gedeelten van FreeBSD door het FDP worden onderhouden. - Install the required documentation tools and files. + De benodigde gereedschappen en bestanden te installeren. - Make changes to the documentation. + Veranderingen aan de documentatie te maken. - Submit changes back for review and inclusion in the FreeBSD - documentation. + Veranderingen terug te sturen voor bespreking en opname in de documentatie van FreeBSD. - The FreeBSD Documentation Set + De FreeBSD Documentatieverzameling - The FDP is responsible for four - categories of FreeBSD documentation. + Het FDP is verantwoordelijk voor vier categoriën van documentatie van FreeBSD. - Handbook: The Handbook is the - comprehensive online resource and reference for FreeBSD - users. + Handboek: Het Handboek is de uitgebreide online bron en referentie voor gebruikers van FreeBSD. - FAQ: The FAQ - uses a short question and answer format to address questions - that are frequently asked on the various mailing lists and - forums devoted to FreeBSD. This format does not permit long - and comprehensive answers. + FAQ: De FAQ gebruikt een kort vraag-en-antwoord-formaat om vragen te bespreken die vaak worden gesteld op de verschillende mailinglijsten en fora gewijd aan FreeBSD. - Manual pages: The English language - system manual pages are usually not written by the - FDP, as they are part of the base system. - However, the FDP can reword parts of - existing manual pages to make them clearer or to correct - inaccuracies. + Handleidingspagina's: De Engelstalige handleidingspagina's van het systeem worden gewoonlijk niet geschreven door het FDP, aangezien ze onderdeel zijn van het basissysteem zijn. Het FDP kan echter delen van bestaande handleidingspagina's hershrijven om ze te verduidelijken of om onjuistheden te corrigeren. - Web site: This is the main FreeBSD - presence on the web, visible at http://www.FreeBSD.org/ - and many mirrors around the world. The web site is - typically a new user's first exposure to FreeBSD. + Website: Dit is de voornaamste aanwezigheid van FreeBSD op het web, zichtbaar op http://www.FreeBSD.org/ en vele spiegels over de wereld. De website is typisch de eerste blootstelling van een nieuwe gebruiker aan FreeBSD. - Translation teams are responsible for translating the - Handbook and web site into different languages. Manual pages - are not translated at present. + Vertaalteams zijn verantwoordelijk voor de vertaling van het Handboek en de website in verschillende talen. Handleidingpagina's worden momenteel niet vertaald. - Documentation source for the FreeBSD web site, Handbook, and - FAQ is available in the documentation - repository at - https://svn.FreeBSD.org/doc/. + Bronnen van de documentatie voor de website, het Handboek en de FAQ van FreeBSD zijn beschikbaar in het documentatie-reservoir op https://svn.FreeBSD.org/doc/. - Source for manual pages is available in a separate - source repository located at - https://svn.FreeBSD.org/base/. + Bronnen voor handleidingspagina's zijn beschikbaar in een apart broncode-reservoir op https://svn.FreeBSD.org/base/. - Documentation commit messages are visible with - svn log. Commit messages are also - archived at http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all. + Commit-berichten over de documentatie zijn zichtbaar met svn log. Commit-berichten zijn ook gearchiveerd op http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all. - Web frontends to both of these repositories are available at and . + Web-frontends voor deze beide reservoirs zijn beschikbaar op en . - Many people have written tutorials or how-to articles about - FreeBSD. Some are stored as part of the FDP - files. In other cases, the author has decided to keep the - documentation separate. The FDP endeavors to - provide links to as much of this external documentation as - possible. + Vele mensen hebben tutorials of stappenplannen over FreeBSD geschreven. Sommigen worden opgeslagen als deel van het FDP. In andere gevallen heeft de auteur besloten om de documentatie apart te houden. Het FDP tracht om verwijzigingen naar zoveel mogelijk van deze externe documentatie te bieden. Quick Start Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the FreeBSD documentation project mailing list. Some team members also interact on the #bsddocs IRC channel on EFnet. These people can help with questions or problems involving the documentation. Install the textproc/docproj package or port. This meta-port installs all of the software needed to edit and build FreeBSD documentation. Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see ). - % svn checkout https://svn.FreeBSD.org/doc/head ~/doc + % svn checkout https://svn.FreeBSD.org/doc/head ~/doc Configure the text editor: Word wrap set to 70 characters. Tab stops set to 2. Replace each group of 8 leading spaces with a single tab. Specific editor configurations are listed in . Update the local working copy: - % svn up ~/doc + % svn up ~/doc Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input. References to tag and entity usage can be found in and . After editing, check for problems by running: - % igor -R filename.xml | less -RS + % igor -R bestandsnaam.xml | less -RS Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved. Always build-test changes before submitting them. Running make in the top-level directory of the documentation being edited will generate that documentation in split HTML format. For example, to build the English version of the Handbook in HTML, run make in the en_US.ISO8859-1/books/handbook/ directory. When changes are complete and tested, generate a diff file: - % cd ~/doc + % cd ~/doc % svn diff > bsdinstall.diff.txt Give the diff file a descriptive name. In the example above, changes have been made to the bsdinstall portion of the Handbook. Submit the diff file using the web-based Problem Report system. If using the web form, enter a synopsis of [patch] short description of problem. Select the category docs and the class doc-bug. In the body of the message, enter a short description of the changes and any important details about them. Use the [ Browse... ] button to attach the diff file. - Tools + Gereedschappen Several software tools are used to manage the FreeBSD documentation and render it to different output formats. Some of these tools are required and must be installed before working through the examples in the following chapters. Some are optional, adding capabilities or making the job of creating documentation less demanding. - Required Tools + Benodigde gereedschappen Install textproc/docproj from the Ports Collection. This meta-port installs all the applications required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below. - <acronym>DTD</acronym>s and - <acronym>Entities</acronym> + <acronym>DTD</acronym>s en <acronym>entiteiten</acronym> FreeBSD documentation uses several Document Type Definitions (DTDs) and sets of XML entities. These are all installed by the textproc/docproj port. XHTML DTD (textproc/xhtml) XHTML is the markup language of choice for the World Wide Web, and is used throughout the FreeBSD web site. - DocBook DTD (textproc/docbook-xml-450) + DocBook DTD (textproc/docbook-xml-450) DocBook is designed for marking up technical documentation. Most of the FreeBSD documentation is written in DocBook. ISO 8879 entities (textproc/iso8879) Character entities from the ISO 8879:1986 standard used by many DTDs. Includes named mathematical symbols, additional characters in the Latin character set (accents, diacriticals, and so on), and Greek symbols. Optional Tools These applications are not required, but can make working on the documentation easier or add capabilities. - Software + Software Vim (editors/vim) A popular editor for working with XML and derived documents, like DocBook XML. Emacs or XEmacs (editors/emacs or editors/xemacs) Both of these editors include a special mode for editing documents marked up according to an XML DTD. This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors. The Working Copy The working copy is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository. A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats. Subversion is used to manage the FreeBSD documentation files. It is installed by textproc/docproj as one of the required applications. Documentation and Manual Pages FreeBSD documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. Two repositories are involved: doc for the books and articles, and base for the operating system and manual pages. To edit manual pages, the base repository must be checked out separately. Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called head. Choosing a Directory FreeBSD documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /usr/src/. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use ~/doc and ~/src, both subdirectories of the user's home directory. Checking Out a Copy A download of a working copy from the repository is called a checkout, and done with svn checkout. This example checks out a copy of the latest version (head) of the main documentation tree: - % svn checkout https://svn.FreeBSD.org/doc/head ~/doc + % svn checkout https://svn.FreeBSD.org/doc/head ~/doc A checkout of the source code to work on manual pages is very similar: - % svn checkout https://svn.FreeBSD.org/base/head ~/src + % svn checkout https://svn.FreeBSD.org/base/head ~/src Updating a Working Copy The documents and files in the FreeBSD repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main FreeBSD repository. To update the local version with the changes that have been made to the main repository, use svn update on the directory containing the local working copy: - % svn update ~/doc + % svn update ~/doc Get in the protective habit of using svn update before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository. Reverting Changes Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be reset to their unchanged form with svn revert. For example, to erase the edits made to chapter.xml and reset it to unmodified form: - % svn revert chapter.xml + % svn revert chapter.xml Making a Diff After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These diff files are produced by redirecting the output of svn diff into a file: % cd ~/doc % svn diff > doc-fix-spelling.diff Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree. If the diff file is to be submitted with the web Submit a FreeBSD problem report interface, add a .txt extension to give the earnest and simple-minded web form a clue that the contents are plain text. Be careful: svn diff includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included: % cd ~/doc % svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff <application>Subversion</application> References These examples show very basic usage of Subversion. More detail is available in the Subversion Book and the Subversion documentation. Documentation Directory Structure Files and directories in the doc/ tree follow a structure meant to: 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 must accommodate documents in many different languages and encodings. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences. The Top Level, <filename>doc/</filename> There are two types of directory under doc/, each with very specific directory names and meanings. Directory Usage - - share + 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 make1 infrastructure are in share/mk, while the additional XML 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 when a translation team wants to provide documentation in the same language but in more than one encoding. This also avoids problems that might be caused by a future switch to Unicode. The <filename><replaceable>lang</replaceable>.<replaceable>encoding</replaceable>/</filename> 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 Usage - - articles + articles Documentation marked up as a DocBook article (or equivalent). Reasonably short, and broken up into sections. Normally only available as one XHTML file. - books + books Documentation marked up as a DocBook book (or equivalent). Book length, and broken up into chapters. Normally available as both one large XHTML 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 + 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 have all of these subdirectories. 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 + Het Handboek - books/handbook/ + books/handbook/ The Handbook is written in DocBook XML using the FreeBSD DocBook extended DTD. The Handbook is organized as a DocBook book. The book is divided into parts, each of which contains 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. Post questions about Handbook organization to the FreeBSD documentation project mailing list. - <filename>Makefile</filename> + <filename>Makefile</filename> The Makefile defines some variables that affect how the XML 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, to bring in the rest of the code that handles converting documents from one format to another. - <filename>book.xml</filename> + <filename>book.xml</filename> 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. <filename role="directory"><replaceable>directory</replaceable>/chapter.xml</filename> 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: chapter id="kernelconfig" ... chapter Then it will be called chapter.xml in the kernelconfig directory. In general, the entire contents of the chapter are in this one file. When the XHTML version of the Handbook is produced, this will yield kernelconfig.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. Now, it is possible to include images in each chapter. Images for each Handbook chapter are stored within share/images/books/handbook. The localized version of these images should be placed in the same directory as the XML sources for each chapter. Namespace collisions are 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. Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy. The chapter.xml files are not complete XML documents that can be built individually. They can only be built as parts of the whole Handbook. The Documentation Build Process This chapter covers organization of the documentation build process and how make1 is used to control it. Rendering DocBook into Output Different types of output can be produced from a single DocBook source file. The type of output desired is set with the FORMATS variable. A list of known formats is stored in KNOWN_FORMATS: % cd ~/doc/en_US.ISO8859-1/books/handbook % make -V KNOWN_FORMATS Common Output Formats FORMATS Value File Type - Description + Beschrijving - html + html HTML, one file A single book.html or article.html. - html-split + html-split HTML, multiple files Multiple HTML files, one for each chapter or section, for use on a typical web site. - pdf - PDF - Portable Document Format + pdf + PDF + Portable Document Format
The default output format can vary by document, but is usually html-split. Other formats are chosen by setting FORMATS to a specific value. Multiple output formats can be created at a single time by setting FORMATS to a list of formats. Build a Single HTML Output File % cd ~/doc/en_US.ISO8859-1/books/handbook % make FORMATS=html Build HTML-Split and <acronym>PDF</acronym> Output Files % cd ~/doc/en_US.ISO8859-1/books/handbook % make FORMATS="html-split pdf" The FreeBSD Documentation Build Toolset These are the tools used to build and install the FDP documentation. The primary build tool is make1, specifically Berkeley Make. Package building is handled by FreeBSD's pkg_create1. gzip1 is used to create compressed versions of the document. bzip21 archives are also supported. tar1 is used for package building. install1 is used to install the documentation. Understanding <filename>Makefile</filename>s 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 <filename>Makefile</filename>s 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" The first four non-empty lines define the make1 variables SUBDIR, COMPAT_SYMLINK, and DOC_PREFIX. The SUBDIR statement and COMPAT_SYMLINK statement show 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. 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 make1 builtin variable with the path to the current directory. The final line includes the FreeBSD Documentation Project's project-wide make1 system file doc.project.mk which is the glue which converts these variables into build instructions. Documentation <filename>Makefile</filename>s These Makefiles set make1 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 allows committers to claim ownership of a document in the FreeBSD Documentation Project, and take 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. The DOC_PREFIX and include statements should be familiar already. FreeBSD Documentation Project <application>Make</application> Includes make1 includes are 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. <filename>doc.project.mk</filename> 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 does not affect which 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 make1 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. <filename>doc.subdir.mk</filename> This file is too long to explain in detail. These notes describe the most important features. 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, the given dependencies must be built 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 <command>make (.for)</command> .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. The Website The FreeBSD web site is part of the FreeBSD documents. Files for the web site are stored in the en_US.ISO8859-1/htdocs subdirectory of the document tree directory, ~/doc in this example. Environment Variables Several environment variables control which parts of the the web site are built or installed, and to which directories. The web build system uses make1, and considers variables to be set when they have been defined, even if they are empty. The examples here show the recommended ways of defining and using these variables. Setting or defining these variables with other values or methods might lead to unexpected surprises. DESTDIR DESTDIR specifies the path where the web site files are to be installed. This variable is best set with env1 or the user shell's method of setting environment variables, setenv for csh1 or export for sh1. ENGLISH_ONLY Default: undefined. Build and include all translations. ENGLISH_ONLY=yes: use only the English documents and ignore all translations. WEB_ONLY Default: undefined. Build both the web site and all the books and articles. WEB_ONLY=yes: build or install only HTML pages from the en_US.ISO8859-1/htdocs directory. Other directories and documents, including books and articles, will be ignored. WEB_LANG Default: undefined. Build and include all the available languages on the web site. Set to a space-separated list of languages to be included in the build or install. The formats are the same as the directory names in the document root directory. For example, to include the German and French documents: WEB_LANG="de_DE.ISO8859-1 fr_FR.ISO8859-1" WEB_ONLY, WEB_LANG, and ENGLISH_ONLY are make1 variables and can be set in /etc/make.conf, Makefile.inc, as environment variables on the command line, or in dot files. Building and Installing the Web Pages Having obtained the documentation and web site source files, the web site can be built. An actual installation of the web site is run as the root user because the permissions on the web server directory will not allow files to be installed by an unprivileged user. For testing, it can be useful to install the files as a normal user to a temporary directory. In these examples, the web site files are built by user jru in their home directory, ~/doc, with a full path of /usr/home/jru/doc. The web site build uses the INDEX from the Ports Collection and might fail if that file or /usr/ports is not present. The simplest approach is to install the Ports Collection. Build the Full Web Site and All Documents Build the web site and all documents. The resulting files are left in the document tree: % cd ~/doc/en_US.ISO8859-1/htdocs/ % make all Build Only the Web Site in English Build the web site only, in English, as user jru, and install the resulting files into /tmp/www for testing: % cd ~/doc/en_US.ISO8859-1/htdocs/ % env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install Build and Install the Web Site Build the web site and all documents as user jru. Install the resulting files as root into the default directory, /root/public_html: % cd ~/doc/en_US.ISO8859-1/htdocs % make all % su - Password: # cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs # make install The install process does not delete any old or outdated files that existed previously in the same directory. If a new copy of the site is built and installed every day, this command will find and delete all files that have not been updated in three days: # find /usr/local/www -ctime 3 -delete XML Primer Most FDP documentation is written with markup languages based on XML. This chapter explains what that means, how to read and understand the documentation source, and the XML techniques used. Portions of this section were inspired by Mark Galassi's Get Going With DocBook. - Overview + Overzicht In the original days of computers, electronic text was simple. There were a few character sets like ASCII or EBCDIC, 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. When text is in a machine-usable format, machines are expected to be able to use and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a glossary, or made into hyperlinks. Filenames could 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. The computer would read 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 computers still require assistance before they can meaningfully process text. More precisely, they need help identifying what is what. Consider this text:
To remove /tmp/foo, use rm1. % rm /tmp/foo
It is easy to 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 (the effort required) to create the document. The previous example is actually represented in this document like this: paraTo remove filename/tmp/foofilename, use &man.rm.1;.para screen&prompt.user; userinputrm /tmp/foouserinputscreen The markup is clearly separate from the content. Markup languages define what the markup means and how it should be interpreted. Of course, one markup language might not be enough. A markup language for technical documentation has very different requirements than a markup language that is intended for cookery recipes. This, in turn, would be very different from a markup language used to describe poetry. What is really needed is a first language used to write these other markup languages. A meta markup language. This is exactly what the eXtensible Markup Language (XML) is. Many markup languages have been written in XML, including the two most used by the FDP, XHTML and DocBook. Each language definition is more properly called a grammar, vocabulary, schema or Document Type Definition (DTD). There are various languages to specify an XML grammar, or schema. A schema 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 XML parser which reads in both the schema and a document which claims to conform to the schema. The parser can then confirm whether or not all the elements required by the vocabulary 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. Validation confirms that the choice of elements, their ordering, and so on, conforms to that listed in the grammar. It does not check whether appropriate markup has been used for the content. If all the filenames in a document were marked up as function names, the parser would not flag this as an error (assuming, of course, that the schema defines elements for filenames and functions, and that they are allowed to appear in the same place). Most contributions to the Documentation Project will be content marked up in either XHTML or DocBook, rather than alterations to the schemas. For this reason, this book will not touch on how to write a vocabulary. Elements, Tags, and Attributes All the vocabularies written in XML share certain characteristics. This is hardly surprising, as the philosophy behind XML will inevitably show through. One of the most obvious manifestations of this philosophy is that of content and elements. 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. It may be helpful to think of this as chunking content. At the very top level is one chunk, the book. Look a little deeper, and there are more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on. Notice how this differentiation between different elements of the content can be made without resorting to any XML terms. It really is surprisingly straightforward. This could be done 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 XML (XHTML, 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 grammar 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) XHTML has an element for indicating that the content enclosed by the element is a paragraph, called p. pThis 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.p pThis is another paragraph. But this one is much shorter.p Some elements have no content. For example, in XHTML, a horizontal line can be included in the document. For these empty elements, XML introduced a shorthand form that is completely equivalent to the two-tag version: Using an Element Without Content XHTML has an element for indicating a horizontal rule, called hr. This element does not wrap content, so it looks like this: pOne paragraph.p hrhr pThis is another paragraph. A horizontal rule separates this from the previous paragraph.p The shorthand version consists of a single tag: pOne paragraph.p hr pThis is another paragraph. A horizontal rule separates this from the previous paragraph.p As shown above, 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; <tag>em</tag> pThis is a simple emparagraphem where some of the emwordsem have been ememphasizedem.p The grammar consists of rules that describe 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 ends. When this document (or anyone else knowledgeable about XML) 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 XHTML, the p element has an attribute called align, which suggests an alignment (justification) for the paragraph to the program displaying the XHTML. 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 p align="left"The inclusion of the align attribute on this paragraph was superfluous, since the default is left.p p align="center"This may appear in the center.p Some attributes only take specific values, such as left or justify. Others allow any value. Single Quotes Around Attributes p align='right'I am on the right!p Attribute values in XML must be enclosed in either single or double quotes. Double quotes are traditional. Single quotes are useful when the attribute value contains double quotes. Information about attributes, elements, and tags is stored in catalog files. The Documentation Project uses standard DocBook catalogs and includes additional catalogs for FreeBSD-specific features. Paths to the catalog files are defined in an environment variable so they can be found by the document build tools. To Do… Before running the examples in this document, install textproc/docproj from the FreeBSD Ports Collection. This is a meta-port that downloads and installs the standard programs and supporting files needed by the Documentation Project. csh1 users must use rehash for the shell to recognize new programs after they have been installed, or log out and then log back in again. Create example.xml, and enter this text: !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head body pThis is a paragraph containing some text.p pThis paragraph contains some more text.p p align="right"This paragraph might be right-justified.p body html Try to validate this file using an XML parser. textproc/docproj includes the xmllint validating parser. Use xmllint to validate the document: % xmllint --valid --noout example.xml xmllint returns without displaying any output, showing that the document validated successfully. See what happens when required elements are omitted. Delete the line with the title and title tags, and re-run the validation. % xmllint --valid --noout example.xml example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got () This shows that the validation error comes from the fifth line of the example.xml file and that the content of the head is the part which does not follow the rules of the XHTML grammar. Then xmllint shows the line where the error was found and marks the exact character position with a ^ sign. Replace the title element. The DOCTYPE Declaration The beginning of each document can specify the name of the DTD to which the document conforms. This DOCTYPE declaration is used by XML parsers to identify the DTD and ensure that the document does conform to it. A typical declaration for a document written to conform with version 1.0 of the XHTML DTD looks like this: !DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" That line contains a number of different components. <! The indicator shows this is an XML declaration. DOCTYPE Shows that this is an XML declaration of the document type. - html + html Names the first element that will appear in the document. PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" Lists the Formal Public Identifier (FPI) Formal Public Identifier for the DTD to which this document conforms. The XML parser uses this to find the correct DTD when processing this document. PUBLIC is not a part of the FPI, but indicates to the XML processor how to find the DTD referenced in the FPI. Other ways of telling the XML parser how to find the DTD are shown later. "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" A local filename or a URL to find the DTD. > Ends the declaration and returns to the document. Formal Public Identifiers (<acronym>FPI</acronym>s) Formal Public Identifier It is not necessary to know this, but it is useful background, and might help debug problems when the XML processor can not locate the DTD. FPIs must follow a specific syntax: "Owner//Keyword Description//Language" Owner The owner of the FPI. The beginning of the string identifies the owner of the 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 International Organization for Standardization (ISO) number for the SGML standard, the predecessor (and a superset) of XML. 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 + identifying it as 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. Additionally, 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. As seen in the example, 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 XML content (text and tags). Description Any description can be given for the contents of this file. This may include version numbers or any short text that is meaningful and unique for the XML system. Language An ISO two-character code that identifies the native language for the file. EN is used for English. <filename>catalog</filename> Files With the syntax above, an XML processor needs to have some way of turning the FPI into the name of the file containing the DTD. 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 XHTML 1.0 Transitional//EN" "1.0/transitional.dtd" The XML processor knows that the DTD is called transitional.dtd in the 1.0 subdirectory of the directory that held catalog. Examine the contents of /usr/local/share/xml/dtd/xhtml/catalog.xml. This is the catalog file for the XHTML DTDs that were installed as part of the textproc/docproj port. Alternatives to <acronym>FPI</acronym>s Instead of using an FPI to indicate the DTD to which the document conforms (and therefore, which file on the system contains the DTD), the filename can be explicitly specified. The syntax is slightly different: !DOCTYPE html SYSTEM "/path/to/file.dtd" The SYSTEM keyword indicates that the XML 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. If the SYSTEM identifier is used, then the DTD must be provided and kept in the same location for everyone. Escaping Back to <acronym>XML</acronym> Some of the underlying XML syntax can be useful within documents. For example, comments can be included in the document, and will be ignored by the parser. Comments are entered using XML syntax. Other uses for XML syntax will be shown later. XML sections begin with a <! tag and end with a >. These sections contain instructions for the parser rather than elements of the document. Everything between these tags is XML syntax. The DOCTYPE declaration shown earlier is an example of XML syntax included in the document. Comments Comments are an XML construct, and are normally only valid inside a DTD. However, as shows, it is possible to use XML syntax within the document. The delimiter for XML comments is the string --. The first occurrence of this string opens a comment, and the second closes it. <acronym>XML</acronym> Generic Comment <!-- This is inside the comment --> <!-- This is another comment --> <!-- This is one way of doing multiline comments --> <!-- This is another way of -- -- doing multiline comments --> XHTML users may be familiar with different rules for comments. In particular, it is often believed that the string <!-- opens a comment, and it is only closed by -->. This is not correct. Many web browsers have broken XHTML parsers, and will accept incorrect input as valid. However, the XML parsers used by the Documentation Project are more strict, and will reject documents with that error. Erroneous <acronym>XML</acronym> Comments <!-- This is in the comment -- THIS IS OUTSIDE THE COMMENT! -- back inside the comment --> The XML parser will treat this as though it were actually: <!THIS IS OUTSIDE THE COMMENT> That is not valid XML, and may give confusing error messages. To Do… Add some comments to example.xml, and check that the file still validates using xmllint. Add some invalid comments to example.xml, and see the error messages that xmllint gives when it encounters an invalid comment. Entities Entities are a mechanism for assigning names to chunks of content. As an XML parser processes a 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 XML documents. It is also the only way to include one marked up file inside another using XML. There are two types of entities for two different situations: general entities and parameter entities. General Entities General entities are used to assign names to reusable chunks of text. These entities can only be used in the document. They cannot be used in an XML context. To include the text of a general entity in the document, include &entity-name; in the text. For example, consider a general entity called current.version which expands to the current version number of a product. To use it in the document, write: paraThe current version of our product is &current.version;.para When the version number changes, edit the definition of the general entity, replacing the value. Then reprocess the document. General entities can also be used to enter characters that could not otherwise be included in an XML document. For example, < and & cannot normally appear in an XML document. The XML parser sees the < symbol as the start of a tag. Likewise, when the & symbol is seen, the next text is expected to be an entity name. These symbols can be included by using two predefined general entities: &lt; and &amp;. General entities can only be defined within an XML context. Such definitions are usually done immediately after the DOCTYPE declaration. Defining General Entities <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY current.version "3.0-RELEASE"> <!ENTITY last.version "2.2.7-RELEASE"> ]> 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, the square bracket is closed, and then the DOCTYPE declaration is closed. The square brackets are necessary to indicate that the DTD indicated by the DOCTYPE declaration is being extended. Parameter Entities Parameter entities, like general entities, are used to assign names to reusable chunks of text. But parameter entities can only be used within an XML context. Parameter entity definitions are similar to those for general entities. However, parameter entries are included with %entity-name;. The definition also includes the % between the ENTITY keyword and the name of the entity. For a mnemonic, think Parameter entities use the Percent symbol. Defining Parameter Entities <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY % param.some "some"> <!ENTITY % param.text "text"> <!ENTITY % param.new "%param.some more %param.text"> <!-- %param.new now contains "some more text" --> ]> To Do… Add a general entity to example.xml. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY version "1.1"> ]> html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head <!-- There may be some comments in here as well --> body pThis is a paragraph containing some text.p pThis paragraph contains some more text.p p align="right"This paragraph might be right-justified.p pThe current version of this document is: &version;p body html Validate the document using xmllint. Load example.xml into a web browser. It may have to be copied to example.html before the browser recognizes it as an XHTML document. Older browsers with simple parsers may not render this file as expected. The entity reference &version; may not be replaced by the version number, or the XML context closing ]> may not be recognized and instead shown in the output. The solution is to normalize the document with an XML normalizer. The normalizer reads valid XML and writes equally valid XML which has been transformed in some way. One way the normalizer transforms the input is by expanding all the entity references in the document, replacing the entities with the text that they represent. xmllint can be used for this. It also has an option to drop the initial DTD section so that the closing ]> does not confuse browsers: % xmllint --noent --dropdtd example.xml > example.html A normalized copy of the document with entities expanded is produced in example.html, ready to load into a web browser. Using Entities to Include Files Both general and parameter entities are particularly useful for including one file inside another. Using General Entities to Include Files Consider some content for an XML book organized into files, one file per chapter, called chapter1.xml, chapter2.xml, and so forth, with a book.xml that will contain these chapters. In order to use the contents of these files as the values for entities, they are declared with the SYSTEM keyword. This directs the XML parser to include the contents of the named file as the value of the entity. Using General Entities to Include Files <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY chapter.1 SYSTEM "chapter1.xml"> <!ENTITY chapter.2 SYSTEM "chapter2.xml"> <!ENTITY chapter.3 SYSTEM "chapter3.xml"> <!-- And so forth --> ]> html xmlns="http://www.w3.org/1999/xhtml" <!-- Use the entities to load in the chapters --> &chapter.1; &chapter.2; &chapter.3; html 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 because entities are low-level constructs and they are resolved before any parsing happens. Using Parameter Entities to Include Files Parameter entities can only be used inside an XML context. Including a file in an XML context can be used to ensure that general entities are reusable. Suppose that there are many chapters in the document, and these chapters were reused in two different books, each book organizing the chapters in a different fashion. The entities could be listed at the top of each book, but that quickly becomes cumbersome to manage. Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within the document. Using Parameter Entities to Include Files Place the entity definitions in a separate file called chapters.ent and containing this text: <!ENTITY chapter.1 SYSTEM "chapter1.xml"> <!ENTITY chapter.2 SYSTEM "chapter2.xml"> <!ENTITY chapter.3 SYSTEM "chapter3.xml"> 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: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!-- Define a parameter entity to load in the chapter general entities --> <!ENTITY % chapters SYSTEM "chapters.ent"> <!-- Now use the parameter entity to load in this file --> %chapters; ]> html xmlns="http://www.w3.org/1999/xhtml" &chapter.1; &chapter.2; &chapter.3; html To Do… Use General Entities to Include Files Create three files, para1.xml, para2.xml, and para3.xml. Put content like this in each file: pThis is the first paragraph.p Edit example.xml so that it looks like this: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY version "1.1"> <!ENTITY para1 SYSTEM "para1.xml"> <!ENTITY para2 SYSTEM "para2.xml"> <!ENTITY para3 SYSTEM "para3.xml"> ]> html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head body pThe current version of this document is: &version;p &para1; &para2; &para3; body html Produce example.html by normalizing example.xml. % xmllint --dropdtd --noent example.xml > example.html Load example.html into the web browser and confirm that the paran.xml files have been included in example.html. Use Parameter Entities to Include Files The previous steps must have completed before this step. Edit example.xml so that it looks like this: <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd" [ <!ENTITY % entities SYSTEM "entities.ent"> %entities; ]> html xmlns="http://www.w3.org/1999/xhtml" head titleAn Example XHTML Filetitle head body pThe current version of this document is: &version;p &para1; &para2; &para3; body html Create a new file called entities.ent with this content: <!ENTITY version "1.1"> <!ENTITY para1 SYSTEM "para1.xml"> <!ENTITY para2 SYSTEM "para2.xml"> <!ENTITY para3 SYSTEM "para3.xml"> Produce example.html by normalizing example.xml. % xmllint --dropdtd --noent example.xml > example.html Load example.html into the web browser and confirm that the paran.xml files have been included in example.html. Marked Sections XML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are called marked sections. Structure of a Marked Section <![KEYWORD[ Contents of marked section ]]> As expected of an XML construct, a marked section starts with <!. The first square bracket begins the marked section. KEYWORD describes how this marked section is to be processed by the parser. The second square bracket indicates the start of the marked section's content. The marked section is finished by closing the two square brackets, and then returning to the document context from the XML context with >. Marked Section Keywords <literal>CDATA</literal> These keywords denote the marked sections content model, and allow you to change it from the default. When an XML parser is processing a document, it keeps track of the content model. The content model describes the content the parser is expecting to see and what it will do with that content. The CDATA content model is one of the most useful. CDATA is for Character Data. When the parser is in this content model, it expects to see only characters. In this model the < and & symbols lose their special status, and will be treated as ordinary characters. When using CDATA in examples of text marked up in XML, remember that the content of CDATA is not validated. The included text must be check with other means. For example, the content could be written in another document, validated, and then pasted into the CDATA section. Using a <literal>CDATA</literal> Marked Section paraHere is an example of how to include some text that contains many literal&lt;literal and literal&amp;literal symbols. The sample text is a fragment of acronymXHTMLacronym. The surrounding text (para and programlisting) are from DocBook.para programlisting<![CDATA[pThis is a sample that shows some of the elements within acronymXHTMLacronym. 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.p ul liThis is a listitemli liThis is a second listitemli liThis is a third listitemli ul pThis is the end of the example.p]]>programlisting <literal>INCLUDE</literal> and <literal>IGNORE</literal> When the keyword is INCLUDE, then the contents of the marked section will be processed. When the keyword is IGNORE, the marked section is ignored and will not be processed. It will not appear in the output. Using <literal>INCLUDE</literal> and <literal>IGNORE</literal> 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. Text to be removed from the document could be cut out, or wrapped in comments. It becomes more useful when controlled by parameter entities, yet this usage is limited to entity files. For example, suppose that documentation was produced in a hard-copy version and an electronic version. Some extra text is desired in the electronic version content that was not to appear in the hard-copy. Create an entity file that defines general entities to include each chapter and guard these definitions with a parameter entity that can be set to either INCLUDE or IGNORE to control whether the entity is defined. After these conditional general entity definitions, place one more definition for each general entity to set them to an empty value. This technique makes use of the fact that entity definitions cannot be overridden but the first definition always takes effect. So the inclusion of the chapter is controlled with the corresponding parameter entity. Set to INCLUDE, the first general entity definition will be read and the second one will be ignored. Set to IGNORE, the first definition will be ignored and the second one will take effect. Using a Parameter Entity to Control a Marked Section <!ENTITY % electronic.copy "INCLUDE"> <![%electronic.copy;[ <!ENTITY chap.preface SYSTEM "preface.xml"> ]]> <!ENTITY chap.preface ""> When producing the hard-copy version, change the parameter entity's definition to: <!ENTITY % electronic.copy "IGNORE"> To Do… Modify entities.ent to contain the following: <!ENTITY version "1.1"> <!ENTITY % conditional.text "IGNORE"> <![%conditional.text;[ <!ENTITY para1 SYSTEM "para1.xml"> ]]> <!ENTITY para1 ""> <!ENTITY para2 SYSTEM "para2.xml"> <!ENTITY para3 SYSTEM "para3.xml"> Normalize example.xml and notice that the conditional text is not present in the output document. Set the parameter entity guard to INCLUDE and regenerate the normalized document and the text will appear again. This method makes sense if there are more conditional chunks depending on the same condition. For example, to control generating printed or online text. Conclusion That is the conclusion of this XML primer. For reasons of space and complexity, several things have not been covered in depth (or at all). However, the previous sections cover enough XML to introduce the organization of the FDP documentation. <acronym>XHTML</acronym> Markup Introduction This chapter describes usage of the XHTML markup language used for the FreeBSD web site. XHTML is the XML version of the HyperText Markup Language, the markup language of choice on the World Wide Web. More information can be found at http://www.w3.org/. XHTML is used to mark up pages on the FreeBSD web site. It is usually not used to mark up other documentation, since DocBook offers a far richer set of elements from which to choose. Consequently, XHTML pages will normally only be encountered when writing for the web site. HTML has gone through a number of versions. The XML-compliant version described here is called XHTML. The latest widespread version is XHTML 1.0, available in both strict and transitional variants. The XHTML DTDs are available from the Ports Collection in textproc/xhtml. They are automatically installed by the textproc/docproj port. This is not an exhaustive list of elements, since that would just repeat the documentation for XHTML. The aim is to list those elements most commonly used. Please post questions about elements or uses not covered here to the FreeBSD documentation project mailing list. Inline Versus 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. Formal Public Identifier (<acronym>FPI</acronym>) There are a number of XHTML FPIs, depending upon the version, or level of XHTML to which a document conforms. Most XHTML documents on the FreeBSD web site comply with the transitional version of XHTML 1.0. PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" Sectional Elements An XHTML 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 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 <acronym>XHTML</acronym> Document Structure html xmlns="http://www.w3.org/1999/xhtml" head titleThe Document's Titletitle head body … body html Block Elements Headings XHTML has tags to denote headings in the 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. <tag>h1</tag>, <tag>h2</tag>, and Other Header Tags Usage: h1First sectionh1 <!-- Document introduction goes here --> h2This is the heading for the first sectionh2 <!-- Content for the first section goes here --> h3This is the heading for the first sub-sectionh3 <!-- Content for the first sub-section goes here --> h2This is the heading for the second sectionh2 <!-- Content for the second section goes here --> Generally, an XHTML 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. Do not leave gaps in the numbering. Paragraphs XHTML supports a single paragraph element, p. <tag>p</tag> Example Usage: pThis is a paragraph. It can contain just about any other element.p Block Quotations A block quotation is an extended quotation from another document that will appear in a separate paragraph. <tag>blockquote</tag> Example Usage: pA small excerpt from the US Constitution:p blockquoteWe 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.blockquote Lists XHTML can present the user with three types of lists: ordered, unordered, and definition. Entries in an ordered list will be numbered, while entries in an unordered list will be preceded by bullet points. Definition lists have two sections for each entry. The first section is the term being defined, and the second section is the definition. 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. <tag>ul</tag> and <tag>ol</tag> Example Usage: pAn unordered list. Listitems will probably be preceded by bullets.p ul liFirst itemli liSecond itemli liThird itemli ul pAn ordered list, with list items consisting of multiple paragraphs. Each item (note: not each paragraph) will be numbered.p ol lipThis is the first item. It only has one paragraph.pli lipThis is the first paragraph of the second item.p pThis is the second paragraph of the second item.pli lipThis is the first and only paragraph of the third item.pli ol Definition Lists with <tag>dl</tag> Usage: dl dtTerm 1dt ddpParagraph 1 of definition 1.p pParagraph 2 of definition 1.pdd dtTerm 2dt ddpParagraph 1 of definition 2.pdd dtTerm 3dt ddpParagraph 1 of definition 3.pdd dl Pre-formatted Text Pre-formatted text is shown to the user exactly as it is in the file. Text is shown in a fixed font. Multiple spaces and line breaks are shown exactly as they are in the file. Wrap pre-formatted text in the pre element. <tag>pre</tag> Example For example, the pre tags could be used to mark up an email message: pre 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 &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt; Comments appreciated. Npre Keep in mind that < and & still are recognized as special characters in pre-formatted text. This is why the example shown had to use &lt; instead of <. For consistency, &gt; was used in place of >, too. Watch out for the special characters that may appear in text copied from a plain-text source, like an email message or program code. Tables 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 the pelement is not needed. Simple Use of <tag>table</tag> Usage: pThis is a simple 2x2 table.p table tr tdTop left celltd tdTop right celltd tr tr tdBottom left celltd tdBottom right celltd tr table A cell can span multiple rows and columns by adding the rowspan or colspan attributes with values for the number of rows or columns to be spanned. Using <tag class="attribute">rowspan</tag> Usage: pOne tall thin cell on the left, two short cells next to it on the right.p table tr td rowspan="2"Long and thintd tr tr tdTop celltd tdBottom celltd tr table Using <tag class="attribute">colspan</tag> Usage: pOne long cell on top, two short cells below it.p table tr td colspan="2"Top celltd tr tr tdBottom left celltd tdBottom right celltd tr table Using <tag class="attribute">rowspan</tag> and <tag class="attribute">colspan</tag> Together Usage: pOn a 3x3 grid, the top left block is a 2x2 set of cells merged into one. The other cells are normal.p table tr td colspan="2" rowspan="2"Top left large celltd tdTop right celltd tr tr <!-- Because the large cell on the left merges into this row, the first <td> will occur on its right --> tdMiddle right celltd tr tr tdBottom left celltd tdBottom middle celltd tdBottom right celltd tr table In-line Elements Emphasizing Information Two levels of emphasis are available in XHTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis. em is typically rendered in italic and strong is rendered in bold. This is not always the case, and should not be relied upon. According to best practices, web pages only hold structural and semantical information, and stylesheets are later applied to them. Think of semantics, not formatting, when using these tags. <tag>em</tag> and <tag>strong</tag> Example Usage: pemThisem has been emphasized, while strongthisstrong has been strongly emphasized.p Indicating Fixed-Pitch Text Content that should be rendered in a fixed pitch (typewriter) typeface is tagged with tt (for teletype). <tag>tt</tag> Example Usage: pMany system settings are stored in tt/etctt.p Links Links are also inline elements. Linking to Other Documents on the Web A link points to the URL of a document on the web. 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, indicated to the user by showing it in a different color or with an underline. Using <tag class="starttag">a href="..."</tag> Usage: pMore information is available at the a href="http://www.&os;.org/"&os; web sitea.p This link always takes the user to the top of the linked document. Linking to Specific Parts of Documents To link to a specific point within a document, that document must include an anchor at the desired point. Anchors are included by setting the id attribute of an element to a name. This example creates an anchor by setting the id attribute of a p element. Creating an Anchor Usage: p id="samplepara"This paragraph can be referenced in other links with the name ttsampleparatt.p Links to anchors are similar to plain links, but include a # symbol and the anchor's ID at the end of the URL. Linking to a Named Part of a Different Document The samplepara example is part of a document called foo.html. A link to that specific paragraph in the document is constructed in this example. pMore information can be found in the a href="foo.html#samplepara"sample paragrapha of ttfoo.htmltt.p To link to a named anchor within the same document, omit the document's URL, and just use the # symbol followed by the name of the anchor. Linking to a Named Part of the Same Document The samplepara example resides in this document. To link to it: pMore information can be found in the a href="#samplepara"sample paragrapha of this document.p DocBook Markup Introduction This chapter is an introduction to DocBook as it is used for FreeBSD documentation. DocBook is a large and complex markup system, but the subset described here covers the parts that are most widely used for FreeBSD documentation. While a moderate subset is covered, it is impossible to anticipate every situation. Please post questions that this document does not answer to the FreeBSD documentation project mailing list. DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a Document Type Definition (DTD) for writing technical documentation A short history can be found under http://www.oasis-open.org/docbook/intro.shtml#d0e41.. Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike LinuxDoc and XHTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented. The DocBook DTD is available from the Ports Collection in the textproc/docbook-xml port. It is automatically installed as part of the textproc/docproj port. Formal Versus 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. Inline Versus 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. FreeBSD Extensions The FreeBSD Documentation Project has extended the DocBook DTD with additional elements and entities. These additions serve to make some of the markup easier or more precise. Throughout the rest of this document, the term DocBook is used to mean the FreeBSD-extended DocBook DTD. Most of these extensions are not unique to FreeBSD, 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 contact Documentation Engineering Team doceng@FreeBSD.org. FreeBSD Elements The additional FreeBSD elements are not (currently) in the Ports Collection. They are stored in the FreeBSD Subversion tree, as head/share/xml/freebsd.dtd. FreeBSD-specific elements used in the examples below are clearly marked. FreeBSD Entities This table shows some of the most useful entities available in the FDP. For a complete list, see the *.ent files in doc/share/xml. FreeBSD Name Entities &os; - FreeBSD + FreeBSD &os.stable; FreeBSD-STABLE &os.current; FreeBSD-CURRENT Manual Page Entities &man.ls.1; ls1 Usage: &man.ls.1; is the manual page for <command>ls</command>. &man.cp.1; cp1 Usage: The manual page for <command>cp</command> is &man.cp.1;. &man.command.sectionnumber; link to command manual page in section sectionnumber Entities are defined for all the FreeBSD manual pages. FreeBSD Mailing List Entities &a.doc; FreeBSD documentation project mailing list Usage: A link to the &a.doc;. &a.questions; FreeBSD general questions mailing list Usage: A link to the &a.questions;. &a.listname; link to listname Entities are defined for all the FreeBSD mailing lists. FreeBSD Document Link Entities &url.books.handbook; @@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook Usage: A link to the <link xlink:href="&url.books.handbook;/advanced-networking.html">Advanced Networking</link> chapter of the Handbook. &url.books.bookname; relative path to bookname Entities are defined for all the FreeBSD books. &url.articles.committers-guide; @@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide Usage: A link to the <link xlink:href="&url.articles.committers-guide;">Committer's Guide</link> article. &url.articles.articlename; relative path to articlename Entities are defined for all the FreeBSD articles. Other Operating System Name Entities &linux; - Linux + Linux The Linux operating system. &unix; - UNIX - The UNIX operating system. + UNIX + Het UNIX besturingssysteem. &windows; - Windows + Windows The Windows operating system. Miscellaneous Entities &prompt.root; # The root user prompt. &prompt.user; % A prompt for an unprivileged user. &postscript; - PostScript + PostScript The PostScript programming language. &tex; TeX The TeX typesetting language. &xorg; Xorg The Xorg open source X Window System. 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.2-Based Extension//EN" Document Structure DocBook allows structuring documentation in several ways. The FreeBSD Documentation Project uses two primary types of DocBook document: the book and the article. Books are organized into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organization. For example, 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. The nature of the document being written should be used to determine 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 FAQ, and the Handbook are all marked up as books, for example. Starting a Book The content of a 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 is contained within info. Boilerplate <tag>book</tag> with <tag>info</tag> book info titleYour Title Heretitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailYour email addressemail address affiliation author copyright year1998year holder role="mailto:your email address"Your nameholder copyright releaseinfo$FreeBSD$releaseinfo abstract paraInclude an abstract of the book's contents here.para abstract info … 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 is contained within info. Boilerplate <tag>article</tag> with <tag>info</tag> article info titleYour title heretitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailYour email addressemailaddress address affiliation author copyright year1998year holder role="mailto:your email address"Your nameholder copyright releaseinfo$FreeBSD$releaseinfo abstract paraInclude an abstract of the article's contents here.para abstract info … 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 chapter titleThe Chapter's Titletitle ... chapter 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 chapter titleThis is An Empty Chaptertitle parapara 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 chapter titleA Sample Chaptertitle paraSome text in the chapter.para sect1 titleFirst Sectiontitle … sect1 sect1 titleSecond Sectiontitle sect2 titleFirst Sub-Sectiontitle sect3 titleFirst Sub-Sub-Sectiontitle … sect3 sect2 sect2 titleSecond Sub-Section (1.2.2)title … sect2 sect1 chapter Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be: 1.1. First Section 1.2. Second Section 1.2.1. First Sub-Section 1.2.1.1. First Sub-Sub-Section 1.2.2. Second Sub-Section Subdividing Using <tag>part</tag> Elements parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article. part titleIntroductiontitle chapter titleOverviewtitle ... chapter chapter titleWhat is FreeBSD?title ... chapter chapter titleHistorytitle ... chapter part Block Elements Paragraphs DocBook supports three types of paragraphs: formalpara, para, and simpara. Almost all paragraphs in FreeBSD documentation use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para. <tag>para</tag> Example Usage: paraThis is a paragraph. It can contain just about any other element.para 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. These are rarely needed. Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed). <tag>blockquote</tag> Example Usage: paraA small excerpt from the US Constitution:para blockquote titlePreamble to the Constitution of the United Statestitle attributionCopied from a web site somewhereattribution paraWe 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.para blockquote Appearance: 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.
Tips, Notes, Warnings, Cautions, and Important Information Extra information may need to be separated from the main body of the text. Typically this is meta information of which the user should be aware. Several types of admonitions are available: tip, note, warning, caution, and important. Which admonition to choose depends on the situation. The DocBook documentation suggests: Note is for information that should be heeded by all readers. Important is a variation on Note. Caution is for information regarding possible data loss or software damage. Warning is for information regarding possible hardware damage or injury to life or limb. <tag>tip</tag> and <tag>important</tag> Example Usage: tip para&os; may reduce stress.para tip important paraPlease use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect.para important Appearance: FreeBSD may reduce stress. Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect. Voorbeelden Examples can be shown with example. <tag>example</tag> Source Usage: example paraEmpty files can be created easily:para screen&prompt.user; userinputtouch file1 file2 file3userinputscreen example Appearance: Rendered <tag>example</tag> Empty files can be created easily: % touch file1 file2 file3 Lists and Procedures Information often needs to be presented as lists, or as a number of steps that must be carried out in order to accomplish a particular goal. To do this, use itemizedlist, orderedlist, variablelist, or procedure. There are other types of list elements in DocBook, but we will not cover them here. 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. <tag>itemizedlist</tag> and <tag>orderedlist</tag> Example Usage: itemizedlist listitem paraThis is the first itemized item.para listitem listitem paraThis is the second itemized item.para listitem itemizedlist orderedlist listitem paraThis is the first ordered item.para listitem listitem paraThis is the second ordered item.para listitem orderedlist 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. An alternate and often useful way of presenting information is the variablelist. These are lists where each entry has a term and a description. They are well suited for many types of descriptions, and present information in a form that is often easier for the reader than sections and subsections. A variablelist has a title, and then pairs of term and listitem entries. <tag>variablelist</tag> Example Usage: variablelist varlistentry termParallelterm listitem paraIn parallel communications, groups of bits arrive at the same time over multiple communications channels.para listitem varlistentry varlistentry termSerialterm listitem paraIn serial communications, bits arrive one at a time over a single communications channel.para listitem varlistentry variablelist Appearance: Parallel In parallel communications, groups of bits arrive at the same time over multiple communications channels. Serial In serial communications, bits arrive one at a time over a single communications channel. A procedure shows a series of steps, which may in turn consist of more steps or substeps. Each step contains block elements and may include an optional title. Sometimes, steps are not sequential, but present a choice: do this or do that, but not both. For these alternative choices, use stepalternatives. <tag>procedure</tag> Example Usage: procedure step paraDo this.para step step paraThen do this.para step step paraAnd now do this.para step step paraFinally, do one of these.para stepalternatives step paraGo left.para step step paraGo right.para step stepalternatives step procedure Appearance: Do this. Then do this. And now do this. Finally, do one of these: Go left. Go right. Showing File Samples Fragments of a file (or perhaps a complete file) are shown by wrapping them in the programlisting element. White space and line breaks within programlisting are 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. <tag>programlisting</tag> Example Usage: paraWhen finished, the program will look like this:para programlisting#include &lt;stdio.h&gt; int main(void) { printf("hello, world\n"); }programlisting Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally. Appearance: When finished, the program will look like this: #include <stdio.h> int main(void) { printf("hello, world\n"); } Callouts A callout is a visual marker for referring to a piece of text or specific position within an example. Callouts are marked with the co element. Each element must have a unique id assigned to it. After the example, include a calloutlist that describes each callout. <tag>co</tag> and <tag>calloutlist</tag> Example paraWhen finished, the program will look like this:para programlisting#include &lt;stdio.h&gt; co xml:id="co-ex-include" int co xml:id="co-ex-return" main(void) { printf("hello, world\n"); co xml:id="co-ex-printf" }programlisting calloutlist callout arearefs="co-ex-include" paraIncludes the standard IO header file.para callout callout arearefs="co-ex-return" paraSpecifies that functionmain()function returns an int.para callout callout arearefs="co-ex-printf" paraThe functionprintf()function call that writes literalhello, worldliteral to standard output.para callout calloutlist Appearance: When finished, the program will 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, DocBook does not need tables for layout purposes, as the stylesheet handles those issues. 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 there is 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. <tag>informaltable</tag> Example Usage: informaltable pgwide="1" tgroup cols="2" thead row entryThis is Column Head 1entry entryThis is Column Head 2entry row thead tbody row entryRow 1, column 1entry entryRow 1, column 2entry row row entryRow 2, column 1entry entryRow 2, column 2entry row tbody tgroup informaltable 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. Table borders can be suppressed by setting the frame attribute to none in the informaltable element. For example, informaltable frame="none". Table with <literal>frame="none"</literal> Example 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 Examples for the user to follow are often necessary. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, the user types 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. 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 be displayed differently than system output text. <tag>screen</tag>, <tag>prompt</tag>, and <tag>userinput</tag> Example Usage: screen&prompt.user; userinputls -1userinput foo1 foo2 foo3 &prompt.user; userinputls -1 | grep foo2userinput foo2 &prompt.user; userinputsuuserinput promptPassword: prompt &prompt.root; userinputcat foo2userinput This is the file called 'foo2'screen Appearance: % ls -1 foo1 foo2 foo3 % ls -1 | grep foo2 foo2 % su Password: # 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 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 the document, no equivalent of HTML's b and i. If the information being presented is important, then consider presenting it in important rather than emphasis. <tag>emphasis</tag> Example Usage: para&os; is without doubt emphasistheemphasis premiere &unix;-like operating system for the Intel architecture.para Appearance: FreeBSD is without doubt the premiere UNIX-like operating system for the Intel architecture. Acronyms Many computer terms are acronyms, words formed from the first letter of each word in a phrase. Acronyms are marked up into acronym elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below. <tag>acronym</tag> Example Usage: paraRequest For Comments (acronymRFCacronym) 1149 defined the use of avian carriers for transmission of Internet Protocol (acronymIPacronym) data. The quantity of acronymIPacronym data currently transmitted in that manner is unknown.para Appearance: Request For Comments (RFC) 1149 defined the use of avian carriers for transmission of Internet Protocol (IP) data. The quantity of IP data currently transmitted in that manner is unknown. Quotations To quote text from another document or source, or to denote a phrase that is used figuratively, use quote. Most of the markup tags available for normal text are also available from within a quote. <tag>quote</tag> Example Usage: paraHowever, make sure that the search does not go beyond the quoteboundary between local and public administrationquote, as acronymRFCacronym 1535 calls it.para 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 Example Usage: paraTo switch to the second virtual terminal, press keycombo action="simul"keycapAltkeycap keycapF1keycapkeycombo.para paraTo exit commandvicommand without saving changes, type keycombo action="seq"keycapEsckeycapkeycap:keycap keycapqkeycapkeycap!keycapkeycombo.para paraMy window manager is configured so that keycombo action="simul"keycapAltkeycap mousebuttonrightmousebutton keycombo mouse button is used to move windows.para Appearance: To switch to the second virtual terminal, press Alt F1. To exit vi without saving changes, type Esc : q !. My window manager is configured so that Alt right mouse button is used to move windows. Applications, Commands, Options, and Cites Both applications and commands are frequently referred to when writing documentation. The distinction between them is that an application is the name of a program or suite of programs that fulfill a particular task. A command is the filename of a program that the user can type and run at a command line. It is often necessary to show some of the options that a command might take. Finally, it is often useful 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. 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 FreeBSD documentation will usually include 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 to include a command name in-line but present it as something the user should type. 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. Applications, Commands, and Options Example Usage: paraapplicationSendmailapplication is the most widely used Unix mail application.para paraapplicationSendmailapplication includes the citerefentry refentrytitlesendmailrefentrytitle manvolnum8manvolnum citerefentry, &man.mailq.1;, and &man.newaliases.1; programs.para paraOne of the command line parameters to citerefentry refentrytitlesendmailrefentrytitle manvolnum8manvolnum citerefentry, option-bpoption, will display the current status of messages in the mail queue. Check this on the command line by running commandsendmail -bpcommand.para Appearance: Sendmail is the most widely used Unix mail application. Sendmail includes the sendmail 8 , mailq1, and newaliases1 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, Device Names To refer to the name of a file, a directory, a file extension, or a device name, use filename. <tag>filename</tag> Example Usage: paraThe source for the Handbook in English is found in filename/usr/doc/en_US.ISO8859-1/books/handbook/filename. The main file is called filenamebook.xmlfilename. There is also a filenameMakefilefilename and a number of files with a filename.entfilename extension.para parafilenamekbd0filename is the first keyboard detected by the system, and appears in filename/devfilename.para Appearance: The source for the Handbook in English is found in /usr/doc/en_US.ISO8859-1/books/handbook/. The main file is called book.xml. There is also a Makefile and a number of files with a .ent extension. kbd0 is the first keyboard detected by the system, and appears in /dev. 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. To include the name of a program from the FreeBSD Ports Collection in the document, use the package tag. Since the Ports Collection can be installed in any number of locations, only include the category and the port name; do not include /usr/ports. By default, package refers to a binary package. To refer to a port that will be built from source, set the role attribute to port. <tag>package</tag> Example Usage: paraInstall the packagenet/wiresharkpackage binary package to view network traffic.para parapackage role="port"net/wiresharkpackage can also be built and installed from the Ports Collection.para Appearance: Install the net/wireshark binary package to view network traffic. net/wireshark can also be built and installed from the Ports Collection. Hosts, Domains, IP Addresses, User Names, Group Names, and Other System Items FreeBSD Extension These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD. Information for system items is marked up with systemitem. The class attribute is used to identify the particular type of information shown. class="domainname" The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component. class="etheraddress" The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons. class="fqdomainname" The text is a Fully Qualified Domain Name, with both hostname and domain name parts. class="ipaddress" The text is an IP address, probably expressed as a dotted quad. class="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 (CIDR notation). class="systemname" With class="systemname" the marked up information is the simple hostname, such as freefall or wcarchive. class="username" The text is a username, like root. class="groupname" The text is a groupname, like wheel. <tag>systemitem</tag> and Classes Example Usage: paraThe local machine can always be referred to by the name systemitem class="systemname"localhostsystemitem, which will have the IP address systemitem class="ipaddress"127.0.0.1systemitem.para paraThe systemitem class="domainname"FreeBSD.orgsystemitem domain contains a number of different hosts, including systemitem class="fqdomainname"freefall.FreeBSD.orgsystemitem and systemitem class="fqdomainname"bento.FreeBSD.orgsystemitem.para paraWhen adding an acronymIPacronym alias to an interface (using commandifconfigcommand) emphasisalwaysemphasis use a netmask of systemitem class="netmask"255.255.255.255systemitem (which can also be expressed as systemitem class="netmask"0xffffffffsystemitem).para paraThe acronymMACacronym address uniquely identifies every network card in existence. A typical acronymMACacronym address looks like systemitem class="etheraddress"08:00:20:87:ef:d0systemitem.para paraTo carry out most system administration functions requires logging in as systemitem class="username"rootsystemitem.para 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. To carry out most system administration functions requires logging in as root. Uniform Resource Identifiers (<acronym>URI</acronym>s) Occasionally it is useful to show a Uniform Resource Identifier (URI) without making it an active hyperlink. The uri element makes this possible: <tag>uri</tag> Example Usage: paraThis URL shows only as text: urihttps://www.FreeBSD.orguri. It does not create a link.para Appearance: This URL shows only as text: https://www.FreeBSD.org. It does not create a link. To create links, see . - Email Addresses + E-mail-adressen Email addresses are marked up as email elements. In the HTML output format, the wrapped text becomes a hyperlink to the email address. Other output formats that support hyperlinks may also make the email address into a link. <tag>email</tag> with a Hyperlink Example Usage: paraAn email address that does not actually exist, like emailnotreal@example.comemail, can be used as an example.para Appearance: An email address that does not actually exist, like notreal@example.com, can be used as an example. A FreeBSD-specific extension allows setting the role attribute to nolink to prevent the creation of the hyperlink to the email address. <tag>email</tag> Without a Hyperlink Example Usage: paraSometimes a link to an email address like email role="nolink"notreal@example.comemail is not desired.para Appearance: Sometimes a link to an email address like notreal@example.com is not desired. Describing <filename>Makefile</filename>s 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, buildtarget and varname. buildtarget identifies a build target exported by a Makefile that can be given as a parameter to make. varname identifies a variable that can be set (in the environment, on the command line with make, or within the Makefile) to influence the process. <tag>buildtarget</tag> and <tag>varname</tag> Example Usage: paraTwo common targets in a filenameMakefilefilename are buildtargetallbuildtarget and buildtargetcleanbuildtarget.para paraTypically, invoking buildtargetallbuildtarget will rebuild the application, and invoking buildtargetcleanbuildtarget will remove the temporary files (filename.ofilename for example) created by the build process.para parabuildtargetcleanbuildtarget may be controlled by a number of variables, including varnameCLOBBERvarname and varnameRECURSEvarname.para 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 Literal text, or text which should be entered verbatim, is often needed in documentation. This is text that is excerpted from another file, or which should be copied exactly as shown from the documentation into another file. Some of the time, programlisting will be sufficient to denote this text. But 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. <tag>literal</tag> Example Usage: paraThe literalmaxusers 10literal 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.para 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 <emphasis>Must</emphasis> Fill In There will often be times when the user is shown what to do, or referred to a file or command line, but cannot simply copy the example provided. Instead, they must supply 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. <tag>replaceable</tag> Example Usage: screen&prompt.user; userinputman replaceablecommandreplaceableuserinputscreen Appearance: % 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. Usage: paraThe literalmaxusers replaceablenreplaceableliteral 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.para paraFor a desktop workstation, literal32literal is a good value for replaceablenreplaceable.para 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. Showing <acronym>GUI</acronym> Buttons Buttons presented by a graphical user interface are marked with guibutton. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text. <tag>guibutton</tag> Example Usage: paraEdit the file, then click guibutton[&nbsp;Save&nbsp;]guibutton to save the changes.para Appearance: Edit the file, then click [ Save ] to save the changes. - Quoting System Errors + Systeemfouten aanhalen System errors generated by FreeBSD are marked with errorname. This indicates the exact error that appears. <tag>errorname</tag> Example Usage: screenerrornamePanic: cannot mount rooterrornamescreen Appearance: Panic: cannot mount root Images Image support in the documentation is somewhat experimental. The mechanisms described here are unlikely to change, but that is not guaranteed. To provide conversion between different image formats, the graphics/ImageMagick port must be installed. This port is not included in the textproc/docproj meta port, and must be installed separately. A good example of the use of images is the doc/en_US.ISO8859-1/articles/vm-design/ document. Examine the files in that directory to see how these elements are used together. Build different output formats to see how the format determines what images are shown in the rendered document. Image Formats The following image formats are currently supported. An image file will automatically be converted to bitmap or vector image depending on the output document format. These are the only formats in which images should be committed to the documentation repository. EPS (Encapsulated Postscript) Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in this format. These images have a .eps extension. PNG (Portable Network Graphic) For bitmaps, such as screen captures, use this format. These images have the .png extension. PIC (PIC graphics language) PIC is a language for drawing simple vector-based figures used in the pic1 utility. These images have the .pic extension. SCR (SCReen capture) This format is specific to screenshots of console output. The following command generates an SCR file shot.scr from video buffer of /dev/ttyv0: # vidcontrol -p < /dev/ttyv0 > shot.scr This is preferable to PNG format for screenshots because the SCR file contains plain text of the command lines so that it can be converted to a PNG image or a plain text depending on the output document format. Use the appropriate format for each image. Documentation will often have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format used. Do not commit the same image to the repository in two different formats. The Documentation Project may eventually switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes this impractical. Image File Locations Image files can be stored in one of several locations, depending on the document and image: In the same directory as the document itself, usually done for articles and small books that keep all their files in a single directory. In a subdirectory of the main document. Typically done when a large book uses separate subdirectories to organize individual chapters. When images are stored in a subdirectory of the main document directory, the subdirectory name must be included in their paths in the Makefile and the imagedata element. In a subdirectory of doc/share/images named after the document. For example, images for the Handbook are stored in doc/share/images/books/handbook. Images that work for multiple translations are stored in this upper level of the documentation file tree. Generally, these are images that can be used unchanged in non-English translations of the document. Image Markup Images are included as part of a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject. Include one imageobject, and two textobject elements. The imageobject will point to the name of the image file without the extension. The textobject elements contain information that will be presented to the user as well as, or instead of, the image itself. Text elements are shown to the reader in several situations. When the document is viewed in HTML, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones. This example shows how to include an image called fig1.png in a document. The image is a rectangle with an A inside it: mediaobject imageobject imagedata fileref="fig1" imageobject textobject literallayout class="monospaced"+---------------+ | A | +---------------+literallayout textobject textobject phraseA picturephrase 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 contains a literallayout element, where the class attribute is set to monospaced. This is an opportunity to demonstrate 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 contains a single phrase element. The contents of this phrase will become the alt attribute for the image when this document is converted to HTML. Image <filename>Makefile</filename> Entries Images must be listed in the Makefile in the IMAGES variable. This variable must contain the names of all the source images. For example, if there are three figures, fig1.eps, fig2.png, fig3.png, then the 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 the source document, you only need to list the image files you provided. Images and Chapters in Subdirectories Be careful when separating documentation into smaller files in different directories (see ). Suppose there is 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, place those images in each chapter's subdirectory (chapter1/, chapter2/, and chapter3/). However, doing this requires including the directory names in the IMAGES variable in the Makefile, and including the directory name in the imagedata element in the document. For example, if the book has 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 … Links Links are also in-line elements. To show a URI without creating a link, see . <literal>xml:id</literal> Attributes Most DocBook elements accept an xml:id attribute to give that part of the document a unique name. The xml:id can be used as a target for a crossreference or link. Any portion of the document that will be a link target must have an xml:id attribute. Assigning an xml:id to all chapters and sections, even if there are no current plans to link to them, is a good idea. These xml:ids can be used as unique reference points by anyone referring to the HTML version of the document. <literal>xml:id</literal> on Chapters and Sections Example chapter xml:id="introduction" titleIntroductiontitle paraThis is the introduction. It contains a subsection, which is identified as well.para sect1 xml:id="introduction-moredetails" titleMore Detailstitle paraThis is a subsection.para sect1 chapter Use descriptive values for xml:id names. The values must be unique within the entire document, not just in a single file. In the example, the subsection xml:id is constructed by appending text to the chapter xml:id. This ensures that the xml:ids are unique. It also helps both reader and anyone editing the document to see where the link is located within the document, similar to a directory path to a file. Crossreferences with <literal>xref</literal> xref provides the reader with a link to jump to another section of the document. The target xml:id is specified in the linkend attribute, and xref generates the link text automatically. <tag>xref</tag> Example Assume that this fragment appears somewhere in a document that includes the xml:id example shown above: paraMore information can be found in xref linkend="introduction".para paraMore specific information can be found in xref linkend="introduction-moredetails".para The link text will be generated automatically, looking like (emphasized text indicates the link text):
More information can be found in Chapter 1, Introduction. More specific information can be found in Section 1.1, More Details.
The link text is generated automatically from the chapter and section number and title elements. Linking to Other Documents on the Web The link element described here allows the writer to define the link text. When link text is used, it is very important to be descriptive to give the reader an idea of where the link goes. Remember that DocBook can be rendered to multiple types of media. The reader might be looking at a printed book or other form of media where there are no links. If the link text is not descriptive enough, the reader might not be able to locate the linked section. The xlink:href attribute is the URL of the page, and the content of the element is the text that will be displayed for the user to activate. In many situations, it is preferable to show the actual URL rather than text. This can be done by leaving out the element text entirely. <tag>link</tag> to a FreeBSD Documentation Web Page Example Link to the book or article URL entity. To link to a specific chapter in a book, add a slash and the chapter file name, followed by an optional anchor within the chapter. For articles, link to the article URL entity, followed by an optional anchor within the article. URL entities can be found in doc/share/xml/urls.ent. Usage for FreeBSD book links: paraRead the link xlink:href="&url.books.handbook;/svn.html#svn-intro"SVN introductionlink, then pick the nearest mirror from the list of link xlink:href="&url.books.handbook;/svn.html#svn-mirrors"Subversion mirror siteslink.para Appearance: Read the SVN introduction, then pick the nearest mirror from the list of Subversion mirror sites. Usage for FreeBSD article links: paraRead this link xlink:href="&url.articles.bsdl-gpl;"article about the BSD licenselink, or just the link xlink:href="&url.articles.bsdl-gpl;#intro"introductionlink.para Appearance: Read this article about the BSD license, or just the introduction. <tag>link</tag> to a FreeBSD Web Page Example Usage: paraOf course, you could stop reading this document and go to the link xlink:href="&url.base;/index.html"FreeBSD home pagelink instead.para Appearance: Of course, you could stop reading this document and go to the FreeBSD home page instead. <tag>link</tag> to an External Web Page Example Usage: paraWikipedia has an excellent reference on link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"GUID Partition Tableslink.para Appearance: Wikipedia has an excellent reference on GUID Partition Tables. The link text can be omitted to show the actual URL: paraWikipedia has an excellent reference on GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table"link.para The same link can be entered using shorter notation instead of a separate ending tag: paraWikipedia has an excellent reference on GUID Partition Tables: link xlink:href="http://en.wikipedia.org/wiki/GUID_Partition_Table".para The two methods are equivalent. Appearance: Wikipedia has an excellent reference on GUID Partition Tables: http://en.wikipedia.org/wiki/GUID_Partition_Table. Style Sheets XML is concerned with content, and says nothing about how that content should be presented to the reader or rendered on paper. Multiple style sheet languages have been developed to describe visual layout, including Extensible Stylesheet Language Transformation (XSLT), Document Style Semantics and Specification Language (DSSSL), and Cascading Style Sheets (CSS). The FDP documents use XSLT stylesheets to transform DocBook into XHTML, and then CSS formatting is applied to the XHTML pages. Printable output is currently rendered with legacy DSSSL stylesheets, but this will probably change in the future. <acronym>CSS</acronym> Cascading Style Sheets (CSS) are a mechanism for attaching style information (font, weight, size, color, and so forth) to elements in an XHTML document without abusing XHTML to do so. The DocBook Documents The FreeBSD XSLT and DSSSL stylesheets refer to docbook.css, which is expected to be present in the same directory as the XHTML files. The project-wide CSS file is copied from doc/share/misc/docbook.css when documents are converted to XHTML, and is installed automatically. Translations This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, manual pages, and others) to different languages. It is very heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer elwood@mc5sys.in-berlin.de and translated back to English by Bernd Warken bwarken@mayn.de. The FAQ is maintained by the Documentation Engineering Team doceng@FreeBSD.org. What do i18n and l10n mean? i18n means internationalization and l10n means localization. They are just a convenient shorthand. i18n can be read as i followed by 18 letters, followed by n. Similarly, l10n is l followed by 10 letters, followed by n. Is there a mailing list for translators? Yes. Different translation groups have their own mailing lists. The list of translation projects has more information about the mailing lists and web sites run by each translation project. In addition there is freebsd-translators@freebsd.org for general translation discussion. Are more translators needed? Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents. You do not have to be a professional translator to be able to help. What languages do I need to know? Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to. English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation. What software do I need to know? It is strongly recommended that you maintain a local copy of the FreeBSD Subversion repository (at least the documentation part). This can be done by running: % svn checkout https://svn.FreeBSD.org/doc/head/ head svn.FreeBSD.org is a public SVN server. Verify the server certificate from the list of Subversion mirror sites. This will require the devel/subversion package to be installed. You should be comfortable using svn. This will allow you to see what has changed between different versions of the files that make up the documentation. For example, to view the differences between revisions r33733 and r33734 of en_US.ISO8859-1/books/fdp-primer/book.xml, run: % svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml How do I find out who else might be translating to the same language? The Documentation Project translations page lists the translation efforts that are currently known about. If others are already working on translating documentation to your language, please do not duplicate their efforts. Instead, contact them to see how you can help. If no one is listed on that page as translating for your language, then send a message to the FreeBSD documentation project mailing list in case someone else is thinking of doing a translation, but has not announced it yet. No one else is translating to my language. What do I do? Congratulations, you have just started the FreeBSD your-language-here Documentation Translation Project. Welcome aboard. First, decide whether or not you have got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicize your work and coordinate any volunteers that might want to help you. Write an email to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained. If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if you can have some webspace for your project, and possibly an email address or mailing list services. Then pick a document and start translating. It is best to start with something fairly small—either the FAQ, or one of the tutorials. I have translated some documentation, where do I send it? That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages. If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question). I am the only person working on translating to this language, how do I submit my translation? or We are a translation team, and want to submit documentation that our members have translated for us. First, make sure your translation is organized properly. This means that it should drop into the existing documentation tree and build straight away. Currently, the FreeBSD documentation is stored in a top level directory called head/. Directories below this are named according to the language code they are written in, as defined in ISO639 (/usr/share/misc/iso639 on a version of FreeBSD newer than 20th January 1999). If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided. Finally, you should have directories for each document. For example, a hypothetical Swedish translation might look like: head/ sv_SE.ISO8859-1/ Makefile htdocs/ docproj/ books/ faq/ Makefile book.xml sv_SE.ISO8859-1 is the name of the translation, in lang.encoding form. Note the two Makefiles, which will be used to build the documentation. Use tar1 and gzip1 to compress up your documentation, and send it to the project. % cd doc % tar cf swedish-docs.tar sv_SE.ISO8859-1 % gzip -9 swedish-docs.tar Put swedish-docs.tar.gz somewhere. If you do not have access to your own webspace (perhaps your ISP does not let you have any) then you can email Documentation Engineering Team doceng@FreeBSD.org, and arrange to email the files when it is convenient. Either way, you should use Bugzilla to submit a report indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language. Someone (probably the Documentation Project Manager, currently Documentation Engineering Team doceng@FreeBSD.org) will then take your translation and confirm that it builds. In particular, the following things will be looked at: Do all your files use RCS strings (such as "ID")? Does make all in the sv_SE.ISO8859-1 directory work correctly? Does make install work correctly? If there are any problems then whoever is looking at the submission will get back to you to work them out. If there are no problems your translation will be committed as soon as possible. Can I include language or country specific text in my translation? We would prefer that you did not. For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook. There is no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or …) versions as well. It is feasible that an English speaker in Korea might try to pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing. If you have country specific information, please submit it as a change to the English Handbook (using Bugzilla) and then translate the change back to your language in the translated Handbook. Thanks. How should language specific characters be included? Non-ASCII characters in the documentation should be included using SGML entities. Briefly, these look like an ampersand (&), the name of the entity, and a semi-colon (;). The entity names are defined in ISO8879, which is in the ports tree as textproc/iso8879. A few examples include: Entity Appearance - Description + Beschrijving &eacute; é Small e with an acute accent &Eacute; É Large E with an acute accent &uuml; ü Small u with an umlaut After you have installed the iso8879 port, the files in /usr/local/share/xml/iso8879 contain the complete list. Addressing the reader In the English documents, the reader is addressed as you, there is no formal/informal distinction as there is in some languages. If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form. Do I need to include any additional information in my translations? Yes. The header of the English version of each document will look something like this: <!-- The FreeBSD Documentation Project $FreeBSD$ --> The exact boilerplate may change, but it will always include a $FreeBSD$ line and the phrase The FreeBSD Documentation Project. Note that the $FreeBSD part is expanded automatically by Subversion, so it should be empty (just $FreeBSD$) for new files. Your translated documents should include their own $FreeBSD$ line, and change the FreeBSD Documentation Project line to The FreeBSD language Documentation Project. In addition, you should add a third line which indicates which revision of the English text this is based on. So, the Spanish version of this file might start: <!-- The FreeBSD Spanish Documentation Project $FreeBSD$ Original revision: r38674 --> <acronym>PO</acronym> Translations Introduction The GNU gettext system offers translators an easy way to create and maintain translations of documents. Translatable strings are extracted from the original document into a PO (Portable Object) file. Translated versions of the strings are entered with a separate editor. The strings can be used directly or built into a complete translated version of the original document. Quick Start The procedure shown in is assumed to have already been performed, but the TRANSLATOR option must be enabled in the textproc/docproj port. If that option was not enabled, display the options menu and enable it, then reinstall the port: # cd /usr/ports/textproc/docproj # make config # make clean deinstall install clean This example shows the creation of a Spanish translation of the short Leap Seconds article. Install a <acronym>PO</acronym> Editor A PO editor is needed to edit translation files. This example uses editors/poedit. # cd /usr/ports/editors/poedit # make install clean Initial Setup When a new translation is first created, the directory structure and Makefile must be created or copied from the English original: Create a directory for the new translation. The English article source is in ~/doc/en_US.ISO8859-1/articles/leap-seconds/. The Spanish translation will go in ~/doc/es_ES.ISO8859-1/articles/leap-seconds/. The path is the same except for the name of the language directory. % svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ Copy the Makefile from the original document into the translation directory: % svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \ ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ Translation Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document. Extract the translatable strings from the original English version into a PO file: % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ % make po Use a PO editor to enter translations in the PO file. There are several different editors available. poedit from editors/poedit is shown here. The PO file name is the two-character language code followed by an underline and a two-character region code. For Spanish, the file name is es_ES.po. % poedit es_ES.po Generating a Translated Document Generate the translated document: % cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/ % make tran The name of the generated document matches the name of the English original, usually article.xml for articles or book.xml for books. Check the generated file by rendering it to HTML and viewing it with a web browser: % make FORMATS=html % firefox article.html Creating New Translations The first step to creating a new translated document is locating or creating a directory to hold it. FreeBSD puts translated documents in a subdirectory named for their language and region in the format lang_REGION. lang is a two-character lowercase code. It is followed by an underscore character and then the two-character uppercase REGION code. Language Names Language Region Translated Directory Name PO File Name Character Set English - United States + Verenigde Staten en_US.ISO8859-1 en_US.po ISO 8859-1 Bengali Bangladesh bn_BD.UTF-8 bn_BD.po UTF-8 Danish Denmark da_DK.ISO8859-1 da_DK.po ISO 8859-1 German Germany de_DE.ISO8859-1 de_DE.po ISO 8859-1 Greek Greece el_GR.ISO8859-7 el_GR.po ISO 8859-7 Spanish Spain es_ES.ISO8859-1 es_ES.po ISO 8859-1 French France fr_FR.ISO8859-1 fr_FR.po ISO 8859-1 Hungarian Hungary hu_HU.ISO8859-2 hu_HU.po ISO 8859-2 Italian Italy it_IT.ISO8859-15 it_IT.po ISO 8859-15 Japanese Japan ja_JP.eucJP ja_JP.po EUC JP Korean Korea ko_KR.UTF-8 ko_KR.po UTF-8 Mongolian Mongolia mn_MN.UTF-8 mn_MN.po UTF-8 Dutch Netherlands nl_NL.ISO8859-1 nl_NL.po ISO 8859-1 Norwegian Norway no_NO.ISO8859-1 no_NO.po ISO 8859-1 Polish Poland pl_PL.ISO8859-2 pl_PL.po ISO 8859-2 Portuguese Brazil pt_BR.ISO8859-1 pt_BR.po ISO 8859-1 Russian Russia ru_RU.KOI8-R ru_RU.po KOI8-R Serbian Serbia sr_YU.ISO8859-2 sr_YU.po ISO 8859-2 Turkish Turkey tr_TR.ISO8859-9 tr_TR.po ISO 8859-9 Chinese China zh_CN.UTF-8 zh_CN.po UTF-8 Chinese Taiwan zh_TW.UTF-8 zh_TW.po UTF-8
The translations are in subdirectories of the main documentation directory, here assumed to be ~/doc/ as shown in . For example, German translations are located in ~/doc/de_DE.ISO8859-1/, and French translations are in ~/doc/fr_FR.ISO8859-1/. Each language directory contains separate subdirectories named for the type of documents, usually articles/ and books/. Combining these directory names gives the complete path to an article or book. For example, the French translation of the NanoBSD article is in ~/doc/fr_FR.ISO8859-1/articles/nanobsd/, and the Mongolian translation of the Handbook is in ~/doc/mn_MN.UTF-8/books/handbook/. A new language directory must be created when translating a document to a new language. If the language directory already exists, only a subdirectory in the articles/ or books/ directory is needed. FreeBSD documentation builds are controlled by a Makefile in the same directory. With simple articles, the Makefile can often just be copied verbatim from the original English directory. The translation process combines multiple separate book.xml and chapter.xml files in books into a single file, so the Makefile for book translations must be copied and modified. Creating a Spanish Translation of the Porter's Handbook Create a new Spanish translation of the Porter's Handbook. The original is a book in ~/doc/en_US.ISO8859-1/books/porters-handbook/. The Spanish language books directory ~/doc/es_ES.ISO8859-1/books/ already exists, so only a new subdirectory for the Porter's Handbook is needed: % cd ~/doc/es_ES.ISO8859-1/books/ % svn mkdir porters-handbook A porters-handbook Copy the Makefile from the original book: % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook % svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile . A Makefile Modify the contents of the Makefile to only expect a single book.xml: # # $FreeBSD$ # # Build the FreeBSD Porter's Handbook. # MAINTAINER=doc@FreeBSD.org DOC?= book FORMATS?= html-split INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= # XML content SRCS= book.xml # Images from the cross-document image library IMAGES_LIB+= callouts/1.png IMAGES_LIB+= callouts/2.png IMAGES_LIB+= callouts/3.png IMAGES_LIB+= callouts/4.png IMAGES_LIB+= callouts/5.png IMAGES_LIB+= callouts/6.png IMAGES_LIB+= callouts/7.png IMAGES_LIB+= callouts/8.png IMAGES_LIB+= callouts/9.png IMAGES_LIB+= callouts/10.png IMAGES_LIB+= callouts/11.png IMAGES_LIB+= callouts/12.png IMAGES_LIB+= callouts/13.png IMAGES_LIB+= callouts/14.png IMAGES_LIB+= callouts/15.png IMAGES_LIB+= callouts/16.png IMAGES_LIB+= callouts/17.png IMAGES_LIB+= callouts/18.png IMAGES_LIB+= callouts/19.png IMAGES_LIB+= callouts/20.png IMAGES_LIB+= callouts/21.png URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. SYMLINKS= ${DESTDIR} index.html handbook.html .include "${DOC_PREFIX}/share/mk/doc.project.mk" Now the document structure is ready for the translator to begin translating with make po. Creating a French Translation of the <acronym>PGP</acronym> Keys Article Create a new French translation of the PGP Keys article. The original is an article in ~/doc/en_US.ISO8859-1/articles/pgpkeys/. The French language article directory ~/doc/fr_FR.ISO8859-1/articles/ already exists, so only a new subdirectory for the PGP Keys article is needed: % cd ~/doc/fr_FR.ISO8859-1/articles/ % svn mkdir pgpkeys A pgpkeys Copy the Makefile from the original article: % cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys % svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile . A Makefile Check the contents of the Makefile. Because this is a simple article, in this case the Makefile can be used unchanged. The $FreeBSD...$ version string on the third line will be replaced by the version control system when this file is committed. # # $FreeBSD$ # # Article: PGP Keys DOC?= article FORMATS?= html WITH_ARTICLE_TOC?= YES INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= SRCS= article.xml # To build with just key fingerprints, set FINGERPRINTS_ONLY. URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" With the document structure complete, the PO file can be created with make po. Translating The gettext system greatly reduces the number of things that must be tracked by a translator. Strings to be translated are extracted from the original document into a PO file. Then a PO editor is used to enter the translated versions of each string. The FreeBSD PO translation system does not overwrite PO files, so the extraction step can be run at any time to update the PO file. A PO editor is used to edit the file. editors/poedit is shown in these examples because it is simple and has minimal requirements. Other PO editors offer features to make the job of translating easier. The Ports Collection offers several of these editors, including devel/gtranslator. It is important to preserve the PO file. It contains all of the work that translators have done. Translating the Porter's Handbook to Spanish Enter Spanish translations of the contents of the Porter's Handbook. Change to the Spanish Porter's Handbook directory and update the PO file. The generated PO file is called es_ES.po as shown in . % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook % make po Enter translations using a PO editor: % poedit es_ES.po Tips for Translators Preserving <acronym>XML</acronym> Tags Preserve XML tags that are shown in the English original. Preserving <acronym>XML</acronym> Tags English original: If acronymNTPacronym is not being used Spanish translation: Si acronymNTPacronym no se utiliza Preserving Spaces Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also. Verbatim Tags The contents of some tags should be copied verbatim, not translated: citerefentry command filename literal manvolnum orgname package programlisting prompt refentrytitle screen userinput varname + + <literal>$FreeBSD$</literal> + Strings + + The $FreeBSD$ version strings used in + files require special handling. In examples like + , these + strings are not meant to be expanded. The English documents + use &dollar; entities to avoid + including actual literal dollar signs in the file: + + &dollar;FreeBSD&dollar; + + The &dollar; entities are not seen + as dollar signs by the version control system and so the + string is not expanded into a version string. + + When a PO file is created, the + &dollar; entities used in examples are + replaced with actual dollar signs. The resulting literal + $FreeBSD$ string will be + wrongly expanded by the version control system when the file + is committed. + + The same technique as used in the English documents can be + used in the translation. The &dollar; + is used to replace the dollar sign in the translation entered + into the PO editor: + + &dollar;FreeBSD&dollar; + + Building a Translated Document A translated version of the original document can be created at any time. Any untranslated portions of the original will be included in English in the resulting document. Most PO editors have an indicator that shows how much of the translation has been completed. This makes it easy for the translator to see when enough strings have been translated to make building the final document worthwhile. Building the Spanish Porter's Handbook Build and preview the Spanish version of the Porter's Handbook that was created in an earlier example. Build the translated document. Because the original is a book, the generated document is book.xml. % cd ~/doc/es_ES.ISO8859-1/books/porters-handbook % make tran Render the translated book.xml to HTML and view it with Firefox. This is the same procedure used with the English version of the documents, and other FORMATS can be used here in the same way. See . % make FORMATS=html % firefox book.html Submitting the New Translation Prepare the new translation files for submission. This example shows a new Spanish translation of the NanoBSD article in ~/doc/es_ES.ISO8859-1/articles/nanobsd. The PO file must contain a FreeBSD version string comment on the first line: - #$FreeBSD$ + #$FreeBSD$ The Makefile, the PO file, and the generated XML translation must all be added to version control: % cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/ % ls Makefile article.xml es_ES.po % svn add Makefile article.xml es_ES.po A Makefile A article.xml A es_ES.po These files must also have the Subversion svn:keywords property set to - FreeBSD=%H: + FreeBSD=%H so + $FreeBSD$ strings are expanded into + the path, revision, date, and author when committed: % svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po property 'svn:keywords' set on 'Makefile' property 'svn:keywords' set on 'article.xml' property 'svn:keywords' set on 'es_ES.po' A diff of these new files is created from the ~/doc/ base directory so the full path is shown with the filenames. This helps committers identify the target language directory. % cd ~/doc svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff The diff file is now ready for attachment to a documentation bug report or code review. Writing Style Tips Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: be clear, be complete, and be concise. These goals can conflict with each other. Good writing consists of a balance between them. - Be Clear + Ben duidelijk Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts. Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate. Keep explanations as short, simple, and clear as possible. Avoid empty phrases like in order to, which usually just means to. Avoid potentially patronizing words like basically. Avoid Latin terms like i.e. or cf., which may be unknown outside of academic or scientific groups. Write in a formal style. Avoid addressing the reader as you. For example, say copy the file to /tmp rather than you can copy the file to /tmp. Give clear, correct, tested examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like but really it should never be done that way. Bad examples are worse than no examples. Give good examples, because even when warned not to use the example as shown, the reader will usually just use the example as shown. Avoid weasel words like should, might, try, or could. These words imply that the speaker is unsure of the facts, and create doubt in the reader. Similarly, give instructions as imperative commands: not you should do this, but merely do this. - Be Complete + Ben compleet Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them. Be Concise While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a quick start section that describes the most common situation, followed by an in-depth reference section. - Guidelines + Richtlijnen To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow. Use American English Spelling There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. color, not colour, rationalize, not rationalise, and so on. The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. will have to use American English. Do not use contractions Do not use contractions. Always spell the phrase out in full. Don't use contractions is wrong. Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators. Use the serial comma In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word and. - For example: + Bijvoorbeeld:
This is a list of one, two and three items.
Is this a list of three items, one, two, and three, or a list of two items, one and two and three? It is better to be explicit and include a serial comma:
This is a list of one, two, and three items.
Avoid redundant phrases Do not use redundant phrases. In particular, the command, the file, and man command are often redundant. For example, commands: Wrong: Use the svn command to update sources. Right: Use svn to update sources. Filenames: Wrong: … in the filename /etc/rc.local… Right: … in /etc/rc.local… Manual page references (the second example uses citerefentry with the &man.csh.1; entity):. Wrong: See man csh for more information. Right: See csh1. Two spaces between sentences Always use two spaces between sentences, as it improves readability and eases use of tools such as Emacs. A period and spaces followed by a capital letter does not always mark a new sentence, especially in names. Jordan K. Hubbard is a good example. It has a capital H following a period and a space, and is certainly not a new sentence. For more information about writing style, see Elements of Style, by William Strunk. Style Guide To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions. Letter Case Tags are entered in lower case, para, not PARA. Text that appears in SGML contexts is generally written in upper case, <!ENTITY…>, and <!DOCTYPE…>, not <!entity…> and <!doctype…>. Acronyms Acronyms should be defined the first time they appear in a document, as in: Network Time Protocol (NTP). After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document. All acronyms should be enclosed in acronym tags. Indentation The first line in each file starts with no indentation, regardless of the indentation level of the file which might contain the current file. Opening tags increase the indentation level by two spaces. Closing tags decrease the indentation level by two spaces. Blocks of eight spaces at the start of a line should be replaced with a tab. Do not use spaces in front of tabs, and do not add extraneous whitespace at the end of a line. Content within elements should be indented by two spaces if the content runs over more than one line. For example, the source for this section looks like this: chapter title...title sect1 title...title sect2 titleIndentationtitle paraThe first line in each file starts with no indentation, emphasisregardlessemphasis of the indentation level of the file which might contain the current file.para ... sect2 sect1 chapter Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags: paraSee the link linkend="gmirror-troubleshooting"Troubleshootinglink section if there are problems booting. Powering down and disconnecting the original filenameada0filename disk will allow it to be kept as an offline backup.para paraIt is also possible to journal the boot disk of a &os; system. Refer to the article link xlink:href="&url.articles.gjournal-desktop;"Implementing UFS Journaling on a Desktop PClink for detailed instructions.para When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the systemitem element has been moved to the next line to avoid wrapping and indenting: paraWith file flags, even systemitem class="username"rootsystemitem can be prevented from removing or altering files.para Configurations to help various text editors conform to these guidelines can be found in . Tag Style Tag Spacing Tags that start at the same indent as a previous tag should be separated by a blank line, and those that are not at the same indent as a previous tag should not: article lang='en' articleinfo titleNIStitle pubdateOctober 1999pubdate abstract para... ... ...para abstract articleinfo sect1 title...title para...para sect1 sect1 title...title para...para sect1 article Separating Tags Tags like itemizedlist which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves. Tags like para and term do not need other tags to contain normal character data, and their contents begin immediately after the tag, on the same line. The same applies to when these two types of tags close. This leads to an obvious problem when mixing these tags. When a starting tag which cannot contain character data directly follows a tag of the type that requires other tags within it to use character data, they are on separate lines. The second tag should be properly indented. When a tag which can contain character data closes directly after a tag which cannot contain character data closes, they co-exist on the same line. Whitespace Changes Do not commit changes to content at the same time as changes to formatting. When content and whitespace changes are kept separate, translation teams can easily see whether a change was content that must be translated or only whitespace. For example, if two sentences have been added to a paragraph so that the line lengths now go over 80 columns, first commit the change with the too-long lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, indicate that this is a whitespace-only change that can be ignored by translators. Non-Breaking Space Avoid line breaks in places where they look ugly or make it difficult to follow a sentence. Line breaks depend on the width of the chosen output medium. In particular, viewing the HTML documentation with a text browser can lead to badly formatted paragraphs like the next one: Data capacity ranges from 40 MB to 15 GB. Hardware compression … The general entity &nbsp; prohibits line breaks between parts belonging together. Use non-breaking spaces in the following places: between numbers and units: 57600&nbsp;bps between program names and version numbers: &os;&nbsp;9.2 between multiword names (use with caution when applying this to more than 3-4 word names like The FreeBSD Brazilian Portuguese Documentation Project): Word List This list of words shows the correct spelling and capitalization when used in FreeBSD documentation. If a word is not on this list, ask about it on the FreeBSD documentation project mailing list. - Word + Woord XML Code Notes - CD-ROM + CD-ROM acronymCD-ROMacronym DoS (Denial of Service) acronymDoSacronym - email + email file system IPsec - Internet + Internet manual page mail server name server Ports Collection read-only Soft Updates stdin varnamestdinvarname stdout varnamestdoutvarname stderr varnamestderrvarname - Subversion + Subversion applicationSubversionapplication Do not refer to the Subversion application as SVN in upper case. To refer to the command, use commandsvncommand. - UNIX + UNIX &unix; - web server + web server Editor Configuration Adjusting text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines. - <application>Vim</application> + <application>Vim</application> Install from editors/vim or editors/vim-lite. - Configuration + Configuratie Edit ~/.vimrc, adding these lines: - if has("autocmd") + if has("autocmd") au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML() au BufNewFile,BufRead *.[1-9] call ShowSpecial() endif " has(autocmd) function Set_Highlights() "match ExtraWhitespace /^\s* \s*\|\s\+$/ highlight default link OverLength ErrorMsg match OverLength /\%71v.\+/ return 0 endfunction function ShowSpecial() setlocal list listchars=tab:>>,trail:*,eol:$ hi def link nontext ErrorMsg return 0 endfunction " ShowSpecial() function Set_SGML() setlocal number syn match sgmlSpecial "&[^;]*;" setlocal syntax=sgml setlocal filetype=xml setlocal shiftwidth=2 setlocal textwidth=70 setlocal tabstop=8 setlocal softtabstop=2 setlocal formatprg="fmt -p" setlocal autoindent setlocal smartindent " Rewrap paragraphs noremap P gqj " Replace spaces with tabs noremap T :s/ /\t/<CR> call ShowSpecial() call Set_Highlights() return 0 endfunction " Set_SGML() - Use + Gebruik Press P to reformat paragraphs or text that has been selected in Visual mode. Press T to replace groups of eight spaces with a tab. - <application>Emacs</application> + <application>Emacs</application> Install from editors/emacs or editors/xemacs. Edit ~/.emacs, adding this line: - (add-hook 'nxml-mode-hook 'turn-on-auto-fill) + (add-hook 'nxml-mode-hook 'turn-on-auto-fill) - <application>nano</application> + <application>nano</application> Install from editors/nano or editors/nano-devel. - Configuration + Configuratie Copy the sample XML syntax highlight file to the user's home directory: - % cp /usr/local/share/nano/xml.nanorc ~/.nanorc + % cp /usr/local/share/nano/xml.nanorc ~/.nanorc Add these lines to the new ~/.nanorc. syntax "xml" "\.([jrs]html?|xml|xslt?)$" # trailing whitespace color ,blue "[[:space:]]+$" # multiples of eight spaces at the start a line # (after zero or more tabs) should be a tab color ,blue "^([TAB]*[ ]{8})+" # tabs after spaces color ,yellow "( )+TAB" # highlight indents that have an odd number of spaces color ,red "^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}" # lines longer than 70 characters color ,yellow "^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$" Process the file to create embedded tabs: - % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc + % perl -i'' -pe 's/TAB/\t/g' ~/.nanorc - Use + Gebruik Specify additional helpful options when running the editor: - % nano -AKipwz -r 70 -T8 chapter.xml + % nano -AKipwz -r 70 -T8 chapter.xml Users of csh1 can define an alias in ~/.cshrc to automate these options: - alias nano "nano -AKipwz -r 70 -T8" + alias nano "nano -AKipwz -r 70 -T8" After the alias is defined, the options will be added automatically: - % nano chapter.xml + % nano chapter.xml - See Also + Zie ook This document is deliberately not an exhaustive discussion of XML, 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 + Het FreeBSD Documentatieproject The FreeBSD Documentation Project web pages The FreeBSD Handbook - XML + XML W3C's XML page SGML/XML web page - HTML + HTML The World Wide Web Consortium The HTML 4.0 specification - DocBook + 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 Voorbeelden These examples are not exhaustive—they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of DocBook markup, examine the XML source for this and other documents available in the Subversion doc repository, or available online starting at http://svnweb.FreeBSD.org/doc/. - DocBook <tag>book</tag> + DocBook <tag>book</tag> - DocBook <tag>book</tag> + DocBook <tag>book</tag> <!DOCTYPE book PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> book xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" info titleAn Example Booktitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailfoo@example.comemail address affiliation author copyright year2000year holderCopyright string hereholder copyright abstract paraIf your book has an abstract then it should go here.para abstract info preface titlePrefacetitle paraYour book may have a preface, in which case it should be placed here.para preface chapter titleMy First Chaptertitle paraThis is the first chapter in my book.para sect1 titleMy First Sectiontitle paraThis is the first section in my book.para sect1 chapter book - DocBook <tag>article</tag> + DocBook <tag>article</tag> - DocBook <tag>article</tag> + DocBook <tag>article</tag> <!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN" "http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd"> article xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en" info titleAn Example Articletitle author personname firstnameYour first namefirstname surnameYour surnamesurname personname affiliation address emailfoo@example.comemail address affiliation author copyright year2000year holderCopyright string hereholder copyright abstract paraIf your article has an abstract then it should go here.para abstract info sect1 titleMy First Sectiontitle paraThis is the first section in my article.para sect2 titleMy First Sub-Sectiontitle paraThis is the first sub-section in my article.para sect2 sect1 article Index: head/nl_NL.ISO8859-1/books/fdp-primer/nl_NL.po =================================================================== --- head/nl_NL.ISO8859-1/books/fdp-primer/nl_NL.po (revision 47758) +++ head/nl_NL.ISO8859-1/books/fdp-primer/nl_NL.po (revision 47759) @@ -1,9481 +1,9504 @@ # $FreeBSD$ msgid "" msgstr "" "Project-Id-Version: FreeBSD Documentation Project\n" -"POT-Creation-Date: 2015-10-27 22:24+0100\n" -"PO-Revision-Date: 2015-10-27 23:08+0100\n" +"POT-Creation-Date: 2015-11-03 00:04+0100\n" +"PO-Revision-Date: 2015-11-08 22:52+0100\n" "Last-Translator: René Ladan \n" "Language-Team: Dutch \n" "Language: nl_NL\n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=UTF-8\n" "Content-Transfer-Encoding: 8bit\n" "X-Generator: Poedit 1.8.4\n" #. Put one translator per line, in the form NAME , YEAR1, YEAR2 msgctxt "_" msgid "translator-credits" msgstr "vertaling" #. (itstool) path: info/title #: book.translate.xml:62 msgid "FreeBSD Documentation Project Primer for New Contributors" msgstr "Overzicht van het FreeBSD Documentatieproject voor nieuwe bijdragers" #. (itstool) path: info/author #: book.translate.xml:66 msgid "The FreeBSD Documentation Project" -msgstr "Het FreeBSD Documentatieroject" +msgstr "Het FreeBSD Documentatieproject" #. (itstool) path: info/copyright #: book.translate.xml:68 msgid "1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 DocEng" msgstr "1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 DocEng" #. (itstool) path: info/pubdate #. (itstool) path: info/releaseinfo #: book.translate.xml:89 book.translate.xml:91 msgid "$FreeBSD$" msgstr "$FreeBSD$" #. (itstool) path: legalnotice/title #: book.translate.xml:95 msgid "Copyright" msgstr "Copyright" #. (itstool) path: legalnotice/para #: book.translate.xml:97 msgid "Redistribution and use in source (XML DocBook) and 'compiled' forms (XML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:" msgstr "Herdistributiie en gebruik in bron- (XML DocBook) en 'gecompileerde' vormen (XML, HTML, PDF, PostScript, RTF enzovoorts) met of zonder aanpassingen, is toegestaan gegeven dat aan de volgende voorwaarden is voldaan:" #. (itstool) path: listitem/para #: book.translate.xml:104 msgid "Redistributions of source code (XML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified." msgstr "Herdistributies van broncode (XML DocBook) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer onveranderd als de eerste regels van dit bestand behouden." #. (itstool) path: listitem/para #: book.translate.xml:110 msgid "Redistributions in compiled form (transformed to other DTDs, converted to PDF, PostScript, RTF and other formats) must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution." msgstr "Herdistributies in gecompileerde vorm (getransformeerd naar andere DTDs, omgezet naar PDF, PostScript, RTF en andere formaten) moeten de bovenstaande copyright-melding, deze lijst van voorwaarden en de volgende disclaimer in de documentatie en/of andere materialen geleverd met de distributie herproduceren." #. (itstool) path: important/para #: book.translate.xml:119 msgid "" "THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT " "LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." msgstr "" "THIS DOCUMENTATION IS PROVIDED BY THE FREEBSD DOCUMENTATION PROJECT \"AS IS\" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FREEBSD DOCUMENTATION PROJECT BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT " "LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE." #. (itstool) path: abstract/para #: book.translate.xml:136 msgid "Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable, and we appreciate it." msgstr "Dank u dat u deel bent geworden van het FreeBSD Documentatieproject. Uw bijdrage is zeer waardevol, en we stellen het op prijs." #. (itstool) path: abstract/para #: book.translate.xml:140 msgid "This primer covers details needed to start contributing to the FreeBSD Documentation Project, or FDP, including tools, software, and the philosophy behind the Documentation Project." msgstr "Deze handleidng behandelt details die nodig zijn om te beginnen met bij te dragen aan het FreeBSD Documentatieproject, of FDP, inclusief gereedschappen, softare en de gedachten achter het Documentatieproject." #. (itstool) path: abstract/para #: book.translate.xml:146 msgid "This is a work in progress. Corrections and additions are always welcome." msgstr "Dit is werk in uitvoering. Correcties en aanvullingen zijn altijd welkom." #. (itstool) path: preface/title #: book.translate.xml:152 msgid "Preface" msgstr "Inleiding" #. (itstool) path: sect1/title #: book.translate.xml:155 msgid "Shell Prompts" msgstr "Shellprompts" #. (itstool) path: sect1/para #: book.translate.xml:157 msgid "This table shows the default system prompt and superuser prompt. The examples use these prompts to indicate which type of user is running the example." msgstr "Deze tabel laat de standaard systeemprompt en de prompt van de supergebruiker zien. Deze voorbeelden gebruiken deze prompts om aan te geven welk soort gebruiker het voorbeeld draait." #. (itstool) path: row/entry #: book.translate.xml:165 msgid "User" msgstr "Gebruiker" #. (itstool) path: row/entry #: book.translate.xml:166 msgid "Prompt" msgstr "Prompt" #. (itstool) path: row/entry #: book.translate.xml:172 msgid "Normal user" msgstr "Gewone gebruiker" #. (itstool) path: row/entry #: book.translate.xml:173 book.translate.xml:4289 msgid "%" msgstr "%" #. (itstool) path: row/entry #: book.translate.xml:177 msgid "root" msgstr "root" #. (itstool) path: row/entry #: book.translate.xml:178 book.translate.xml:4282 msgid "#" msgstr "#" #. (itstool) path: sect1/title #: book.translate.xml:186 msgid "Typographic Conventions" msgstr "Typografische aannames" #. (itstool) path: sect1/para #: book.translate.xml:188 msgid "This table describes the typographic conventions used in this book." msgstr "Deze tabel beschrijft de typografische aannames die in dit boek gebruikt worden." #. (itstool) path: row/entry #: book.translate.xml:195 msgid "Meaning" msgstr "Betekenis" #. (itstool) path: row/entry #. (itstool) path: sect2/title #. (itstool) path: appendix/title -#: book.translate.xml:196 book.translate.xml:4789 book.translate.xml:8958 +#: book.translate.xml:196 book.translate.xml:4789 book.translate.xml:8992 msgid "Examples" msgstr "Voorbeelden" #. (itstool) path: row/entry #: book.translate.xml:202 msgid "The names of commands." msgstr "De naam van commando's." #. (itstool) path: row/entry #: book.translate.xml:203 msgid "Use ls -l to list all files." msgstr "Gebruik ls -l voor een lijst van alle bestanden." #. (itstool) path: row/entry #: book.translate.xml:208 msgid "The names of files." msgstr "De namen van bestanden." #. (itstool) path: row/entry #: book.translate.xml:209 msgid "Edit .login." msgstr "Bewerk .login." #. (itstool) path: row/entry #: book.translate.xml:213 msgid "On-screen computer output." msgstr "Uitvoer op het computerscherm." #. (itstool) path: entry/screen #: book.translate.xml:214 #, no-wrap msgid "You have mail." msgstr "You have mail." #. (itstool) path: row/entry #: book.translate.xml:218 msgid "What the user types, contrasted with on-screen computer output." msgstr "Wat de gebruiker typt, in contrast met uitvoer op het computerscherm." #. (itstool) path: entry/screen #: book.translate.xml:221 #, no-wrap msgid "" "% date +\"The time is %H:%M\"\n" "The time is 09:18" msgstr "" "% date +\"De tijd is %H:%M\"\n" "De tijd is 09:18" #. (itstool) path: row/entry #: book.translate.xml:226 msgid "Manual page references." msgstr "Verwijzing naar handleidingspagina's." #. (itstool) path: row/entry #: book.translate.xml:227 msgid "Use su1 to change user identity." msgstr "Gebruik su1 om van gebruikersidentiteit te veranderen." #. (itstool) path: row/entry #: book.translate.xml:231 msgid "User and group names." msgstr "Gebruiker- en groepnamen." #. (itstool) path: row/entry #: book.translate.xml:232 msgid "Only root can do this." msgstr "Alleen root kan dit doen." #. (itstool) path: row/entry #: book.translate.xml:237 msgid "Emphasis." msgstr "Nadruk." #. (itstool) path: row/entry #: book.translate.xml:238 msgid "The user must do this." msgstr "De gebruiker moet dit doen." #. (itstool) path: row/entry #: book.translate.xml:243 msgid "Text that the user is expected to replace with the actual text." msgstr "Tekst die de gebruiker door de eigenlijke tekst dient te vervangen." #. (itstool) path: row/entry #: book.translate.xml:246 msgid "To search for a keyword in the manual pages, type man -k keyword" msgstr "Gebruik man -ksleutelwoord om naar een sleutelwoord in handleidingspagina's te zoeken." #. (itstool) path: row/entry #: book.translate.xml:252 msgid "Environment variables." msgstr "Omgevingsvariabelen." #. (itstool) path: row/entry #: book.translate.xml:253 msgid "$HOME is set to the user's home directory." -msgstr "" +msgstr "$HOME is ingesteld op de thuismap van de gebruiker." #. (itstool) path: sect1/title #: book.translate.xml:262 msgid "Notes, Tips, Important Information, Warnings, and Examples" -msgstr "" +msgstr "Opmerkingen, tips, belangrijke informatie, waarschuwingen en voorbeelden" #. (itstool) path: sect1/para #: book.translate.xml:265 msgid "Notes, warnings, and examples appear within the text." -msgstr "" +msgstr "Opmerkingen, waarschuwingen en voorbeelden verschijnen in de tekst." #. (itstool) path: note/para #: book.translate.xml:269 msgid "Notes are represented like this, and contain information to take note of, as it may affect what the user does." -msgstr "" +msgstr "Opmerkingen worden zo weergegeven en bevatten informatie waarvan kennis genomen moet worden, aangezien ze kunne beïnvloeden wat de gebruiker doet." #. (itstool) path: tip/para #: book.translate.xml:275 msgid "Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something." -msgstr "" +msgstr "Tips worden zo weergegeven en bevatten behulpzame informatie voor de gebruiker, zoals een eenvoudigere manier laten zien om iets te doen." #. (itstool) path: important/para #: book.translate.xml:281 msgid "Important information is represented like this. Typically, these show extra steps the user may need to take." -msgstr "" +msgstr "Belangrijke informatie wordt zo weergegeven. Typisch laat het extra stappen zien die de gebruiker kan moeten nemen." #. (itstool) path: warning/para #: book.translate.xml:287 msgid "Warnings are represented like this, and contain information warning about possible damage if the instructions are not followed. This damage may be physical, to the hardware or the user, or it may be non-physical, such as the inadvertent deletion of important files." -msgstr "" +msgstr "Waarschuwingen worden zo weergegeven en bevatten informatie die waarschuuwt over mogelijke schade indien de instructies niet worden opgevolgd. Deze schade kan fysiek zijn, aan de hardware of de gebruiker, of het kan niet-fysiek zijn, zoals het onbedoeld verwijderen van belangrijke bestanden." #. (itstool) path: example/title #: book.translate.xml:295 msgid "A Sample Example" -msgstr "" +msgstr "Een voorbeeld van een voorbeeld" #. (itstool) path: example/para #: book.translate.xml:297 msgid "Examples are represented like this, and typically contain examples showing a walkthrough, or the results of a particular action." -msgstr "" +msgstr "Voorbeelden worden zo weergegeven en bevatten typisch een voorbeeld dat een stappenplan of het resultaat van een bepaalde actie laat zien." #. (itstool) path: sect1/title #: book.translate.xml:304 msgid "Acknowledgments" -msgstr "" +msgstr "Erkenningen" #. (itstool) path: sect1/para #: book.translate.xml:306 msgid "My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, and Christopher Maden, who took the time to read early drafts of this document and offer many valuable comments and criticisms." -msgstr "" +msgstr "Veel dank aan Sue Blake, Patrick Durusau, Jon Hamilton, Peter Flynn, en Christopher Maden. die te tijd hebben genomen om vroege kladversies van dit document te lezen en veel waardevol commentaar en kritiek hebben geboden." #. (itstool) path: chapter/title #. (itstool) path: sect1/title #: book.translate.xml:346 book.translate.xml:1970 msgid "Overview" -msgstr "" +msgstr "Overzicht" #. (itstool) path: chapter/para #: book.translate.xml:348 msgid "Welcome to the FreeBSD Documentation Project (FDP). Quality documentation is crucial to the success of FreeBSD, and we value your contributions very highly." -msgstr "" +msgstr "Welkom bij het FreeBSD Documentatieproject (FDP). Kwaliteitsdocumentatie is cruciaal voor het succes van FreeBSD en we stellen uw bijdragen zeer op prijs." #. (itstool) path: chapter/para #: book.translate.xml:353 msgid "This document describes how the FDP is organized, how to write and submit documentation, and how to effectively use the available tools." -msgstr "" +msgstr "Dit document beschrijft hoe het FDP is georganiseerd, hoe documentatie te schrijven en op te sturen, en hoe effectief van de beschikbare gereedschappen gebruik te maken." #. (itstool) path: chapter/para #: book.translate.xml:357 msgid "Everyone is welcome to contribute to the FDP. Willingness to contribute is the only membership requirement." -msgstr "" +msgstr "Iedereen is welkom om aan het FDP bij te dragen. Bereidheid om bij te dragen is de enige eis voor lidmaatschap." #. (itstool) path: chapter/para #: book.translate.xml:361 -#, fuzzy msgid "This primer shows how to:" -msgstr "Hoe wordt BSD ontwikkeld en bijgewerkt?" +msgstr "Deze handleiding laat zien hoe:" #. (itstool) path: listitem/para #: book.translate.xml:365 msgid "Identify which parts of FreeBSD are maintained by the FDP." -msgstr "" +msgstr "Te identificeren welke gedeelten van FreeBSD door het FDP worden onderhouden." #. (itstool) path: listitem/para #: book.translate.xml:370 msgid "Install the required documentation tools and files." -msgstr "" +msgstr "De benodigde gereedschappen en bestanden te installeren." #. (itstool) path: listitem/para #: book.translate.xml:374 msgid "Make changes to the documentation." -msgstr "" +msgstr "Veranderingen aan de documentatie te maken." #. (itstool) path: listitem/para #: book.translate.xml:378 msgid "Submit changes back for review and inclusion in the FreeBSD documentation." -msgstr "" +msgstr "Veranderingen terug te sturen voor bespreking en opname in de documentatie van FreeBSD." #. (itstool) path: sect1/title #: book.translate.xml:384 -#, fuzzy msgid "The FreeBSD Documentation Set" -msgstr "FreeBSD is een geregistreerd handelsmerk van de FreeBSD Foundation." +msgstr "De FreeBSD Documentatieverzameling " #. (itstool) path: sect1/para #: book.translate.xml:386 msgid "The FDP is responsible for four categories of FreeBSD documentation." -msgstr "" +msgstr "Het FDP is verantwoordelijk voor vier categoriën van documentatie van FreeBSD." #. (itstool) path: listitem/para #: book.translate.xml:391 msgid "Handbook: The Handbook is the comprehensive online resource and reference for FreeBSD users." -msgstr "" +msgstr "Handboek: Het Handboek is de uitgebreide online bron en referentie voor gebruikers van FreeBSD." #. (itstool) path: listitem/para #: book.translate.xml:397 msgid "FAQ: The FAQ uses a short question and answer format to address questions that are frequently asked on the various mailing lists and forums devoted to FreeBSD. This format does not permit long and comprehensive answers." -msgstr "" +msgstr "FAQ: De FAQ gebruikt een kort vraag-en-antwoord-formaat om vragen te bespreken die vaak worden gesteld op de verschillende mailinglijsten en fora gewijd aan FreeBSD." #. (itstool) path: listitem/para #: book.translate.xml:405 msgid "Manual pages: The English language system manual pages are usually not written by the FDP, as they are part of the base system. However, the FDP can reword parts of existing manual pages to make them clearer or to correct inaccuracies." -msgstr "" +msgstr "Handleidingspagina's: De Engelstalige handleidingspagina's van het systeem worden gewoonlijk niet geschreven door het FDP, aangezien ze onderdeel zijn van het basissysteem zijn. Het FDP kan echter delen van bestaande handleidingspagina's hershrijven om ze te verduidelijken of om onjuistheden te corrigeren." #. (itstool) path: listitem/para #: book.translate.xml:414 msgid "Web site: This is the main FreeBSD presence on the web, visible at http://www.FreeBSD.org/ and many mirrors around the world. The web site is typically a new user's first exposure to FreeBSD." -msgstr "" +msgstr "Website: Dit is de voornaamste aanwezigheid van FreeBSD op het web, zichtbaar op http://www.FreeBSD.org/ en vele spiegels over de wereld. De website is typisch de eerste blootstelling van een nieuwe gebruiker aan FreeBSD. " #. (itstool) path: sect1/para #: book.translate.xml:421 msgid "Translation teams are responsible for translating the Handbook and web site into different languages. Manual pages are not translated at present." -msgstr "" +msgstr "Vertaalteams zijn verantwoordelijk voor de vertaling van het Handboek en de website in verschillende talen. Handleidingpagina's worden momenteel niet vertaald." #. (itstool) path: sect1/para #: book.translate.xml:425 msgid "Documentation source for the FreeBSD web site, Handbook, and FAQ is available in the documentation repository at https://svn.FreeBSD.org/doc/." -msgstr "" +msgstr "Bronnen van de documentatie voor de website, het Handboek en de FAQ van FreeBSD zijn beschikbaar in het documentatie-reservoir op https://svn.FreeBSD.org/doc/." #. (itstool) path: sect1/para #: book.translate.xml:430 msgid "Source for manual pages is available in a separate source repository located at https://svn.FreeBSD.org/base/." -msgstr "" +msgstr "Bronnen voor handleidingspagina's zijn beschikbaar in een apart broncode-reservoir op https://svn.FreeBSD.org/base/." #. (itstool) path: sect1/para #: book.translate.xml:434 msgid "Documentation commit messages are visible with svn log. Commit messages are also archived at http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all." -msgstr "" +msgstr "Commit-berichten over de documentatie zijn zichtbaar met svn log. Commit-berichten zijn ook gearchiveerd op http://lists.FreeBSD.org/mailman/listinfo/svn-doc-all." #. (itstool) path: sect1/para #: book.translate.xml:438 msgid "Web frontends to both of these repositories are available at and ." -msgstr "" +msgstr "Web-frontends voor deze beide reservoirs zijn beschikbaar op en ." #. (itstool) path: sect1/para #: book.translate.xml:440 msgid "Many people have written tutorials or how-to articles about FreeBSD. Some are stored as part of the FDP files. In other cases, the author has decided to keep the documentation separate. The FDP endeavors to provide links to as much of this external documentation as possible." -msgstr "" +msgstr "Vele mensen hebben tutorials of stappenplannen over FreeBSD geschreven. Sommigen worden opgeslagen als deel van het FDP. In andere gevallen heeft de auteur besloten om de documentatie apart te houden. Het FDP tracht om verwijzigingen naar zoveel mogelijk van deze externe documentatie te bieden." #. (itstool) path: sect1/title #: book.translate.xml:449 book.translate.xml:7257 msgid "Quick Start" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:451 msgid "" "Some preparatory steps must be taken before editing the FreeBSD documentation. First, subscribe to the FreeBSD documentation project mailing list. Some team members also interact on the #bsddocs IRC channel on EFnet. These people can help " "with questions or problems involving the documentation." msgstr "" #. (itstool) path: step/para #: book.translate.xml:461 msgid "Install the textproc/docproj package or port. This meta-port installs all of the software needed to edit and build FreeBSD documentation." msgstr "" #. (itstool) path: step/para #: book.translate.xml:468 msgid "Install a local working copy of the documentation from the FreeBSD repository in ~/doc (see )." msgstr "" #. (itstool) path: step/screen #. (itstool) path: sect1/screen #: book.translate.xml:473 book.translate.xml:798 #, no-wrap msgid "% svn checkout https://svn.FreeBSD.org/doc/head ~/doc" -msgstr "" +msgstr "% svn checkout https://svn.FreeBSD.org/doc/head ~/doc" #. (itstool) path: step/para #: book.translate.xml:477 msgid "Configure the text editor:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:481 msgid "Word wrap set to 70 characters." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:485 msgid "Tab stops set to 2." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:489 msgid "Replace each group of 8 leading spaces with a single tab." msgstr "" #. (itstool) path: step/para #: book.translate.xml:494 msgid "Specific editor configurations are listed in ." msgstr "" #. (itstool) path: step/para #: book.translate.xml:499 msgid "Update the local working copy:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:501 #, no-wrap msgid "% svn up ~/doc" -msgstr "" +msgstr "% svn up ~/doc" #. (itstool) path: step/para #: book.translate.xml:505 msgid "Edit the documentation files that require changes. If a file needs major changes, consult the mailing list for input." msgstr "" #. (itstool) path: step/para #: book.translate.xml:509 msgid "References to tag and entity usage can be found in and ." msgstr "" #. (itstool) path: step/para #: book.translate.xml:515 msgid "After editing, check for problems by running:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:517 #, no-wrap msgid "% igor -R filename.xml | less -RS" -msgstr "" +msgstr "% igor -R bestandsnaam.xml | less -RS" #. (itstool) path: step/para #: book.translate.xml:519 msgid "Review the output and edit the file to fix any problems shown, then rerun the command to find any remaining problems. Repeat until all of the errors are resolved." msgstr "" #. (itstool) path: step/para #: book.translate.xml:526 msgid "Always build-test changes before submitting them. Running make in the top-level directory of the documentation being edited will generate that documentation in split HTML format. For example, to build the English version of the Handbook in HTML, run make in the en_US.ISO8859-1/books/handbook/ directory." msgstr "" #. (itstool) path: step/para #: book.translate.xml:537 msgid "When changes are complete and tested, generate a diff file:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:540 #, no-wrap msgid "" "% cd ~/doc\n" "% svn diff > bsdinstall.diff.txt" msgstr "" +"% cd ~/doc\n" +"% svn diff > bsdinstall.diff.txt" #. (itstool) path: step/para #: book.translate.xml:543 msgid "Give the diff file a descriptive name. In the example above, changes have been made to the bsdinstall portion of the Handbook." msgstr "" #. (itstool) path: step/para #: book.translate.xml:550 msgid "" "Submit the diff file using the web-based Problem Report system. If using the web form, enter a synopsis of [patch] short description of problem. Select the category docs and the class doc-bug. In the body of the message, enter a short description of the changes " "and any important details about them. Use the [ Browse... ] button to attach the diff file." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:600 msgid "Tools" -msgstr "" +msgstr "Gereedschappen" #. (itstool) path: chapter/para #: book.translate.xml:602 msgid "Several software tools are used to manage the FreeBSD documentation and render it to different output formats. Some of these tools are required and must be installed before working through the examples in the following chapters. Some are optional, adding capabilities or making the job of creating documentation less demanding." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:610 msgid "Required Tools" -msgstr "" +msgstr "Benodigde gereedschappen" #. (itstool) path: sect1/para #: book.translate.xml:612 msgid "Install textproc/docproj from the Ports Collection. This meta-port installs all the applications required to do useful work with the FreeBSD documentation. Some further notes on particular components are given below." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:620 msgid "DTDs and Entities" -msgstr "" +msgstr "DTDs en entiteiten" #. (itstool) path: sect2/para #: book.translate.xml:623 msgid "FreeBSD documentation uses several Document Type Definitions (DTDs) and sets of XML entities. These are all installed by the textproc/docproj port." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:631 msgid "XHTML DTD (textproc/xhtml)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:635 msgid "XHTML is the markup language of choice for the World Wide Web, and is used throughout the FreeBSD web site." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:642 msgid "DocBook DTD (textproc/docbook-xml-450)" -msgstr "" +msgstr "DocBook DTD (textproc/docbook-xml-450)" #. (itstool) path: listitem/para #: book.translate.xml:645 msgid "DocBook is designed for marking up technical documentation. Most of the FreeBSD documentation is written in DocBook." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:652 msgid "ISO 8879 entities (textproc/iso8879)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:656 msgid "Character entities from the ISO 8879:1986 standard used by many DTDs. Includes named mathematical symbols, additional characters in the Latin character set (accents, diacriticals, and so on), and Greek symbols." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:668 msgid "Optional Tools" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:670 msgid "These applications are not required, but can make working on the documentation easier or add capabilities." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:674 -#, fuzzy msgid "Software" -msgstr "" -"In de loop van de jaren 80 ontsproten er een aantal nieuwe werkstationbedrijven. Vele verkozen het om UNIX te licenseren boven het ontwikkelen van hun eigen besturingssystemen. In het bijzonder licenseerde Sun Microsystems UNIX en implementeerde het een versie van 4.2BSD, wat ze SunOS noemden. " -"Toen AT&T zelf UNIX commercieel mocht verkopen, begonnen ze met een ietwat kale basisimplementatie genaamd System III, die snel gevolgd werd door System V. De codebase van System V bevatte geen netwerkcode, dus bevatten alle implementaties aanvullende software van de BSD, waaronder de TCP/IP-software, maar ook gereedschappen zoals de csh-" -"shell en de tekstverwerker vi. Deze uitbreidingen stonden gezamenlijk bekend als de Berkeley Extensions." +msgstr "Software" #. (itstool) path: varlistentry/term #: book.translate.xml:679 msgid "Vim (editors/vim)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:683 msgid "A popular editor for working with XML and derived documents, like DocBook XML." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:690 msgid "Emacs or XEmacs (editors/emacs or editors/xemacs)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:696 msgid "Both of these editors include a special mode for editing documents marked up according to an XML DTD. This mode includes commands to reduce the amount of typing needed, and help reduce the possibility of errors." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:739 msgid "The Working Copy" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:741 msgid "The working copy is a copy of the FreeBSD repository documentation tree downloaded onto the local computer. Changes are made to the local working copy, tested, and then submitted as patches to be committed to the main repository." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:747 msgid "A full copy of the documentation tree can occupy 700 megabytes of disk space. Allow for a full gigabyte of space to have room for temporary files and test versions of various output formats." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:752 msgid "Subversion is used to manage the FreeBSD documentation files. It is installed by textproc/docproj as one of the required applications." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:758 msgid "Documentation and Manual Pages" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:760 msgid "" "FreeBSD documentation is not just books and articles. Manual pages for all the commands and configuration files are also part of the documentation, and part of the FDP's territory. Two repositories are involved: doc for the books and articles, and base for the operating system and manual pages. To edit manual pages, the base " "repository must be checked out separately." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:769 msgid "Repositories may contain multiple versions of documentation and source code. New modifications are almost always made only to the latest version, called head." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:775 msgid "Choosing a Directory" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:777 msgid "" "FreeBSD documentation is traditionally stored in /usr/doc/, and system source code with manual pages in /usr/src/. These directory trees are relocatable, and users may want to put the working copies in other locations to avoid interfering with existing information in the main directories. The examples that follow use ~/doc and ~/src, both subdirectories of the user's home directory." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:790 msgid "Checking Out a Copy" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:792 msgid "A download of a working copy from the repository is called a checkout, and done with svn checkout. This example checks out a copy of the latest version (head) of the main documentation tree:" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:800 msgid "A checkout of the source code to work on manual pages is very similar:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:803 #, no-wrap msgid "% svn checkout https://svn.FreeBSD.org/base/head ~/src" -msgstr "" +msgstr "% svn checkout https://svn.FreeBSD.org/base/head ~/src" #. (itstool) path: sect1/title #: book.translate.xml:807 msgid "Updating a Working Copy" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:809 msgid "" "The documents and files in the FreeBSD repository change daily. People modify files and commit changes frequently. Even a short time after an initial checkout, there will already be differences between the local working copy and the main FreeBSD repository. To update the local version with the changes that have been made to the main repository, use svn update on the directory containing the " "local working copy:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:818 #, no-wrap msgid "% svn update ~/doc" -msgstr "" +msgstr "% svn update ~/doc" #. (itstool) path: sect1/para #: book.translate.xml:820 msgid "Get in the protective habit of using svn update before editing document files. Someone else may have edited that file very recently, and the local working copy will not include the latest changes until it has been updated. Editing the newest version of a file is much easier than trying to combine an older, edited local file with the newer version from the repository." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:830 msgid "Reverting Changes" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:832 msgid "Sometimes it turns out that changes were not necessary after all, or the writer just wants to start over. Files can be reset to their unchanged form with svn revert. For example, to erase the edits made to chapter.xml and reset it to unmodified form:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:839 #, no-wrap msgid "% svn revert chapter.xml" -msgstr "" +msgstr "% svn revert chapter.xml" #. (itstool) path: sect1/title #: book.translate.xml:843 msgid "Making a Diff" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:845 msgid "After edits to a file or group of files are completed, the differences between the local working copy and the version on the FreeBSD repository must be collected into a single file for submission. These diff files are produced by redirecting the output of svn diff into a file:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:852 #, no-wrap msgid "" "% cd ~/doc\n" "% svn diff > doc-fix-spelling.diff" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:855 msgid "Give the file a meaningful name that identifies the contents. The example above is for spelling fixes to the whole documentation tree." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:859 msgid "If the diff file is to be submitted with the web Submit a FreeBSD problem report interface, add a .txt extension to give the earnest and simple-minded web form a clue that the contents are plain text." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:866 msgid "Be careful: svn diff includes all changes made in the current directory and any subdirectories. If there are files in the working copy with edits that are not ready to be submitted yet, provide a list of only the files that are to be included:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:872 #, no-wrap msgid "" "% cd ~/doc\n" "% svn diff disks/chapter.xml printers/chapter.xml > disks-printers.diff" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:877 msgid "Subversion References" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:879 msgid "These examples show very basic usage of Subversion. More detail is available in the Subversion Book and the Subversion documentation." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:920 msgid "Documentation Directory Structure" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:922 msgid "Files and directories in the doc/ tree follow a structure meant to:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:928 msgid "Make it easy to automate converting the document to other formats." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:933 msgid "Promote consistency between the different documentation organizations, to make it easier to switch between working on different documents." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:939 msgid "Make it easy to decide where in the tree new documentation should be placed." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:944 msgid "In addition, the documentation tree must accommodate documents in many different languages and encodings. It is important that the documentation tree structure does not enforce any particular defaults or cultural preferences." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:950 msgid "The Top Level, doc/" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:953 msgid "There are two types of directory under doc/, each with very specific directory names and meanings." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:961 book.translate.xml:1015 msgid "Directory" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:962 book.translate.xml:1016 msgid "Usage" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:968 msgid "share" -msgstr "" +msgstr "share" #. (itstool) path: row/entry #: book.translate.xml:971 msgid "" "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 make1 infrastructure are in share/mk, while the additional XML support files (such " "as the FreeBSD extended DocBook DTD) are in share/xml." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:983 msgid "lang.encoding" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:986 msgid "" "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 when a translation team wants to provide documentation in the same language but in more than one encoding. This also avoids problems " "that might be caused by a future switch to Unicode." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1003 msgid "The lang.encoding/ Directories" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1007 msgid "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." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1022 msgid "articles" -msgstr "" +msgstr "articles" #. (itstool) path: row/entry #: book.translate.xml:1025 msgid "Documentation marked up as a DocBook article (or equivalent). Reasonably short, and broken up into sections. Normally only available as one XHTML file." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1032 msgid "books" -msgstr "" +msgstr "books" #. (itstool) path: row/entry #: book.translate.xml:1034 msgid "Documentation marked up as a DocBook book (or equivalent). Book length, and broken up into chapters. Normally available as both one large XHTML file (for people with fast connections, or who want to print it easily from a browser) and as a collection of linked, smaller files." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1044 msgid "man" -msgstr "" +msgstr "man" #. (itstool) path: row/entry #: book.translate.xml:1047 msgid "For translations of the system manual pages. This directory will contain one or more mann directories, corresponding to the sections that have been translated." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1056 msgid "Not every lang.encoding directory will have all of these subdirectories. It depends on how much translation has been accomplished by that translation team." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1063 msgid "Document-Specific Information" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1065 msgid "This section contains specific notes about particular documents managed by the FDP." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:1069 msgid "The Handbook" -msgstr "" +msgstr "Het Handboek" #. (itstool) path: sect2/subtitle #: book.translate.xml:1071 msgid "books/handbook/" -msgstr "" +msgstr "books/handbook/" #. (itstool) path: sect2/para #: book.translate.xml:1073 msgid "The Handbook is written in DocBook XML using the FreeBSD DocBook extended DTD." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1076 msgid "The Handbook is organized as a DocBook book. The book is divided into parts, each of which contains several chapters. chapters are further subdivided into sections (sect1) and subsections (sect2, sect3) and so on." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:1085 msgid "Physical Organization" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1087 msgid "There are a number of files and directories within the handbook directory." msgstr "" #. (itstool) path: note/para #: book.translate.xml:1091 msgid "The Handbook's organization may change over time, and this document may lag in detailing the organizational changes. Post questions about Handbook organization to the FreeBSD documentation project mailing list." msgstr "" #. (itstool) path: sect4/title #: book.translate.xml:1098 msgid "Makefile" -msgstr "" +msgstr "Makefile" #. (itstool) path: sect4/para #: book.translate.xml:1100 msgid "The Makefile defines some variables that affect how the XML 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, to bring in the rest of the code that handles converting documents from one format to another." msgstr "" #. (itstool) path: sect4/title #: book.translate.xml:1110 msgid "book.xml" -msgstr "" +msgstr "book.xml" #. (itstool) path: sect4/para #: book.translate.xml:1112 msgid "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." msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1117 msgid "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." msgstr "" #. (itstool) path: sect4/title #: book.translate.xml:1126 msgid "directory/chapter.xml" msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1128 msgid "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." msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1135 msgid "For example, if one of the chapter files contains:" msgstr "" #. (itstool) path: sect4/programlisting #: book.translate.xml:1138 #, no-wrap msgid "" "chapter id=\"kernelconfig\"\n" "...\n" "chapter" msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1142 msgid "Then it will be called chapter.xml in the kernelconfig directory. In general, the entire contents of the chapter are in this one file." msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1148 msgid "When the XHTML version of the Handbook is produced, this will yield kernelconfig.html. This is because of the id value, and is not related to the name of the directory." msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1154 msgid "" "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. Now, it is possible to include images in each chapter. Images for each Handbook chapter are stored within share/images/books/handbook. The localized version of these " "images should be placed in the same directory as the XML sources for each chapter. Namespace collisions are 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." msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1168 msgid "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." msgstr "" #. (itstool) path: important/para #: book.translate.xml:1175 msgid "Do not name chapters or directories after their ordering within the Handbook. This ordering can change as the content within the Handbook is reorganized. Reorganization should be possible without renaming files, unless entire chapters are being promoted or demoted within the hierarchy." msgstr "" #. (itstool) path: sect4/para #: book.translate.xml:1183 msgid "The chapter.xml files are not complete XML documents that can be built individually. They can only be built as parts of the whole Handbook." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:1226 msgid "The Documentation Build Process" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:1228 msgid "This chapter covers organization of the documentation build process and how make1 is used to control it." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1232 msgid "Rendering DocBook into Output" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1234 msgid "Different types of output can be produced from a single DocBook source file. The type of output desired is set with the FORMATS variable. A list of known formats is stored in KNOWN_FORMATS:" msgstr "" #. (itstool) path: sect1/screen #. (itstool) id: book.translate.xml#doc-build-rendering-known-formats #: book.translate.xml:1239 #, no-wrap msgid "" "% cd ~/doc/en_US.ISO8859-1/books/handbook\n" "% make -V KNOWN_FORMATS" msgstr "" #. (itstool) path: table/title #: book.translate.xml:1243 msgid "Common Output Formats" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1248 msgid "FORMATS Value" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1249 msgid "File Type" msgstr "" #. (itstool) path: row/entry #. (itstool) path: segmentedlist/segtitle #: book.translate.xml:1250 book.translate.xml:7142 -#, fuzzy msgid "Description" -msgstr "" -"In contrast hiermee onderhoudt Linux twee gescheiden codebomen: de stabiele versie en de ontwikkelversie. Stabiele versies hebben een even klein versienummer, zoals 2.0, 2.2, of 2.4. Ontwikkelversies hebben een oneven klein versienummer, zoals 2.1, 2.3, of 2.5. In alle gevallen wordt het nummer gevolgd door een nog een nummer dat de exacte uitgave aangeeft. Verder voegt elke verkoper zijn eigen " -"gebruikersprogramma's en gereedschappen toe, dus is de naam van de distributie ook belangrijk. Elke verkoper van distributies kent ook versienummers aan de distributie toe, dus kan een volledige omschrijving iets zijn als TurboLinux 6.0 met kernel 2.2.14 zijn." +msgstr "Beschrijving" #. (itstool) path: row/entry #. (itstool) path: varlistentry/term #: book.translate.xml:1256 book.translate.xml:2403 msgid "html" -msgstr "" +msgstr "html" #. (itstool) path: row/entry #: book.translate.xml:1257 msgid "HTML, one file" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1258 msgid "A single book.html or article.html." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1263 msgid "html-split" -msgstr "" +msgstr "html-split" #. (itstool) path: row/entry #: book.translate.xml:1264 msgid "HTML, multiple files" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1265 msgid "Multiple HTML files, one for each chapter or section, for use on a typical web site." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:1271 msgid "pdf" -msgstr "" +msgstr "pdf" #. (itstool) path: row/entry #: book.translate.xml:1272 msgid "PDF" -msgstr "" +msgstr "PDF" #. (itstool) path: row/entry #: book.translate.xml:1273 msgid "Portable Document Format" -msgstr "" +msgstr "Portable Document Format" #. (itstool) path: sect1/para #: book.translate.xml:1279 msgid "The default output format can vary by document, but is usually html-split. Other formats are chosen by setting FORMATS to a specific value. Multiple output formats can be created at a single time by setting FORMATS to a list of formats." msgstr "" #. (itstool) path: example/title #: book.translate.xml:1286 msgid "Build a Single HTML Output File" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:1288 #, no-wrap msgid "" "% cd ~/doc/en_US.ISO8859-1/books/handbook\n" "% make FORMATS=html" msgstr "" #. (itstool) path: example/title #: book.translate.xml:1293 msgid "Build HTML-Split and PDF Output Files" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:1296 #, no-wrap msgid "" "% cd ~/doc/en_US.ISO8859-1/books/handbook\n" "% make FORMATS=\"html-split pdf\"" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1302 msgid "The FreeBSD Documentation Build Toolset" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1304 msgid "These are the tools used to build and install the FDP documentation." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1309 msgid "The primary build tool is make1, specifically Berkeley Make." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1314 msgid "Package building is handled by FreeBSD's pkg_create1." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1319 msgid "gzip1 is used to create compressed versions of the document. bzip21 archives are also supported. tar1 is used for package building." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1325 msgid "install1 is used to install the documentation." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1333 msgid "Understanding Makefiles in the Documentation Tree" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1336 msgid "There are three main types of Makefiles in the FreeBSD Documentation Project tree." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1341 msgid "Subdirectory Makefiles simply pass commands to those directories below them." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1347 msgid "Documentation Makefiles describe the document(s) that should be produced from this directory." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1354 msgid "Make includes are the glue that perform the document production, and are usually of the form doc.xxx.mk." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:1362 msgid "Subdirectory Makefiles" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1364 msgid "These Makefiles usually take the form of:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:1367 #, no-wrap msgid "" "SUBDIR =articles\n" "SUBDIR+=books\n" "\n" "COMPAT_SYMLINK = en\n" "\n" "DOC_PREFIX?= ${.CURDIR}/..\n" ".include \"${DOC_PREFIX}/share/mk/doc.project.mk\"" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1375 msgid "The first four non-empty lines define the make1 variables SUBDIR, COMPAT_SYMLINK, and DOC_PREFIX." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1380 msgid "The SUBDIR statement and COMPAT_SYMLINK statement show how to assign a value to a variable, overriding any previous value." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1385 msgid "The second SUBDIR statement shows how a value is appended to the current value of a variable. The SUBDIR variable is now articles books." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1390 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1397 msgid "What does it all mean? SUBDIR mentions which subdirectories below this one the build process should pass any work on to." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1401 msgid "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)." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1406 msgid "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 make1 builtin variable with the path to the current directory." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1413 msgid "The final line includes the FreeBSD Documentation Project's project-wide make1 system file doc.project.mk which is the glue which converts these variables into build instructions." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:1420 msgid "Documentation Makefiles" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1422 msgid "These Makefiles set make1 variables that describe how to build the documentation contained in that directory." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1426 msgid "Here is an example:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:1428 #, no-wrap msgid "" "MAINTAINER=nik@FreeBSD.org\n" "\n" "DOC?= book\n" "\n" "FORMATS?= html-split html\n" "\n" "INSTALL_COMPRESSED?= gz\n" "INSTALL_ONLY_COMPRESSED?=\n" "\n" "# SGML content\n" "SRCS= book.xml\n" "\n" "DOC_PREFIX?= ${.CURDIR}/../../..\n" "\n" ".include \"$(DOC_PREFIX)/share/mk/docproj.docbook.mk\"" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1444 msgid "The MAINTAINER variable allows committers to claim ownership of a document in the FreeBSD Documentation Project, and take responsibility for maintaining it." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1449 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1456 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1464 msgid "The DOC_PREFIX and include statements should be familiar already." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1470 msgid "FreeBSD Documentation Project Make Includes" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1473 msgid "make1 includes are best explained by inspection of the code. Here are the system include files:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1478 msgid "doc.project.mk is the main project include file, which includes all the following include files, as necessary." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1484 msgid "doc.subdir.mk handles traversing of the document tree during the build and install processes." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1490 msgid "doc.install.mk provides variables that affect ownership and installation of documents." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1495 msgid "doc.docbook.mk is included if DOCFORMAT is docbook and DOC is set." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:1502 msgid "doc.project.mk" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1504 msgid "By inspection:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:1506 #, no-wrap msgid "" "DOCFORMAT?=\tdocbook\n" "MAINTAINER?=\tdoc@FreeBSD.org\n" "\n" "PREFIX?=\t/usr/local\n" "PRI_LANG?=\ten_US.ISO8859-1\n" "\n" ".if defined(DOC)\n" ".if ${DOCFORMAT} == \"docbook\"\n" ".include \"doc.docbook.mk\"\n" ".endif\n" ".endif\n" "\n" ".include \"doc.subdir.mk\"\n" ".include \"doc.install.mk\"" msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:1523 book.translate.xml:1573 msgid "Variables" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1525 msgid "DOCFORMAT and MAINTAINER are assigned default values, if these are not set by the document make file." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1529 msgid "PREFIX is the prefix under which the documentation building tools are installed. For normal package and port installation, this is /usr/local." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1534 msgid "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." msgstr "" #. (itstool) path: note/para #: book.translate.xml:1540 msgid "PRI_LANG does not affect which documents can, or even will, be built. Its main use is creating links to commonly referenced documents into the FreeBSD documentation install root." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:1548 msgid "Conditionals" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1550 msgid "The .if defined(DOC) line is an example of a make1 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." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1556 msgid ".if ${DOCFORMAT} == \"docbook\", next, tests whether the DOCFORMAT variable is \"docbook\", and in this case, includes doc.docbook.mk." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1561 msgid "The two .endifs close the two above conditionals, marking the end of their application." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:1567 msgid "doc.subdir.mk" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:1569 msgid "This file is too long to explain in detail. These notes describe the most important features." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1577 msgid "SUBDIR is a list of subdirectories that the build process should go further down into." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1583 msgid "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)." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1591 msgid "COMPAT_SYMLINK is described in the Subdirectory Makefile section." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:1600 msgid "Targets and Macros" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1602 msgid "Dependencies are described by target: dependency1 dependency2 ... tuples, where to build target, the given dependencies must be built first." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1609 msgid "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." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1615 msgid "A special dependency .USE defines the equivalent of a macro." msgstr "" #. (itstool) path: sect3/programlisting #: book.translate.xml:1618 book.translate.xml:1705 #, no-wrap msgid "" "_SUBDIRUSE: .USE\n" ".for entry in ${SUBDIR}\n" "\t@${ECHO} \"===> ${DIRPRFX}${entry}\"\n" "\t@(cd ${.CURDIR}/${entry} && \\\n" "\t${MAKE} ${.TARGET:S/realpackage/package/:S/realinstall/install/} DIRPRFX=${DIRPRFX}${entry}/ )\n" ".endfor" msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:1625 book.translate.xml:1641 msgid "_SUBDIRUSE" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1625 msgid "In the above, <_:buildtarget-1/> is now a macro which will execute the given commands when it is listed as a dependency." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1629 msgid "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." msgstr "" #. (itstool) path: sect3/programlisting #: book.translate.xml:1637 #, no-wrap msgid "" "clean: _SUBDIRUSE\n" "\trm -f ${CLEANFILES}" msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:1640 book.translate.xml:1644 book.translate.xml:1664 book.translate.xml:6010 book.translate.xml:6014 book.translate.xml:6018 msgid "clean" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1640 msgid "In the above, <_:buildtarget-1/> will use the <_:buildtarget-2/> macro after it has executed the instruction rm -f ${CLEANFILES}. In effect, this causes <_:buildtarget-3/> to go further and further down the directory tree, deleting built files as it goes down, not on the way back up." msgstr "" #. (itstool) path: sect4/title #: book.translate.xml:1650 msgid "Provided Targets" msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:1654 msgid "install" msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:1655 -#, fuzzy msgid "package" -msgstr "" -"Aangezien er minder applicaties beschikbaar zijn voor BSD dan voor Linux, hebben de ontwikkelaars van BSD een Linux-compatibiliteitspakket ontwikkeld, wat het mogelijk maakt om Linux-programma's onder BSD te draaien. Het pakket bevat zowel kernelwijzigingen, om Linux-systeemaanroepen correct uit te voeren, en Linux-compatibiliteitsbestanden zoals de C-bibliotheek. Er is geen merkbaar verschil in " -"uitvoersnelheid tussen een Linux-applicatie die op een Linux-machine draait en een Linux-applicatie die op een BSD-machine die dezelfde snelheid heeft draait." +msgstr "package" #. (itstool) path: para/buildtarget #: book.translate.xml:1658 msgid "realinstall" msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:1659 msgid "realpackage" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1654 msgid "<_:buildtarget-1/> and <_:buildtarget-2/> both go down the directory tree calling the real versions of themselves in the subdirectories (<_:buildtarget-3/> and <_:buildtarget-4/> respectively)." msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:1667 msgid "cleandir" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1664 msgid "<_:buildtarget-1/> removes files created by the build process (and goes down the directory tree too). <_:buildtarget-2/> does the same, and also removes the object directory, if any." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:1675 msgid "More on Conditionals" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1679 msgid "exists is another condition function which returns true if the given file exists." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1685 msgid "empty returns true if the given variable is empty." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1690 msgid "target returns true if the given target does not already exist." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:1697 msgid "Looping Constructs in make (.for)" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1700 msgid ".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." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:1712 msgid "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." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:1756 msgid "The Website" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:1758 msgid "The FreeBSD web site is part of the FreeBSD documents. Files for the web site are stored in the en_US.ISO8859-1/htdocs subdirectory of the document tree directory, ~/doc in this example." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1765 msgid "Environment Variables" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1767 msgid "Several environment variables control which parts of the the web site are built or installed, and to which directories." msgstr "" #. (itstool) path: tip/para #: book.translate.xml:1772 msgid "The web build system uses make1, and considers variables to be set when they have been defined, even if they are empty. The examples here show the recommended ways of defining and using these variables. Setting or defining these variables with other values or methods might lead to unexpected surprises." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:1782 msgid "DESTDIR" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1785 msgid "DESTDIR specifies the path where the web site files are to be installed." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1788 msgid "" "This variable is best set with env1 or the user shell's method of setting environment variables, setenv for csh1 or export for sh1." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:1798 msgid "ENGLISH_ONLY" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1801 msgid "Default: undefined. Build and include all translations." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1804 msgid "ENGLISH_ONLY=yes: use only the English documents and ignore all translations." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:1810 msgid "WEB_ONLY" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1813 msgid "Default: undefined. Build both the web site and all the books and articles." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1816 msgid "WEB_ONLY=yes: build or install only HTML pages from the en_US.ISO8859-1/htdocs directory. Other directories and documents, including books and articles, will be ignored." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:1825 msgid "WEB_LANG" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1828 msgid "Default: undefined. Build and include all the available languages on the web site." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:1831 msgid "Set to a space-separated list of languages to be included in the build or install. The formats are the same as the directory names in the document root directory. For example, to include the German and French documents:" msgstr "" #. (itstool) path: listitem/screen #: book.translate.xml:1837 #, no-wrap msgid "WEB_LANG=\"de_DE.ISO8859-1 fr_FR.ISO8859-1\"" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1842 msgid "WEB_ONLY, WEB_LANG, and ENGLISH_ONLY are make1 variables and can be set in /etc/make.conf, Makefile.inc, as environment variables on the command line, or in dot files." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:1850 msgid "Building and Installing the Web Pages" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1852 msgid "Having obtained the documentation and web site source files, the web site can be built." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1855 msgid "An actual installation of the web site is run as the root user because the permissions on the web server directory will not allow files to be installed by an unprivileged user. For testing, it can be useful to install the files as a normal user to a temporary directory." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1861 msgid "In these examples, the web site files are built by user jru in their home directory, ~/doc, with a full path of /usr/home/jru/doc." msgstr "" #. (itstool) path: tip/para #: book.translate.xml:1867 msgid "The web site build uses the INDEX from the Ports Collection and might fail if that file or /usr/ports is not present. The simplest approach is to install the Ports Collection." msgstr "" #. (itstool) path: example/title #: book.translate.xml:1875 msgid "Build the Full Web Site and All Documents" msgstr "" #. (itstool) path: example/para #: book.translate.xml:1877 msgid "Build the web site and all documents. The resulting files are left in the document tree:" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:1880 #, no-wrap msgid "" "% cd ~/doc/en_US.ISO8859-1/htdocs/\n" "% make all" msgstr "" #. (itstool) path: example/title #: book.translate.xml:1885 msgid "Build Only the Web Site in English" msgstr "" #. (itstool) path: example/para #: book.translate.xml:1887 msgid "Build the web site only, in English, as user jru, and install the resulting files into /tmp/www for testing:" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:1892 #, no-wrap msgid "" "% cd ~/doc/en_US.ISO8859-1/htdocs/\n" "% env DESTDIR=/tmp/www make ENGLISH_ONLY=yes WEB_ONLY=yes all install" msgstr "" #. (itstool) path: example/title #: book.translate.xml:1897 msgid "Build and Install the Web Site" msgstr "" #. (itstool) path: example/para #: book.translate.xml:1899 msgid "Build the web site and all documents as user jru. Install the resulting files as root into the default directory, /root/public_html:" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:1906 #, no-wrap msgid "" "% cd ~/doc/en_US.ISO8859-1/htdocs\n" "% make all\n" "% su -\n" "Password:\n" "# cd /usr/home/jru/doc/en_US.ISO8859-1/htdocs\n" "# make install" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1914 msgid "The install process does not delete any old or outdated files that existed previously in the same directory. If a new copy of the site is built and installed every day, this command will find and delete all files that have not been updated in three days:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:1920 #, no-wrap msgid "# find /usr/local/www -ctime 3 -delete" msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:1957 msgid "XML Primer" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:1959 msgid "Most FDP documentation is written with markup languages based on XML. This chapter explains what that means, how to read and understand the documentation source, and the XML techniques used." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:1965 msgid "Portions of this section were inspired by Mark Galassi's Get Going With DocBook." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1972 msgid "In the original days of computers, electronic text was simple. There were a few character sets like ASCII or EBCDIC, but that was about it. Text was text, and what you saw really was what you got. No frills, no formatting, no intelligence." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1978 msgid "" "Inevitably, this was not enough. When text is in a machine-usable format, machines are expected to be able to use and manipulate it intelligently. Authors want to indicate that certain phrases should be emphasized, or added to a glossary, or made into hyperlinks. Filenames could 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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1987 msgid "It was once hoped that Artificial Intelligence (AI) would make this easy. The computer would read 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 computers still require assistance before they can meaningfully process text." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:1995 msgid "More precisely, they need help identifying what is what. Consider this text:" msgstr "" #. (itstool) path: blockquote/para #: book.translate.xml:1999 msgid "To remove /tmp/foo, use rm1." msgstr "" #. (itstool) path: blockquote/screen #: book.translate.xml:2002 #, no-wrap msgid "% rm /tmp/foo" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2005 msgid "It is easy to 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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2010 msgid "" "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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2020 msgid "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 (the effort required) to create the document." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2029 msgid "The previous example is actually represented in this document like this:" msgstr "" #. (itstool) path: sect1/programlisting #: book.translate.xml:2032 #, no-wrap msgid "" "paraTo remove filename/tmp/foofilename, use &man.rm.1;.para\n" "\n" "screen&prompt.user; userinputrm /tmp/foouserinputscreen" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2036 msgid "The markup is clearly separate from the content." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2038 msgid "Markup languages define what the markup means and how it should be interpreted." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2041 msgid "" "Of course, one markup language might not be enough. A markup language for technical documentation has very different requirements than a markup language that is intended for cookery recipes. This, in turn, would be very different from a markup language used to describe poetry. What is really needed is a first language used to write these other markup languages. A meta markup language." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2049 msgid "This is exactly what the eXtensible Markup Language (XML) is. Many markup languages have been written in XML, including the two most used by the FDP, XHTML and DocBook." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2055 msgid "Each language definition is more properly called a grammar, vocabulary, schema or Document Type Definition (DTD). There are various languages to specify an XML grammar, or schema." msgstr "" #. (itstool) path: sect1/para #. (itstool) id: book.translate.xml#xml-primer-validating #: book.translate.xml:2061 msgid "" "A schema 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 XML parser which reads in both the schema and a document which claims to conform to the schema. The parser can then confirm " "whether or not all the elements required by the vocabulary 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." msgstr "" #. (itstool) path: note/para #: book.translate.xml:2075 msgid "" "Validation confirms that the choice of elements, their ordering, and so on, conforms to that listed in the grammar. It does not check whether appropriate markup has been used for the content. If all the filenames in a document were marked up as function names, the parser would not flag this as an error (assuming, of course, that the schema defines elements for " "filenames and functions, and that they are allowed to appear in the same place)." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2086 msgid "Most contributions to the Documentation Project will be content marked up in either XHTML or DocBook, rather than alterations to the schemas. For this reason, this book will not touch on how to write a vocabulary." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:2094 msgid "Elements, Tags, and Attributes" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2096 msgid "All the vocabularies written in XML share certain characteristics. This is hardly surprising, as the philosophy behind XML will inevitably show through. One of the most obvious manifestations of this philosophy is that of content and elements." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2103 msgid "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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2109 msgid "" "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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2118 msgid "It may be helpful to think of this as chunking content. At the very top level is one chunk, the book. Look a little deeper, and there are more chunks, the individual chapters. These are chunked further into paragraphs, footnotes, character names, and so on." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2124 msgid "Notice how this differentiation between different elements of the content can be made without resorting to any XML terms. It really is surprisingly straightforward. This could be done with a highlighter pen and a printout of the book, using different colors to indicate different chunks of content." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2131 msgid "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 XML (XHTML, DocBook, et al) this is done by means of tags." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2137 msgid "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 grammar 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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2144 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2150 msgid "Using an Element (Start and End Tags)" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2152 msgid "XHTML has an element for indicating that the content enclosed by the element is a paragraph, called p." msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2156 #, no-wrap msgid "" "pThis is a paragraph. It starts with the start tag for\n" " the 'p' element, and it will end with the end tag for the 'p'\n" " element.p\n" "\n" "pThis is another paragraph. But this one is much shorter.p" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2163 msgid "Some elements have no content. For example, in XHTML, a horizontal line can be included in the document. For these empty elements, XML introduced a shorthand form that is completely equivalent to the two-tag version:" msgstr "" #. (itstool) path: example/title #: book.translate.xml:2170 msgid "Using an Element Without Content" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2172 msgid "XHTML has an element for indicating a horizontal rule, called hr. This element does not wrap content, so it looks like this:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2176 #, no-wrap msgid "" "pOne paragraph.p\n" "hrhr\n" "\n" "pThis is another paragraph. A horizontal rule separates this\n" " from the previous paragraph.p" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2182 msgid "The shorthand version consists of a single tag:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2184 #, no-wrap msgid "" "pOne paragraph.p\n" "hr\n" "\n" "pThis is another paragraph. A horizontal rule separates this\n" " from the previous paragraph.p" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2191 msgid "As shown above, 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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2197 msgid "Elements Within Elements; em" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2199 #, no-wrap msgid "" "pThis is a simple emparagraphem where some\n" " of the emwordsem have been ememphasizedem.p" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2203 msgid "The grammar consists of rules that describe which elements can contain other elements, and exactly what they can contain." msgstr "" #. (itstool) path: important/para #: book.translate.xml:2208 msgid "People often confuse the terms tags and elements, and use the terms as if they were interchangeable. They are not." msgstr "" #. (itstool) path: important/para #: book.translate.xml:2212 msgid "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 ends." msgstr "" #. (itstool) path: important/para #: book.translate.xml:2216 msgid "When this document (or anyone else knowledgeable about XML) 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." msgstr "" #. (itstool) path: important/para #: book.translate.xml:2225 msgid "This distinction is very subtle. But keep it in mind." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2229 msgid "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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2235 msgid "An element's attributes are written inside the start tag for that element, and take the form attribute-name=\"attribute-value\"." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2240 msgid "In XHTML, the p element has an attribute called align, which suggests an alignment (justification) for the paragraph to the program displaying the XHTML." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2246 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2253 msgid "Using an Element with an Attribute" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2255 #, no-wrap msgid "" "p align=\"left\"The inclusion of the align attribute\n" " on this paragraph was superfluous, since the default is left.p\n" "\n" "p align=\"center\"This may appear in the center.p" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2261 msgid "Some attributes only take specific values, such as left or justify. Others allow any value." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2266 msgid "Single Quotes Around Attributes" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2268 #, no-wrap msgid "p align='right'I am on the right!p" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2271 msgid "Attribute values in XML must be enclosed in either single or double quotes. Double quotes are traditional. Single quotes are useful when the attribute value contains double quotes." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2276 msgid "Information about attributes, elements, and tags is stored in catalog files. The Documentation Project uses standard DocBook catalogs and includes additional catalogs for FreeBSD-specific features. Paths to the catalog files are defined in an environment variable so they can be found by the document build tools." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:2284 book.translate.xml:2697 book.translate.xml:2831 book.translate.xml:3018 book.translate.xml:3311 msgid "To Do…" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2286 msgid "" "Before running the examples in this document, install textproc/docproj from the FreeBSD Ports Collection. This is a meta-port that downloads and installs the standard programs and supporting files needed by the Documentation Project. csh1 users must use rehash for the " "shell to recognize new programs after they have been installed, or log out and then log back in again." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2298 msgid "Create example.xml, and enter this text:" msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:2301 #, no-wrap msgid "" "!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"\n" "\n" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " head\n" " titleAn Example XHTML Filetitle\n" " head\n" "\n" " body\n" " pThis is a paragraph containing some text.p\n" "\n" " pThis paragraph contains some more text.p\n" "\n" " p align=\"right\"This paragraph might be right-justified.p\n" " body\n" "html" msgstr "" #. (itstool) path: step/para #: book.translate.xml:2319 msgid "Try to validate this file using an XML parser." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2322 msgid "textproc/docproj includes the xmllint validating parser." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2327 msgid "Use xmllint to validate the document:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:2330 #, no-wrap msgid "% xmllint --valid --noout example.xml" msgstr "" #. (itstool) path: step/para #: book.translate.xml:2332 msgid "xmllint returns without displaying any output, showing that the document validated successfully." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2338 msgid "See what happens when required elements are omitted. Delete the line with the title and title tags, and re-run the validation." msgstr "" #. (itstool) path: step/screen #: book.translate.xml:2344 #, no-wrap msgid "" "% xmllint --valid --noout example.xml\n" "example.xml:5: element head: validity error : Element head content does not follow the DTD, expecting ((script | style | meta | link | object | isindex)* , ((title , (script | style | meta | link | object | isindex)* , (base , (script | style | meta | link | object | isindex)*)?) | (base , (script | style | meta | link | object | isindex)* , title , (script | style | meta | link | object | isindex)*))), got ()" msgstr "" #. (itstool) path: step/para #: book.translate.xml:2347 msgid "This shows that the validation error comes from the fifth line of the example.xml file and that the content of the head is the part which does not follow the rules of the XHTML grammar." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2354 msgid "Then xmllint shows the line where the error was found and marks the exact character position with a ^ sign." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2360 msgid "Replace the title element." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:2367 msgid "The DOCTYPE Declaration" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2369 msgid "The beginning of each document can specify the name of the DTD to which the document conforms. This DOCTYPE declaration is used by XML parsers to identify the DTD and ensure that the document does conform to it." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2375 msgid "A typical declaration for a document written to conform with version 1.0 of the XHTML DTD looks like this:" msgstr "" #. (itstool) path: sect1/programlisting #: book.translate.xml:2379 #, no-wrap msgid "!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2381 msgid "That line contains a number of different components." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2385 msgid "<!" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2388 msgid "The indicator shows this is an XML declaration." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2394 msgid "DOCTYPE" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2397 msgid "Shows that this is an XML declaration of the document type." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2406 msgid "Names the first element that will appear in the document." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2413 msgid "PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"" msgstr "" #. (itstool) path: para/indexterm #. (itstool) path: sect2/indexterm #: book.translate.xml:2419 book.translate.xml:2460 msgid "Formal Public Identifier" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2417 msgid "Lists the Formal Public Identifier (FPI) <_:indexterm-1/> for the DTD to which this document conforms. The XML parser uses this to find the correct DTD when processing this document." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2427 msgid "PUBLIC is not a part of the FPI, but indicates to the XML processor how to find the DTD referenced in the FPI. Other ways of telling the XML parser how to find the DTD are shown later." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2438 msgid "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2441 msgid "A local filename or a URL to find the DTD." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2447 msgid ">" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2450 msgid "Ends the declaration and returns to the document." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:2457 msgid "Formal Public Identifiers (FPIs)" msgstr "" #. (itstool) path: note/para #: book.translate.xml:2465 msgid "It is not necessary to know this, but it is useful background, and might help debug problems when the XML processor can not locate the DTD." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2471 msgid "FPIs must follow a specific syntax:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:2474 #, no-wrap msgid "\"Owner//Keyword Description//Language\"" msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2478 msgid "Owner" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2481 msgid "The owner of the FPI." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2483 msgid "" "The beginning of the string identifies the owner of the 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 International Organization for Standardization (ISO) number for the " "SGML standard, the predecessor (and a superset) of XML." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2496 msgid "Otherwise, this string will either look like -//Owner or +//Owner (notice the only difference is the leading + or -)." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2503 msgid "If the string starts with - then the owner information is unregistered, with a + identifying it as registered." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2508 msgid "" "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. Additionally, a registration authority could be created in order to assign registered names. The ISO council delegated this to the " "American National Standards Institute (ANSI)." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2519 msgid "Because the FreeBSD Project has not been registered, the owner string is -//FreeBSD. As seen in the example, the W3C are not a registered owner either." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2527 msgid "Keyword" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2530 msgid "" "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 XML content (text and tags)." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2545 msgid "Description" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2548 msgid "Any description can be given for the contents of this file. This may include version numbers or any short text that is meaningful and unique for the XML system." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:2556 msgid "Language" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:2559 msgid "An ISO two-character code that identifies the native language for the file. EN is used for English." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:2567 msgid "catalog Files" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:2569 msgid "With the syntax above, an XML processor needs to have some way of turning the FPI into the name of the file containing the DTD. A catalog file (typically called catalog) contains lines that map FPIs to filenames. For example, if the catalog file contained the line:" msgstr "" #. (itstool) path: sect3/programlisting #: book.translate.xml:2579 #, no-wrap msgid "PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\" \"1.0/transitional.dtd\"" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:2581 msgid "The XML processor knows that the DTD is called transitional.dtd in the 1.0 subdirectory of the directory that held catalog." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:2587 msgid "Examine the contents of /usr/local/share/xml/dtd/xhtml/catalog.xml. This is the catalog file for the XHTML DTDs that were installed as part of the textproc/docproj port." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:2596 msgid "Alternatives to FPIs" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2598 msgid "Instead of using an FPI to indicate the DTD to which the document conforms (and therefore, which file on the system contains the DTD), the filename can be explicitly specified." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2604 msgid "The syntax is slightly different:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:2606 #, no-wrap msgid "!DOCTYPE html SYSTEM \"/path/to/file.dtd\"" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2608 msgid "The SYSTEM keyword indicates that the XML processor should locate the DTD in a system specific fashion. This typically (but not always) means the DTD will be provided as a filename." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2614 msgid "Using FPIs is preferred for reasons of portability. If the SYSTEM identifier is used, then the DTD must be provided and kept in the same location for everyone." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:2622 msgid "Escaping Back to XML" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2624 msgid "Some of the underlying XML syntax can be useful within documents. For example, comments can be included in the document, and will be ignored by the parser. Comments are entered using XML syntax. Other uses for XML syntax will be shown later." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2630 msgid "" "XML sections begin with a <! tag and end with a >. These sections contain instructions for the parser rather than elements of the document. Everything between these tags is XML syntax. The DOCTYPE declaration shown earlier is an example of XML syntax " "included in the document." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:2642 msgid "Comments" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2644 msgid "Comments are an XML construct, and are normally only valid inside a DTD. However, as shows, it is possible to use XML syntax within the document." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2649 msgid "The delimiter for XML comments is the string --. The first occurrence of this string opens a comment, and the second closes it." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2654 msgid "XML Generic Comment" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2656 #, no-wrap msgid "" "<!-- This is inside the comment -->\n" "\n" "<!-- This is another comment -->\n" "\n" "<!-- This is one way\n" " of doing multiline comments -->\n" "\n" "<!-- This is another way of --\n" " -- doing multiline comments -->" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2667 msgid "XHTML users may be familiar with different rules for comments. In particular, it is often believed that the string <!-- opens a comment, and it is only closed by -->." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2672 msgid "This is not correct. Many web browsers have broken XHTML parsers, and will accept incorrect input as valid. However, the XML parsers used by the Documentation Project are more strict, and will reject documents with that error." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2679 msgid "Erroneous XML Comments" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2681 #, no-wrap msgid "" "<!-- This is in the comment --\n" "\n" " THIS IS OUTSIDE THE COMMENT!\n" "\n" " -- back inside the comment -->" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2687 msgid "The XML parser will treat this as though it were actually:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2690 #, no-wrap msgid "<!THIS IS OUTSIDE THE COMMENT>" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2692 msgid "That is not valid XML, and may give confusing error messages." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2701 msgid "Add some comments to example.xml, and check that the file still validates using xmllint." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2707 msgid "Add some invalid comments to example.xml, and see the error messages that xmllint gives when it encounters an invalid comment." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:2717 msgid "Entities" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2719 msgid "Entities are a mechanism for assigning names to chunks of content. As an XML parser processes a document, any entities it finds are replaced by the content of the entity." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2724 msgid "This is a good way to have re-usable, easily changeable chunks of content in XML documents. It is also the only way to include one marked up file inside another using XML." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2729 msgid "There are two types of entities for two different situations: general entities and parameter entities." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:2734 msgid "General Entities" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2736 msgid "General entities are used to assign names to reusable chunks of text. These entities can only be used in the document. They cannot be used in an XML context." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2741 msgid "To include the text of a general entity in the document, include &entity-name; in the text. For example, consider a general entity called current.version which expands to the current version number of a product. To use it in the document, write:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:2749 #, no-wrap msgid "" "paraThe current version of our product is\n" " &current.version;.para" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2752 msgid "When the version number changes, edit the definition of the general entity, replacing the value. Then reprocess the document." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2756 msgid "" "General entities can also be used to enter characters that could not otherwise be included in an XML document. For example, < and & cannot normally appear in an XML document. The XML parser sees the < symbol as the start of a tag. Likewise, when the & symbol is " "seen, the next text is expected to be an entity name." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2765 msgid "These symbols can be included by using two predefined general entities: &lt; and &amp;." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2769 msgid "General entities can only be defined within an XML context. Such definitions are usually done immediately after the DOCTYPE declaration." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2774 msgid "Defining General Entities" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2776 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!ENTITY current.version \"3.0-RELEASE\">\n" "<!ENTITY last.version \"2.2.7-RELEASE\">\n" "]>" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2782 msgid "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, the square bracket is closed, and then the DOCTYPE declaration is closed." msgstr "" #. (itstool) path: example/para #: book.translate.xml:2788 msgid "The square brackets are necessary to indicate that the DTD indicated by the DOCTYPE declaration is being extended." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:2795 msgid "Parameter Entities" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2797 msgid "Parameter entities, like general entities, are used to assign names to reusable chunks of text. But parameter entities can only be used within an XML context." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2804 msgid "Parameter entity definitions are similar to those for general entities. However, parameter entries are included with %entity-name;. The definition also includes the % between the ENTITY keyword and the name of the entity." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2812 msgid "For a mnemonic, think Parameter entities use the Percent symbol." msgstr "" #. (itstool) path: example/title #: book.translate.xml:2817 msgid "Defining Parameter Entities" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2819 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!ENTITY % param.some \"some\">\n" "<!ENTITY % param.text \"text\">\n" "<!ENTITY % param.new \"%param.some more %param.text\">\n" "\n" "<!-- %param.new now contains \"some more text\" -->\n" "]>" msgstr "" #. (itstool) path: step/para #: book.translate.xml:2835 msgid "Add a general entity to example.xml." msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:2838 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!ENTITY version \"1.1\">\n" "]>\n" "\n" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " head\n" " titleAn Example XHTML Filetitle\n" " head\n" "\n" " <!-- There may be some comments in here as well -->\n" "\n" " body\n" " pThis is a paragraph containing some text.p\n" "\n" " pThis paragraph contains some more text.p\n" "\n" " p align=\"right\"This paragraph might be right-justified.p\n" "\n" " pThe current version of this document is: &version;p\n" " body\n" "html" msgstr "" #. (itstool) path: step/para #: book.translate.xml:2863 msgid "Validate the document using xmllint." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2868 msgid "Load example.xml into a web browser. It may have to be copied to example.html before the browser recognizes it as an XHTML document." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2874 msgid "Older browsers with simple parsers may not render this file as expected. The entity reference &version; may not be replaced by the version number, or the XML context closing ]> may not be recognized and instead shown in the output." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2883 msgid "The solution is to normalize the document with an XML normalizer. The normalizer reads valid XML and writes equally valid XML which has been transformed in some way. One way the normalizer transforms the input is by expanding all the entity references in the document, replacing the entities with the text that they represent." msgstr "" #. (itstool) path: step/para #: book.translate.xml:2892 msgid "xmllint can be used for this. It also has an option to drop the initial DTD section so that the closing ]> does not confuse browsers:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:2897 #, no-wrap msgid "% xmllint --noent --dropdtd example.xml > example.html" msgstr "" #. (itstool) path: step/para #: book.translate.xml:2899 msgid "A normalized copy of the document with entities expanded is produced in example.html, ready to load into a web browser." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:2908 msgid "Using Entities to Include Files" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:2910 msgid "Both general and parameter entities are particularly useful for including one file inside another." msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title #: book.translate.xml:2917 book.translate.xml:2933 msgid "Using General Entities to Include Files" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2919 msgid "Consider some content for an XML book organized into files, one file per chapter, called chapter1.xml, chapter2.xml, and so forth, with a book.xml that will contain these chapters." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2926 msgid "In order to use the contents of these files as the values for entities, they are declared with the SYSTEM keyword. This directs the XML parser to include the contents of the named file as the value of the entity." msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2935 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!ENTITY chapter.1 SYSTEM \"chapter1.xml\">\n" "<!ENTITY chapter.2 SYSTEM \"chapter2.xml\">\n" "<!ENTITY chapter.3 SYSTEM \"chapter3.xml\">\n" "<!-- And so forth -->\n" "]>\n" "\n" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " <!-- Use the entities to load in the chapters -->\n" "\n" " &chapter.1;\n" " &chapter.2;\n" " &chapter.3;\n" "html" msgstr "" #. (itstool) path: warning/para #: book.translate.xml:2953 msgid "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 because entities are low-level constructs and they are resolved before any parsing happens." msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title #: book.translate.xml:2965 book.translate.xml:2984 msgid "Using Parameter Entities to Include Files" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2967 msgid "Parameter entities can only be used inside an XML context. Including a file in an XML context can be used to ensure that general entities are reusable." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2972 msgid "Suppose that there are many chapters in the document, and these chapters were reused in two different books, each book organizing the chapters in a different fashion." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2976 msgid "The entities could be listed at the top of each book, but that quickly becomes cumbersome to manage." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:2979 msgid "Instead, place the general entity definitions inside one file, and use a parameter entity to include that file within the document." msgstr "" #. (itstool) path: example/para #: book.translate.xml:2986 msgid "Place the entity definitions in a separate file called chapters.ent and containing this text:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:2990 #, no-wrap msgid "" "<!ENTITY chapter.1 SYSTEM \"chapter1.xml\">\n" "<!ENTITY chapter.2 SYSTEM \"chapter2.xml\">\n" "<!ENTITY chapter.3 SYSTEM \"chapter3.xml\">" msgstr "" #. (itstool) path: example/para #: book.translate.xml:2994 msgid "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:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3000 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!-- Define a parameter entity to load in the chapter general entities -->\n" "<!ENTITY % chapters SYSTEM \"chapters.ent\">\n" "\n" "<!-- Now use the parameter entity to load in this file -->\n" "%chapters;\n" "]>\n" "\n" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " &chapter.1;\n" " &chapter.2;\n" " &chapter.3;\n" "html" msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:3021 msgid "Use General Entities to Include Files" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3025 msgid "Create three files, para1.xml, para2.xml, and para3.xml." msgstr "" #. (itstool) path: step/para #: book.translate.xml:3029 msgid "Put content like this in each file:" msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:3031 #, no-wrap msgid "pThis is the first paragraph.p" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3035 book.translate.xml:3088 msgid "Edit example.xml so that it looks like this:" msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:3038 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!ENTITY version \"1.1\">\n" "<!ENTITY para1 SYSTEM \"para1.xml\">\n" "<!ENTITY para2 SYSTEM \"para2.xml\">\n" "<!ENTITY para3 SYSTEM \"para3.xml\">\n" "]>\n" "\n" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " head\n" " titleAn Example XHTML Filetitle\n" " head\n" "\n" " body\n" " pThe current version of this document is: &version;p\n" "\n" " &para1;\n" " &para2;\n" " &para3;\n" " body\n" "html" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3062 book.translate.xml:3123 msgid "Produce example.html by normalizing example.xml." msgstr "" #. (itstool) path: step/screen #: book.translate.xml:3065 book.translate.xml:3126 #, no-wrap msgid "% xmllint --dropdtd --noent example.xml > example.html" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3069 book.translate.xml:3130 msgid "Load example.html into the web browser and confirm that the paran.xml files have been included in example.html." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:3079 msgid "Use Parameter Entities to Include Files" msgstr "" #. (itstool) path: note/para #: book.translate.xml:3082 msgid "The previous steps must have completed before this step." msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:3091 #, no-wrap msgid "" "<!DOCTYPE html PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"\n" "\"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd\" [\n" "<!ENTITY % entities SYSTEM \"entities.ent\"> %entities;\n" "]>\n" "\n" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " head\n" " titleAn Example XHTML Filetitle\n" " head\n" "\n" " body\n" " pThe current version of this document is: &version;p\n" "\n" " &para1;\n" " &para2;\n" " &para3;\n" " body\n" "html" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3112 msgid "Create a new file called entities.ent with this content:" msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:3116 #, no-wrap msgid "" "<!ENTITY version \"1.1\">\n" "<!ENTITY para1 SYSTEM \"para1.xml\">\n" "<!ENTITY para2 SYSTEM \"para2.xml\">\n" "<!ENTITY para3 SYSTEM \"para3.xml\">" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3142 msgid "Marked Sections" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3144 msgid "XML provides a mechanism to indicate that particular pieces of the document should be processed in a special way. These are called marked sections." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3150 msgid "Structure of a Marked Section" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3152 #, no-wrap msgid "" "<![KEYWORD[\n" " Contents of marked section\n" "]]>" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3157 msgid "As expected of an XML construct, a marked section starts with <!." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3160 msgid "The first square bracket begins the marked section." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3162 msgid "KEYWORD describes how this marked section is to be processed by the parser." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3165 msgid "The second square bracket indicates the start of the marked section's content." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3168 msgid "The marked section is finished by closing the two square brackets, and then returning to the document context from the XML context with >." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3174 msgid "Marked Section Keywords" msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:3177 msgid "CDATA" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3179 msgid "These keywords denote the marked sections content model, and allow you to change it from the default." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3183 msgid "When an XML parser is processing a document, it keeps track of the content model." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3187 msgid "The content model describes the content the parser is expecting to see and what it will do with that content." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3191 msgid "The CDATA content model is one of the most useful." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3194 msgid "CDATA is for Character Data. When the parser is in this content model, it expects to see only characters. In this model the < and & symbols lose their special status, and will be treated as ordinary characters." msgstr "" #. (itstool) path: note/para #: book.translate.xml:3202 msgid "When using CDATA in examples of text marked up in XML, remember that the content of CDATA is not validated. The included text must be check with other means. For example, the content could be written in another document, validated, and then pasted into the CDATA section." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3212 msgid "Using a CDATA Marked Section" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3215 #, no-wrap msgid "" "paraHere is an example of how to include some text that contains\n" " many literal&lt;literal and literal&amp;literal\n" " symbols. The sample text is a fragment of\n" " acronymXHTMLacronym. The surrounding text (para and\n" " programlisting) are from DocBook.para\n" "\n" "programlisting<![CDATA[pThis is a sample that shows some of the\n" " elements within acronymXHTMLacronym. Since the angle\n" " brackets are used so many times, it is simpler to say the whole\n" " example is a CDATA marked section than to use the entity names for\n" " the left and right angle brackets throughout.p\n" "\n" " ul\n" " liThis is a listitemli\n" " liThis is a second listitemli\n" " liThis is a third listitemli\n" " ul\n" "\n" " pThis is the end of the example.p]]>programlisting" msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:3238 msgid "INCLUDE and IGNORE" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3241 msgid "When the keyword is INCLUDE, then the contents of the marked section will be processed. When the keyword is IGNORE, the marked section is ignored and will not be processed. It will not appear in the output." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3248 msgid "Using INCLUDE and IGNORE in Marked Sections" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3251 #, no-wrap msgid "" "<![INCLUDE[\n" " This text will be processed and included.\n" "]]>\n" "\n" "<![IGNORE[\n" " This text will not be processed or included.\n" "]]>" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3260 msgid "By itself, this is not too useful. Text to be removed from the document could be cut out, or wrapped in comments." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3264 msgid "It becomes more useful when controlled by parameter entities, yet this usage is limited to entity files." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3269 msgid "For example, suppose that documentation was produced in a hard-copy version and an electronic version. Some extra text is desired in the electronic version content that was not to appear in the hard-copy." msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3274 msgid "" "Create an entity file that defines general entities to include each chapter and guard these definitions with a parameter entity that can be set to either INCLUDE or IGNORE to control whether the entity is defined. After these conditional general entity definitions, place one more definition for each general entity to set them to an empty value. This technique makes use of " "the fact that entity definitions cannot be overridden but the first definition always takes effect. So the inclusion of the chapter is controlled with the corresponding parameter entity. Set to INCLUDE, the first general entity definition will be read and the second one will be ignored. Set to IGNORE, the first definition will be ignored and the second one will take " "effect." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3291 msgid "Using a Parameter Entity to Control a Marked Section" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3294 #, no-wrap msgid "" "<!ENTITY % electronic.copy \"INCLUDE\">\n" "\n" "<![%electronic.copy;[\n" "<!ENTITY chap.preface\tSYSTEM \"preface.xml\">\n" "]]>\n" "\n" "<!ENTITY chap.preface \"\">" msgstr "" #. (itstool) path: example/para #: book.translate.xml:3302 msgid "When producing the hard-copy version, change the parameter entity's definition to:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3305 #, no-wrap msgid "<!ENTITY % electronic.copy \"IGNORE\">" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3315 msgid "Modify entities.ent to contain the following:" msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:3318 #, no-wrap msgid "" "<!ENTITY version \"1.1\">\n" "<!ENTITY % conditional.text \"IGNORE\">\n" "\n" "<![%conditional.text;[\n" "<!ENTITY para1 SYSTEM \"para1.xml\">\n" "]]>\n" "\n" "<!ENTITY para1 \"\">\n" "\n" "<!ENTITY para2 SYSTEM \"para2.xml\">\n" "<!ENTITY para3 SYSTEM \"para3.xml\">" msgstr "" #. (itstool) path: step/para #: book.translate.xml:3332 msgid "Normalize example.xml and notice that the conditional text is not present in the output document. Set the parameter entity guard to INCLUDE and regenerate the normalized document and the text will appear again. This method makes sense if there are more conditional chunks depending on the same condition. For example, to control generating printed or online text." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3347 msgid "Conclusion" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3349 msgid "That is the conclusion of this XML primer. For reasons of space and complexity, several things have not been covered in depth (or at all). However, the previous sections cover enough XML to introduce the organization of the FDP documentation." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:3391 msgid "XHTML Markup" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3394 book.translate.xml:3997 book.translate.xml:7244 msgid "Introduction" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3396 msgid "This chapter describes usage of the XHTML markup language used for the FreeBSD web site." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3399 msgid "XHTML is the XML version of the HyperText Markup Language, the markup language of choice on the World Wide Web. More information can be found at http://www.w3.org/." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3404 msgid "XHTML is used to mark up pages on the FreeBSD web site. It is usually not used to mark up other documentation, since DocBook offers a far richer set of elements from which to choose. Consequently, XHTML pages will normally only be encountered when writing for the web site." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3411 msgid "HTML has gone through a number of versions. The XML-compliant version described here is called XHTML. The latest widespread version is XHTML 1.0, available in both strict and transitional variants." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3418 msgid "The XHTML DTDs are available from the Ports Collection in textproc/xhtml. They are automatically installed by the textproc/docproj port." msgstr "" #. (itstool) path: note/para #: book.translate.xml:3424 msgid "This is not an exhaustive list of elements, since that would just repeat the documentation for XHTML. The aim is to list those elements most commonly used. Please post questions about elements or uses not covered here to the FreeBSD documentation project mailing list." msgstr "" #. (itstool) path: note/title #: book.translate.xml:3432 book.translate.xml:4036 msgid "Inline Versus Block" msgstr "" #. (itstool) path: note/para #: book.translate.xml:3434 book.translate.xml:4038 msgid "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." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3444 msgid "Formal Public Identifier (FPI)" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3446 msgid "There are a number of XHTML FPIs, depending upon the version, or level of XHTML to which a document conforms. Most XHTML documents on the FreeBSD web site comply with the transitional version of XHTML 1.0." msgstr "" #. (itstool) path: sect1/programlisting #: book.translate.xml:3453 #, no-wrap msgid "PUBLIC \"-//W3C//DTD XHTML 1.0 Transitional//EN\"" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3457 msgid "Sectional Elements" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3459 msgid "An XHTML 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 content that will be displayed to the user." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3467 msgid "These sections are indicated with head and body elements respectively. These elements are contained within the top-level html element." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3473 msgid "Normal XHTML Document Structure" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3476 #, no-wrap msgid "" "html xmlns=\"http://www.w3.org/1999/xhtml\"\n" " head\n" "\t titleThe Document's Titletitle\n" " head\n" "\n" " body\n" "\n" " …\n" "\n" " body\n" "html" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3491 book.translate.xml:4636 msgid "Block Elements" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3494 msgid "Headings" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3496 msgid "XHTML has tags to denote headings in the document at up to six different levels." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3499 msgid "The largest and most prominent heading is h1, then h2, continuing down to h6." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3503 msgid "The element's content is the text of the heading." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3506 msgid "h1, h2, and Other Header Tags" msgstr "" #. (itstool) path: example/para #: book.translate.xml:3509 book.translate.xml:3544 book.translate.xml:3560 book.translate.xml:3605 book.translate.xml:3637 book.translate.xml:3714 book.translate.xml:3742 book.translate.xml:3764 book.translate.xml:3786 book.translate.xml:3842 book.translate.xml:3859 book.translate.xml:3889 book.translate.xml:3914 book.translate.xml:4655 book.translate.xml:4681 book.translate.xml:4762 book.translate.xml:4796 #: book.translate.xml:4843 book.translate.xml:4903 book.translate.xml:4965 book.translate.xml:5045 book.translate.xml:5179 book.translate.xml:5340 book.translate.xml:5399 book.translate.xml:5426 book.translate.xml:5456 book.translate.xml:5495 book.translate.xml:5603 book.translate.xml:5660 book.translate.xml:5711 book.translate.xml:5830 book.translate.xml:5898 book.translate.xml:5927 book.translate.xml:5948 #: book.translate.xml:5990 book.translate.xml:6045 book.translate.xml:6078 book.translate.xml:6095 book.translate.xml:6129 book.translate.xml:6153 book.translate.xml:6633 book.translate.xml:6649 msgid "Usage:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3511 #, no-wrap msgid "" "h1First sectionh1\n" "\n" "<!-- Document introduction goes here -->\n" "\n" "h2This is the heading for the first sectionh2\n" "\n" "<!-- Content for the first section goes here -->\n" "\n" "h3This is the heading for the first sub-sectionh3\n" "\n" "<!-- Content for the first sub-section goes here -->\n" "\n" "h2This is the heading for the second sectionh2\n" "\n" "<!-- Content for the second section goes here -->" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3528 msgid "Generally, an XHTML 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. Do not leave gaps in the numbering." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3536 book.translate.xml:4639 msgid "Paragraphs" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3538 msgid "XHTML supports a single paragraph element, p." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3542 msgid "p Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3546 #, no-wrap msgid "" "pThis is a paragraph. It can contain just about any\n" " other element.p" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3552 book.translate.xml:4668 msgid "Block Quotations" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3554 msgid "A block quotation is an extended quotation from another document that will appear in a separate paragraph." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3558 book.translate.xml:4679 msgid "blockquote Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3562 #, no-wrap msgid "" "pA small excerpt from the US Constitution:p\n" "\n" "blockquoteWe the People of the United States, in Order to form\n" " a more perfect Union, establish Justice, insure domestic\n" " Tranquility, provide for the common defence, promote the general\n" " Welfare, and secure the Blessings of Liberty to ourselves and our\n" " Posterity, do ordain and establish this Constitution for the\n" " United States of America.blockquote" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3574 msgid "Lists" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3576 msgid "XHTML can present the user with three types of lists: ordered, unordered, and definition." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3579 msgid "Entries in an ordered list will be numbered, while entries in an unordered list will be preceded by bullet points. Definition lists have two sections for each entry. The first section is the term being defined, and the second section is the definition." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3585 msgid "Ordered lists are indicated by the ol element, unordered lists by the ul element, and definition lists by the dl element." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3590 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3595 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3602 msgid "ul and ol Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3607 #, no-wrap msgid "" "pAn unordered list. Listitems will probably be\n" " preceded by bullets.p\n" "\n" "ul\n" " liFirst itemli\n" "\n" " liSecond itemli\n" "\n" " liThird itemli\n" "ul\n" "\n" "pAn ordered list, with list items consisting of multiple\n" " paragraphs. Each item (note: not each paragraph) will be\n" " numbered.p\n" "\n" "ol\n" " lipThis is the first item. It only has one paragraph.pli\n" "\n" " lipThis is the first paragraph of the second item.p\n" "\n" " pThis is the second paragraph of the second item.pli\n" "\n" " lipThis is the first and only paragraph of the third\n" " item.pli\n" "ol" msgstr "" #. (itstool) path: example/title #: book.translate.xml:3635 msgid "Definition Lists with dl" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3639 #, no-wrap msgid "" "dl\n" " dtTerm 1dt\n" "\n" " ddpParagraph 1 of definition 1.p\n" "\n" " pParagraph 2 of definition 1.pdd\n" "\n" " dtTerm 2dt\n" "\n" " ddpParagraph 1 of definition 2.pdd\n" "\n" " dtTerm 3dt\n" "\n" " ddpParagraph 1 of definition 3.pdd\n" "dl" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3658 msgid "Pre-formatted Text" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3660 msgid "Pre-formatted text is shown to the user exactly as it is in the file. Text is shown in a fixed font. Multiple spaces and line breaks are shown exactly as they are in the file." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3665 msgid "Wrap pre-formatted text in the pre element." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3669 msgid "pre Example" msgstr "" #. (itstool) path: example/para #: book.translate.xml:3671 msgid "For example, the pre tags could be used to mark up an email message:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3674 #, no-wrap msgid "" "pre From: nik@FreeBSD.org\n" " To: freebsd-doc@FreeBSD.org\n" " Subject: New documentation available\n" "\n" " There is a new copy of my primer for contributors to the FreeBSD\n" " Documentation Project available at\n" "\n" " &lt;URL:http://people.FreeBSD.org/~nik/primer/index.html&gt;\n" "\n" " Comments appreciated.\n" "\n" " Npre" msgstr "" #. (itstool) path: example/para #: book.translate.xml:3687 msgid "" "Keep in mind that < and & still are recognized as special characters in pre-formatted text. This is why the example shown had to use &lt; instead of <. For consistency, &gt; was used in place of >, too. Watch out for the special characters that may appear in text copied from a " "plain-text source, like an email message or program code." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3700 book.translate.xml:5152 msgid "Tables" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3702 msgid "" "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 the pelement is not " "needed." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3712 msgid "Simple Use of table" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3716 #, no-wrap msgid "" "pThis is a simple 2x2 table.p\n" "\n" "table\n" " tr\n" " tdTop left celltd\n" "\n" " tdTop right celltd\n" " tr\n" "\n" " tr\n" " tdBottom left celltd\n" "\n" " tdBottom right celltd\n" " tr\n" "table" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3733 msgid "A cell can span multiple rows and columns by adding the rowspan or colspan attributes with values for the number of rows or columns to be spanned." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3739 msgid "Using rowspan" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3744 #, no-wrap msgid "" "pOne tall thin cell on the left, two short cells next to\n" " it on the right.p\n" "\n" "table\n" " tr\n" " td rowspan=\"2\"Long and thintd\n" " tr\n" "\n" " tr\n" " tdTop celltd\n" "\n" " tdBottom celltd\n" " tr\n" "table" msgstr "" #. (itstool) path: example/title #: book.translate.xml:3761 msgid "Using colspan" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3766 #, no-wrap msgid "" "pOne long cell on top, two short cells below it.p\n" "\n" "table\n" " tr\n" " td colspan=\"2\"Top celltd\n" " tr\n" "\n" " tr\n" " tdBottom left celltd\n" "\n" " tdBottom right celltd\n" " tr\n" "table" msgstr "" #. (itstool) path: example/title #: book.translate.xml:3782 msgid "Using rowspan and colspan Together" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3788 #, no-wrap msgid "" "pOn a 3x3 grid, the top left block is a 2x2 set of\n" " cells merged into one. The other cells are normal.p\n" "\n" "table\n" " tr\n" " td colspan=\"2\" rowspan=\"2\"Top left large celltd\n" "\n" " tdTop right celltd\n" " tr\n" "\n" " tr\n" " <!-- Because the large cell on the left merges into\n" " this row, the first <td> will occur on its\n" " right -->\n" "\n" " tdMiddle right celltd\n" " tr\n" "\n" " tr\n" " tdBottom left celltd\n" "\n" " tdBottom middle celltd\n" "\n" " tdBottom right celltd\n" " tr\n" "table" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:3819 book.translate.xml:5378 msgid "In-line Elements" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3822 book.translate.xml:5381 msgid "Emphasizing Information" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3824 msgid "Two levels of emphasis are available in XHTML, em and strong. em is for a normal level of emphasis and strong indicates stronger emphasis." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3830 msgid "em is typically rendered in italic and strong is rendered in bold. This is not always the case, and should not be relied upon. According to best practices, web pages only hold structural and semantical information, and stylesheets are later applied to them. Think of semantics, not formatting, when using these tags." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3839 msgid "em and strong Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3844 #, no-wrap msgid "" "pemThisem has been emphasized, while\n" " strongthisstrong has been strongly emphasized.p" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:3850 msgid "Indicating Fixed-Pitch Text" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:3852 msgid "Content that should be rendered in a fixed pitch (typewriter) typeface is tagged with tt (for teletype)." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3857 msgid "tt Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3861 #, no-wrap msgid "" "pMany system settings are stored in\n" " tt/etctt.p" msgstr "" #. (itstool) path: sect2/title #. (itstool) path: sect1/title #: book.translate.xml:3867 book.translate.xml:6471 msgid "Links" msgstr "" #. (itstool) path: note/para #: book.translate.xml:3870 msgid "Links are also inline elements." msgstr "" #. (itstool) path: sect3/title #. (itstool) path: sect2/title #: book.translate.xml:3874 book.translate.xml:6566 msgid "Linking to Other Documents on the Web" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3876 msgid "A link points to the URL of a document on the web. 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, indicated to the user by showing it in a different color or with an underline." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3886 msgid "Using a href=\"...\"" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3891 #, no-wrap msgid "" "pMore information is available at the\n" " a href=\"http://www.&os;.org/\"&os; web sitea.p" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3895 msgid "This link always takes the user to the top of the linked document." msgstr "" #. (itstool) path: sect3/title #: book.translate.xml:3900 msgid "Linking to Specific Parts of Documents" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3902 msgid "To link to a specific point within a document, that document must include an anchor at the desired point. Anchors are included by setting the id attribute of an element to a name. This example creates an anchor by setting the id attribute of a p element." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3912 msgid "Creating an Anchor" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3916 #, no-wrap msgid "" "p id=\"samplepara\"This paragraph can be referenced\n" " in other links with the name ttsampleparatt.p" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3920 msgid "Links to anchors are similar to plain links, but include a # symbol and the anchor's ID at the end of the URL." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3926 msgid "Linking to a Named Part of a Different Document" msgstr "" #. (itstool) path: example/para #: book.translate.xml:3929 msgid "The samplepara example is part of a document called foo.html. A link to that specific paragraph in the document is constructed in this example." msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3934 #, no-wrap msgid "" "pMore information can be found in the\n" " a href=\"foo.html#samplepara\"sample paragrapha of\n" " ttfoo.htmltt.p" msgstr "" #. (itstool) path: sect3/para #: book.translate.xml:3939 msgid "To link to a named anchor within the same document, omit the document's URL, and just use the # symbol followed by the name of the anchor." msgstr "" #. (itstool) path: example/title #: book.translate.xml:3945 msgid "Linking to a Named Part of the Same Document" msgstr "" #. (itstool) path: example/para #: book.translate.xml:3947 msgid "The samplepara example resides in this document. To link to it:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:3950 #, no-wrap msgid "" "pMore information can be found in the\n" " a href=\"#samplepara\"sample paragrapha of this\n" " document.p" msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:3994 msgid "DocBook Markup" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:3999 msgid "" "This chapter is an introduction to DocBook as it is used for FreeBSD documentation. DocBook is a large and complex markup system, but the subset described here covers the parts that are most widely used for FreeBSD documentation. While a moderate subset is covered, it is impossible to anticipate every situation. Please post questions that this document does not answer to the FreeBSD documentation project mailing list." msgstr "" #. (itstool) path: footnote/para #: book.translate.xml:4010 msgid "A short history can be found under http://www.oasis-open.org/docbook/intro.shtml#d0e41." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4007 msgid "" "DocBook was originally developed by HaL Computer Systems and O'Reilly & Associates to be a Document Type Definition (DTD) for writing technical documentation <_:footnote-1/>. Since 1998 it is maintained by the DocBook Technical Committee. As such, and unlike LinuxDoc and XHTML, DocBook is very heavily oriented towards markup that describes what something is, rather than describing how it should be presented." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4018 msgid "The DocBook DTD is available from the Ports Collection in the textproc/docbook-xml port. It is automatically installed as part of the textproc/docproj port." msgstr "" #. (itstool) path: note/title #: book.translate.xml:4026 msgid "Formal Versus Informal" msgstr "" #. (itstool) path: note/para #: book.translate.xml:4028 msgid "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." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:4048 msgid "FreeBSD Extensions" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4050 msgid "The FreeBSD Documentation Project has extended the DocBook DTD with additional elements and entities. These additions serve to make some of the markup easier or more precise." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4055 msgid "Throughout the rest of this document, the term DocBook is used to mean the FreeBSD-extended DocBook DTD." msgstr "" #. (itstool) path: note/para #: book.translate.xml:4060 msgid "Most of these extensions are not unique to FreeBSD, 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 contact Documentation Engineering Team doceng@FreeBSD.org." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4069 msgid "FreeBSD Elements" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4071 msgid "The additional FreeBSD elements are not (currently) in the Ports Collection. They are stored in the FreeBSD Subversion tree, as head/share/xml/freebsd.dtd." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4075 msgid "FreeBSD-specific elements used in the examples below are clearly marked." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4080 msgid "FreeBSD Entities" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4082 msgid "This table shows some of the most useful entities available in the FDP. For a complete list, see the *.ent files in doc/share/xml." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4102 msgid "FreeBSD Name Entities" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4107 msgid "&os;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4108 -#, fuzzy msgid "FreeBSD" -msgstr "FreeBSD is een geregistreerd handelsmerk van de FreeBSD Foundation." +msgstr "FreeBSD" #. (itstool) path: row/entry #: book.translate.xml:4113 msgid "&os.stable;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4114 msgid "FreeBSD-STABLE" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4119 msgid "&os.current;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4120 msgid "FreeBSD-CURRENT" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4131 msgid "Manual Page Entities" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4136 msgid "&man.ls.1;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4137 msgid "ls1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4138 msgid "Usage: &man.ls.1; is the manual page for <command>ls</command>." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4144 msgid "&man.cp.1;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4145 msgid "cp1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4146 msgid "Usage: The manual page for <command>cp</command> is &man.cp.1;." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4152 msgid "&man.command.sectionnumber;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4153 msgid "link to command manual page in section sectionnumber" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4157 msgid "Entities are defined for all the FreeBSD manual pages." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4169 msgid "FreeBSD Mailing List Entities" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4174 msgid "&a.doc;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4175 msgid "FreeBSD documentation project mailing list" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4176 msgid "Usage: A link to the &a.doc;." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4181 msgid "&a.questions;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4182 msgid "FreeBSD general questions mailing list" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4183 msgid "Usage: A link to the &a.questions;." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4188 msgid "&a.listname;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4189 msgid "link to listname" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4191 msgid "Entities are defined for all the FreeBSD mailing lists." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4202 msgid "FreeBSD Document Link Entities" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4207 msgid "&url.books.handbook;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4208 msgid "@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/books/handbook" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4209 msgid "Usage: A link to the <link xlink:href=\"&url.books.handbook;/advanced-networking.html\">Advanced Networking</link> chapter of the Handbook." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4216 msgid "&url.books.bookname;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4217 msgid "relative path to bookname" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4219 msgid "Entities are defined for all the FreeBSD books." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4224 msgid "&url.articles.committers-guide;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4225 msgid "@@URL_RELPREFIX@@/doc/en_US.ISO8859-1/articles/committers-guide" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4226 msgid "Usage: A link to the <link xlink:href=\"&url.articles.committers-guide;\">Committer's Guide</link> article." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4233 msgid "&url.articles.articlename;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4234 msgid "relative path to articlename" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4236 msgid "Entities are defined for all the FreeBSD articles." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4247 msgid "Other Operating System Name Entities" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4252 msgid "&linux;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4253 -#, fuzzy msgid "Linux" -msgstr "Linux is een geregistreerd handelsmerk van Linus Torvalds." +msgstr "Linux" #. (itstool) path: row/entry #: book.translate.xml:4254 msgid "The Linux operating system." msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:4258 book.translate.xml:8633 +#: book.translate.xml:4258 book.translate.xml:8667 msgid "&unix;" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:4259 book.translate.xml:8632 -#, fuzzy +#: book.translate.xml:4259 book.translate.xml:8666 msgid "UNIX" -msgstr "Wat, een echte UNIX?" +msgstr "UNIX" #. (itstool) path: row/entry #: book.translate.xml:4260 -#, fuzzy msgid "The UNIX operating system." -msgstr "" -"In de open-source wereld is het woord Linux bijna een synoniem van besturingssysteem, maar het is niet het enige open-source UNIX besturingssysteem. Volgens de Internet Operating System Counter, draait sinds april 1999 31.3% van de machines op de wereld die met " -"een netwerk verbonden zijn Linux. 14.6% draait BSD UNIX. Sommige van 's werelds grootste webinstallaties, zoals Yahoo!, draaien BSD. De drukste FTP-server van de wereld van 1999 (nu buiten werking), ftp.cdrom.com, gebruikte BSD om 1.4 TB aan gegevens per dag over te " -"brengen. Het is duidelijk dat dit geen nichemarkt is: BSD is een goed bewaard geheim." +msgstr "Het UNIX besturingssysteem." #. (itstool) path: row/entry #: book.translate.xml:4264 msgid "&windows;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4265 -#, fuzzy msgid "Windows" -msgstr "Wat, een echte UNIX?" +msgstr "Windows" #. (itstool) path: row/entry #: book.translate.xml:4266 msgid "The Windows operating system." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4276 msgid "Miscellaneous Entities" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4281 msgid "&prompt.root;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4283 msgid "The root user prompt." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4288 msgid "&prompt.user;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4290 msgid "A prompt for an unprivileged user." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4294 msgid "&postscript;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4295 -#, fuzzy msgid "PostScript" -msgstr "Wat, een echte UNIX?" +msgstr "PostScript" #. (itstool) path: row/entry #: book.translate.xml:4296 msgid "The PostScript programming language." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4301 msgid "&tex;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4302 msgid "TeX" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4303 msgid "The TeX typesetting language." msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4308 msgid "&xorg;" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4309 msgid "Xorg" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:4310 msgid "The Xorg open source X Window System." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:4320 msgid "Formal Public Identifier (FPI)" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4322 msgid "In compliance with the DocBook guidelines for writing FPIs for DocBook customizations, the FPI for the FreeBSD extended DocBook DTD is:" msgstr "" #. (itstool) path: sect1/programlisting #: book.translate.xml:4327 #, no-wrap msgid "PUBLIC \"-//FreeBSD//DTD DocBook V4.2-Based Extension//EN\"" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:4331 msgid "Document Structure" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4333 msgid "DocBook allows structuring documentation in several ways. The FreeBSD Documentation Project uses two primary types of DocBook document: the book and the article." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4337 msgid "Books are organized into chapters. This is a mandatory requirement. There may be parts between the book and the chapter to provide another layer of organization. For example, the Handbook is arranged in this way." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4343 msgid "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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4349 msgid "Chapters and sections contain the remainder of the content." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4352 msgid "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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4358 msgid "" "The nature of the document being written should be used to determine 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." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:4367 msgid "The FreeBSD tutorials are all marked up as articles, while this document, the FAQ, and the Handbook are all marked up as books, for example." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4374 msgid "Starting a Book" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4376 msgid "The content of a 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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4383 book.translate.xml:4438 msgid "This additional information is contained within info." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4387 msgid "Boilerplate book with info" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4393 #, no-wrap msgid "" "book\n" " info\n" " titleYour Title Heretitle\n" "\n" " author\n" " personname\n" " firstnameYour first namefirstname\n" " surnameYour surnamesurname\n" " personname\n" "\n" " affiliation\n" "\taddress\n" " emailYour email addressemail\n" "\taddress\n" " affiliation\n" " author\n" "\n" " copyright\n" " year1998year\n" " holder role=\"mailto:your email address\"Your nameholder\n" " copyright\n" "\n" " releaseinfo$FreeBSD$releaseinfo\n" "\n" " abstract\n" " paraInclude an abstract of the book's contents here.para\n" " abstract\n" " info\n" "\n" " …\n" "\n" "book" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4429 msgid "Starting an Article" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4431 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4442 msgid "Boilerplate article with info" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4448 #, no-wrap msgid "" "article\n" " info\n" " titleYour title heretitle\n" "\n" " author\n" " personname\n" "\tfirstnameYour first namefirstname\n" "\tsurnameYour surnamesurname\n" " personname\n" "\n" " affiliation\n" "\taddress\n" "\t emailYour email addressemailaddress\n" "\taddress\n" " affiliation\n" " author\n" "\n" " copyright\n" " year1998year\n" " holder role=\"mailto:your email address\"Your nameholder\n" " copyright\n" "\n" " releaseinfo$FreeBSD$releaseinfo\n" "\n" " abstract\n" " paraInclude an abstract of the article's contents here.para\n" " abstract\n" " info\n" "\n" " …\n" "\n" "article" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4484 msgid "Indicating Chapters" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4486 msgid "Use chapter to mark up your chapters. Each chapter has a mandatory title. Articles do not contain chapters, they are reserved for books." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4492 msgid "A Simple Chapter" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4494 #, no-wrap msgid "" "chapter\n" " titleThe Chapter's Titletitle\n" "\n" " ...\n" "chapter" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4501 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4507 msgid "Empty Chapters" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4509 #, no-wrap msgid "" "chapter\n" " titleThis is An Empty Chaptertitle\n" "\n" " parapara\n" "chapter" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4518 msgid "Sections Below Chapters" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4520 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4528 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4536 msgid "Sections in Chapters" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4538 #, no-wrap msgid "" "chapter\n" " titleA Sample Chaptertitle\n" "\n" " paraSome text in the chapter.para\n" "\n" " sect1\n" " titleFirst Sectiontitle\n" "\n" " …\n" " sect1\n" "\n" " sect1\n" " titleSecond Sectiontitle\n" "\n" " sect2\n" " titleFirst Sub-Sectiontitle\n" "\n" " sect3\n" "\ttitleFirst Sub-Sub-Sectiontitle\n" "\n" "\t…\n" " sect3\n" " sect2\n" "\n" " sect2\n" " titleSecond Sub-Section (1.2.2)title\n" "\n" " …\n" " sect2\n" " sect1\n" "chapter" msgstr "" #. (itstool) path: note/para #: book.translate.xml:4572 msgid "Section numbers are automatically generated and prepended to titles when the document is rendered to an output format. The generated section numbers and titles from the example above will be:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4579 msgid "1.1. First Section" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4583 msgid "1.2. Second Section" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4587 msgid "1.2.1. First Sub-Section" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4591 msgid "1.2.1.1. First Sub-Sub-Section" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4595 msgid "1.2.2. Second Sub-Section" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4602 msgid "Subdividing Using part Elements" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4605 msgid "parts introduce another level of organization between book and chapter with one or more parts. This cannot be done in an article." msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:4611 #, no-wrap msgid "" "part\n" " titleIntroductiontitle\n" "\n" " chapter\n" " titleOverviewtitle\n" "\n" " ...\n" " chapter\n" "\n" " chapter\n" " titleWhat is FreeBSD?title\n" "\n" " ...\n" " chapter\n" "\n" " chapter\n" " titleHistorytitle\n" "\n" " ...\n" " chapter\n" "part" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4641 msgid "DocBook supports three types of paragraphs: formalpara, para, and simpara." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4645 msgid "Almost all paragraphs in FreeBSD documentation use para. formalpara includes a title element, and simpara disallows some elements from within para. Stick with para." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4653 msgid "para Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4657 #, no-wrap msgid "" "paraThis is a paragraph. It can contain just about any\n" " other element.para" msgstr "" #. (itstool) path: example/para #. (itstool) path: sect2/para #: book.translate.xml:4660 book.translate.xml:4698 book.translate.xml:4775 book.translate.xml:4806 book.translate.xml:4865 book.translate.xml:4927 book.translate.xml:4995 book.translate.xml:5062 book.translate.xml:5120 book.translate.xml:5204 book.translate.xml:5244 book.translate.xml:5353 book.translate.xml:5405 book.translate.xml:5434 book.translate.xml:5462 book.translate.xml:5510 book.translate.xml:5622 #: book.translate.xml:5672 book.translate.xml:5719 book.translate.xml:5856 book.translate.xml:5904 book.translate.xml:5933 book.translate.xml:5954 book.translate.xml:6006 book.translate.xml:6052 book.translate.xml:6082 book.translate.xml:6105 book.translate.xml:6135 book.translate.xml:6157 book.translate.xml:6609 book.translate.xml:6623 book.translate.xml:6638 book.translate.xml:6656 msgid "Appearance:" msgstr "" #. (itstool) path: example/para #: book.translate.xml:4662 msgid "This is a paragraph. It can contain just about any other element." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4670 msgid "A block quotation is an extended quotation from another document that should not appear within the current paragraph. These are rarely needed." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4674 msgid "Blockquotes can optionally contain a title and an attribution (or they can be left untitled and unattributed)." msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4683 #, no-wrap msgid "" "paraA small excerpt from the US Constitution:para\n" "\n" "blockquote\n" " titlePreamble to the Constitution of the United Statestitle\n" "\n" " attributionCopied from a web site somewhereattribution\n" "\n" " paraWe the People of the United States, in Order to form a more\n" " perfect Union, establish Justice, insure domestic Tranquility,\n" " provide for the common defence, promote the general Welfare, and\n" " secure the Blessings of Liberty to ourselves and our Posterity, do\n" " ordain and establish this Constitution for the United States of\n" " America.para\n" "blockquote" msgstr "" #. (itstool) path: example/para #: book.translate.xml:4700 msgid "A small excerpt from the US Constitution:" msgstr "" #. (itstool) path: blockquote/title #: book.translate.xml:4703 msgid "Preamble to the Constitution of the United States" msgstr "" #. (itstool) path: blockquote/attribution #: book.translate.xml:4706 msgid "Copied from a web site somewhere" msgstr "" #. (itstool) path: blockquote/para #: book.translate.xml:4709 msgid "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." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4721 msgid "Tips, Notes, Warnings, Cautions, and Important Information" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4724 msgid "Extra information may need to be separated from the main body of the text. Typically this is meta information of which the user should be aware." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4729 msgid "Several types of admonitions are available: tip, note, warning, caution, and important." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4734 msgid "Which admonition to choose depends on the situation. The DocBook documentation suggests:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4740 msgid "Note is for information that should be heeded by all readers." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4745 msgid "Important is a variation on Note." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4749 msgid "Caution is for information regarding possible data loss or software damage." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4754 msgid "Warning is for information regarding possible hardware damage or injury to life or limb." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4760 msgid "tip and important Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4764 #, no-wrap msgid "" "tip\n" " para&os; may reduce stress.para\n" "tip\n" "\n" "important\n" " paraPlease use admonitions sparingly. Too many admonitions\n" " are visually jarring and can have the opposite of the\n" " intended effect.para\n" "important" msgstr "" #. (itstool) path: tip/para #: book.translate.xml:4778 msgid "FreeBSD may reduce stress." msgstr "" #. (itstool) path: important/para #: book.translate.xml:4782 msgid "Please use admonitions sparingly. Too many admonitions are visually jarring and can have the opposite of the intended effect." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4791 msgid "Examples can be shown with example." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4794 msgid "example Source" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4798 #, no-wrap msgid "" "example\n" " paraEmpty files can be created easily:para\n" "\n" " screen&prompt.user; userinputtouch file1 file2 file3userinputscreen\n" "example" msgstr "" #. (itstool) path: example/title #: book.translate.xml:4809 msgid "Rendered example" msgstr "" #. (itstool) path: example/para #: book.translate.xml:4811 msgid "Empty files can be created easily:" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:4813 #, no-wrap msgid "% touch file1 file2 file3" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:4818 msgid "Lists and Procedures" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4820 msgid "Information often needs to be presented as lists, or as a number of steps that must be carried out in order to accomplish a particular goal." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4824 msgid "To do this, use itemizedlist, orderedlist, variablelist, or procedure. There are other types of list elements in DocBook, but we will not cover them here." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4829 msgid "" "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4840 msgid "itemizedlist and orderedlist Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4845 #, no-wrap msgid "" "itemizedlist\n" " listitem\n" " paraThis is the first itemized item.para\n" " listitem\n" "\n" " listitem\n" " paraThis is the second itemized item.para\n" " listitem\n" "itemizedlist\n" "\n" "orderedlist\n" " listitem\n" " paraThis is the first ordered item.para\n" " listitem\n" "\n" " listitem\n" " paraThis is the second ordered item.para\n" " listitem\n" "orderedlist" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4869 msgid "This is the first itemized item." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4873 msgid "This is the second itemized item." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4879 msgid "This is the first ordered item." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4883 msgid "This is the second ordered item." msgstr "" #. (itstool) path: sect2/para #. (itstool) id: book.translate.xml#docbook-markup-varlist #: book.translate.xml:4888 msgid "An alternate and often useful way of presenting information is the variablelist. These are lists where each entry has a term and a description. They are well suited for many types of descriptions, and present information in a form that is often easier for the reader than sections and subsections." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4896 msgid "A variablelist has a title, and then pairs of term and listitem entries." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4901 msgid "variablelist Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4905 #, no-wrap msgid "" "variablelist\n" " varlistentry\n" " termParallelterm\n" "\n" " listitem\n" " paraIn parallel communications, groups of bits arrive\n" "\tat the same time over multiple communications\n" "\tchannels.para\n" " listitem\n" " varlistentry\n" "\n" " varlistentry\n" " termSerialterm\n" "\n" " listitem\n" " paraIn serial communications, bits arrive one at a\n" "\ttime over a single communications\n" "\tchannel.para\n" " listitem\n" " varlistentry\n" "variablelist" msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:4931 msgid "Parallel" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4934 msgid "In parallel communications, groups of bits arrive at the same time over multiple communications channels." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:4941 msgid "Serial" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:4944 msgid "In serial communications, bits arrive one at a time over a single communications channel." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4951 msgid "A procedure shows a series of steps, which may in turn consist of more steps or substeps. Each step contains block elements and may include an optional title." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:4957 msgid "Sometimes, steps are not sequential, but present a choice: do this or do that, but not both. For these alternative choices, use stepalternatives." msgstr "" #. (itstool) path: example/title #: book.translate.xml:4963 msgid "procedure Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:4967 #, no-wrap msgid "" "procedure\n" " step\n" " paraDo this.para\n" " step\n" "\n" " step\n" " paraThen do this.para\n" " step\n" "\n" " step\n" " paraAnd now do this.para\n" " step\n" "\n" " step\n" " paraFinally, do one of these.para\n" "\n" " stepalternatives\n" " step\n" "\tparaGo left.para\n" " step\n" "\n" " step\n" "\tparaGo right.para\n" " step\n" " stepalternatives\n" " step\n" "procedure" msgstr "" #. (itstool) path: step/para #: book.translate.xml:4999 msgid "Do this." msgstr "" #. (itstool) path: step/para #: book.translate.xml:5003 msgid "Then do this." msgstr "" #. (itstool) path: step/para #: book.translate.xml:5007 msgid "And now do this." msgstr "" #. (itstool) path: step/para #: book.translate.xml:5011 msgid "Finally, do one of these:" msgstr "" #. (itstool) path: step/para #: book.translate.xml:5015 msgid "Go left." msgstr "" #. (itstool) path: step/para #: book.translate.xml:5019 msgid "Go right." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5028 msgid "Showing File Samples" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5030 msgid "Fragments of a file (or perhaps a complete file) are shown by wrapping them in the programlisting element." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5034 msgid "White space and line breaks within programlisting are 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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5043 msgid "programlisting Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5047 #, no-wrap msgid "" "paraWhen finished, the program will look like\n" " this:para\n" "\n" "programlisting#include &lt;stdio.h&gt;\n" "\n" "int\n" "main(void)\n" "{\n" " printf(\"hello, world\\n\");\n" "}programlisting" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5058 msgid "Notice how the angle brackets in the #include line need to be referenced by their entities instead of being included literally." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5064 book.translate.xml:5122 msgid "When finished, the program will look like this:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5066 #, no-wrap msgid "" "#include <stdio.h>\n" "\n" "int\n" "main(void)\n" "{\n" " printf(\"hello, world\\n\");\n" "}" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5077 msgid "Callouts" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5079 msgid "A callout is a visual marker for referring to a piece of text or specific position within an example." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5083 msgid "Callouts are marked with the co element. Each element must have a unique id assigned to it. After the example, include a calloutlist that describes each callout." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5090 msgid "co and calloutlist Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5093 #, no-wrap msgid "" "paraWhen finished, the program will look like\n" " this:para\n" "\n" "programlisting#include &lt;stdio.h&gt; co xml:id=\"co-ex-include\"\n" "\n" "int co xml:id=\"co-ex-return\"\n" "main(void)\n" "{\n" " printf(\"hello, world\\n\"); co xml:id=\"co-ex-printf\"\n" "}programlisting\n" "\n" "calloutlist\n" " callout arearefs=\"co-ex-include\"\n" " paraIncludes the standard IO header file.para\n" " callout\n" "\n" " callout arearefs=\"co-ex-return\"\n" " paraSpecifies that functionmain()function returns an\n" " int.para\n" " callout\n" "\n" " callout arearefs=\"co-ex-printf\"\n" " paraThe functionprintf()function call that writes\n" " literalhello, worldliteral to standard output.para\n" " callout\n" "calloutlist" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5124 #, no-wrap msgid "" "#include <stdio.h> \n" "\n" "int \n" "main(void)\n" "{\n" " printf(\"hello, world\\n\"); \n" "}" msgstr "" #. (itstool) path: callout/para #: book.translate.xml:5134 msgid "Includes the standard IO header file." msgstr "" #. (itstool) path: callout/para #: book.translate.xml:5138 msgid "Specifies that main() returns an int." msgstr "" #. (itstool) path: callout/para #: book.translate.xml:5143 msgid "The printf() call that writes hello, world to standard output." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5154 msgid "Unlike HTML, DocBook does not need tables for layout purposes, as the stylesheet handles those issues. Instead, just use tables for marking up tabular data." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5159 msgid "" "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 there is one thead element, which contains elements for the table headings (column " "headings), and one tbody which contains the body of the table." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5170 msgid "Both tgroup and thead contain row elements, which in turn contain entry elements. Each entry element specifies one cell in the table." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5177 msgid "informaltable Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5181 #, no-wrap msgid "" "informaltable pgwide=\"1\"\n" " tgroup cols=\"2\"\n" " thead\n" " row\n" " entryThis is Column Head 1entry\n" " entryThis is Column Head 2entry\n" " row\n" " thead\n" "\n" " tbody\n" " row\n" "\tentryRow 1, column 1entry\n" "\tentryRow 1, column 2entry\n" " row\n" "\n" " row\n" "\tentryRow 2, column 1entry\n" "\tentryRow 2, column 2entry\n" " row\n" " tbody\n" " tgroup\n" "informaltable" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:5210 book.translate.xml:5250 msgid "This is Column Head 1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:5211 book.translate.xml:5251 msgid "This is Column Head 2" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:5217 book.translate.xml:5257 msgid "Row 1, column 1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:5218 book.translate.xml:5258 msgid "Row 1, column 2" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:5222 book.translate.xml:5262 msgid "Row 2, column 1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:5223 book.translate.xml:5263 msgid "Row 2, column 2" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5230 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5236 msgid "Table borders can be suppressed by setting the frame attribute to none in the informaltable element. For example, informaltable frame=\"none\"." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5242 msgid "Table with frame=\"none\" Example" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5272 msgid "Examples for the User to Follow" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5274 msgid "Examples for the user to follow are often necessary. Typically, these will consist of dialogs with the computer; the user types in a command, the user gets a response back, the user types another command, and so on." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5279 msgid "A number of distinct elements and entities come into play here." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5284 msgid "screen" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5287 msgid "Everything the user sees in this example will be on the computer screen, so the next element is screen." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5291 msgid "Within screen, white space is significant." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5297 msgid "prompt, &prompt.root; and &prompt.user;" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5302 msgid "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." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5308 msgid "As a special case, the two shell prompts for the normal user and the root user have been provided as entities. 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." msgstr "" #. (itstool) path: note/para #: book.translate.xml:5317 msgid "&prompt.root; and &prompt.user; are FreeBSD extensions to DocBook, and are not part of the original DTD." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5326 msgid "userinput" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5329 msgid "When displaying text that the user should type in, wrap it in userinput tags. It will be displayed differently than system output text." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5337 msgid "screen, prompt, and userinput Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5342 #, no-wrap msgid "" "screen&prompt.user; userinputls -1userinput\n" "foo1\n" "foo2\n" "foo3\n" "&prompt.user; userinputls -1 | grep foo2userinput\n" "foo2\n" "&prompt.user; userinputsuuserinput\n" "promptPassword: prompt\n" "&prompt.root; userinputcat foo2userinput\n" "This is the file called 'foo2'screen" msgstr "" #. (itstool) path: example/screen #: book.translate.xml:5355 #, no-wrap msgid "" "% ls -1\n" "foo1\n" "foo2\n" "foo3\n" "% ls -1 | grep foo2\n" "foo2\n" "% su\n" "Password: \n" "# cat foo2\n" "This is the file called 'foo2'" msgstr "" #. (itstool) path: note/para #: book.translate.xml:5368 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5383 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5388 msgid "There is no way to change the presentation of the emphasis within the document, no equivalent of HTML's b and i. If the information being presented is important, then consider presenting it in important rather than emphasis." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5397 msgid "emphasis Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5401 #, no-wrap msgid "" "para&os; is without doubt emphasistheemphasis\n" " premiere &unix;-like operating system for the Intel\n" " architecture.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5407 msgid "FreeBSD is without doubt the premiere UNIX-like operating system for the Intel architecture." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:5414 book.translate.xml:8329 +#: book.translate.xml:5414 book.translate.xml:8363 msgid "Acronyms" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5416 msgid "Many computer terms are acronyms, words formed from the first letter of each word in a phrase. Acronyms are marked up into acronym elements. It is helpful to the reader when an acronym is defined on the first use, as shown in the example below." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5424 msgid "acronym Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5428 #, no-wrap msgid "" "paraRequest For Comments (acronymRFCacronym) 1149\n" " defined the use of avian carriers for transmission of\n" " Internet Protocol (acronymIPacronym) data. The\n" " quantity of acronymIPacronym data currently\n" " transmitted in that manner is unknown.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5436 msgid "Request For Comments (RFC) 1149 defined the use of avian carriers for transmission of Internet Protocol (IP) data. The quantity of IP data currently transmitted in that manner is unknown." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5445 msgid "Quotations" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5447 msgid "To quote text from another document or source, or to denote a phrase that is used figuratively, use quote. Most of the markup tags available for normal text are also available from within a quote." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5454 msgid "quote Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5458 #, no-wrap msgid "" "paraHowever, make sure that the search does not go beyond the\n" " quoteboundary between local and public administrationquote,\n" " as acronymRFCacronym 1535 calls it.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5464 msgid "However, make sure that the search does not go beyond the boundary between local and public administration, as RFC 1535 calls it." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5472 msgid "Keys, Mouse Buttons, and Combinations" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5474 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5480 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5488 msgid "The stylesheets automatically add any connecting symbols, such as +, between the key names, when wrapped in keycombo." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5493 msgid "Keys, Mouse Buttons, and Combinations Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5497 #, no-wrap msgid "" "paraTo switch to the second virtual terminal, press\n" " keycombo action=\"simul\"keycapAltkeycap\n" " keycapF1keycapkeycombo.para\n" "\n" "paraTo exit commandvicommand without saving changes, type\n" " keycombo action=\"seq\"keycapEsckeycapkeycap:keycap\n" " keycapqkeycapkeycap!keycapkeycombo.para\n" "\n" "paraMy window manager is configured so that\n" " keycombo action=\"simul\"keycapAltkeycap\n" " mousebuttonrightmousebutton\n" " keycombo mouse button is used to move windows.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5512 msgid "To switch to the second virtual terminal, press Alt F1." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5516 msgid "To exit vi without saving changes, type Esc : q !." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5523 msgid "My window manager is configured so that Alt right mouse button is used to move windows." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5532 msgid "Applications, Commands, Options, and Cites" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5534 msgid "Both applications and commands are frequently referred to when writing documentation. The distinction between them is that an application is the name of a program or suite of programs that fulfill a particular task. A command is the filename of a program that the user can type and run at a command line." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5541 msgid "It is often necessary to show some of the options that a command might take." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5544 msgid "Finally, it is often useful to list a command with its manual section number, in the command(number) format so common in Unix manuals." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5548 msgid "Mark up application names with application." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5551 msgid "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." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5561 msgid "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;." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5567 msgid "The file that contains these entities is in doc/share/xml/man-refs.ent, and can be referred to using this FPI:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:5571 #, no-wrap msgid "PUBLIC \"-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN\"" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5573 msgid "Therefore, the introduction to FreeBSD documentation will usually include this:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:5576 #, no-wrap msgid "" "<!DOCTYPE book PUBLIC \"-//FreeBSD//DTD DocBook V4.1-Based Extension//EN\" [\n" "\n" "<!ENTITY % man PUBLIC \"-//FreeBSD//ENTITIES DocBook Manual Page Entities//EN\">\n" "%man;\n" "\n" "…\n" "\n" "]>" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5585 msgid "Use command to include a command name in-line but present it as something the user should type." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5589 msgid "Use option to mark up the options which will be passed to a command." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5592 msgid "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." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5601 msgid "Applications, Commands, and Options Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5605 #, no-wrap msgid "" "paraapplicationSendmailapplication is the most\n" " widely used Unix mail application.para\n" "\n" "paraapplicationSendmailapplication includes the\n" " citerefentry\n" " refentrytitlesendmailrefentrytitle\n" " manvolnum8manvolnum\n" " citerefentry, &man.mailq.1;, and &man.newaliases.1;\n" " programs.para\n" "\n" "paraOne of the command line parameters to citerefentry\n" " refentrytitlesendmailrefentrytitle\n" " manvolnum8manvolnum\n" " citerefentry, option-bpoption, will display the current\n" " status of messages in the mail queue. Check this on the command\n" " line by running commandsendmail -bpcommand.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5624 msgid "Sendmail is the most widely used Unix mail application." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5627 msgid "Sendmail includes the sendmail 8 , mailq1, and newaliases1 programs." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5634 msgid "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." msgstr "" #. (itstool) path: note/para #: book.translate.xml:5645 msgid "Notice how the &man.command.section; notation is easier to follow." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5652 msgid "Files, Directories, Extensions, Device Names" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5654 msgid "To refer to the name of a file, a directory, a file extension, or a device name, use filename." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5658 msgid "filename Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5662 #, no-wrap msgid "" "paraThe source for the Handbook in English is found in\n" " filename/usr/doc/en_US.ISO8859-1/books/handbook/filename.\n" " The main file is called filenamebook.xmlfilename.\n" " There is also a filenameMakefilefilename and a\n" " number of files with a filename.entfilename extension.para\n" "\n" "parafilenamekbd0filename is the first keyboard detected\n" " by the system, and appears in\n" " filename/devfilename.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5674 msgid "The source for the Handbook in English is found in /usr/doc/en_US.ISO8859-1/books/handbook/. The main file is called book.xml. There is also a Makefile and a number of files with a .ent extension." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5680 msgid "kbd0 is the first keyboard detected by the system, and appears in /dev." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5687 msgid "The Name of Ports" msgstr "" #. (itstool) path: note/title #: book.translate.xml:5690 book.translate.xml:5734 book.translate.xml:5966 msgid "FreeBSD Extension" msgstr "" #. (itstool) path: note/para #: book.translate.xml:5692 book.translate.xml:5736 book.translate.xml:5968 msgid "These elements are part of the FreeBSD extension to DocBook, and do not exist in the original DocBook DTD." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5697 msgid "To include the name of a program from the FreeBSD Ports Collection in the document, use the package tag. Since the Ports Collection can be installed in any number of locations, only include the category and the port name; do not include /usr/ports." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5703 msgid "By default, package refers to a binary package. To refer to a port that will be built from source, set the role attribute to port." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5709 msgid "package Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5713 #, no-wrap msgid "" "paraInstall the packagenet/wiresharkpackage binary\n" " package to view network traffic.para\n" "\n" "parapackage role=\"port\"net/wiresharkpackage can also be\n" " built and installed from the Ports Collection.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5721 msgid "Install the net/wireshark binary package to view network traffic." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5724 msgid "net/wireshark can also be built and installed from the Ports Collection." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5730 msgid "Hosts, Domains, IP Addresses, User Names, Group Names, and Other System Items" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5741 msgid "Information for system items is marked up with systemitem. The class attribute is used to identify the particular type of information shown." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5748 msgid "class=\"domainname\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5751 msgid "The text is a domain name, such as FreeBSD.org or ngo.org.uk. There is no hostname component." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5759 msgid "class=\"etheraddress\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5762 msgid "The text is an Ethernet MAC address, expressed as a series of 2 digit hexadecimal numbers separated by colons." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5769 msgid "class=\"fqdomainname\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5772 msgid "The text is a Fully Qualified Domain Name, with both hostname and domain name parts." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5778 msgid "class=\"ipaddress\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5781 msgid "The text is an IP address, probably expressed as a dotted quad." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5787 msgid "class=\"netmask\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5790 msgid "The text is a network mask, which might be expressed as a dotted quad, a hexadecimal string, or as a / followed by a number (CIDR notation)." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5798 msgid "class=\"systemname\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5801 msgid "With class=\"systemname\" the marked up information is the simple hostname, such as freefall or wcarchive." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5809 msgid "class=\"username\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5812 msgid "The text is a username, like root." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:5818 msgid "class=\"groupname\"" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:5821 msgid "The text is a groupname, like wheel." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5828 msgid "systemitem and Classes Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5832 #, no-wrap msgid "" "paraThe local machine can always be referred to by the\n" " name systemitem class=\"systemname\"localhostsystemitem, which will have the IP\n" " address systemitem class=\"ipaddress\"127.0.0.1systemitem.para\n" "\n" "paraThe systemitem class=\"domainname\"FreeBSD.orgsystemitem\n" " domain contains a number of different hosts, including\n" " systemitem class=\"fqdomainname\"freefall.FreeBSD.orgsystemitem and\n" " systemitem class=\"fqdomainname\"bento.FreeBSD.orgsystemitem.para\n" "\n" "paraWhen adding an acronymIPacronym alias to an\n" " interface (using commandifconfigcommand)\n" " emphasisalwaysemphasis use a netmask of\n" " systemitem class=\"netmask\"255.255.255.255systemitem (which can\n" " also be expressed as\n" " systemitem class=\"netmask\"0xffffffffsystemitem).para\n" "\n" "paraThe acronymMACacronym address uniquely identifies\n" " every network card in existence. A typical\n" " acronymMACacronym address looks like\n" " systemitem class=\"etheraddress\"08:00:20:87:ef:d0systemitem.para\n" "\n" "paraTo carry out most system administration functions\n" " requires logging in as systemitem class=\"username\"rootsystemitem.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5858 msgid "The local machine can always be referred to by the name localhost, which will have the IP address 127.0.0.1." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5863 msgid "The FreeBSD.org domain contains a number of different hosts, including freefall.FreeBSD.org and bento.FreeBSD.org." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5869 msgid "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)." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5876 msgid "The MAC address uniquely identifies every network card in existence. A typical MAC address looks like 08:00:20:87:ef:d0." msgstr "" #. (itstool) path: example/para #: book.translate.xml:5880 msgid "To carry out most system administration functions requires logging in as root." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5887 msgid "Uniform Resource Identifiers (URIs)" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5890 msgid "Occasionally it is useful to show a Uniform Resource Identifier (URI) without making it an active hyperlink. The uri element makes this possible:" msgstr "" #. (itstool) path: example/title #: book.translate.xml:5896 msgid "uri Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5900 #, no-wrap msgid "" "paraThis URL shows only as text:\n" " urihttps://www.FreeBSD.orguri. It does not\n" " create a link.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5906 msgid "This URL shows only as text: https://www.FreeBSD.org. It does not create a link." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5911 msgid "To create links, see ." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5916 -#, fuzzy msgid "Email Addresses" -msgstr "grog@FreeBSD.org" +msgstr "E-mail-adressen" #. (itstool) path: sect2/para #: book.translate.xml:5918 msgid "Email addresses are marked up as email elements. In the HTML output format, the wrapped text becomes a hyperlink to the email address. Other output formats that support hyperlinks may also make the email address into a link." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5925 msgid "email with a Hyperlink Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5929 #, no-wrap msgid "" "paraAn email address that does not actually exist, like\n" " emailnotreal@example.comemail, can be used as an\n" " example.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5935 msgid "An email address that does not actually exist, like notreal@example.com, can be used as an example." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5940 msgid "A FreeBSD-specific extension allows setting the role attribute to nolink to prevent the creation of the hyperlink to the email address." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5946 msgid "email Without a Hyperlink Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5950 #, no-wrap msgid "" "paraSometimes a link to an email address like\n" " email role=\"nolink\"notreal@example.comemail is not\n" " desired.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:5956 msgid "Sometimes a link to an email address like notreal@example.com is not desired." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:5963 msgid "Describing Makefiles" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5973 msgid "Two elements exist to describe parts of Makefiles, buildtarget and varname." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:5977 msgid "buildtarget identifies a build target exported by a Makefile that can be given as a parameter to make. varname identifies a variable that can be set (in the environment, on the command line with make, or within the Makefile) to influence the process." msgstr "" #. (itstool) path: example/title #: book.translate.xml:5987 msgid "buildtarget and varname Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:5992 #, no-wrap msgid "" "paraTwo common targets in a filenameMakefilefilename\n" " are buildtargetallbuildtarget and\n" " buildtargetcleanbuildtarget.para\n" "\n" "paraTypically, invoking buildtargetallbuildtarget will\n" " rebuild the application, and invoking\n" " buildtargetcleanbuildtarget will remove the temporary\n" " files (filename.ofilename for example) created by the\n" " build process.para\n" "\n" "parabuildtargetcleanbuildtarget may be controlled by a\n" " number of variables, including varnameCLOBBERvarname\n" " and varnameRECURSEvarname.para" msgstr "" #. (itstool) path: para/buildtarget #: book.translate.xml:6009 book.translate.xml:6012 -#, fuzzy msgid "all" -msgstr "Van de andere kant is er een centraal repository, een enkele plaats waar u de gehele broncode van het besturingssysteem kunt vinden, inclusief alle oudere versies." +msgstr "all" #. (itstool) path: example/para #: book.translate.xml:6008 msgid "Two common targets in a Makefile are <_:buildtarget-1/> and <_:buildtarget-2/>." msgstr "" #. (itstool) path: example/para #: book.translate.xml:6012 msgid "Typically, invoking <_:buildtarget-1/> will rebuild the application, and invoking <_:buildtarget-2/> will remove the temporary files (.o for example) created by the build process." msgstr "" #. (itstool) path: example/para #: book.translate.xml:6018 msgid "<_:buildtarget-1/> may be controlled by a number of variables, including CLOBBER and RECURSE." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6025 msgid "Literal Text" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6027 msgid "Literal text, or text which should be entered verbatim, is often needed in documentation. This is text that is excerpted from another file, or which should be copied exactly as shown from the documentation into another file." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6032 msgid "Some of the time, programlisting will be sufficient to denote this text. But programlisting is not always appropriate, particularly when you want to include a portion of a file in-line with the rest of the paragraph." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6039 msgid "On these occasions, use literal." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6043 msgid "literal Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6047 #, no-wrap msgid "" "paraThe literalmaxusers 10literal line in the kernel\n" " configuration file determines the size of many system tables, and is\n" " a rough guide to how many simultaneous logins the system will\n" " support.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6054 msgid "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." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6062 msgid "Showing Items That the User Must Fill In" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6065 msgid "There will often be times when the user is shown what to do, or referred to a file or command line, but cannot simply copy the example provided. Instead, they must supply some information themselves." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6070 msgid "replaceable is designed for this eventuality. Use it inside other elements to indicate parts of that element's content that the user must replace." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6076 msgid "replaceable Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6080 #, no-wrap msgid "screen&prompt.user; userinputman replaceablecommandreplaceableuserinputscreen" msgstr "" #. (itstool) path: informalexample/screen #: book.translate.xml:6085 #, no-wrap msgid "% man command" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6088 msgid "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." msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6097 #, no-wrap msgid "" "paraThe literalmaxusers replaceablenreplaceableliteral\n" " line in the kernel configuration file determines the size of many system\n" " tables, and is a rough guide to how many simultaneous logins the system will\n" " support.para\n" "\n" "paraFor a desktop workstation, literal32literal is a good value\n" " for replaceablenreplaceable.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6107 msgid "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." msgstr "" #. (itstool) path: example/para #: book.translate.xml:6113 msgid "For a desktop workstation, 32 is a good value for n." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6119 msgid "Showing GUI Buttons" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6121 msgid "Buttons presented by a graphical user interface are marked with guibutton. To make the text look more like a graphical button, brackets and non-breaking spaces are added surrounding the text." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6127 msgid "guibutton Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6131 #, no-wrap msgid "" "paraEdit the file, then click\n" " guibutton[&nbsp;Save&nbsp;]guibutton to save the\n" " changes.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6137 msgid "Edit the file, then click [ Save ] to save the changes." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6144 -#, fuzzy msgid "Quoting System Errors" -msgstr "De C-bibliotheek, de basis-API voor het systeem." +msgstr "Systeemfouten aanhalen" #. (itstool) path: sect2/para #: book.translate.xml:6146 msgid "System errors generated by FreeBSD are marked with errorname. This indicates the exact error that appears." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6151 msgid "errorname Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6155 #, no-wrap msgid "screenerrornamePanic: cannot mount rooterrornamescreen" msgstr "" #. (itstool) path: informalexample/screen #: book.translate.xml:6160 #, no-wrap msgid "Panic: cannot mount root" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:6167 msgid "Images" msgstr "" #. (itstool) path: important/para #: book.translate.xml:6170 msgid "Image support in the documentation is somewhat experimental. The mechanisms described here are unlikely to change, but that is not guaranteed." msgstr "" #. (itstool) path: important/para #: book.translate.xml:6174 msgid "To provide conversion between different image formats, the graphics/ImageMagick port must be installed. This port is not included in the textproc/docproj meta port, and must be installed separately." msgstr "" #. (itstool) path: important/para #: book.translate.xml:6180 msgid "A good example of the use of images is the doc/en_US.ISO8859-1/articles/vm-design/ document. Examine the files in that directory to see how these elements are used together. Build different output formats to see how the format determines what images are shown in the rendered document." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6189 msgid "Image Formats" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6191 msgid "The following image formats are currently supported. An image file will automatically be converted to bitmap or vector image depending on the output document format." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6195 msgid "These are the only formats in which images should be committed to the documentation repository." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:6201 msgid "EPS (Encapsulated Postscript)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6205 msgid "Images that are primarily vector based, such as network diagrams, time lines, and similar, should be in this format. These images have a .eps extension." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:6213 msgid "PNG (Portable Network Graphic)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6217 msgid "For bitmaps, such as screen captures, use this format. These images have the .png extension." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:6224 msgid "PIC (PIC graphics language)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6227 msgid "PIC is a language for drawing simple vector-based figures used in the pic1 utility. These images have the .pic extension." msgstr "" #. (itstool) path: varlistentry/term #: book.translate.xml:6235 msgid "SCR (SCReen capture)" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6238 msgid "This format is specific to screenshots of console output. The following command generates an SCR file shot.scr from video buffer of /dev/ttyv0:" msgstr "" #. (itstool) path: listitem/screen #: book.translate.xml:6243 #, no-wrap msgid "# vidcontrol -p < /dev/ttyv0 > shot.scr" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6245 msgid "This is preferable to PNG format for screenshots because the SCR file contains plain text of the command lines so that it can be converted to a PNG image or a plain text depending on the output document format." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6255 msgid "Use the appropriate format for each image. Documentation will often have a mix of EPS and PNG images. The Makefiles ensure that the correct format image is chosen depending on the output format used. Do not commit the same image to the repository in two different formats." msgstr "" #. (itstool) path: important/para #: book.translate.xml:6264 msgid "The Documentation Project may eventually switch to using the SVG (Scalable Vector Graphic) format for vector images. However, the current state of SVG capable editing tools makes this impractical." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6273 msgid "Image File Locations" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6275 msgid "Image files can be stored in one of several locations, depending on the document and image:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6280 msgid "In the same directory as the document itself, usually done for articles and small books that keep all their files in a single directory." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6286 msgid "In a subdirectory of the main document. Typically done when a large book uses separate subdirectories to organize individual chapters." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6290 msgid "When images are stored in a subdirectory of the main document directory, the subdirectory name must be included in their paths in the Makefile and the imagedata element." msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:6298 msgid "In a subdirectory of doc/share/images named after the document. For example, images for the Handbook are stored in doc/share/images/books/handbook. Images that work for multiple translations are stored in this upper level of the documentation file tree. Generally, these are images that can be used unchanged in non-English translations of the document." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6311 msgid "Image Markup" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6313 msgid "Images are included as part of a mediaobject. The mediaobject can contain other, more specific objects. We are concerned with two, the imageobject and the textobject." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6318 msgid "Include one imageobject, and two textobject elements. The imageobject will point to the name of the image file without the extension. The textobject elements contain information that will be presented to the user as well as, or instead of, the image itself." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6325 msgid "Text elements are shown to the reader in several situations. When the document is viewed in HTML, text elements are shown while the image is loading, or if the mouse pointer is hovered over the image, or if a text-only browser is being used. In formats like plain text where graphics are not possible, the text elements are shown instead of the graphical ones." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6333 msgid "This example shows how to include an image called fig1.png in a document. The image is a rectangle with an A inside it:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:6337 #, no-wrap msgid "" "mediaobject\n" " imageobject\n" " imagedata fileref=\"fig1\" \n" " imageobject\n" "\n" " textobject\n" " literallayout class=\"monospaced\"+---------------+ \n" "| A |\n" "+---------------+literallayout\n" " textobject\n" "\n" " textobject\n" " phraseA picturephrase \n" " textobject\n" "mediaobject" msgstr "" #. (itstool) path: callout/para #: book.translate.xml:6355 msgid "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." msgstr "" #. (itstool) path: callout/para #: book.translate.xml:6365 msgid "The first textobject contains a literallayout element, where the class attribute is set to monospaced. This is an opportunity to demonstrate ASCII art skills. This content will be used if the document is converted to plain text." msgstr "" #. (itstool) path: callout/para #: book.translate.xml:6373 msgid "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." msgstr "" #. (itstool) path: callout/para #: book.translate.xml:6380 msgid "The second textobject contains a single phrase element. The contents of this phrase will become the alt attribute for the image when this document is converted to HTML." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6390 msgid "Image Makefile Entries" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6392 msgid "Images must be listed in the Makefile in the IMAGES variable. This variable must contain the names of all the source images. For example, if there are three figures, fig1.eps, fig2.png, fig3.png, then the Makefile should have lines like this in it." msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:6401 #, no-wrap msgid "" "…\n" "IMAGES= fig1.eps fig2.png fig3.png\n" "…" msgstr "" #. (itstool) path: sect2/para #. (itstool) path: question/para #: book.translate.xml:6405 book.translate.xml:6993 msgid "or" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:6407 #, no-wrap msgid "" "…\n" "IMAGES= fig1.eps\n" "IMAGES+= fig2.png\n" "IMAGES+= fig3.png\n" "…" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6413 msgid "Again, the Makefile will work out the complete list of images it needs to build the source document, you only need to list the image files you provided." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6420 msgid "Images and Chapters in Subdirectories" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6422 msgid "Be careful when separating documentation into smaller files in different directories (see )." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6425 msgid "" "Suppose there is 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, place those images in each chapter's subdirectory (chapter1/, chapter2/, and " "chapter3/)." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6435 msgid "However, doing this requires including the directory names in the IMAGES variable in the Makefile, and including the directory name in the imagedata element in the document." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6441 msgid "For example, if the book has chapter1/fig1.png, then chapter1/chapter.xml should contain:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:6446 #, no-wrap msgid "" "mediaobject\n" " imageobject\n" " imagedata fileref=\"chapter1/fig1\" \n" " imageobject\n" "\n" " …\n" "\n" "mediaobject" msgstr "" #. (itstool) path: callout/para #: book.translate.xml:6457 msgid "The directory name must be included in the fileref attribute." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6462 msgid "The Makefile must contain:" msgstr "" #. (itstool) path: sect2/programlisting #: book.translate.xml:6464 #, no-wrap msgid "" "…\n" "IMAGES= chapter1/fig1.png\n" "…" msgstr "" #. (itstool) path: note/para #: book.translate.xml:6474 msgid "Links are also in-line elements. To show a URI without creating a link, see ." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6480 msgid "xml:id Attributes" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6482 msgid "Most DocBook elements accept an xml:id attribute to give that part of the document a unique name. The xml:id can be used as a target for a crossreference or link." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6487 msgid "Any portion of the document that will be a link target must have an xml:id attribute. Assigning an xml:id to all chapters and sections, even if there are no current plans to link to them, is a good idea. These xml:ids can be used as unique reference points by anyone referring to the HTML version of the document." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6496 msgid "xml:id on Chapters and Sections Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6499 #, no-wrap msgid "" "chapter xml:id=\"introduction\"\n" " titleIntroductiontitle\n" "\n" " paraThis is the introduction. It contains a subsection,\n" " which is identified as well.para\n" "\n" " sect1 xml:id=\"introduction-moredetails\"\n" " titleMore Detailstitle\n" "\n" " paraThis is a subsection.para\n" " sect1\n" "chapter" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6513 msgid "" "Use descriptive values for xml:id names. The values must be unique within the entire document, not just in a single file. In the example, the subsection xml:id is constructed by appending text to the chapter xml:id. This ensures that the xml:ids are unique. It also helps both reader and anyone editing the document to see where the " "link is located within the document, similar to a directory path to a file." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6525 msgid "Crossreferences with xref" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6527 msgid "xref provides the reader with a link to jump to another section of the document. The target xml:id is specified in the linkend attribute, and xref generates the link text automatically." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6534 msgid "xref Example" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6536 msgid "Assume that this fragment appears somewhere in a document that includes the xml:id example shown above:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6540 #, no-wrap msgid "" "paraMore information can be found\n" " in xref linkend=\"introduction\".para\n" "\n" "paraMore specific information can be found\n" " in xref linkend=\"introduction-moredetails\".para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6546 msgid "The link text will be generated automatically, looking like (emphasized text indicates the link text):" msgstr "" #. (itstool) path: blockquote/para #: book.translate.xml:6551 msgid "More information can be found in Chapter 1, Introduction." msgstr "" #. (itstool) path: blockquote/para #: book.translate.xml:6554 msgid "More specific information can be found in Section 1.1, More Details." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6560 msgid "The link text is generated automatically from the chapter and section number and title elements." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6569 msgid "" "The link element described here allows the writer to define the link text. When link text is used, it is very important to be descriptive to give the reader an idea of where the link goes. Remember that DocBook can be rendered to multiple types of media. The reader might be looking at a printed book or other form of media where there are no links. If the link text is not descriptive enough, the reader might " "not be able to locate the linked section." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6578 msgid "The xlink:href attribute is the URL of the page, and the content of the element is the text that will be displayed for the user to activate." msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6583 msgid "In many situations, it is preferable to show the actual URL rather than text. This can be done by leaving out the element text entirely." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6588 msgid "link to a FreeBSD Documentation Web Page Example" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6591 msgid "Link to the book or article URL entity. To link to a specific chapter in a book, add a slash and the chapter file name, followed by an optional anchor within the chapter. For articles, link to the article URL entity, followed by an optional anchor within the article. URL entities can be found in doc/share/xml/urls.ent." msgstr "" #. (itstool) path: example/para #: book.translate.xml:6600 msgid "Usage for FreeBSD book links:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6602 #, no-wrap msgid "" "paraRead the link\n" " xlink:href=\"&url.books.handbook;/svn.html#svn-intro\"SVN\n" " introductionlink, then pick the nearest mirror from\n" " the list of link\n" " xlink:href=\"&url.books.handbook;/svn.html#svn-mirrors\"Subversion\n" " mirror siteslink.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6611 msgid "Read the SVN introduction, then pick the nearest mirror from the list of Subversion mirror sites." msgstr "" #. (itstool) path: example/para #: book.translate.xml:6616 msgid "Usage for FreeBSD article links:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6618 #, no-wrap msgid "" "paraRead this\n" " link xlink:href=\"&url.articles.bsdl-gpl;\"article\n" " about the BSD licenselink, or just the\n" " link xlink:href=\"&url.articles.bsdl-gpl;#intro\"introductionlink.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6625 msgid "Read this article about the BSD license, or just the introduction." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6631 msgid "link to a FreeBSD Web Page Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6635 #, no-wrap msgid "" "paraOf course, you could stop reading this document and go to the\n" " link xlink:href=\"&url.base;/index.html\"FreeBSD home pagelink instead.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6640 msgid "Of course, you could stop reading this document and go to the FreeBSD home page instead." msgstr "" #. (itstool) path: example/title #: book.translate.xml:6646 msgid "link to an External Web Page Example" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6651 #, no-wrap msgid "" "paraWikipedia has an excellent reference on\n" " link\n" " xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\"GUID\n" " Partition Tableslink.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6658 msgid "Wikipedia has an excellent reference on GUID Partition Tables." msgstr "" #. (itstool) path: example/para #: book.translate.xml:6661 msgid "The link text can be omitted to show the actual URL:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6664 #, no-wrap msgid "" "paraWikipedia has an excellent reference on\n" " GUID Partition Tables: link\n" " xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\"link.para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6668 msgid "The same link can be entered using shorter notation instead of a separate ending tag:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:6671 #, no-wrap msgid "" "paraWikipedia has an excellent reference on\n" " GUID Partition Tables: link\n" " xlink:href=\"http://en.wikipedia.org/wiki/GUID_Partition_Table\".para" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6675 msgid "The two methods are equivalent. Appearance:" msgstr "" #. (itstool) path: example/para #: book.translate.xml:6677 msgid "Wikipedia has an excellent reference on GUID Partition Tables: http://en.wikipedia.org/wiki/GUID_Partition_Table." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:6717 msgid "Style Sheets" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:6719 msgid "" "XML is concerned with content, and says nothing about how that content should be presented to the reader or rendered on paper. Multiple style sheet languages have been developed to describe visual layout, including Extensible Stylesheet Language Transformation (XSLT), Document Style Semantics and Specification Language (DSSSL), and " "Cascading Style Sheets (CSS)." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:6728 msgid "The FDP documents use XSLT stylesheets to transform DocBook into XHTML, and then CSS formatting is applied to the XHTML pages. Printable output is currently rendered with legacy DSSSL stylesheets, but this will probably change in the future." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:6737 msgid "CSS" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:6739 msgid "Cascading Style Sheets (CSS) are a mechanism for attaching style information (font, weight, size, color, and so forth) to elements in an XHTML document without abusing XHTML to do so." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:6746 msgid "The DocBook Documents" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:6748 msgid "" "The FreeBSD XSLT and DSSSL stylesheets refer to docbook.css, which is expected to be present in the same directory as the XHTML files. The project-wide CSS file is copied from doc/share/misc/docbook.css when documents are converted to XHTML, and is installed automatically." msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:6793 msgid "Translations" msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:6795 msgid "This is the FAQ for people translating the FreeBSD documentation (FAQ, Handbook, tutorials, manual pages, and others) to different languages." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:6799 msgid "It is very heavily based on the translation FAQ from the FreeBSD German Documentation Project, originally written by Frank Gründer elwood@mc5sys.in-berlin.de and translated back to English by Bernd Warken bwarken@mayn.de." msgstr "" #. (itstool) path: chapter/para #: book.translate.xml:6805 msgid "The FAQ is maintained by the Documentation Engineering Team doceng@FreeBSD.org." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6810 msgid "What do i18n and l10n mean?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6815 msgid "i18n means internationalization and l10n means localization. They are just a convenient shorthand." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6820 msgid "i18n can be read as i followed by 18 letters, followed by n. Similarly, l10n is l followed by 10 letters, followed by n." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6829 msgid "Is there a mailing list for translators?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6833 msgid "Yes. Different translation groups have their own mailing lists. The list of translation projects has more information about the mailing lists and web sites run by each translation project. In addition there is freebsd-translators@freebsd.org for general translation discussion." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6845 msgid "Are more translators needed?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6849 msgid "Yes. The more people work on translation the faster it gets done, and the faster changes to the English documentation are mirrored in the translated documents." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6854 msgid "You do not have to be a professional translator to be able to help." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6861 msgid "What languages do I need to know?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6865 msgid "Ideally, you will have a good knowledge of written English, and obviously you will need to be fluent in the language you are translating to." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6869 msgid "English is not strictly necessary. For example, you could do a Hungarian translation of the FAQ from the Spanish translation." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6877 msgid "What software do I need to know?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6881 msgid "It is strongly recommended that you maintain a local copy of the FreeBSD Subversion repository (at least the documentation part). This can be done by running:" msgstr "" #. (itstool) path: answer/screen #: book.translate.xml:6885 #, no-wrap msgid "% svn checkout https://svn.FreeBSD.org/doc/head/ head" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6887 msgid "svn.FreeBSD.org is a public SVN server. Verify the server certificate from the list of Subversion mirror sites." msgstr "" #. (itstool) path: note/para #: book.translate.xml:6894 msgid "This will require the devel/subversion package to be installed." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6898 msgid "You should be comfortable using svn. This will allow you to see what has changed between different versions of the files that make up the documentation." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6903 msgid "For example, to view the differences between revisions r33733 and r33734 of en_US.ISO8859-1/books/fdp-primer/book.xml, run:" msgstr "" #. (itstool) path: answer/screen #: book.translate.xml:6908 #, no-wrap msgid "% svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml" msgstr "" #. (itstool) path: question/para #: book.translate.xml:6914 msgid "How do I find out who else might be translating to the same language?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6919 msgid "The Documentation Project translations page lists the translation efforts that are currently known about. If others are already working on translating documentation to your language, please do not duplicate their efforts. Instead, contact them to see how you can help." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6926 msgid "If no one is listed on that page as translating for your language, then send a message to the FreeBSD documentation project mailing list in case someone else is thinking of doing a translation, but has not announced it yet." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6935 msgid "No one else is translating to my language. What do I do?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6940 msgid "Congratulations, you have just started the FreeBSD your-language-here Documentation Translation Project. Welcome aboard." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6945 msgid "First, decide whether or not you have got the time to spare. Since you are the only person working on your language at the moment it is going to be your responsibility to publicize your work and coordinate any volunteers that might want to help you." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6951 msgid "Write an email to the Documentation Project mailing list, announcing that you are going to translate the documentation, so the Documentation Project translations page can be maintained." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6956 msgid "If there is already someone in your country providing FreeBSD mirroring services you should contact them and ask if you can have some webspace for your project, and possibly an email address or mailing list services." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6961 msgid "Then pick a document and start translating. It is best to start with something fairly small—either the FAQ, or one of the tutorials." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6969 msgid "I have translated some documentation, where do I send it?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6974 msgid "That depends. If you are already working with a translation team (such as the Japanese team, or the German team) then they will have their own procedures for handling submitted documentation, and these will be outlined on their web pages." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:6980 msgid "If you are the only person working on a particular language (or you are responsible for a translation project and want to submit your changes back to the FreeBSD project) then you should send your translation to the FreeBSD project (see the next question)." msgstr "" #. (itstool) path: question/para #: book.translate.xml:6990 msgid "I am the only person working on translating to this language, how do I submit my translation?" msgstr "" #. (itstool) path: question/para #: book.translate.xml:6995 msgid "We are a translation team, and want to submit documentation that our members have translated for us." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7001 msgid "First, make sure your translation is organized properly. This means that it should drop into the existing documentation tree and build straight away." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7005 msgid "Currently, the FreeBSD documentation is stored in a top level directory called head/. Directories below this are named according to the language code they are written in, as defined in ISO639 (/usr/share/misc/iso639 on a version of FreeBSD newer than 20th January 1999)." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7012 msgid "If your language can be encoded in different ways (for example, Chinese) then there should be directories below this, one for each encoding format you have provided." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7016 msgid "Finally, you should have directories for each document." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7019 msgid "For example, a hypothetical Swedish translation might look like:" msgstr "" #. (itstool) path: answer/programlisting #: book.translate.xml:7022 #, no-wrap msgid "" "head/\n" " sv_SE.ISO8859-1/\n" " Makefile\n" " htdocs/\n" " docproj/\n" " books/\n" " faq/\n" " Makefile\n" " book.xml" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7032 msgid "sv_SE.ISO8859-1 is the name of the translation, in lang.encoding form. Note the two Makefiles, which will be used to build the documentation." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7038 msgid "Use tar1 and gzip1 to compress up your documentation, and send it to the project." msgstr "" #. (itstool) path: answer/screen #: book.translate.xml:7041 #, no-wrap msgid "" "% cd doc\n" "% tar cf swedish-docs.tar sv_SE.ISO8859-1\n" "% gzip -9 swedish-docs.tar" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7045 msgid "Put swedish-docs.tar.gz somewhere. If you do not have access to your own webspace (perhaps your ISP does not let you have any) then you can email Documentation Engineering Team doceng@FreeBSD.org, and arrange to email the files when it is convenient." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7051 msgid "Either way, you should use Bugzilla to submit a report indicating that you have submitted the documentation. It would be very helpful if you could get other people to look over your translation and double check it first, since it is unlikely that the person committing it will be fluent in the language." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7058 msgid "Someone (probably the Documentation Project Manager, currently Documentation Engineering Team doceng@FreeBSD.org) will then take your translation and confirm that it builds. In particular, the following things will be looked at:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7065 msgid "Do all your files use RCS strings (such as \"ID\")?" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7070 msgid "Does make all in the sv_SE.ISO8859-1 directory work correctly?" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7076 msgid "Does make install work correctly?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7081 msgid "If there are any problems then whoever is looking at the submission will get back to you to work them out." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7084 msgid "If there are no problems your translation will be committed as soon as possible." msgstr "" #. (itstool) path: question/para #: book.translate.xml:7091 msgid "Can I include language or country specific text in my translation?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7096 msgid "We would prefer that you did not." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7098 msgid "For example, suppose that you are translating the Handbook to Korean, and want to include a section about retailers in Korea in your Handbook." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7102 msgid "There is no real reason why that information should not be in the English (or German, or Spanish, or Japanese, or …) versions as well. It is feasible that an English speaker in Korea might try to pick up a copy of FreeBSD whilst over there. It also helps increase FreeBSD's perceived presence around the globe, which is not a bad thing." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7110 msgid "If you have country specific information, please submit it as a change to the English Handbook (using Bugzilla) and then translate the change back to your language in the translated Handbook." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7115 msgid "Thanks." msgstr "" #. (itstool) path: question/para #: book.translate.xml:7121 msgid "How should language specific characters be included?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7126 msgid "Non-ASCII characters in the documentation should be included using SGML entities." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7129 msgid "Briefly, these look like an ampersand (&), the name of the entity, and a semi-colon (;)." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7132 msgid "The entity names are defined in ISO8879, which is in the ports tree as textproc/iso8879." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7135 msgid "A few examples include:" msgstr "" #. (itstool) path: segmentedlist/segtitle #: book.translate.xml:7138 msgid "Entity" msgstr "" #. (itstool) path: segmentedlist/segtitle #: book.translate.xml:7140 msgid "Appearance" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7145 msgid "&eacute;" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7146 msgid "é" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7147 msgid "Small e with an acute accent" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7151 msgid "&Eacute;" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7152 msgid "É" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7153 msgid "Large E with an acute accent" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7157 msgid "&uuml;" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7158 msgid "ü" msgstr "" #. (itstool) path: seglistitem/seg #: book.translate.xml:7159 msgid "Small u with an umlaut" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7163 msgid "After you have installed the iso8879 port, the files in /usr/local/share/xml/iso8879 contain the complete list." msgstr "" #. (itstool) path: question/para #: book.translate.xml:7171 msgid "Addressing the reader" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7175 msgid "In the English documents, the reader is addressed as you, there is no formal/informal distinction as there is in some languages." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7179 msgid "If you are translating to a language which does distinguish, use whichever form is typically used in other technical documentation in your language. If in doubt, use a mildly polite form." msgstr "" #. (itstool) path: question/para #: book.translate.xml:7188 msgid "Do I need to include any additional information in my translations?" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7193 msgid "Yes." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7195 msgid "The header of the English version of each document will look something like this:" msgstr "" #. (itstool) path: answer/programlisting #: book.translate.xml:7198 #, no-wrap msgid "" "<!--\n" " The FreeBSD Documentation Project\n" "\n" " $FreeBSD$\n" "-->" msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7204 msgid "The exact boilerplate may change, but it will always include a $FreeBSD$ line and the phrase The FreeBSD Documentation Project. Note that the $FreeBSD part is expanded automatically by Subversion, so it should be empty (just $FreeBSD$) for new files." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7212 msgid "Your translated documents should include their own $FreeBSD$ line, and change the FreeBSD Documentation Project line to The FreeBSD language Documentation Project." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7218 msgid "In addition, you should add a third line which indicates which revision of the English text this is based on." msgstr "" #. (itstool) path: answer/para #: book.translate.xml:7221 msgid "So, the Spanish version of this file might start:" msgstr "" #. (itstool) path: answer/programlisting #: book.translate.xml:7223 #, no-wrap msgid "" "<!--\n" " The FreeBSD Spanish Documentation Project\n" "\n" " $FreeBSD$\n" " Original revision: r38674\n" "-->" msgstr "" #. (itstool) path: chapter/title #: book.translate.xml:7241 msgid "PO Translations" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7246 msgid "" "The GNU gettext system offers translators an easy way to create and maintain translations of documents. Translatable strings are extracted from the original document into a PO (Portable Object) file. Translated versions of the strings are entered with a separate editor. The strings " "can be used directly or built into a complete translated version of the original document." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7259 msgid "The procedure shown in is assumed to have already been performed, but the TRANSLATOR option must be enabled in the textproc/docproj port. If that option was not enabled, display the options menu and enable it, then reinstall the port:" msgstr "" #. (itstool) path: sect1/screen #: book.translate.xml:7267 #, no-wrap msgid "" "# cd /usr/ports/textproc/docproj\n" "# make config\n" "# make clean deinstall install clean" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7271 msgid "This example shows the creation of a Spanish translation of the short Leap Seconds article." msgstr "" #. (itstool) path: procedure/title #: book.translate.xml:7276 msgid "Install a PO Editor" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7279 msgid "A PO editor is needed to edit translation files. This example uses editors/poedit." msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7283 #, no-wrap msgid "" "# cd /usr/ports/editors/poedit\n" "# make install clean" msgstr "" #. (itstool) path: procedure/title #: book.translate.xml:7289 msgid "Initial Setup" msgstr "" #. (itstool) path: procedure/para #: book.translate.xml:7291 msgid "When a new translation is first created, the directory structure and Makefile must be created or copied from the English original:" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7296 msgid "Create a directory for the new translation. The English article source is in ~/doc/en_US.ISO8859-1/articles/leap-seconds/. The Spanish translation will go in ~/doc/es_ES.ISO8859-1/articles/leap-seconds/. The path is the same except for the name of the language directory." msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7304 #, no-wrap msgid "% svn mkdir --parents ~/doc/es_ES.ISO8859-1/articles/leap-seconds/" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7308 msgid "Copy the Makefile from the original document into the translation directory:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7311 #, no-wrap msgid "" "% svn cp ~/doc/en_US.ISO8859-1/articles/leap-seconds/Makefile \\\n" " ~/doc/es_ES.ISO8859-1/articles/leap-seconds/" msgstr "" #. (itstool) path: procedure/title #: book.translate.xml:7317 msgid "Translation" msgstr "" #. (itstool) path: procedure/para #: book.translate.xml:7319 msgid "Translating a document consists of two steps: extracting translatable strings from the original document, and entering translations for those strings. These steps are repeated until the translator feels that enough of the document has been translated to produce a usable translated document." msgstr "" #. (itstool) path: step/para #: book.translate.xml:7327 msgid "Extract the translatable strings from the original English version into a PO file:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7330 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/\n" "% make po" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7335 msgid "Use a PO editor to enter translations in the PO file. There are several different editors available. poedit from editors/poedit is shown here." msgstr "" #. (itstool) path: step/para #: book.translate.xml:7341 msgid "The PO file name is the two-character language code followed by an underline and a two-character region code. For Spanish, the file name is es_ES.po." msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7346 book.translate.xml:7812 #, no-wrap msgid "% poedit es_ES.po" msgstr "" #. (itstool) path: procedure/title #: book.translate.xml:7351 msgid "Generating a Translated Document" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7354 msgid "Generate the translated document:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7356 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/articles/leap-seconds/\n" "% make tran" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7359 msgid "The name of the generated document matches the name of the English original, usually article.xml for articles or book.xml for books." msgstr "" #. (itstool) path: step/para #: book.translate.xml:7366 msgid "Check the generated file by rendering it to HTML and viewing it with a web browser:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7370 #, no-wrap msgid "" "% make FORMATS=html\n" "% firefox article.html" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:7377 msgid "Creating New Translations" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7379 msgid "" "The first step to creating a new translated document is locating or creating a directory to hold it. FreeBSD puts translated documents in a subdirectory named for their language and region in the format lang_REGION. lang is a two-character lowercase code. It is followed by an underscore character and then the " "two-character uppercase REGION code." msgstr "" #. (itstool) path: table/title #: book.translate.xml:7390 msgid "Language Names" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7395 msgid "Language" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7396 msgid "Region" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7397 msgid "Translated Directory Name" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7398 msgid "PO File Name" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7399 msgid "Character Set" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7405 msgid "English" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7406 -#, fuzzy msgid "United States" -msgstr "Motif, OSF/1, en UNIX zijn geregistreerde handelsmerken en IT DialTone en The Open Group zijn handelsmerken van The Open Group in de Verenigde Staten en andere landen." +msgstr "Verenigde Staten" #. (itstool) path: row/entry #: book.translate.xml:7407 msgid "en_US.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7408 msgid "en_US.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7409 book.translate.xml:7425 book.translate.xml:7433 book.translate.xml:7449 book.translate.xml:7457 book.translate.xml:7505 book.translate.xml:7513 book.translate.xml:7529 msgid "ISO 8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7413 msgid "Bengali" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7414 msgid "Bangladesh" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7415 msgid "bn_BD.UTF-8" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7416 msgid "bn_BD.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7417 book.translate.xml:7489 book.translate.xml:7497 book.translate.xml:7561 book.translate.xml:7569 msgid "UTF-8" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7421 msgid "Danish" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7422 msgid "Denmark" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7423 msgid "da_DK.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7424 msgid "da_DK.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7429 msgid "German" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7430 msgid "Germany" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7431 msgid "de_DE.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7432 msgid "de_DE.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7437 msgid "Greek" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7438 msgid "Greece" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7439 msgid "el_GR.ISO8859-7" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7440 msgid "el_GR.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7441 msgid "ISO 8859-7" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7445 msgid "Spanish" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7446 msgid "Spain" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7447 msgid "es_ES.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7448 msgid "es_ES.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7453 msgid "French" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7454 msgid "France" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7455 msgid "fr_FR.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7456 msgid "fr_FR.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7461 msgid "Hungarian" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7462 msgid "Hungary" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7463 msgid "hu_HU.ISO8859-2" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7464 msgid "hu_HU.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7465 book.translate.xml:7521 book.translate.xml:7545 msgid "ISO 8859-2" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7469 msgid "Italian" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7470 msgid "Italy" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7471 msgid "it_IT.ISO8859-15" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7472 msgid "it_IT.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7473 msgid "ISO 8859-15" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7477 msgid "Japanese" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7478 msgid "Japan" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7479 msgid "ja_JP.eucJP" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7480 msgid "ja_JP.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7481 msgid "EUC JP" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7485 msgid "Korean" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7486 msgid "Korea" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7487 msgid "ko_KR.UTF-8" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7488 msgid "ko_KR.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7493 msgid "Mongolian" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7494 msgid "Mongolia" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7495 msgid "mn_MN.UTF-8" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7496 msgid "mn_MN.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7501 msgid "Dutch" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7502 msgid "Netherlands" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7503 msgid "nl_NL.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7504 msgid "nl_NL.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7509 msgid "Norwegian" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7510 msgid "Norway" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7511 msgid "no_NO.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7512 msgid "no_NO.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7517 msgid "Polish" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7518 msgid "Poland" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7519 msgid "pl_PL.ISO8859-2" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7520 msgid "pl_PL.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7525 msgid "Portuguese" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7526 msgid "Brazil" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7527 msgid "pt_BR.ISO8859-1" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7528 msgid "pt_BR.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7533 msgid "Russian" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7534 msgid "Russia" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7535 msgid "ru_RU.KOI8-R" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7536 msgid "ru_RU.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7537 msgid "KOI8-R" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7541 msgid "Serbian" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7542 msgid "Serbia" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7543 msgid "sr_YU.ISO8859-2" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7544 msgid "sr_YU.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7549 msgid "Turkish" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7550 msgid "Turkey" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7551 msgid "tr_TR.ISO8859-9" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7552 msgid "tr_TR.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7553 msgid "ISO 8859-9" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7557 book.translate.xml:7565 msgid "Chinese" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7558 msgid "China" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7559 msgid "zh_CN.UTF-8" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7560 msgid "zh_CN.po" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7566 msgid "Taiwan" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7567 msgid "zh_TW.UTF-8" msgstr "" #. (itstool) path: row/entry #: book.translate.xml:7568 msgid "zh_TW.po" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7575 msgid "The translations are in subdirectories of the main documentation directory, here assumed to be ~/doc/ as shown in . For example, German translations are located in ~/doc/de_DE.ISO8859-1/, and French translations are in ~/doc/fr_FR.ISO8859-1/." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7584 msgid "Each language directory contains separate subdirectories named for the type of documents, usually articles/ and books/." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7589 msgid "Combining these directory names gives the complete path to an article or book. For example, the French translation of the NanoBSD article is in ~/doc/fr_FR.ISO8859-1/articles/nanobsd/, and the Mongolian translation of the Handbook is in ~/doc/mn_MN.UTF-8/books/handbook/." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7596 msgid "A new language directory must be created when translating a document to a new language. If the language directory already exists, only a subdirectory in the articles/ or books/ directory is needed." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7602 msgid "" "FreeBSD documentation builds are controlled by a Makefile in the same directory. With simple articles, the Makefile can often just be copied verbatim from the original English directory. The translation process combines multiple separate book.xml and chapter.xml files in books into a single file, so the Makefile for book translations must be copied and modified." msgstr "" #. (itstool) path: example/title #: book.translate.xml:7613 msgid "Creating a Spanish Translation of the Porter's Handbook" msgstr "" #. (itstool) path: example/para #: book.translate.xml:7616 msgid "Create a new Spanish translation of the Porter's Handbook. The original is a book in ~/doc/en_US.ISO8859-1/books/porters-handbook/." msgstr "" #. (itstool) path: step/para #: book.translate.xml:7623 msgid "The Spanish language books directory ~/doc/es_ES.ISO8859-1/books/ already exists, so only a new subdirectory for the Porter's Handbook is needed:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7627 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/books/\n" "% svn mkdir porters-handbook\n" "A porters-handbook" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7633 msgid "Copy the Makefile from the original book:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7636 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook\n" "% svn cp ~/doc/en_US.ISO8859-1/books/porters-handbook/Makefile .\n" "A Makefile" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7640 msgid "Modify the contents of the Makefile to only expect a single book.xml:" msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:7644 #, no-wrap msgid "" "#\n" "# $FreeBSD$\n" "#\n" "# Build the FreeBSD Porter's Handbook.\n" "#\n" "\n" "MAINTAINER=doc@FreeBSD.org\n" "\n" "DOC?= book\n" "\n" "FORMATS?= html-split\n" "\n" "INSTALL_COMPRESSED?= gz\n" "INSTALL_ONLY_COMPRESSED?=\n" "\n" "# XML content\n" "SRCS= book.xml\n" "\n" "# Images from the cross-document image library\n" "IMAGES_LIB+= callouts/1.png\n" "IMAGES_LIB+= callouts/2.png\n" "IMAGES_LIB+= callouts/3.png\n" "IMAGES_LIB+= callouts/4.png\n" "IMAGES_LIB+= callouts/5.png\n" "IMAGES_LIB+= callouts/6.png\n" "IMAGES_LIB+= callouts/7.png\n" "IMAGES_LIB+= callouts/8.png\n" "IMAGES_LIB+= callouts/9.png\n" "IMAGES_LIB+= callouts/10.png\n" "IMAGES_LIB+= callouts/11.png\n" "IMAGES_LIB+= callouts/12.png\n" "IMAGES_LIB+= callouts/13.png\n" "IMAGES_LIB+= callouts/14.png\n" "IMAGES_LIB+= callouts/15.png\n" "IMAGES_LIB+= callouts/16.png\n" "IMAGES_LIB+= callouts/17.png\n" "IMAGES_LIB+= callouts/18.png\n" "IMAGES_LIB+= callouts/19.png\n" "IMAGES_LIB+= callouts/20.png\n" "IMAGES_LIB+= callouts/21.png\n" "\n" "URL_RELPREFIX?= ../../../..\n" "DOC_PREFIX?= ${.CURDIR}/../../..\n" "\n" "SYMLINKS= ${DESTDIR} index.html handbook.html\n" "\n" ".include \"${DOC_PREFIX}/share/mk/doc.project.mk\"" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7692 msgid "Now the document structure is ready for the translator to begin translating with make po." msgstr "" #. (itstool) path: example/title #: book.translate.xml:7700 msgid "Creating a French Translation of the PGP Keys Article" msgstr "" #. (itstool) path: example/para #: book.translate.xml:7703 msgid "Create a new French translation of the PGP Keys article. The original is an article in ~/doc/en_US.ISO8859-1/articles/pgpkeys/." msgstr "" #. (itstool) path: step/para #: book.translate.xml:7710 msgid "The French language article directory ~/doc/fr_FR.ISO8859-1/articles/ already exists, so only a new subdirectory for the PGP Keys article is needed:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7714 #, no-wrap msgid "" "% cd ~/doc/fr_FR.ISO8859-1/articles/\n" "% svn mkdir pgpkeys\n" "A pgpkeys" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7720 msgid "Copy the Makefile from the original article:" msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7723 #, no-wrap msgid "" "% cd ~/doc/fr_FR.ISO8859-1/articles/pgpkeys\n" "% svn cp ~/doc/en_US.ISO8859-1/articles/pgpkeys/Makefile .\n" "A Makefile" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7727 msgid "Check the contents of the Makefile. Because this is a simple article, in this case the Makefile can be used unchanged. The $FreeBSD...$ version string on the third line will be replaced by the version control system when this file is committed." msgstr "" #. (itstool) path: step/programlisting #: book.translate.xml:7734 #, no-wrap msgid "" "#\n" "# $FreeBSD$\n" "#\n" "# Article: PGP Keys\n" "\n" "DOC?= article\n" "\n" "FORMATS?= html\n" "WITH_ARTICLE_TOC?= YES\n" "\n" "INSTALL_COMPRESSED?= gz\n" "INSTALL_ONLY_COMPRESSED?=\n" "\n" "SRCS= article.xml\n" "\n" "# To build with just key fingerprints, set FINGERPRINTS_ONLY.\n" "\n" "URL_RELPREFIX?= ../../../..\n" "DOC_PREFIX?= ${.CURDIR}/../../..\n" "\n" ".include \"${DOC_PREFIX}/share/mk/doc.project.mk\"" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7756 msgid "With the document structure complete, the PO file can be created with make po." msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:7765 msgid "Translating" msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7767 msgid "The gettext system greatly reduces the number of things that must be tracked by a translator. Strings to be translated are extracted from the original document into a PO file. Then a PO editor is used to enter the translated versions of each string." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7774 msgid "The FreeBSD PO translation system does not overwrite PO files, so the extraction step can be run at any time to update the PO file." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7779 msgid "A PO editor is used to edit the file. editors/poedit is shown in these examples because it is simple and has minimal requirements. Other PO editors offer features to make the job of translating easier. The Ports Collection offers several of these editors, including devel/gtranslator." msgstr "" #. (itstool) path: sect1/para #: book.translate.xml:7787 msgid "It is important to preserve the PO file. It contains all of the work that translators have done." msgstr "" #. (itstool) path: example/title #: book.translate.xml:7791 msgid "Translating the Porter's Handbook to Spanish" msgstr "" #. (itstool) path: example/para #: book.translate.xml:7793 msgid "Enter Spanish translations of the contents of the Porter's Handbook." msgstr "" #. (itstool) path: step/para #: book.translate.xml:7798 msgid "Change to the Spanish Porter's Handbook directory and update the PO file. The generated PO file is called es_ES.po as shown in ." msgstr "" #. (itstool) path: step/screen #: book.translate.xml:7804 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook\n" "% make po" msgstr "" #. (itstool) path: step/para #: book.translate.xml:7809 msgid "Enter translations using a PO editor:" msgstr "" #. (itstool) path: sect1/title #: book.translate.xml:7819 msgid "Tips for Translators" msgstr "" #. (itstool) path: sect2/title #. (itstool) path: example/title #: book.translate.xml:7822 book.translate.xml:7828 msgid "Preserving XML Tags" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:7824 msgid "Preserve XML tags that are shown in the English original." msgstr "" #. (itstool) path: example/para #: book.translate.xml:7830 msgid "English original:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:7832 #, no-wrap msgid "If acronymNTPacronym is not being used" msgstr "" #. (itstool) path: example/para #: book.translate.xml:7834 msgid "Spanish translation:" msgstr "" #. (itstool) path: example/programlisting #: book.translate.xml:7836 #, no-wrap msgid "Si acronymNTPacronym no se utiliza" msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:7841 msgid "Preserving Spaces" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:7843 msgid "Preserve existing spaces at the beginning and end of strings to be translated. The translated version must have these spaces also." msgstr "" #. (itstool) path: sect2/title #: book.translate.xml:7849 msgid "Verbatim Tags" msgstr "" #. (itstool) path: sect2/para #: book.translate.xml:7851 msgid "The contents of some tags should be copied verbatim, not translated:" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7856 msgid "citerefentry" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7860 msgid "command" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7864 msgid "filename" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7868 msgid "literal" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7872 msgid "manvolnum" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7876 msgid "orgname" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7880 msgid "package" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7884 msgid "programlisting" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7888 msgid "prompt" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7892 msgid "refentrytitle" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7896 msgid "screen" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7900 msgid "userinput" msgstr "" #. (itstool) path: listitem/para #: book.translate.xml:7904 msgid "varname" msgstr "" +#. (itstool) path: sect2/title +#: book.translate.xml:7910 +#, fuzzy +msgid "$FreeBSD$ Strings" +msgstr "FreeBSD" + +#. (itstool) path: sect2/para +#: book.translate.xml:7913 +msgid "The $FreeBSD$ version strings used in files require special handling. In examples like , these strings are not meant to be expanded. The English documents use &dollar; entities to avoid including actual literal dollar signs in the file:" +msgstr "" + +#. (itstool) path: sect2/programlisting +#: book.translate.xml:7920 book.translate.xml:7938 +#, no-wrap +msgid "&dollar;FreeBSD&dollar;" +msgstr "" + +#. (itstool) path: sect2/para +#: book.translate.xml:7922 +msgid "The &dollar; entities are not seen as dollar signs by the version control system and so the string is not expanded into a version string." +msgstr "" + +#. (itstool) path: sect2/para +#: book.translate.xml:7926 +msgid "When a PO file is created, the &dollar; entities used in examples are replaced with actual dollar signs. The resulting literal $FreeBSD$ string will be wrongly expanded by the version control system when the file is committed." +msgstr "" + +#. (itstool) path: sect2/para +#: book.translate.xml:7933 +msgid "The same technique as used in the English documents can be used in the translation. The &dollar; is used to replace the dollar sign in the translation entered into the PO editor:" +msgstr "" + #. (itstool) path: sect1/title -#: book.translate.xml:7949 +#: book.translate.xml:7981 msgid "Building a Translated Document" msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:7951 +#: book.translate.xml:7983 msgid "" "A translated version of the original document can be created at any time. Any untranslated portions of the original will be included in English in the resulting document. Most PO editors have an indicator that shows how much of the translation has been completed. This makes it easy for the translator to see when enough strings have been translated to make building the final document " "worthwhile." msgstr "" #. (itstool) path: example/title -#: book.translate.xml:7961 +#: book.translate.xml:7993 msgid "Building the Spanish Porter's Handbook" msgstr "" #. (itstool) path: example/para -#: book.translate.xml:7963 +#: book.translate.xml:7995 msgid "Build and preview the Spanish version of the Porter's Handbook that was created in an earlier example." msgstr "" #. (itstool) path: step/para -#: book.translate.xml:7968 +#: book.translate.xml:8000 msgid "Build the translated document. Because the original is a book, the generated document is book.xml." msgstr "" #. (itstool) path: step/screen -#: book.translate.xml:7972 +#: book.translate.xml:8004 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/books/porters-handbook\n" "% make tran" msgstr "" #. (itstool) path: step/para -#: book.translate.xml:7977 +#: book.translate.xml:8009 msgid "Render the translated book.xml to HTML and view it with Firefox. This is the same procedure used with the English version of the documents, and other FORMATS can be used here in the same way. See ." msgstr "" #. (itstool) path: step/screen -#: book.translate.xml:7984 +#: book.translate.xml:8016 #, no-wrap msgid "" "% make FORMATS=html\n" "% firefox book.html" msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:7992 +#: book.translate.xml:8024 msgid "Submitting the New Translation" msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:7994 +#: book.translate.xml:8026 msgid "Prepare the new translation files for submission. This example shows a new Spanish translation of the NanoBSD article in ~/doc/es_ES.ISO8859-1/articles/nanobsd." msgstr "" #. (itstool) path: step/para -#: book.translate.xml:8001 +#: book.translate.xml:8033 msgid "The PO file must contain a FreeBSD version string comment on the first line:" msgstr "" #. (itstool) path: step/programlisting -#: book.translate.xml:8004 -#, fuzzy, no-wrap +#: book.translate.xml:8036 +#, no-wrap msgid "#$FreeBSD$" -msgstr "BSDi / FreeBSD Mall Inc. bieden sinds bijna een decennium ondersteuningscontracten aan voor FreeBSD." +msgstr "#$FreeBSD$" #. (itstool) path: step/para -#: book.translate.xml:8008 +#: book.translate.xml:8040 msgid "The Makefile, the PO file, and the generated XML translation must all be added to version control:" msgstr "" #. (itstool) path: step/screen -#: book.translate.xml:8013 +#: book.translate.xml:8045 #, no-wrap msgid "" "% cd ~/doc/es_ES.ISO8859-1/articles/nanobsd/\n" "% ls\n" "Makefile\tarticle.xml\tes_ES.po\n" "% svn add Makefile article.xml es_ES.po\n" "A Makefile\n" "A article.xml\n" "A es_ES.po" msgstr "" #. (itstool) path: step/para -#: book.translate.xml:8023 -msgid "These files must also have the Subversion svn:keywords property set to FreeBSD=%H:" +#: book.translate.xml:8055 +msgid "These files must also have the Subversion svn:keywords property set to FreeBSD=%H so $FreeBSD$ strings are expanded into the path, revision, date, and author when committed:" msgstr "" #. (itstool) path: step/screen -#: book.translate.xml:8028 +#: book.translate.xml:8062 #, no-wrap msgid "" "% svn propset svn:keywords FreeBSD=%H Makefile article.xml es_ES.po\n" "property 'svn:keywords' set on 'Makefile'\n" "property 'svn:keywords' set on 'article.xml'\n" "property 'svn:keywords' set on 'es_ES.po'" msgstr "" #. (itstool) path: step/para -#: book.translate.xml:8035 +#: book.translate.xml:8069 msgid "A diff of these new files is created from the ~/doc/ base directory so the full path is shown with the filenames. This helps committers identify the target language directory." msgstr "" #. (itstool) path: step/screen -#: book.translate.xml:8040 +#: book.translate.xml:8074 #, no-wrap msgid "" "% cd ~/doc\n" "svn diff es_ES.ISO8859-1/articles/nanobsd/ > /tmp/es_nanobsd.diff" msgstr "" #. (itstool) path: step/para -#: book.translate.xml:8043 +#: book.translate.xml:8077 msgid "The diff file is now ready for attachment to a documentation bug report or code review." msgstr "" #. (itstool) path: chapter/title -#: book.translate.xml:8085 +#: book.translate.xml:8119 msgid "Writing Style" msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8088 +#: book.translate.xml:8122 msgid "Tips" msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:8090 +#: book.translate.xml:8124 msgid "Technical documentation can be improved by consistent use of several principles. Most of these can be classified into three goals: be clear, be complete, and be concise. These goals can conflict with each other. Good writing consists of a balance between them." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8099 -#, fuzzy +#: book.translate.xml:8133 msgid "Be Clear" -msgstr "Een gevolg van het formele beheer van een enkele SVN-broncodeboom is dat de BSD-ontwikkeling helder is, en dat het mogelijk is om elke versie van het systeem aan de hand van het uitgavenummer of datum te benaderen. SVN staat ook incrementele wijzigingen aan het systeem toe: het repository van FreeBSD bijvoorbeeld wordt ongeveer 100 keer per dag bijgewerkt. De meeste van deze veranderingen zijn klein." +msgstr "Ben duidelijk" #. (itstool) path: sect2/para -#: book.translate.xml:8101 +#: book.translate.xml:8135 msgid "Clarity is extremely important. The reader may be a novice, or reading the document in a second language. Strive for simple, uncomplicated text that clearly explains the concepts." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8106 +#: book.translate.xml:8140 msgid "Avoid flowery or embellished speech, jokes, or colloquial expressions. Write as simply and clearly as possible. Simple text is easier to understand and translate." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8110 +#: book.translate.xml:8144 msgid "Keep explanations as short, simple, and clear as possible. Avoid empty phrases like in order to, which usually just means to. Avoid potentially patronizing words like basically. Avoid Latin terms like i.e. or cf., which may be unknown outside of academic or scientific groups." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8118 +#: book.translate.xml:8152 msgid "Write in a formal style. Avoid addressing the reader as you. For example, say copy the file to /tmp rather than you can copy the file to /tmp." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8124 +#: book.translate.xml:8158 msgid "" "Give clear, correct, tested examples. A trivial example is better than no example. A good example is better yet. Do not give bad examples, identifiable by apologies or sentences like but really it should never be done that way. Bad examples are worse than no examples. Give good examples, because even when warned not to use the example as shown, the " "reader will usually just use the example as shown." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8133 +#: book.translate.xml:8167 msgid "Avoid weasel words like should, might, try, or could. These words imply that the speaker is unsure of the facts, and create doubt in the reader." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8139 +#: book.translate.xml:8173 msgid "Similarly, give instructions as imperative commands: not you should do this, but merely do this." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8145 -#, fuzzy +#: book.translate.xml:8179 msgid "Be Complete" -msgstr "" -"De BSD-tapes bevatten de broncode van AT&T en hadden dus een UNIX bronlicentie nodig. Tegen 1990 raakten de fondsen van de CSRG uitgeput, en er dreigde sluiting. Sommige leden van de groep besloten om de BSD-code uit te geven, welke Open Source was, zonder de propriëtaire code van AT&T. Dit gebeurde eindelijk met de Networking Tape 2, " -"gewoonlijk bekend als Net/2. Net/2 was geen compleet besturingssysteem: ongeveer 20% van de kernelcode ontbrak. Een van de leden van de CSRG, William F. Jolitz, schreef de overblijvende code en gaf het in het begin van 1992 uit als 386BSD. In diezelfde tijd begon een andere groep van ex-CSRG-leden een commercieel bedrijf genaamd Berkeley Software Design Inc. en gaf een betaversie van een besturingssysteem genaamd BSD/386 uit, welke op dezelfde bronnen was gebaseerd. De naam van het besturingssysteem werd later veranderd in BSD/OS." +msgstr "Ben compleet" #. (itstool) path: sect2/para -#: book.translate.xml:8147 +#: book.translate.xml:8181 msgid "Do not make assumptions about the reader's abilities or skill level. Tell them what they need to know. Give links to other documents to provide background information without having to recreate it. Put yourself in the reader's place, anticipate the questions they will ask, and answer them." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8156 +#: book.translate.xml:8190 msgid "Be Concise" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8158 +#: book.translate.xml:8192 msgid "While features should be documented completely, sometimes there is so much information that the reader cannot easily find the specific detail needed. The balance between being complete and being concise is a challenge. One approach is to have an introduction, then a quick start section that describes the most common situation, followed by an in-depth reference section." msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8169 -#, fuzzy +#: book.translate.xml:8203 msgid "Guidelines" -msgstr "Dit is een erg moeilijke vraag om te beantwoorden. Hier zijn wat richtlijnen:" +msgstr "Richtlijnen" #. (itstool) path: sect1/para -#: book.translate.xml:8171 +#: book.translate.xml:8205 msgid "To promote consistency between the myriad authors of the FreeBSD documentation, some guidelines have been drawn up for authors to follow." msgstr "" #. (itstool) path: varlistentry/term -#: book.translate.xml:8177 +#: book.translate.xml:8211 msgid "Use American English Spelling" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8180 +#: book.translate.xml:8214 msgid "There are several variants of English, with different spellings for the same word. Where spellings differ, use the American English variant. color, not colour, rationalize, not rationalise, and so on." msgstr "" #. (itstool) path: note/para -#: book.translate.xml:8187 +#: book.translate.xml:8221 msgid "The use of British English may be accepted in the case of a contributed article, however the spelling must be consistent within the whole document. The other documents such as books, web site, manual pages, etc. will have to use American English." msgstr "" #. (itstool) path: varlistentry/term -#: book.translate.xml:8197 +#: book.translate.xml:8231 msgid "Do not use contractions" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8200 +#: book.translate.xml:8234 msgid "Do not use contractions. Always spell the phrase out in full. Don't use contractions is wrong." msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8204 +#: book.translate.xml:8238 msgid "Avoiding contractions makes for a more formal tone, is more precise, and is slightly easier for translators." msgstr "" #. (itstool) path: varlistentry/term -#: book.translate.xml:8211 +#: book.translate.xml:8245 msgid "Use the serial comma" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8214 +#: book.translate.xml:8248 msgid "In a list of items within a paragraph, separate each item from the others with a comma. Separate the last item from the others with a comma and the word and." msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8219 -#, fuzzy +#: book.translate.xml:8253 msgid "For example:" -msgstr "Een gevolg van het formele beheer van een enkele SVN-broncodeboom is dat de BSD-ontwikkeling helder is, en dat het mogelijk is om elke versie van het systeem aan de hand van het uitgavenummer of datum te benaderen. SVN staat ook incrementele wijzigingen aan het systeem toe: het repository van FreeBSD bijvoorbeeld wordt ongeveer 100 keer per dag bijgewerkt. De meeste van deze veranderingen zijn klein." +msgstr "Bijvoorbeeld:" #. (itstool) path: blockquote/para -#: book.translate.xml:8222 +#: book.translate.xml:8256 msgid "This is a list of one, two and three items." msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8225 +#: book.translate.xml:8259 msgid "Is this a list of three items, one, two, and three, or a list of two items, one and two and three?" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8230 +#: book.translate.xml:8264 msgid "It is better to be explicit and include a serial comma:" msgstr "" #. (itstool) path: blockquote/para -#: book.translate.xml:8234 +#: book.translate.xml:8268 msgid "This is a list of one, two, and three items." msgstr "" #. (itstool) path: varlistentry/term -#: book.translate.xml:8240 +#: book.translate.xml:8274 msgid "Avoid redundant phrases" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8243 +#: book.translate.xml:8277 msgid "Do not use redundant phrases. In particular, the command, the file, and man command are often redundant." msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8247 +#: book.translate.xml:8281 msgid "For example, commands:" msgstr "" #. (itstool) path: informalexample/para -#: book.translate.xml:8250 +#: book.translate.xml:8284 msgid "Wrong: Use the svn command to update sources." msgstr "" #. (itstool) path: informalexample/para -#: book.translate.xml:8255 +#: book.translate.xml:8289 msgid "Right: Use svn to update sources." msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8259 +#: book.translate.xml:8293 msgid "Filenames:" msgstr "" #. (itstool) path: informalexample/para -#: book.translate.xml:8262 +#: book.translate.xml:8296 msgid "Wrong: … in the filename /etc/rc.local…" msgstr "" #. (itstool) path: informalexample/para -#: book.translate.xml:8267 +#: book.translate.xml:8301 msgid "Right: … in /etc/rc.local…" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8271 +#: book.translate.xml:8305 msgid "Manual page references (the second example uses citerefentry with the &man.csh.1; entity):." msgstr "" #. (itstool) path: informalexample/para -#: book.translate.xml:8276 +#: book.translate.xml:8310 msgid "Wrong: See man csh for more information." msgstr "" #. (itstool) path: informalexample/para -#: book.translate.xml:8281 +#: book.translate.xml:8315 msgid "Right: See csh1." msgstr "" #. (itstool) path: varlistentry/term -#: book.translate.xml:8287 +#: book.translate.xml:8321 msgid "Two spaces between sentences" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8290 +#: book.translate.xml:8324 msgid "Always use two spaces between sentences, as it improves readability and eases use of tools such as Emacs." msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8294 +#: book.translate.xml:8328 msgid "A period and spaces followed by a capital letter does not always mark a new sentence, especially in names. Jordan K. Hubbard is a good example. It has a capital H following a period and a space, and is certainly not a new sentence." msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:8303 +#: book.translate.xml:8337 msgid "For more information about writing style, see Elements of Style, by William Strunk." msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8308 +#: book.translate.xml:8342 msgid "Style Guide" msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:8310 +#: book.translate.xml:8344 msgid "To keep the source for the documentation consistent when many different people are editing it, please follow these style conventions." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8315 +#: book.translate.xml:8349 msgid "Letter Case" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8317 +#: book.translate.xml:8351 msgid "Tags are entered in lower case, para, not PARA." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8320 +#: book.translate.xml:8354 msgid "Text that appears in SGML contexts is generally written in upper case, <!ENTITY…>, and <!DOCTYPE…>, not <!entity…> and <!doctype…>." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8331 +#: book.translate.xml:8365 msgid "Acronyms should be defined the first time they appear in a document, as in: Network Time Protocol (NTP). After the acronym has been defined, use the acronym alone unless it makes more sense contextually to use the whole term. Acronyms are usually defined only once per chapter or per document." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8339 +#: book.translate.xml:8373 msgid "All acronyms should be enclosed in acronym tags." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8344 +#: book.translate.xml:8378 msgid "Indentation" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8346 +#: book.translate.xml:8380 msgid "The first line in each file starts with no indentation, regardless of the indentation level of the file which might contain the current file." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8350 +#: book.translate.xml:8384 msgid "Opening tags increase the indentation level by two spaces. Closing tags decrease the indentation level by two spaces. Blocks of eight spaces at the start of a line should be replaced with a tab. Do not use spaces in front of tabs, and do not add extraneous whitespace at the end of a line. Content within elements should be indented by two spaces if the content runs over more than one line." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8358 +#: book.translate.xml:8392 msgid "For example, the source for this section looks like this:" msgstr "" #. (itstool) path: sect2/programlisting -#: book.translate.xml:8361 +#: book.translate.xml:8395 #, no-wrap msgid "" "chapter\n" " title...title\n" "\n" " sect1\n" " title...title\n" "\n" " sect2\n" " titleIndentationtitle\n" "\n" " paraThe first line in each file starts with no indentation,\n" "\temphasisregardlessemphasis of the indentation level of\n" "\tthe file which might contain the current file.para\n" "\n" " ...\n" " sect2\n" " sect1\n" "chapter" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8379 +#: book.translate.xml:8413 msgid "Tags containing long attributes follow the same rules. Following the indentation rules in this case helps editors and writers see which content is inside the tags:" msgstr "" #. (itstool) path: sect2/programlisting -#: book.translate.xml:8384 +#: book.translate.xml:8418 #, no-wrap msgid "" "paraSee the link\n" " linkend=\"gmirror-troubleshooting\"Troubleshootinglink\n" " section if there are problems booting. Powering down and\n" " disconnecting the original filenameada0filename disk\n" " will allow it to be kept as an offline backup.para\n" "\n" "paraIt is also possible to journal the boot disk of a &os;\n" " system. Refer to the article link\n" " xlink:href=\"&url.articles.gjournal-desktop;\"Implementing UFS\n" " Journaling on a Desktop PClink for detailed\n" " instructions.para" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8396 +#: book.translate.xml:8430 msgid "When an element is too long to fit on the remainder of a line without wrapping, moving the start tag to the next line can make the source easier to read. In this example, the systemitem element has been moved to the next line to avoid wrapping and indenting:" msgstr "" #. (itstool) path: sect2/programlisting -#: book.translate.xml:8402 +#: book.translate.xml:8436 #, no-wrap msgid "" "paraWith file flags, even\n" " systemitem class=\"username\"rootsystemitem can be\n" " prevented from removing or altering files.para" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8406 +#: book.translate.xml:8440 msgid "Configurations to help various text editors conform to these guidelines can be found in ." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8412 +#: book.translate.xml:8446 msgid "Tag Style" msgstr "" #. (itstool) path: sect3/title -#: book.translate.xml:8415 +#: book.translate.xml:8449 msgid "Tag Spacing" msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8417 +#: book.translate.xml:8451 msgid "Tags that start at the same indent as a previous tag should be separated by a blank line, and those that are not at the same indent as a previous tag should not:" msgstr "" #. (itstool) path: informalexample/programlisting -#: book.translate.xml:8422 +#: book.translate.xml:8456 #, no-wrap msgid "" "article lang='en'\n" " articleinfo\n" " titleNIStitle\n" "\n" " pubdateOctober 1999pubdate\n" "\n" " abstract\n" " para...\n" "\t...\n" "\t...para\n" " abstract\n" " articleinfo\n" "\n" " sect1\n" " title...title\n" "\n" " para...para\n" " sect1\n" "\n" " sect1\n" " title...title\n" "\n" " para...para\n" " sect1\n" "article" msgstr "" #. (itstool) path: sect3/title -#: book.translate.xml:8451 +#: book.translate.xml:8485 msgid "Separating Tags" msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8453 +#: book.translate.xml:8487 msgid "Tags like itemizedlist which will always have further tags inside them, and in fact do not take character data themselves, are always on a line by themselves." msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8458 +#: book.translate.xml:8492 msgid "Tags like para and term do not need other tags to contain normal character data, and their contents begin immediately after the tag, on the same line." msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8463 +#: book.translate.xml:8497 msgid "The same applies to when these two types of tags close." msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8466 +#: book.translate.xml:8500 msgid "This leads to an obvious problem when mixing these tags." msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8469 +#: book.translate.xml:8503 msgid "When a starting tag which cannot contain character data directly follows a tag of the type that requires other tags within it to use character data, they are on separate lines. The second tag should be properly indented." msgstr "" #. (itstool) path: sect3/para -#: book.translate.xml:8474 +#: book.translate.xml:8508 msgid "When a tag which can contain character data closes directly after a tag which cannot contain character data closes, they co-exist on the same line." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8481 +#: book.translate.xml:8515 msgid "Whitespace Changes" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8483 +#: book.translate.xml:8517 msgid "Do not commit changes to content at the same time as changes to formatting." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8487 +#: book.translate.xml:8521 msgid "When content and whitespace changes are kept separate, translation teams can easily see whether a change was content that must be translated or only whitespace." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8491 +#: book.translate.xml:8525 msgid "For example, if two sentences have been added to a paragraph so that the line lengths now go over 80 columns, first commit the change with the too-long lines. Then fix the line wrapping, and commit this second change. In the commit message for the second change, indicate that this is a whitespace-only change that can be ignored by translators." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8501 +#: book.translate.xml:8535 msgid "Non-Breaking Space" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8503 +#: book.translate.xml:8537 msgid "Avoid line breaks in places where they look ugly or make it difficult to follow a sentence. Line breaks depend on the width of the chosen output medium. In particular, viewing the HTML documentation with a text browser can lead to badly formatted paragraphs like the next one:" msgstr "" #. (itstool) path: sect2/literallayout -#: book.translate.xml:8509 +#: book.translate.xml:8543 #, no-wrap msgid "" "Data capacity ranges from 40 MB to 15\n" "GB. Hardware compression …" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8512 +#: book.translate.xml:8546 msgid "The general entity &nbsp; prohibits line breaks between parts belonging together. Use non-breaking spaces in the following places:" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8518 +#: book.translate.xml:8552 msgid "between numbers and units:" msgstr "" #. (itstool) path: listitem/programlisting -#: book.translate.xml:8519 +#: book.translate.xml:8553 #, no-wrap msgid "57600&nbsp;bps" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8523 +#: book.translate.xml:8557 msgid "between program names and version numbers:" msgstr "" #. (itstool) path: listitem/programlisting -#: book.translate.xml:8524 +#: book.translate.xml:8558 #, no-wrap msgid "&os;&nbsp;9.2" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8528 +#: book.translate.xml:8562 msgid "between multiword names (use with caution when applying this to more than 3-4 word names like The FreeBSD Brazilian Portuguese Documentation Project):" msgstr "" #. (itstool) path: listitem/programlisting -#: book.translate.xml:8532 +#: book.translate.xml:8566 #, no-wrap msgid "Sun&nbsp;Microsystems" msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8539 +#: book.translate.xml:8573 msgid "Word List" msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:8541 +#: book.translate.xml:8575 msgid "This list of words shows the correct spelling and capitalization when used in FreeBSD documentation. If a word is not on this list, ask about it on the FreeBSD documentation project mailing list." msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8549 -#, fuzzy +#: book.translate.xml:8583 msgid "Word" -msgstr "" -"In de open-source wereld is het woord Linux bijna een synoniem van besturingssysteem, maar het is niet het enige open-source UNIX besturingssysteem. Volgens de Internet Operating System Counter, draait sinds april 1999 31.3% van de machines op de wereld die met " -"een netwerk verbonden zijn Linux. 14.6% draait BSD UNIX. Sommige van 's werelds grootste webinstallaties, zoals Yahoo!, draaien BSD. De drukste FTP-server van de wereld van 1999 (nu buiten werking), ftp.cdrom.com, gebruikte BSD om 1.4 TB aan gegevens per dag over te " -"brengen. Het is duidelijk dat dit geen nichemarkt is: BSD is een goed bewaard geheim." +msgstr "Woord" #. (itstool) path: row/entry -#: book.translate.xml:8550 +#: book.translate.xml:8584 msgid "XML Code" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8551 +#: book.translate.xml:8585 msgid "Notes" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8557 -#, fuzzy +#: book.translate.xml:8591 msgid "CD-ROM" -msgstr "" -"De projecten brengen met regelmatige tussenpozen, tussen twee en vier keer per jaar, een RELEASE-versie van het systeem uit, welke beschikbaar is op CD-ROM en vrij te downloaden is van FTP-sites, bijvoorbeeld OpenBSD 2.6-RELEASE of NetBSD 1.4-RELEASE. De RELEASE-versie is bedoeld voor eindgebruikers en is de normale versie van het systeem. NetBSD biedt ook patch-uitgaven aan met een derde cijfer, bijvoorbeeld NetBSD 1.4.2." +msgstr "CD-ROM" #. (itstool) path: row/entry -#: book.translate.xml:8559 +#: book.translate.xml:8593 msgid "acronymCD-ROMacronym" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8563 +#: book.translate.xml:8597 msgid "DoS (Denial of Service)" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8564 +#: book.translate.xml:8598 msgid "acronymDoSacronym" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8568 -#, fuzzy +#: book.translate.xml:8602 msgid "email" -msgstr "grog@FreeBSD.org" +msgstr "email" #. (itstool) path: row/entry -#: book.translate.xml:8572 +#: book.translate.xml:8606 msgid "file system" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8576 +#: book.translate.xml:8610 msgid "IPsec" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8580 -#, fuzzy +#: book.translate.xml:8614 msgid "Internet" -msgstr "" -"In de open-source wereld is het woord Linux bijna een synoniem van besturingssysteem, maar het is niet het enige open-source UNIX besturingssysteem. Volgens de Internet Operating System Counter, draait sinds april 1999 31.3% van de machines op de wereld die met " -"een netwerk verbonden zijn Linux. 14.6% draait BSD UNIX. Sommige van 's werelds grootste webinstallaties, zoals Yahoo!, draaien BSD. De drukste FTP-server van de wereld van 1999 (nu buiten werking), ftp.cdrom.com, gebruikte BSD om 1.4 TB aan gegevens per dag over te " -"brengen. Het is duidelijk dat dit geen nichemarkt is: BSD is een goed bewaard geheim." +msgstr "Internet" #. (itstool) path: row/entry -#: book.translate.xml:8584 +#: book.translate.xml:8618 msgid "manual page" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8588 +#: book.translate.xml:8622 msgid "mail server" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8592 +#: book.translate.xml:8626 msgid "name server" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8596 +#: book.translate.xml:8630 msgid "Ports Collection" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8600 +#: book.translate.xml:8634 msgid "read-only" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8604 +#: book.translate.xml:8638 msgid "Soft Updates" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8608 +#: book.translate.xml:8642 msgid "stdin" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8609 +#: book.translate.xml:8643 msgid "varnamestdinvarname" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8613 +#: book.translate.xml:8647 msgid "stdout" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8614 +#: book.translate.xml:8648 msgid "varnamestdoutvarname" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8618 +#: book.translate.xml:8652 msgid "stderr" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8619 +#: book.translate.xml:8653 msgid "varnamestderrvarname" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8623 -#, fuzzy +#: book.translate.xml:8657 msgid "Subversion" -msgstr "" -"De BSD-kernels worden ontwikkeld en bijgewerkt volgens het Open Source ontwikkelmodel. Elk project beheerst een publiek toegankelijke broncodeboom onder Subversion (SVN), wat alle bronbestanden voor het project bevat, inclusief documentatie en andere toevallige bestanden. SVN stelt gebruikers in staat om een check out te doen (met andere woorden, om een kopie te maken) van elke gewenste versie van het systeem." +msgstr "Subversion" #. (itstool) path: row/entry -#: book.translate.xml:8625 +#: book.translate.xml:8659 msgid "applicationSubversionapplication" msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8626 +#: book.translate.xml:8660 msgid "Do not refer to the Subversion application as SVN in upper case. To refer to the command, use commandsvncommand." msgstr "" #. (itstool) path: row/entry -#: book.translate.xml:8637 +#: book.translate.xml:8671 msgid "web server" -msgstr "" +msgstr "web server" #. (itstool) path: chapter/title -#: book.translate.xml:8676 +#: book.translate.xml:8710 msgid "Editor Configuration" msgstr "" #. (itstool) path: chapter/para -#: book.translate.xml:8678 +#: book.translate.xml:8712 msgid "Adjusting text editor configuration can make working on document files quicker and easier, and help documents conform to FDP guidelines." msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8683 +#: book.translate.xml:8717 msgid "Vim" -msgstr "" +msgstr "Vim" #. (itstool) path: sect1/para -#: book.translate.xml:8685 +#: book.translate.xml:8719 msgid "Install from editors/vim or editors/vim-lite." msgstr "" #. (itstool) path: sect2/title -#: book.translate.xml:8689 book.translate.xml:8764 +#: book.translate.xml:8723 book.translate.xml:8798 msgid "Configuration" -msgstr "" +msgstr "Configuratie" #. (itstool) path: sect2/para -#: book.translate.xml:8691 +#: book.translate.xml:8725 msgid "Edit ~/.vimrc, adding these lines:" msgstr "" #. (itstool) path: sect2/programlisting -#: book.translate.xml:8694 +#: book.translate.xml:8728 #, no-wrap msgid "" "if has(\"autocmd\")\n" " au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()\n" " au BufNewFile,BufRead *.[1-9] call ShowSpecial()\n" "endif \" has(autocmd)\n" "\n" "function Set_Highlights()\n" " \"match ExtraWhitespace /^\\s* \\s*\\|\\s\\+$/\n" " highlight default link OverLength ErrorMsg\n" " match OverLength /\\%71v.\\+/\n" " return 0\n" "endfunction\n" "\n" "function ShowSpecial()\n" " setlocal list listchars=tab:>>,trail:*,eol:$\n" " hi def link nontext ErrorMsg\n" " return 0\n" "endfunction \" ShowSpecial()\n" "\n" "function Set_SGML()\n" " setlocal number\n" " syn match sgmlSpecial \"&[^;]*;\"\n" " setlocal syntax=sgml\n" " setlocal filetype=xml\n" " setlocal shiftwidth=2\n" " setlocal textwidth=70\n" " setlocal tabstop=8\n" " setlocal softtabstop=2\n" " setlocal formatprg=\"fmt -p\"\n" " setlocal autoindent\n" " setlocal smartindent\n" " \" Rewrap paragraphs\n" " noremap P gqj\n" " \" Replace spaces with tabs\n" " noremap T :s/ /\\t/<CR>\n" " call ShowSpecial()\n" " call Set_Highlights()\n" " return 0\n" "endfunction \" Set_SGML()" msgstr "" +"if has(\"autocmd\")\n" +" au BufNewFile,BufRead *.sgml,*.ent,*.xsl,*.xml call Set_SGML()\n" +" au BufNewFile,BufRead *.[1-9] call ShowSpecial()\n" +"endif \" has(autocmd)\n" +"\n" +"function Set_Highlights()\n" +" \"match ExtraWhitespace /^\\s* \\s*\\|\\s\\+$/\n" +" highlight default link OverLength ErrorMsg\n" +" match OverLength /\\%71v.\\+/\n" +" return 0\n" +"endfunction\n" +"\n" +"function ShowSpecial()\n" +" setlocal list listchars=tab:>>,trail:*,eol:$\n" +" hi def link nontext ErrorMsg\n" +" return 0\n" +"endfunction \" ShowSpecial()\n" +"\n" +"function Set_SGML()\n" +" setlocal number\n" +" syn match sgmlSpecial \"&[^;]*;\"\n" +" setlocal syntax=sgml\n" +" setlocal filetype=xml\n" +" setlocal shiftwidth=2\n" +" setlocal textwidth=70\n" +" setlocal tabstop=8\n" +" setlocal softtabstop=2\n" +" setlocal formatprg=\"fmt -p\"\n" +" setlocal autoindent\n" +" setlocal smartindent\n" +" \" Rewrap paragraphs\n" +" noremap P gqj\n" +" \" Replace spaces with tabs\n" +" noremap T :s/ /\\t/<CR>\n" +" call ShowSpecial()\n" +" call Set_Highlights()\n" +" return 0\n" +"endfunction \" Set_SGML()" #. (itstool) path: sect2/title -#: book.translate.xml:8735 book.translate.xml:8793 -#, fuzzy +#: book.translate.xml:8769 book.translate.xml:8827 msgid "Use" -msgstr "Wat betekent dit allemaal in de praktijk? Wie zou BSD moeten gebruiken, en wie Linux?" +msgstr "Gebruik" #. (itstool) path: sect2/para -#: book.translate.xml:8737 +#: book.translate.xml:8771 msgid "Press P to reformat paragraphs or text that has been selected in Visual mode. Press T to replace groups of eight spaces with a tab." msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8744 +#: book.translate.xml:8778 msgid "Emacs" -msgstr "" +msgstr "Emacs" #. (itstool) path: sect1/para -#: book.translate.xml:8746 +#: book.translate.xml:8780 msgid "Install from editors/emacs or editors/xemacs." msgstr "" #. (itstool) path: sect1/para -#: book.translate.xml:8750 +#: book.translate.xml:8784 msgid "Edit ~/.emacs, adding this line:" msgstr "" #. (itstool) path: sect1/programlisting -#: book.translate.xml:8753 +#: book.translate.xml:8787 #, no-wrap msgid "(add-hook 'nxml-mode-hook 'turn-on-auto-fill)" -msgstr "" +msgstr "(add-hook 'nxml-mode-hook 'turn-on-auto-fill)" #. (itstool) path: sect1/title -#: book.translate.xml:8757 +#: book.translate.xml:8791 msgid "nano" -msgstr "" +msgstr "nano" #. (itstool) path: sect1/para -#: book.translate.xml:8759 +#: book.translate.xml:8793 msgid "Install from editors/nano or editors/nano-devel." msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8766 +#: book.translate.xml:8800 msgid "Copy the sample XML syntax highlight file to the user's home directory:" msgstr "" #. (itstool) path: sect2/screen -#: book.translate.xml:8769 +#: book.translate.xml:8803 #, no-wrap msgid "% cp /usr/local/share/nano/xml.nanorc ~/.nanorc" -msgstr "" +msgstr "% cp /usr/local/share/nano/xml.nanorc ~/.nanorc" #. (itstool) path: sect2/para -#: book.translate.xml:8771 +#: book.translate.xml:8805 msgid "Add these lines to the new ~/.nanorc." msgstr "" #. (itstool) path: sect2/programlisting -#: book.translate.xml:8774 +#: book.translate.xml:8808 #, no-wrap msgid "" "syntax \"xml\" \"\\.([jrs]html?|xml|xslt?)$\"\n" "# trailing whitespace\n" "color ,blue \"[[:space:]]+$\"\n" "# multiples of eight spaces at the start a line\n" "# (after zero or more tabs) should be a tab\n" "color ,blue \"^([TAB]*[ ]{8})+\"\n" "# tabs after spaces\n" "color ,yellow \"( )+TAB\"\n" "# highlight indents that have an odd number of spaces\n" "color ,red \"^(([ ]{2})+|(TAB+))*[ ]{1}[^ ]{1}\"\n" "# lines longer than 70 characters\n" "color ,yellow \"^(.{71})|(TAB.{63})|(TAB{2}.{55})|(TAB{3}.{47}).+$\"" msgstr "" #. (itstool) path: sect2/para -#: book.translate.xml:8787 +#: book.translate.xml:8821 msgid "Process the file to create embedded tabs:" msgstr "" #. (itstool) path: sect2/screen -#: book.translate.xml:8789 +#: book.translate.xml:8823 #, no-wrap msgid "% perl -i'' -pe 's/TAB/\\t/g' ~/.nanorc" -msgstr "" +msgstr "% perl -i'' -pe 's/TAB/\\t/g' ~/.nanorc" #. (itstool) path: sect2/para -#: book.translate.xml:8795 +#: book.translate.xml:8829 msgid "Specify additional helpful options when running the editor:" msgstr "" #. (itstool) path: sect2/screen -#: book.translate.xml:8798 +#: book.translate.xml:8832 #, no-wrap msgid "% nano -AKipwz -r 70 -T8 chapter.xml" -msgstr "" +msgstr "% nano -AKipwz -r 70 -T8 chapter.xml" #. (itstool) path: sect2/para -#: book.translate.xml:8800 +#: book.translate.xml:8834 msgid "Users of csh1 can define an alias in ~/.cshrc to automate these options:" msgstr "" #. (itstool) path: sect2/programlisting -#: book.translate.xml:8804 +#: book.translate.xml:8838 #, no-wrap msgid "alias nano \"nano -AKipwz -r 70 -T8\"" -msgstr "" +msgstr "alias nano \"nano -AKipwz -r 70 -T8\"" #. (itstool) path: sect2/para -#: book.translate.xml:8806 +#: book.translate.xml:8840 msgid "After the alias is defined, the options will be added automatically:" msgstr "" #. (itstool) path: sect2/screen -#: book.translate.xml:8809 +#: book.translate.xml:8843 #, no-wrap msgid "% nano chapter.xml" -msgstr "" +msgstr "% nano chapter.xml" #. (itstool) path: chapter/title -#: book.translate.xml:8847 +#: book.translate.xml:8881 msgid "See Also" -msgstr "" +msgstr "Zie ook" #. (itstool) path: chapter/para -#: book.translate.xml:8849 +#: book.translate.xml:8883 msgid "This document is deliberately not an exhaustive discussion of XML, the DTDs listed, and the FreeBSD Documentation Project. For more information about these, you are encouraged to see the following web sites." msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8855 -#, fuzzy +#: book.translate.xml:8889 msgid "The FreeBSD Documentation Project" -msgstr "FreeBSD is een geregistreerd handelsmerk van de FreeBSD Foundation." +msgstr "Het FreeBSD Documentatieproject" #. (itstool) path: listitem/para -#: book.translate.xml:8859 +#: book.translate.xml:8893 msgid "The FreeBSD Documentation Project web pages" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8864 +#: book.translate.xml:8898 msgid "The FreeBSD Handbook" msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8871 +#: book.translate.xml:8905 msgid "XML" -msgstr "" +msgstr "XML" #. (itstool) path: listitem/para -#: book.translate.xml:8875 +#: book.translate.xml:8909 msgid "W3C's XML page SGML/XML web page" msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8882 +#: book.translate.xml:8916 msgid "HTML" -msgstr "" +msgstr "HTML" #. (itstool) path: listitem/para -#: book.translate.xml:8886 +#: book.translate.xml:8920 msgid "The World Wide Web Consortium" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8891 +#: book.translate.xml:8925 msgid "The HTML 4.0 specification" msgstr "" #. (itstool) path: sect1/title -#: book.translate.xml:8898 +#: book.translate.xml:8932 msgid "DocBook" -msgstr "" +msgstr "DocBook" #. (itstool) path: listitem/para -#: book.translate.xml:8902 +#: book.translate.xml:8936 msgid "The DocBook Technical Committee, maintainers of the DocBook DTD" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8908 +#: book.translate.xml:8942 msgid "DocBook: The Definitive Guide, the online documentation for the DocBook DTD" msgstr "" #. (itstool) path: listitem/para -#: book.translate.xml:8914 +#: book.translate.xml:8948 msgid "The DocBook Open Repository contains DSSSL stylesheets and other resources for people using DocBook" msgstr "" #. (itstool) path: appendix/para -#: book.translate.xml:8960 +#: book.translate.xml:8994 msgid "" "These examples are not exhaustive—they do not contain all the elements that might be desirable to use, particularly in a document's front matter. For more examples of DocBook markup, examine the XML source for this and other documents available in the Subversion doc repository, or available online starting at http://svnweb.FreeBSD.org/doc/." msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: book.translate.xml:8969 book.translate.xml:8972 +#: book.translate.xml:9003 book.translate.xml:9006 msgid "DocBook book" -msgstr "" +msgstr "DocBook book" #. (itstool) path: example/programlisting -#: book.translate.xml:8974 +#: book.translate.xml:9008 #, no-wrap msgid "" "<!DOCTYPE book PUBLIC \"-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN\"\n" "\t\"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd\">\n" "\n" "book xmlns=\"http://docbook.org/ns/docbook\"\n" " xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"5.0\"\n" " xml:lang=\"en\"\n" "\n" " info\n" " titleAn Example Booktitle\n" "\n" " author\n" " personname\n" " firstnameYour first namefirstname\n" " surnameYour surnamesurname\n" " personname\n" "\n" " affiliation\n" "\taddress\n" "\t emailfoo@example.comemail\n" "\taddress\n" " affiliation\n" " author\n" "\n" " copyright\n" " year2000year\n" " holderCopyright string hereholder\n" " copyright\n" "\n" " abstract\n" " paraIf your book has an abstract then it should go here.para\n" " abstract\n" " info\n" "\n" " preface\n" " titlePrefacetitle\n" "\n" " paraYour book may have a preface, in which case it should be placed\n" " here.para\n" " preface\n" "\n" " chapter\n" " titleMy First Chaptertitle\n" "\n" " paraThis is the first chapter in my book.para\n" "\n" " sect1\n" " titleMy First Sectiontitle\n" "\n" " paraThis is the first section in my book.para\n" " sect1\n" " chapter\n" "book" msgstr "" #. (itstool) path: sect1/title #. (itstool) path: example/title -#: book.translate.xml:9030 book.translate.xml:9033 +#: book.translate.xml:9064 book.translate.xml:9067 msgid "DocBook article" -msgstr "" +msgstr "DocBook article" #. (itstool) path: example/programlisting -#: book.translate.xml:9035 +#: book.translate.xml:9069 #, no-wrap msgid "" "<!DOCTYPE article PUBLIC \"-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN\"\n" "\t\"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd\">\n" "\n" "article xmlns=\"http://docbook.org/ns/docbook\"\n" " xmlns:xlink=\"http://www.w3.org/1999/xlink\" version=\"5.0\"\n" " xml:lang=\"en\"\n" "\n" " info\n" " titleAn Example Articletitle\n" "\n" " author\n" " personname\n" " firstnameYour first namefirstname\n" " surnameYour surnamesurname\n" " personname\n" "\n" " affiliation\n" "\taddress\n" "\t emailfoo@example.comemail\n" "\taddress\n" " affiliation\n" " author\n" "\n" " copyright\n" " year2000year\n" " holderCopyright string hereholder\n" " copyright\n" "\n" " abstract\n" " paraIf your article has an abstract then it should go here.para\n" " abstract\n" " info\n" "\n" " sect1\n" " titleMy First Sectiontitle\n" "\n" " paraThis is the first section in my article.para\n" "\n" " sect2\n" " titleMy First Sub-Sectiontitle\n" "\n" " paraThis is the first sub-section in my article.para\n" " sect2\n" " sect1\n" "article" msgstr ""