Index: head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 52690) +++ head/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml (revision 52691) @@ -1,264 +1,264 @@ Overview Welcome to the &os; Documentation Project (FDP). Quality documentation is crucial to the success of &os;, 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 &os; 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 &os; documentation. Quick Start Some preparatory steps must be taken before editing the &os; documentation. First, subscribe to the &a.doc;. 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 meta-package and Subversion. This meta-package installs all of the software needed to edit and build &os; documentation. The Subversion package is needed to obtain a working copy of the documentation and generate patches with. &prompt.root; pkg install docproj subversion Install a local working copy of the documentation from the &os; repository in ~/doc (see ). - &prompt.user; svn checkout https://repo.FreeBSD.org/doc/head ~/doc + &prompt.user; svn checkout http://repo.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: &prompt.user; 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: &prompt.user; 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: &prompt.user; cd ~/doc &prompt.user; 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 Summary of [patch] short description of problem. Select the Component Documentation. In the Description field, enter a short description of the changes and any important details about them. Use the [ Add an attachment ] button to attach the diff file. Finally, use the [ Submit Bug ] button to submit your diff to the problem report system. The &os; Documentation Set The FDP is responsible for four categories of &os; documentation. Handbook: The Handbook is the comprehensive online resource and reference for &os; 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 &os;. 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 &os; presence on the web, visible at https://www.FreeBSD.org/ and many mirrors around the world. The web site is typically a new user's first exposure to &os;. 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 &os; 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 &a.svn-doc-all.url;. Web frontends to both of these repositories are available at and . Many people have written tutorials or how-to articles about &os;. 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. Index: head/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml (revision 52690) +++ head/en_US.ISO8859-1/books/fdp-primer/translations/chapter.xml (revision 52691) @@ -1,483 +1,483 @@ 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 &a.doceng;. 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: - &prompt.user; svn checkout https://repo.FreeBSD.org/doc/head/ head + &prompt.user; svn checkout http://repo.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: &prompt.user; svn diff -r33733:33734 en_US.ISO8859-1/books/fdp-primer/book.xml Please see the complete explanation of using Subversion in &os; in the &os; Handbook. 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 &a.doc; 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 &man.tar.1; and &man.gzip.1; to compress up your documentation, and send it to the project. &prompt.user; cd doc &prompt.user; tar cf swedish-docs.tar sv_SE.ISO8859-1 &prompt.user; 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 &a.doceng;, 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 &a.doceng;) 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 &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: head/en_US.ISO8859-1/books/faq/book.xml 38674 2012-04-14 13:52:52Z $ --> 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: head/es_ES.ISO8859-1/books/faq/book.xml 38826 2012-05-17 19:12:14Z hrs $ Original revision: r38674 --> Index: head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml =================================================================== --- head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 52690) +++ head/en_US.ISO8859-1/books/fdp-primer/working-copy/chapter.xml (revision 52691) @@ -1,184 +1,184 @@ The Working Copy The working copy is a copy of the &os; 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 &os; documentation files. It is obtained by installing the Subversion package: &prompt.root; pkg install subversion Documentation and Manual Pages &os; 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 &os; 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: - &prompt.user; svn checkout https://repo.FreeBSD.org/doc/head ~/doc + &prompt.user; svn checkout http://repo.FreeBSD.org/doc/head ~/doc A checkout of the source code to work on manual pages is very similar: - &prompt.user; svn checkout https://repo.FreeBSD.org/base/head ~/src + &prompt.user; svn checkout http://repo.FreeBSD.org/base/head ~/src Updating a Working Copy The documents and files in the &os; 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 &os; 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: &prompt.user; 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: &prompt.user; 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 &os; 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: &prompt.user; cd ~/doc &prompt.user; 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 &os; 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: &prompt.user; cd ~/doc &prompt.user; 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.