FreeBSD Documentation Project Primer for New Contributors

Nik Clayton

nik@FreeBSD.org

Copyright © 1998, 1999, 2000 by Nik Clayton

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.

Redistribution and use in source (SGML DocBook) and 'compiled' forms (SGML, HTML, PDF, PostScript, RTF and so forth) with or without modification, are permitted provided that the following conditions are met:

Redistributions of source code (SGML DocBook) must retain the above copyright notice, this list of conditions and the following disclaimer as the first lines of this file unmodified.
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.

Important: THIS DOCUMENTATION IS PROVIDED BY NIK CLAYTON "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 NIK CLAYTON 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.

Table of Contents

1. Shell Prompts
2. Typographic Conventions
3. Notes, tips, important information, warnings, and examples
4. Acknowledgments

1. Overview

11

1.1. The FreeBSD Documentation Set

11

1.2. Before you start

12

2.1. Mandatory tools

2.1.1. Software
2.1.2. DTDs and Entities
2.1.3. Stylesheets

2.2. Optional tools

2.2.1. Software

3. SGML Primer

3.1. Overview

3.2. Elements, tags, and attributes

3.2.1. For you to do...

3.3. The DOCTYPE declaration

31
3.3.1. Formal Public Identifiers (FPIs)
3.3.2. Alternatives to FPIs

3.4. Escaping back to SGML

3.5. Comments

3.5.1. For you to do...

3.6. Entities

3.6.1. General Entities
3.6.2. Parameter entities
3.6.3. For you to do...

3.7. Using entities to include files

3.7.1. Using general entities to include files
3.7.2. Using parameter entities to include files
3.7.3. For you to do...

3.8. Marked sections

3.8.1. Marked section keywords
3.8.2. For you to do...

3.9. Conclusion

4. SGML Markup

4.1. HTML

4.1.1. Formal Public Identifier (FPI)
4.1.2. Sectional elements
4.1.3. Block elements
4.1.4. In-line elements
4.1.5. Links

4.2. DocBook

4.2.1. FreeBSD extensions
4.2.2. Formal Public Identifier (FPI)
4.2.3. Document structure
4.2.4. Block elements
4.2.5. In-line elements
4.2.6. Images
4.2.7. Links

4.3. * LinuxDoc

5. * Stylesheets

5.1. * DSSSL
5.2. * CSS

6. Structuring documents under doc/

61.

6.1. The top level, doc/

61

6.2. The lang.encoding/ directories

62

6.3. Document specific information

6.3.1. The Handbook

7. The Documentation Build Process

71

7.1. The FreeBSD Documentation Build Toolset

72

7.2. Understanding Makefiles in the Documentation tree

73
7.2.1. Subdirectory Makefiles
7.2.2. Documentation Makefiles

7.3. FreeBSD Documentation Project make includes

74
7.3.1. doc.project.mk
7.3.2. doc.subdir.mk

8. The Website

8.1. Preparation

8.2. Build the web pages from scratch

8.3. Install the web pages into your web server

8.4. Environment variables

81

9. Translations

10. Writing style

101

10.1. Style guide

10.1.1. Letter case
10.1.2. Indentation
10.1.3. Tag style
10.1.4. White space changes

11. Using sgml-mode with Emacs

111

12. See Also

12.1. The FreeBSD Documentation Project

121

12.2. SGML

122

12.3. HTML

123

12.4. DocBook

124

12.5. The Linux Documentation Project

125

A. Examples

A.1. DocBook <book>

A.2. DocBook <article>

A.3. Producing formatted output

A.3.1. Using Jade

List of Examples
1. A sample example
3-1. Using an element (start and end tags)
3-2. Using an element (start tag only)
3-3. Elements within elements; <em>
3-4. Using an element with an attribute
3-5. Single quotes around attributes
3-6. .profile, for sh(1) and bash(1) users
3-7. .login, for csh(1) and tcsh(1) users
3-8. SGML generic comment
3-9. Errorneous SGML comments
3-10. Defining general entities
3-11. Defining parameter entities
3-12. Using general entities to include files
3-13. Using parameter entities to include files
3-14. Structure of a marked section
3-15. Using a CDATA marked section
3-16. Using INCLUDE and IGNORE in marked sections
3-17. Using a parameter entity to control a marked section
4-1. Normal HTML document structure
4-2. <h1>, <h2>, etc.
4-3. Bad ordering of <hn> elements
4-4. <p>
4-5. <blockquote>
4-6. <ul> and <ol>
4-7. Definition lists with <dl>
4-8. <pre>
4-9. Simple use of <table>
4-10. Using rowspan
4-11. Using colspan
4-12. Using rowspan and colspan together
4-13. <em> and <strong>
4-14. <b> and <i>
4-15. <tt>
4-16. <big>, <small>, and <font>
4-17. Using <a href="...">
4-18. Using <a name="...">
4-19. Linking to a named part of another document
4-20. Linking to a named part of the same document
4-21. Boilerplate <book> with <bookinfo>
4-22. Boilerplate <article> with <artheader>
4-23. A simple chapter
4-24. Empty chapters
4-25. Sections in chapters
4-26. <para>
4-27. <blockquote>
4-28. <warning>
4-29. <itemizedlist>, <orderedlist>, and <procedure>
4-30. <programlisting>
4-31. <co> and <calloutlist>
4-32. <informaltable>
4-33. Tables where frame="none"
4-34. <screen>, <prompt>, and <userinput>
4-35. <emphasis>
4-36. Applications, commands, and options.
4-37. <filename>
4-38. <devicename>
4-39. <hostid> and roles
4-40. <username>
4-41. <maketarget> and <makevar>
4-42. <literal>
4-43. <replaceable>
4-44. id on chapters and sections
4-45. <anchor>
4-46. Using <xref>
4-47. Using <link>
4-48. <ulink>
A-1. DocBook <book>
A-2. DocBook <article>
A-3. Converting DocBook to HTML (one large file)
A-4. Converting DocBook to HTML (several small files)
A-5. Converting DocBook to Postscript
A-6. Converting DocBook to PDF

		Next
		Preface

For questions about FreeBSD, e-mail <questions@FreeBSD.org>.
For questions about this documentation, e-mail <doc@FreeBSD.org>.

Партнёры:

Хостинг:

Закладки на сайте
Проследить за страницей

Created 1996-2024 by Maxim Chirkov
Добавить, Поддержать, Вебмастеру