cvs: peardoc /en/chapters/faq documentation.xml
| From: | Christian Weiske | Date: | Sat, 23 Feb 2008 19:08:00 +0000 |
| Subject: | cvs: peardoc /en/chapters/faq documentation.xml | ||
| Groups: | php.pear.doc | ||
| Request: | Send a blank email to pear-doc+get-10534@lists.php.net to get a copy of this message | ||
cweiske Sat Feb 23 19:08:00 2008 UTC
Modified files:
/peardoc/en/chapters/faq documentation.xml
Log:
Add hint to xsl sheets
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/faq/documentation.xml?r1=1.4&r2=1.5&diff_format=u Index: peardoc/en/chapters/faq/documentation.xml diff -u peardoc/en/chapters/faq/documentation.xml:1.4 peardoc/en/chapters/faq/documentation.xml:1.5 --- peardoc/en/chapters/faq/documentation.xml:1.4 Fri Sep 7 07:21:59 2007 +++ peardoc/en/chapters/faq/documentation.xml Sat Feb 23 19:08:00 2008 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="utf-8"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 id="faq.documentation"> <title>Documentation/translation FAQ</title> <sect2 id="faq.docs-pagedoesnotshowup"> <title> - I added some new package documentation, but the pages + I added some new package documentation, but the pages don't show up in the compiled manual! </title> <titleabbrev>New pages hidden</titleabbrev> @@ -22,7 +22,7 @@ links to the package documentation files. Add the link to your new pages there. </para> - + <para> This also applies if you get a message stating <literal>cannot generate system identifier for general entity @@ -39,9 +39,19 @@ <titleabbrev>Manual echoed on console</titleabbrev> <para> - <filename>configure</filename> did not find the Docbook DSSSL stylesheets. - Install them first. + <filename>configure</filename> did not find the Docbook DSSSL or XSLT + stylesheets. Install them first. </para> + + <para> + If the style sheets are installed, <command>./configure</command> will + list the found directories like this: + </para> + + <screen><![CDATA[ +checking for docbook.dsl... autodetected: /path/to/dsssl-stylesheets-x.yz +checking for docbook.xsl... autodetected: /path/to/xsl-stylesheets-x.y.z +]]></screen> </sect2> @@ -53,41 +63,41 @@ Revision Tracking </titleabbrev> <para> - Working on the translations is not just translating an English file - and committing the results. Much of the work is needed to update - the already translated ones, to get in sync with the content of - the English files. To follow the modifications in the English tree, + Working on the translations is not just translating an English file + and committing the results. Much of the work is needed to update + the already translated ones, to get in sync with the content of + the English files. To follow the modifications in the English tree, you should <ulink url="mailto:&email.pear.doc-subscribe;">subscribe to the PEAR documentation mailing list</ulink> to get CVS commit messages, or read the archives. If you never update your - files, the translations can get useless. + files, the translations can get useless. </para> <para> - Updating a foreign language file can get difficult, as you may not - know when and who translated that file, so you may not know where - you should look for the updates needed. We have one system + Updating a foreign language file can get difficult, as you may not + know when and who translated that file, so you may not know where + you should look for the updates needed. We have one system for tracking the revisions and modification dates of the files - in <literal>peardoc</literal>. + in <literal>peardoc</literal>. </para> <sect3 id="faq.translators.revcheck-comments"> <title>The Revision Comments</title> <para> Instead of storing all responsibilities in a central file, the revision - comment system stores them in the files they provide information about. - Information about translator, revision numbers, and status information - is stored in the revision comment. - Let's see what would be in the header of the example file - <filename>bookinfo.xml</filename> file in this case: + comment system stores them in the files they provide information about. + Information about translator, revision numbers, and status information + is stored in the revision comment. + Let's see what would be in the header of the example file + <filename>bookinfo.xml</filename> file in this case: <programlisting> <!-- EN-Revision: 1.16 Maintainer: jane Status: ready --> </programlisting> </para> <para> - We can see the revision number for the last english file used to - update the translation (EN-Revision: 1.16), the translator cvs account + We can see the revision number for the last english file used to + update the translation (EN-Revision: 1.16), the translator cvs account name. - But we can also add some other status information in the case it is + But we can also add some other status information in the case it is needed (eg. "partial" for incomplete translations). This revision comment system is basically about storing the information in the XML files, and not in a central place. This is extremely @@ -98,7 +108,7 @@ Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a CVS user name, or some nickname without a space, status can be anything without a space. - Note, that this header is not updated by CVS (in contrast with + Note, that this header is not updated by CVS (in contrast with <literal>$Revision</literal>, which is updated automatically). This is only updated when you edit the contents of the comment yourself. @@ -107,7 +117,7 @@ You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. - No, you do not lose this, but get much more! + No, you do not lose this, but get much more! If you would like to build a full list of you files, you can go to the /peardoc/ directory and run: <programlisting> @@ -117,16 +127,16 @@ After running this script you'll get a <filename>revcheck.html</filename> in the same directory. You can find revision comparisons and links to diffs - for all the files in this language. + for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer. </para> <para> There are some optional extensions introduced for this script, - to be available in this generated HTML page. + to be available in this generated HTML page. This is why the <filename>translation.xml</filename> files are - introduced. + introduced. Here comes a simple <filename>translation.xml</filename> file for the imaginary xx language : <programlisting><![CDATA[ @@ -161,24 +171,24 @@ </translation> ]]></programlisting> In this file, you can add users without a CVS account, and can - assign ready documents or work-in-progress files to them. + assign ready documents or work-in-progress files to them. The biggest advantage of using this addon is that all this information is used to generate dynamic tables of translators and files in - the <filename>revcheck.html</filename> file. + the <filename>revcheck.html</filename> file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for - all the translators. - Assigning ready files may be needed if a time consuming update is + all the translators. + Assigning ready files may be needed if a time consuming update is in progress on that file. </para> <para> There are two optional parameters you can add to a <file>, if you would like to record it: the <literal>date</literal> - and <literal>revision</literal>. - Date is assumed to be the date when the work was started, revision - is the checked out revision of the English file used to start the work - (denoted as CO-Revision in the generated table). - There is currently no fixed format for the <literal>date</literal> + and <literal>revision</literal>. + Date is assumed to be the date when the work was started, revision + is the checked out revision of the English file used to start the work + (denoted as CO-Revision in the generated table). + There is currently no fixed format for the <literal>date</literal> parameter. </para> <para>
http://cvs.php.net/viewvc.cgi/peardoc/en/chapters/faq/documentation.xml?r1=1.4&r2=1.5&diff_format=u Index: peardoc/en/chapters/faq/documentation.xml diff -u peardoc/en/chapters/faq/documentation.xml:1.4 peardoc/en/chapters/faq/documentation.xml:1.5 --- peardoc/en/chapters/faq/documentation.xml:1.4 Fri Sep 7 07:21:59 2007 +++ peardoc/en/chapters/faq/documentation.xml Sat Feb 23 19:08:00 2008 @@ -1,12 +1,12 @@ <?xml version="1.0" encoding="utf-8"?> -<!-- $Revision: 1.4 $ --> +<!-- $Revision: 1.5 $ --> <sect1 id="faq.documentation"> <title>Documentation/translation FAQ</title> <sect2 id="faq.docs-pagedoesnotshowup"> <title> - I added some new package documentation, but the pages + I added some new package documentation, but the pages don't show up in the compiled manual! </title> <titleabbrev>New pages hidden</titleabbrev> @@ -22,7 +22,7 @@ links to the package documentation files. Add the link to your new pages there. </para> - + <para> This also applies if you get a message stating <literal>cannot generate system identifier for general entity @@ -39,9 +39,19 @@ <titleabbrev>Manual echoed on console</titleabbrev> <para> - <filename>configure</filename> did not find the Docbook DSSSL stylesheets. - Install them first. + <filename>configure</filename> did not find the Docbook DSSSL or XSLT + stylesheets. Install them first. </para> + + <para> + If the style sheets are installed, <command>./configure</command> will + list the found directories like this: + </para> + + <screen><![CDATA[ +checking for docbook.dsl... autodetected: /path/to/dsssl-stylesheets-x.yz +checking for docbook.xsl... autodetected: /path/to/xsl-stylesheets-x.y.z +]]></screen> </sect2> @@ -53,41 +63,41 @@ Revision Tracking </titleabbrev> <para> - Working on the translations is not just translating an English file - and committing the results. Much of the work is needed to update - the already translated ones, to get in sync with the content of - the English files. To follow the modifications in the English tree, + Working on the translations is not just translating an English file + and committing the results. Much of the work is needed to update + the already translated ones, to get in sync with the content of + the English files. To follow the modifications in the English tree, you should <ulink url="mailto:&email.pear.doc-subscribe;">subscribe to the PEAR documentation mailing list</ulink> to get CVS commit messages, or read the archives. If you never update your - files, the translations can get useless. + files, the translations can get useless. </para> <para> - Updating a foreign language file can get difficult, as you may not - know when and who translated that file, so you may not know where - you should look for the updates needed. We have one system + Updating a foreign language file can get difficult, as you may not + know when and who translated that file, so you may not know where + you should look for the updates needed. We have one system for tracking the revisions and modification dates of the files - in <literal>peardoc</literal>. + in <literal>peardoc</literal>. </para> <sect3 id="faq.translators.revcheck-comments"> <title>The Revision Comments</title> <para> Instead of storing all responsibilities in a central file, the revision - comment system stores them in the files they provide information about. - Information about translator, revision numbers, and status information - is stored in the revision comment. - Let's see what would be in the header of the example file - <filename>bookinfo.xml</filename> file in this case: + comment system stores them in the files they provide information about. + Information about translator, revision numbers, and status information + is stored in the revision comment. + Let's see what would be in the header of the example file + <filename>bookinfo.xml</filename> file in this case: <programlisting> <!-- EN-Revision: 1.16 Maintainer: jane Status: ready --> </programlisting> </para> <para> - We can see the revision number for the last english file used to - update the translation (EN-Revision: 1.16), the translator cvs account + We can see the revision number for the last english file used to + update the translation (EN-Revision: 1.16), the translator cvs account name. - But we can also add some other status information in the case it is + But we can also add some other status information in the case it is needed (eg. "partial" for incomplete translations). This revision comment system is basically about storing the information in the XML files, and not in a central place. This is extremely @@ -98,7 +108,7 @@ Currently, all three fields (English revision, Maintainer, Status) are needed. Maintainer is intended to be a CVS user name, or some nickname without a space, status can be anything without a space. - Note, that this header is not updated by CVS (in contrast with + Note, that this header is not updated by CVS (in contrast with <literal>$Revision</literal>, which is updated automatically). This is only updated when you edit the contents of the comment yourself. @@ -107,7 +117,7 @@ You may see this as a good thing, but using these comments, you lose the quick look on the whole list of your files. - No, you do not lose this, but get much more! + No, you do not lose this, but get much more! If you would like to build a full list of you files, you can go to the /peardoc/ directory and run: <programlisting> @@ -117,16 +127,16 @@ After running this script you'll get a <filename>revcheck.html</filename> in the same directory. You can find revision comparisons and links to diffs - for all the files in this language. + for all the files in this language. You can also add a further restriction parameter, the maintainer name, so the script will only list the files corresponding to the given maintainer. </para> <para> There are some optional extensions introduced for this script, - to be available in this generated HTML page. + to be available in this generated HTML page. This is why the <filename>translation.xml</filename> files are - introduced. + introduced. Here comes a simple <filename>translation.xml</filename> file for the imaginary xx language : <programlisting><![CDATA[ @@ -161,24 +171,24 @@ </translation> ]]></programlisting> In this file, you can add users without a CVS account, and can - assign ready documents or work-in-progress files to them. + assign ready documents or work-in-progress files to them. The biggest advantage of using this addon is that all this information is used to generate dynamic tables of translators and files in - the <filename>revcheck.html</filename> file. + the <filename>revcheck.html</filename> file. All translators are linked to from the individual files they are assigned to, and there is a nice table showing the state of files for - all the translators. - Assigning ready files may be needed if a time consuming update is + all the translators. + Assigning ready files may be needed if a time consuming update is in progress on that file. </para> <para> There are two optional parameters you can add to a <file>, if you would like to record it: the <literal>date</literal> - and <literal>revision</literal>. - Date is assumed to be the date when the work was started, revision - is the checked out revision of the English file used to start the work - (denoted as CO-Revision in the generated table). - There is currently no fixed format for the <literal>date</literal> + and <literal>revision</literal>. + Date is assumed to be the date when the work was started, revision + is the checked out revision of the English file used to start the work + (denoted as CO-Revision in the generated table). + There is currently no fixed format for the <literal>date</literal> parameter. </para> <para>