GNOME Bugzilla – Bug 628745
guide: What's New section is outdated
Last modified: 2018-06-29 22:44:06 UTC
File: guide/C/ch_oview.xml Line: 297 The `What's New' section of the Tutorial and Concepts Guide is outdated. It refers to GnuCash version 2.0 as the latest version, and contains information specific to that version, such as what version of Gnome is used, and the latest features added. What needs to be done This section needs to be rewritten with information pertaining to the latest stable and unstable releases of GnuCash--latest features and minimum version of Gnome required. Alternatively, we could just drop the whole section and refer the reader instead to the GnuCash website or a link to the NEWS/ChangeLog file for the latest updates.
Eventually subchapters "From Version to Version" (newest first) would be fine. IMHO Changelog has too much noise for the end user, examples: Fix Typo in Comment Preparing Patch: Remove trailing whitespace Apply Standard Indentation and often a new or fixed feature contains a whole serie of patches.
Created attachment 173106 [details] [review] guide: Add What's New section for current stable series The idea is to always have the What's New section for the current stable series at the top and move older What's New sections down as they get superseded. The list of changes is a greatly summarised one compiled by looking through the milestone bugfixes pointed to by http://wiki.gnucash.org/wiki/Release_Schedule to pick up on significant user-visible improvements.
I would suggest adding a comment before the new section you are adding in the xml file to remark the source for version changes and the concept behind the update. Something like this would be good: <!-- The What's New section for the current stable series must be at the top and the older What's New sections must be moved down as they get superseded. The list of changes is a greatly summarised one compiled by looking through the milestone bugfixes pointed to by http://wiki.gnucash.org/wiki/Release_Schedule to pick up on significant user-visible improvements. --> I noticed you used ’ entity for apostrophe: is this intended? With this entity I cannot validate the document with xmllint.
Comment on attachment 173106 [details] [review] guide: Add What's New section for current stable series Looks good to me. I like Cristian's suggestion as well to add a comment for other editors.
Cristian, (In reply to comment #3) > I would suggest adding a comment before the new section you are adding in the > xml file to remark the source for version changes and the concept behind the > update > [...] Smart idea--I'll put that in the patch. > I noticed you used ’ entity for apostrophe: is this intended? With this > entity I cannot validate the document with xmllint. Yes, I'm using lsquo, rsquo, ndash--they all help with the appearance and all render in both HTML (xsltproc) and PDF (fop) without errors. But I want to debug this further--I just tried xmllint and it errors out because several entities are not defined, apparently: ch_oview.xml:255: parser error : Entity 'app' not defined para>For those knowledgeable in accounting, here is a list of <application>&app; ^ ch_oview.xml:298: parser error : Entity 'rsquo' not defined <title>What’s New in &series-stable;</title> ^ ch_oview.xml:298: parser error : Entity 'series-stable' not defined <title>What’s New in &series-stable;</title> I'm using the following command line: xmllint --dtdvalid /usr/local/Cellar/docbook/5.0/docbook/xml/4.5/docbookx.dtd ch_oview.xml What command are you using, and any ideas on how to get xmllint to recognise that we've defined these?
Hi Geert, (In reply to comment #4) > (From update of attachment 173106 [details] [review]) > Looks good to me. I like Cristian's suggestion as well to add a comment for > other editors. Sweet, once we get the xmllint thing worked out we should be good to commit.
(In reply to comment #5) > Yes, I'm using lsquo, rsquo, ndash--they all help with the appearance and all > render in both HTML (xsltproc) and PDF (fop) without errors. I'm testing the documentation under Ubuntu and if I try to open it with yelp it stops for error. The error is gone if I add this line <!ENTITY rsquo "'"> on the gnucash-guide.xml entity definition section. Same apply for any other entity you listed. > But I want to > debug this further--I just tried xmllint and it errors out because several > entities are not defined, apparently: > > ch_oview.xml:255: parser error : Entity 'app' not defined > para>For those knowledgeable in accounting, here is a list of > <application>&app; > > ^ > ch_oview.xml:298: parser error : Entity 'rsquo' not defined > <title>What’s New in &series-stable;</title> > ^ > ch_oview.xml:298: parser error : Entity 'series-stable' not defined > <title>What’s New in &series-stable;</title> > > I'm using the following command line: > > xmllint --dtdvalid /usr/local/Cellar/docbook/5.0/docbook/xml/4.5/docbookx.dtd > ch_oview.xml > > What command are you using, and any ideas on how to get xmllint to recognise > that we've defined these? I'm using "xmllint --noout --valid ch_oview.xml" as suggested in [1] but I havn't figured out yet how to instruct xmllint to recognise the already defined entity [1] http://library.gnome.org/devel/gdp-handbook/stable/gettingstarted.html.en#xmllint
With further reading [1] on the rsquo and others entity I think it's better to use those symbols throughout the documentation. Apart those listed in [1] that are automatically recognized during validation, in the following pages are listed all others special characters. After triyng on my local copy, the best setup seems to be adding a entity declaration on the gnucash-guide.xml file of this type: <!ENTITY rsquo "’"> [2] [1] http://infohost.nmt.edu/tcc/help/pubs/docbook/special-chars.html [2] http://infohost.nmt.edu/tcc/help/pubs/docbook/special-symbols.html
(In reply to comment #8) > [...] > After triyng on my local copy, the best setup seems to be adding a entity > declaration on the gnucash-guide.xml file of this type: <!ENTITY rsquo > "’"> If this gets rid of all the errors, I'll do it right now :-) But the strange thing is, I haven't seen any errors with yelp 2.30.1 on Ubuntu 10.10 (running in a VirtualBox VM).
(In reply to comment #7) > [...] > I'm using "xmllint --noout --valid ch_oview.xml" as suggested in [1] but I > havn't figured out yet how to instruct xmllint to recognise the already defined > entity > > [1] > http://library.gnome.org/devel/gdp-handbook/stable/gettingstarted.html.en#xmllint Looking at [2], it seems that we can't get xmllint to recognise new entities we define in the gnucash-guide.xml file while validating individual chapter files--unless we define our own customised DTD (e.g. DocBook-GnuCash) and define the custom entities (app, vers-stable, etc.) in there, and then run xmllint with: xmllint --noout --noent --dtdvalid docbook-gnucash.dtd ch_oview.xml I don't think it's worth it to go to all that trouble just to make xmllint happy, when all the rendering tools (yelp, fop, xsltproc) seem to work fine. Any thoughts...? [2] http://www.oasis-open.org/docbook/documentation/reference/html/ch05.html#AEN5995
Committed patch and Cristian Marchi's suggested improvements.
(In reply to comment #5) > ch_oview.xml:255: parser error : Entity 'app' not defined > para>For those knowledgeable in accounting, here is a list of > <application>&app; It is defined in gnucash-guide.xml: <!ENTITY app "GnuCash"> > I'm using the following command line: > > xmllint --dtdvalid /usr/local/Cellar/docbook/5.0/docbook/xml/4.5/docbookx.dtd > ch_oview.xml So, you should always run xmllint [your options] gnucash-guide.xml
(In reply to comment #12) > [...] > So, you should always run > xmllint [your options] gnucash-guide.xml Wow, you're right! I just deliberately introduced an error into one of the chapters and ran the above command, and it caught it! So it seems xmllint is parsing each of the included chapters in the main file. This simplifies thing a LOT--we don't have to worry about xmllint failing on chapter files, it's the main file that has to pass.
Yawar, I just tried to make it clearer in http://wiki.gnucash.org/wiki/Translation#The_Procedure 5. If you feel, the instructions in http://wiki.gnucash.org/wiki/Documentation_Update_Instructions #The_Documentation_Change_Process_--_What_and_How_it_happens and #Step_5_-_validate_xml_changes are not clear enough, improve them. O.T.: Can you have a look at Bug 633066? - On the long term, I think you and Tom should become the assignees for documentation bugs, if Chris agrees.
(In reply to comment #14) > Yawar, I just tried to make it clearer in > http://wiki.gnucash.org/wiki/Translation#The_Procedure 5. > > If you feel, the instructions in > http://wiki.gnucash.org/wiki/Documentation_Update_Instructions > #The_Documentation_Change_Process_--_What_and_How_it_happens and > #Step_5_-_validate_xml_changes are not clear enough, improve them. I just added Frank's improvements to this wiki: http://wiki.gnucash.org/wiki/Documentation_Update_Instructions#The_Documentation_Change_Process_--_What_and_How_it_happens thanks, Frank, for this improvement. Tom
GnuCash bug tracking has moved to a new Bugzilla host. This bug has been copied to https://bugs.gnucash.org/show_bug.cgi?id=628745. Please update any external references or bookmarks.