svn commit: r42011 - in projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer: . docbook-markup overview sgml-markup writing-style xhtml-markup
Glen Barber
gjb at FreeBSD.org
Sun Jun 23 21:08:12 UTC 2013
Author: gjb
Date: Sun Jun 23 21:08:11 2013
New Revision: 42011
URL: http://svnweb.freebsd.org/changeset/doc/42011
Log:
MFH:
Merged /head/en_US.ISO8859-1:r42005-42010
Approved by: doceng (implicit)
Added:
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/docbook-markup/
- copied from r42010, head/en_US.ISO8859-1/books/fdp-primer/docbook-markup/
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/
- copied from r42010, head/en_US.ISO8859-1/books/fdp-primer/xhtml-markup/
Deleted:
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/sgml-markup/
Modified:
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/Makefile
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/book.xml
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/chapters.ent
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
Directory Properties:
projects/ISBN_1-57176-407-0/en_US.ISO8859-1/ (props changed)
Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/Makefile
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 21:04:16 2013 (r42010)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/Makefile Sun Jun 23 21:08:11 2013 (r42011)
@@ -23,7 +23,8 @@ SRCS= book.xml
SRCS+= overview/chapter.xml
SRCS+= psgml-mode/chapter.xml
SRCS+= see-also/chapter.xml
-SRCS+= sgml-markup/chapter.xml
+SRCS+= xhtml-markup/chapter.xml
+SRCS+= docbook-markup/chapter.xml
SRCS+= sgml-primer/chapter.xml
SRCS+= stylesheets/chapter.xml
SRCS+= structure/chapter.xml
Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/book.xml
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 21:04:16 2013 (r42010)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/book.xml Sun Jun 23 21:08:11 2013 (r42011)
@@ -248,7 +248,8 @@ Password:</screen></entry>
&chap.overview;
&chap.tools;
&chap.xml-primer;
- &chap.xml-markup;
+ &chap.xhtml-markup;
+ &chap.docbook-markup;
&chap.stylesheets;
&chap.structure;
&chap.doc-build;
Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/chapters.ent
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 21:04:16 2013 (r42010)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/chapters.ent Sun Jun 23 21:08:11 2013 (r42011)
@@ -13,7 +13,8 @@
<!ENTITY chap.overview SYSTEM "overview/chapter.xml">
<!ENTITY chap.xml-primer SYSTEM "sgml-primer/chapter.xml">
<!ENTITY chap.tools SYSTEM "tools/chapter.xml">
-<!ENTITY chap.xml-markup SYSTEM "sgml-markup/chapter.xml">
+<!ENTITY chap.xhtml-markup SYSTEM "xhtml-markup/chapter.xml">
+<!ENTITY chap.docbook-markup SYSTEM "docbook-markup/chapter.xml">
<!ENTITY chap.stylesheets SYSTEM "stylesheets/chapter.xml">
<!ENTITY chap.structure SYSTEM "structure/chapter.xml">
<!ENTITY chap.the-website SYSTEM "the-website/chapter.xml">
Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Sun Jun 23 21:04:16 2013 (r42010)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/overview/chapter.xml Sun Jun 23 21:08:11 2013 (r42011)
@@ -211,7 +211,8 @@
to the tags which surround the text or the entities that
represent that text in the <acronym>XML</acronym> file.
A reference to the commonly used tags and entities can be
- found in <xref linkend="xml-markup"/>.</para>
+ found in <xref linkend="xhtml-markup"/> and
+ <xref linkend="docbook-markup"/>.</para>
</step>
<step>
@@ -291,4 +292,4 @@
</step>
</procedure>
</sect1>
- </chapter>
\ No newline at end of file
+ </chapter>
Modified: projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml
==============================================================================
--- projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Sun Jun 23 21:04:16 2013 (r42010)
+++ projects/ISBN_1-57176-407-0/en_US.ISO8859-1/books/fdp-primer/writing-style/chapter.xml Sun Jun 23 21:08:11 2013 (r42011)
@@ -71,6 +71,15 @@
rather than <quote>you can copy the file to
<filename>/tmp</filename></quote>.</para>
+ <para>Give clear, correct examples. A trivial example is better
+ than no example, but a good example is better yet. Do not
+ give bad examples, identifiable by apologies or sentences like
+ <quote>but really it should never be done that way</quote>.
+ Bad examples are worse than no examples. Give good examples,
+ because <emphasis>even when warned not to use the example
+ as shown</emphasis>, the reader will usually just use the
+ example as shown.</para>
+
<para>Avoid <emphasis>weasel words</emphasis> like
<quote>should</quote>, <quote>might</quote>,
<quote>try</quote>, or <quote>could</quote>. These words
@@ -89,7 +98,8 @@
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,
- and answer the questions they will ask.</para>
+ anticipate the questions they will ask, and answer
+ them.</para>
</sect2>
<sect2 id="writing-style-be-concise">
More information about the svn-doc-projects
mailing list