From owner-svn-doc-all@freebsd.org Tue Oct 27 22:23:29 2015 Return-Path: Delivered-To: svn-doc-all@mailman.ysv.freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) by mailman.ysv.freebsd.org (Postfix) with ESMTP id 59942A1F2E5; Tue, 27 Oct 2015 22:23:29 +0000 (UTC) (envelope-from rene@FreeBSD.org) Received: from repo.freebsd.org (repo.freebsd.org [IPv6:2610:1c1:1:6068::e6a:0]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id DD4541EC6; Tue, 27 Oct 2015 22:23:28 +0000 (UTC) (envelope-from rene@FreeBSD.org) Received: from repo.freebsd.org ([127.0.1.37]) by repo.freebsd.org (8.15.2/8.15.2) with ESMTP id t9RMNSPg088871; Tue, 27 Oct 2015 22:23:28 GMT (envelope-from rene@FreeBSD.org) Received: (from rene@localhost) by repo.freebsd.org (8.15.2/8.15.2/Submit) id t9RMNRfx088868; Tue, 27 Oct 2015 22:23:27 GMT (envelope-from rene@FreeBSD.org) Message-Id: <201510272223.t9RMNRfx088868@repo.freebsd.org> X-Authentication-Warning: repo.freebsd.org: rene set sender to rene@FreeBSD.org using -f From: Rene Ladan Date: Tue, 27 Oct 2015 22:23:27 +0000 (UTC) To: doc-committers@freebsd.org, svn-doc-all@freebsd.org, svn-doc-head@freebsd.org Subject: svn commit: r47688 - head/nl_NL.ISO8859-1/books/fdp-primer X-SVN-Group: doc-head MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit X-BeenThere: svn-doc-all@freebsd.org X-Mailman-Version: 2.1.20 Precedence: list List-Id: "SVN commit messages for the entire doc trees \(except for " user" , " projects" , and " translations" \)" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Tue, 27 Oct 2015 22:23:29 -0000 Author: rene Date: Tue Oct 27 22:23:27 2015 New Revision: 47688 URL: https://svnweb.freebsd.org/changeset/doc/47688 Log: Add an initial and work-in-progress Dutch PO translation of the FreeBSD ocumentation Project Primer. Some notes: - 'make tran' generates a single book.xml from the PO file which combines the contents of the separate English files. - Makefile is simplified to only have book.xml as source. Split output is supported as usual. - IMAGE_LIB is left undefined, 'make' does not complain about this. Added: head/nl_NL.ISO8859-1/books/fdp-primer/ - copied from r47683, head/en_US.ISO8859-1/books/fdp-primer/ head/nl_NL.ISO8859-1/books/fdp-primer/nl_NL.po (contents, props changed) Modified: head/nl_NL.ISO8859-1/books/fdp-primer/Makefile head/nl_NL.ISO8859-1/books/fdp-primer/book.xml Modified: head/nl_NL.ISO8859-1/books/fdp-primer/Makefile ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/Makefile Tue Oct 27 13:11:32 2015 (r47683) +++ head/nl_NL.ISO8859-1/books/fdp-primer/Makefile Tue Oct 27 22:23:27 2015 (r47688) @@ -20,33 +20,6 @@ INSTALL_ONLY_COMPRESSED?= # XML content SRCS= book.xml -SRCS+= overview/chapter.xml -SRCS+= tools/chapter.xml -SRCS+= working-copy/chapter.xml -SRCS+= structure/chapter.xml -SRCS+= doc-build/chapter.xml -SRCS+= the-website/chapter.xml -SRCS+= xml-primer/chapter.xml -SRCS+= xhtml-markup/chapter.xml -SRCS+= docbook-markup/chapter.xml -SRCS+= stylesheets/chapter.xml -SRCS+= translations/chapter.xml -SRCS+= po-translations/chapter.xml -SRCS+= writing-style/chapter.xml -SRCS+= editor-config/chapter.xml -SRCS+= see-also/chapter.xml - -SRCS+= examples/appendix.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 - -# Entities -SRCS+= chapters.ent URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. Modified: head/nl_NL.ISO8859-1/books/fdp-primer/book.xml ============================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/book.xml Tue Oct 27 13:11:32 2015 (r47683) +++ head/nl_NL.ISO8859-1/books/fdp-primer/book.xml Tue Oct 27 22:23:27 2015 (r47688) @@ -1,9 +1,32 @@ - - %chapters; - -]> + + + + + + + + + + + + + + + + + + +]> - - FreeBSD Documentation Project Primer for New - Contributors + + Overzicht van het FreeBSD Documentatieproject voor nieuwe bijdragers - The FreeBSD Documentation Project + Het FreeBSD Documentatieroject - - 1998 - 1999 - 2000 - 2001 - 2002 - 2003 - 2004 - 2005 - 2006 - 2007 - 2008 - 2009 - 2010 - 2011 - 2012 - 2013 - 2014 - DocEng - + 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 DocEng $FreeBSD$ $FreeBSD$ - &legalnotice; + + + 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. + + + - Thank you for becoming a part of the FreeBSD Documentation - Project. Your contribution is extremely valuable, and we - appreciate it. - - 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. + 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. - This is a work in progress. Corrections and - additions are always welcome. + Dit is werk in uitvoering. Correcties en aanvullingen zijn altijd welkom. - Preface + Inleiding - Shell Prompts + Shellprompts - 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. + 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. - User + Gebruiker Prompt - Normal user - &prompt.user; + Gewone gebruiker + % root - &prompt.root; + # @@ -120,74 +134,66 @@ - Typographic Conventions + Typografische aannames - This table describes the typographic conventions - used in this book. + Deze tabel beschrijft de typografische aannames die in dit boek gebruikt worden. - Meaning - Examples + Betekenis + Voorbeelden - The names of commands. - Use ls -l to list all - files. + De naam van commando's. + Gebruik ls -l voor een lijst van alle bestanden. - The names of files. - Edit .login. + De namen van bestanden. + Bewerk .login. - On-screen computer output. + Uitvoer op het computerscherm. You have mail. - What the user types, contrasted with on-screen - computer output. + Wat de gebruiker typt, in contrast met uitvoer op het computerscherm. - &prompt.user; date +"The time is %H:%M" -The time is 09:18 + % date +"De tijd is %H:%M" +De tijd is 09:18 - Manual page references. - Use &man.su.1; to change user identity. + Verwijzing naar handleidingspagina's. + Gebruik su1 om van gebruikersidentiteit te veranderen. - User and group names. - Only root can do - this. + Gebruiker- en groepnamen. + Alleen root kan dit doen. - Emphasis. - The user must do - this. + Nadruk. + De gebruiker moet dit doen. - Text that the user is expected to replace with - the actual text. + Tekst die de gebruiker door de eigenlijke tekst dient te vervangen. - To search for a keyword in the manual pages, type - man -k - keyword + Gebruik man -ksleutelwoord om naar een sleutelwoord in handleidingspagina's te zoeken. - Environment variables. - $HOME is set to the user's home + Omgevingsvariabelen. + $HOME is set to the user's home directory. @@ -196,32 +202,32 @@ The time is 09:18 - Notes, Tips, Important Information, Warnings, and + <title xml:lang="en">Notes, Tips, Important Information, Warnings, and Examples - Notes, warnings, and examples appear within the + Notes, warnings, and examples appear within the text. - Notes are represented like this, and contain information + Notes are represented like this, and contain information to take note of, as it may affect what the user does. - Tips are represented like this, and contain information + Tips are represented like this, and contain information helpful to the user, like showing an easier way to do something. - Important information is represented like this. + Important information is represented like this. Typically, these show extra steps the user may need to take. - Warnings are represented like this, and contain + 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 @@ -229,41 +235,8795 @@ The time is 09:18 - A Sample Example + A Sample Example - Examples are represented like this, and typically + Examples are represented like this, and typically contain examples showing a walkthrough, or the results of a particular action. - Acknowledgments + Acknowledgments - My thanks to Sue Blake, Patrick Durusau, Jon Hamilton, + 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. - &chap.overview; - &chap.tools; - &chap.working-copy; - &chap.structure; - &chap.doc-build; - &chap.the-website; - &chap.xml-primer; - &chap.xhtml-markup; - &chap.docbook-markup; - &chap.stylesheets; - &chap.translations; - &chap.po-translations; - &chap.writing-style; - &chap.editor-config; - &chap.see-also; + + + + Overview + + Welcome to the FreeBSD Documentation Project + (FDP). Quality documentation is crucial + to the success of FreeBSD, and we value your contributions very + highly. + + This document describes how the FDP is + organized, how to write and submit documentation, and how to + effectively use the available tools. + + Everyone is welcome to contribute to the + FDP. Willingness to contribute is the only + membership requirement. + + This primer shows how to: + + + + Identify which parts of FreeBSD are maintained by the + FDP. + + + + Install the required documentation tools and files. + + + + Make changes to the documentation. + + + + Submit changes back for review and inclusion in the FreeBSD + documentation. + + + + + The FreeBSD Documentation Set + + The FDP is responsible for four + categories of FreeBSD documentation. + + + + Handbook: The Handbook is the + comprehensive online resource and reference for FreeBSD + users. + + + + 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. + + + + 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. + + + + 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. + + + + Translation teams are responsible for translating the + Handbook and web site into different languages. Manual pages + are not translated at present. + + Documentation source for the FreeBSD web site, Handbook, and + FAQ is available in the documentation + repository at + https://svn.FreeBSD.org/doc/. + + Source for manual pages is available in a separate + source repository located at + 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. + + Web frontends to both of these repositories are available at and . + + 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. + + + + 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 + + + + 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 + + + + 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 + + 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 +% 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 + + 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 + + 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> + + 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 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 + + + + + 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 + + A checkout of the source code to work on manual pages is + very similar: + + % 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 + + 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 + + + + 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. + + *** DIFF OUTPUT TRUNCATED AT 1000 LINES ***