Date: Sun, 23 Jun 2013 21:08:11 +0000 (UTC) From: Glen Barber <gjb@FreeBSD.org> To: doc-committers@freebsd.org, svn-doc-projects@freebsd.org Subject: 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 Message-ID: <201306232108.r5NL8BXk081430@svn.freebsd.org>
next in thread | raw e-mail | index | archive | help
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">
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?201306232108.r5NL8BXk081430>