diff --git a/en_US.ISO8859-1/books/fdp-primer/book.sgml b/en_US.ISO8859-1/books/fdp-primer/book.sgml index 8477b85427..db3bb1162b 100644 --- a/en_US.ISO8859-1/books/fdp-primer/book.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/book.sgml @@ -1,259 +1,260 @@ %books.ent; %chapters; ]> FreeBSD Documentation Project Primer for New Contributors The FreeBSD Documentation Project 1998 1999 2000 2001 2002 2003 2004 + 2005 DocEng $FreeBSD$ $FreeBSD$ &bookinfo.legalnotice; Thank you for becoming a part of the FreeBSD Documentation Project. Your contribution is extremely valuable. This primer covers everything you will need to know in order to start contributing to the FreeBSD Documentation Project, from the tools and software you will be using (both mandatory and recommended) to the philosophy behind the Documentation Project. This document is a work in progress, and is not complete. Sections that are known to be incomplete are indicated with a * in their name. Preface Shell Prompts The following table shows the default system prompt and superuser prompt. The examples will use this prompt to indicate which user you should be running the example as. User Prompt Normal user &prompt.user; root &prompt.root; Typographic Conventions The following table describes the typographic conventions used in this book. Meaning Examples The name of commands, files, and directories. On screen computer output. Edit your .login file.Use ls -a to list all files.You have mail. What you type, when contrasted with on-screen computer output. &prompt.user; su Password: Manual page references. Use su 1 to change user names. User and group names Only root can do this. Emphasis You must do this. Command line variables; replace with the real name or variable. To delete a file, type rm filename Environment variables $HOME is your home directory. Notes, tips, important information, warnings, and examples Within the text appear notes, warnings, and examples. Notes are represented like this, and contain information that you should take note of, as it may affect what you do. Tips are represented like this, and contain information that you might find useful, or lead to an easier way to do something. Important information is represented like this. Typically they flag extra steps you may need to carry out. Warnings are represented like this, and contain information warning you about possible damage if you do not follow the instructions. This damage may be physical, to your hardware or to you, or it may be non-physical, such as the inadvertent deletion of important files. A sample example Examples are represented like this, and typically contain examples you should walk through, or show you what the results of a particular action should be. Acknowledgments 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.sgml-primer; &chap.sgml-markup; &chap.stylesheets; &chap.structure; &chap.doc-build; &chap.the-website; &chap.translations; &chap.writing-style; &chap.psgml-mode; &chap.see-also; &app.examples; diff --git a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml index fdebeb44e8..b7a8ab04a8 100644 --- a/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml +++ b/en_US.ISO8859-1/books/fdp-primer/overview/chapter.sgml @@ -1,300 +1,300 @@ Overview Welcome to the FreeBSD Documentation Project. Good quality documentation is very important to the success of FreeBSD, and the FreeBSD Documentation Project (FDP) is how a lot of that documentation is produced. Your contributions are very valuable. This document's main purpose is to clearly explain how the FDP is organized, how to write and submit documentation to the FDP, and how to effectively use the tools available to you when writing documentation. Membership Everyone is welcome to join the FDP. There is no minimum membership requirement, no quota of documentation you need to produce per month. All you need to do is subscribe to the &a.doc;. After you have finished reading this document you should: Know which documentation is maintained by the FDP. Be able to read and understand the SGML source code for the documentation maintained by the FDP. Be able to make changes to the documentation. Be able to submit your changes back for review and eventual inclusion in the FreeBSD documentation. The FreeBSD Documentation Set The FDP is responsible for four categories of FreeBSD documentation. Manual pages The English language system manual pages are not written by the FDP, as they are part of the base system. However, the FDP can (and has) re-worded parts of existing manual pages to make them clearer, or to correct inaccuracies. The translation teams are responsible for translating the system manual pages into different languages. These translations are kept within the FDP. FAQ The FAQ aims to address (in short question and answer format) questions that are asked, or should be asked, on the various mailing lists and newsgroups devoted to FreeBSD. The format does not permit long and comprehensive answers. Handbook The Handbook aims to be the comprehensive on-line resource and reference for FreeBSD users. Web site This is the main FreeBSD presence on the World Wide Web, visible at http://www.FreeBSD.org/ and many mirrors around the world. The web site is many people's first exposure to FreeBSD. These four groups of documentation are all available in the FreeBSD CVS tree. This means that the logs of changes to these files are visible to anyone, and anyone can use a program such as CVSup or CTM to keep local copies of this documentation. In addition, many people have written tutorials or other web sites relating to FreeBSD. Some of these are stored in the CVS repository as well (where the author has agreed to this). In other cases the author has decided to keep his documentation - separate from the main FreeBSD repository. The FDP endeavours to + separate from the main FreeBSD repository. The FDP endeavors to provide links to as much of this documentation as possible. Before you start This document assumes that you already know: How to maintain an up-to-date local copy of the FreeBSD documentation by maintaining a local copy of the FreeBSD CVS repository (using CVS and either CVSup or CTM) or by using CVSup to download just a checked-out copy. How to download and install new software using either the FreeBSD Ports system or &man.pkg.add.1;. Quick Start If you just want to get going, and feel confident you can pick things up as you go along, follow these instructions. Install the textproc/docproj meta-port. &prompt.root; cd /usr/ports/textproc/docproj &prompt.root; make JADETEX=no install Get a local copy of the FreeBSD doc tree. Either use CVSup in checkout mode to do this, or get a full copy of the CVS repository locally. If you have the CVS repository locally then as a minimum you will need to checkout the doc/share, and doc/en_US.ISO8859-1/share directories. &prompt.user; cvs checkout doc/share &prompt.user; cvs checkout doc/en_US.ISO8859-1/share If you have plenty of disk space then you could check out everything. &prompt.user; cvs checkout doc If you are preparing a change to an existing book or article, check it out of the repository as necessary. If you are planning on contributing a new book or article then use an existing one as a guide. For example, if you want to contribute a new article about setting up a VPN between FreeBSD and Windows 2000 you might do the following. Check out the articles directory. &prompt.user; cvs checkout doc/en_US.ISO8859-1/articles Copy an existing article to use as a template. In this case, you have decided that your new article belongs in a directory called vpn-w2k. &prompt.user; cd doc/en_US.ISO8859-1/articles &prompt.user; cp -R committers-guide vpn-w2k If you wanted to edit an existing document, such as the FAQ, which is in doc/en_US.ISO8859-1/books/faq you would check it out of the repository like this. &prompt.user; cvs checkout doc/en_US.ISO8859-1/books/faq Edit the .sgml files using your editor of choice. Test the markup using the lint target. This will quickly find any errors in the document without actually performing the time-consuming transformation. &prompt.user; make lint When you are ready to actually build the document, you may specify a single format or a list of formats in the FORMATS variable. Currently, html, html-split, txt, ps, pdf, and rtf are supported. The most up to date list of supported formats is listed at the top of the doc/share/mk/doc.docbook.mk file. Make sure to use quotes around the list of formats when you build more than one format with a single command. For example, to convert the document to html only, you would use: &prompt.user; make FORMATS=html But when you want to convert the document to both html and txt format, you could use either two separate &man.make.1; runs, with: &prompt.user; make FORMATS=html &prompt.user; make FORMATS=txt or, you can do it in one command: &prompt.user; make FORMATS="html txt" Submit your changes using &man.send-pr.1;.