| 1 |
neysx 06/03/21 21:55:23 |
| 2 |
|
| 3 |
Modified: doc-tipsntricks.xml |
| 4 |
Log: |
| 5 |
#100026 Added submitters tips. Thanks to rane for initiating it and to nightmorph for turning it into English :) |
| 6 |
|
| 7 |
Revision Changes Path |
| 8 |
1.14 xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml |
| 9 |
|
| 10 |
file : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml?rev=1.14&content-type=text/x-cvsweb-markup&cvsroot=gentoo |
| 11 |
plain: http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml?rev=1.14&content-type=text/plain&cvsroot=gentoo |
| 12 |
diff : http://www.gentoo.org/cgi-bin/viewcvs.cgi/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml.diff?r1=1.13&r2=1.14&cvsroot=gentoo |
| 13 |
|
| 14 |
Index: doc-tipsntricks.xml |
| 15 |
=================================================================== |
| 16 |
RCS file: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v |
| 17 |
retrieving revision 1.13 |
| 18 |
retrieving revision 1.14 |
| 19 |
diff -u -r1.13 -r1.14 |
| 20 |
--- doc-tipsntricks.xml 21 Mar 2006 12:17:12 -0000 1.13 |
| 21 |
+++ doc-tipsntricks.xml 21 Mar 2006 21:55:23 -0000 1.14 |
| 22 |
@@ -1,7 +1,7 @@ |
| 23 |
<?xml version='1.0' encoding="UTF-8"?> |
| 24 |
<!DOCTYPE guide SYSTEM "/dtd/guide.dtd"> |
| 25 |
|
| 26 |
-<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v 1.13 2006/03/21 12:17:12 neysx Exp $ --> |
| 27 |
+<!-- $Header: /var/cvsroot/gentoo/xml/htdocs/proj/en/gdp/doc/doc-tipsntricks.xml,v 1.14 2006/03/21 21:55:23 neysx Exp $ --> |
| 28 |
|
| 29 |
<guide link="/proj/en/gdp/doc/doc-tipsntricks.xml"> |
| 30 |
<title>Documentation Development Tips & Tricks</title> |
| 31 |
@@ -20,8 +20,8 @@ |
| 32 |
|
| 33 |
<license/> |
| 34 |
|
| 35 |
-<version>0.18</version> |
| 36 |
-<date>2005-03-21</date> |
| 37 |
+<version>0.19</version> |
| 38 |
+<date>2006-03-21</date> |
| 39 |
|
| 40 |
<chapter> |
| 41 |
<title>Setting up your local environment</title> |
| 42 |
@@ -417,6 +417,84 @@ |
| 43 |
</chapter> |
| 44 |
|
| 45 |
<chapter> |
| 46 |
+<title>Documentation Submission Tips</title> |
| 47 |
+<section> |
| 48 |
+<title>Check for correct <guide> tags</title> |
| 49 |
+<body> |
| 50 |
+ |
| 51 |
+<p> |
| 52 |
+Make sure that the <guide link> attribute points to the correct location |
| 53 |
+for the guide. This is generally <path>/doc/${LANG}/filename.xml</path>. If you |
| 54 |
+have a translated document, always specify the absolute path to the document |
| 55 |
+(e.g. <path>/doc/${LANG}/</path>). If you are writing a guide that uses the |
| 56 |
+<c>guide</c> or <c>book</c> DTD, you may use either |
| 57 |
+<path>/doc/${LANG}/filename.xml</path> or <path>filename.xml</path>. Generally, |
| 58 |
+the GDP recommends the former specification. |
| 59 |
+</p> |
| 60 |
+ |
| 61 |
+</body> |
| 62 |
+</section> |
| 63 |
+<section> |
| 64 |
+<title>Check links</title> |
| 65 |
+<body> |
| 66 |
+ |
| 67 |
+<p> |
| 68 |
+You <e>must</e> verify that all hyperlinks in your document work. If it is a |
| 69 |
+translated document, make sure that any links to other translated documents |
| 70 |
+point to the existing files. |
| 71 |
+</p> |
| 72 |
+ |
| 73 |
+</body> |
| 74 |
+</section> |
| 75 |
+<section> |
| 76 |
+<title>Check for tabs</title> |
| 77 |
+<body> |
| 78 |
+ |
| 79 |
+<p> |
| 80 |
+Tabs are absolutely forbidden in GuideXML documents except when required (e.g. |
| 81 |
+if the document instructs the user to use tabs). To check a document for tabs, |
| 82 |
+run <c>grep "CTRL+V<TAB>" file.xml</c>. Fix any lines that <c>grep</c> |
| 83 |
+prints out. |
| 84 |
+</p> |
| 85 |
+ |
| 86 |
+</body> |
| 87 |
+</section> |
| 88 |
+<section> |
| 89 |
+<title>Bugzilla</title> |
| 90 |
+<body> |
| 91 |
+ |
| 92 |
+<p> |
| 93 |
+Once you have finished your document, submit it to the Documentation Team using |
| 94 |
+<uri |
| 95 |
+link="http://bugs.gentoo.org/enter_bug.cgi?product=Documentation">Bugzilla</uri>. |
| 96 |
+You don't have to mention information like platform, <c>emerge info</c> |
| 97 |
+output, arch, steps to reproduce, etc. If you have a translated document, be |
| 98 |
+sure to select the <uri |
| 99 |
+link="http://bugs.gentoo.org/enter_bug.cgi?product=Doc%20Translations">Doc |
| 100 |
+Translations</uri> component for your bugs. Also, include a helpful summary |
| 101 |
+for your translation using the preferred format: "[fr] New translation: |
| 102 |
+/doc/fr/gnupg-user.xml". Replace <b>[fr]</b> with the two-letter code for your |
| 103 |
+language. |
| 104 |
+</p> |
| 105 |
+ |
| 106 |
+<p> |
| 107 |
+By default, <mail>docs-team@g.o</mail> is the assignee of your bug; |
| 108 |
+there's no need to change the assignee field. |
| 109 |
+</p> |
| 110 |
+ |
| 111 |
+<p> |
| 112 |
+Attach files and patches to the bug using the "plain text (text/plain)" |
| 113 |
+selection. Do <e>not</e> select "XML source (application/xml)", even if you |
| 114 |
+are submitting a <path>.xml</path> file. Patches should have the "Patch" option |
| 115 |
+checked. Do not submit tarballs full of documents; attach each document and |
| 116 |
+patch individually. |
| 117 |
+</p> |
| 118 |
+ |
| 119 |
+</body> |
| 120 |
+</section> |
| 121 |
+</chapter> |
| 122 |
+ |
| 123 |
+<chapter> |
| 124 |
<title>Commonly or Dangerous Made Mistakes</title> |
| 125 |
<section> |
| 126 |
<title>Forgetting the all-arch-aspect of the Gentoo Handbook</title> |
| 127 |
@@ -442,10 +520,17 @@ |
| 128 |
<body> |
| 129 |
|
| 130 |
<p> |
| 131 |
-Conforming the policy, you <e>must</e> bump a version/date when you make certain |
| 132 |
-changes (most actually). Although the version is less important (SwifT will |
| 133 |
-still kill you if you forget it) the date tells our users when the document was |
| 134 |
-altered for the last time. |
| 135 |
+Conforming to the policy, you <e>must</e> bump a version/date when you make |
| 136 |
+certain changes (most actually). Although the version is less important (SwifT |
| 137 |
+will still kill you if you forget it) the date tells our users when the |
| 138 |
+document was last modified. |
| 139 |
+</p> |
| 140 |
+ |
| 141 |
+<p> |
| 142 |
+If you are making a <e>content</e> change to a document (such as instructions, |
| 143 |
+code examples, etc.), then you must increment the version. For |
| 144 |
+<e>non-content</e> changes (e.g. typo or GuideXML fixes), version bumping is |
| 145 |
+usually unnecessary. |
| 146 |
</p> |
| 147 |
|
| 148 |
<p> |
| 149 |
|
| 150 |
|
| 151 |
|
| 152 |
-- |
| 153 |
gentoo-doc-cvs@g.o mailing list |
Archives