Difference between revisions of "Documentation Improvement"

Revision as of 20:52, 22 September 2012

[Due to the the width of browser pages, all readers are invited to adjust page width to reading comfort by installing this free tool: "http:// lab dot arc90 dot com/experiments/readability/"]

These instructions describe the process to change both the GnuCash "Guide" and the GnuCash "Help" manuals as well as any other parts of GnuCash documentation.

Preface and Introduction -- What to expect

The recommendation of experienced programmers who work with code and related documentation is to obtain a copy of the full set of the most recent documentation. Nightly builds can be seen at http://svn.gnucash.org/docs/. Besides having the modules you think you will need to change, you will easily be able to update other files, if you discover additional places requiring a modification.

In addition, other persons could be making changes to parts of the documentation at the same time you are. You will need to make sure any changes (others have made following your acquiring a set of the documentation) are included in what you will install.

After obtaining your full set of the documentation, you will be inserting your modifications into the proper places in the set of documents. Modules in the set are formatted using XML. Later in processing, the XML modules are converted to HTML versions for online easy viewing. As a documentation support person, your task is to shepherd your enhancements through all stages from start to finish.

At each stage changes must be validated to assure that intended changes occur, and other unexpected changes found are understood and either accepted or rejected after proper analysis.

Since your changes will be carried out by software, there is a difference determination process that identifies exactly what and where changes will be made. This process permits you to be sure that only what you intend will actually be installed.

For the sake of quality control there is a review process that you must use in order to make your change "official". The above brief description when executed results in a file of changes. These changes must be explained as to their purpose. Accompanying the explanation in words is everything that makes up the substance of the change. The term for this is "patch". Whether you introduce a major restructuring or a small tweak, every thing is a "patch".

Creation of the explanation and the content of the change you are making are combined in a bugzilla event, otherwise called a "bug". In this usage bug means a statement of what is changing and why along with the content that will be the change when approved and applied to all the places needed. It does not necessarily mean a problem is being corrected, enhancements are handled as bugs too.

After creating your patch and presenting it in a bugzilla bug, usually a developer watching the bugzilla patchreport will review it. If you see no reaction in the next days, you can inform them also on their list and ask for the review and approval. Your email should list a brief statement of what your bug is about. You also provide the Bugzilla bug ID number so it can be found and reviewed easily.

If everything is accepted without requiring further work, your patch will be applied to the main set of documentation by a developer and you will be notified of that action.

As your first act in getting started, become very familiar with the references given in the REFERENCES section following the NOTES section below.

The Documentation Change Process -- What and How it happens

To write GnuCash documentation the following steps must be completed in the order given. [See the NOTES for each step, which are listed after all the steps! Also, when executing any command listed, do not use around the commands quotations of any sort.]

1. Use this command exactly as written to download to your own computer a full set of documentation files.

   svn checkout http://svn.gnucash.org/repo/gnucash-docs/trunk gnucash-docs

2. Find the place in the documentation that you want to change; identify the file(s) that need to be changed to accomplish your documentation objective. Your changes should roughly follow the GNOME Documentation Style Guide of the GNOME Documentation Project.
3. Draft your text changes for each module that will be affected by your update. For substantive changes to the documentation it frequently is helpful to open a text editor and develop your ideas there. See [4] in the References section for a link to the jEdit text editor, which installs in both Linux and Windows operating systems. If your changes are minor, you may skip this step and enter your changes directly into the XML modules.
4. Insert your changes into the XML file(s) affected. Make your changes fit the XML tags in the manner of the existing documentation. Adjust your XML tag structure so that the finished structure appears properly and as you intended in the HTML version of the documentation. You may have to return to this step should step 7 reveal a less than desirable arrangement of the data.
5. Test that your xml file has no syntax errors by running xmllint on the main file gnucash-{guide|help}.xml. Use this command in a terminal:

   xmllint -–valid -–noout gnucash-guide.xml

   Repeatedly perform this step until no xml errors are found. Then move on to the next step. If you become unable to identify an XML error, then send an email to the developers' list and ask for their help in understanding the error and making a change to remove it. [The program xmllint is part of the package libxml.]

6. Compare the original and changed documentation using the command below. The command must be executed from within the proper directory ("../guide/C" for the GnuCash Guide and "../help/C" for the GnuCash Help). Use this command in a terminal:

   svn diff > gc-diffs-this-date

   The result of this command is a file that lists all modules changed and the exact places in the modules where the change(s) occur. A patch should always be made against the most recent revision of the gnucash-docs project in subversion. In order to make sure your working copy is based on the most recent revision, run svn update (abbreviated, svn up). This will pull in all changes and patches that have been committed to the gnucash-docs module since you checked out your own working copy from subversion. If those changes don't conflict with your local changes, they will be merged automatically into your local working copy.

7. Build the Guide or Help file in HTML. Use this command exactly as written in a terminal (NOTE: there must be a space following the directory name 'output_html/' in the command below):

   xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-guide.xml

   When updating the Help manual, change the above command's file name to be gnucash-help.xml.

8. Create the documentation change as a bugzilla bug:
   • At this URL, register yourself to create an account.
   • After your account has been created, Login to the section of bugzilla reserved for GnuCash.
   • Enter your userid and password and press 'login'.
   • After logging in you are at this page and you can start the bug creation process by answering the questions on the page.
     • In the comment box, explain the nature of the bug fix.
     • Attach to the bug any supporting files (differences found, new modules (if any), changed modules, and anything else that might be required to explain and support your changes.
   • When you press commit, bugzilla creates the bug and a unique id for it.
9. Note the bug number. You will be listed as wanting to be notified any time there is an update to the bug. Monitor it until it is confirmed and installed to the trunk.

NOTES for each of the above steps

Step 1 - svn checkout

[The comments for this step reflect features of the most recent svn distributions. It is best for each user to refer to her/his specific subversion application installation tools to accomplish this step's objective.]

The terminal command will cause the documentation to be copied to your computer under the name you specify in the command. Executing the command assumes that subversion has previously been installed successfully on your computer. If the system finds that subversion is not installed, it ignores your request and replies with the correct command to download and install the package.

If you need to install svn, make note of the module(s) that it tells you should be deleted. Also, note the command it provides to delete such module(s). Next install subversion with the install command given. Note any instructions given during the install process and carry them out. Finally, use the instruction first noted that tells you what module(s) to remove and carry out the remove instruction.

In the checkout command "gnucash-docs" is the directory name where the checkout process places the full set of documentation modules. You can use that name or some other. I like to include in the directory name the date of download, thus: gc-docs-09302010. Use what is most helpful to you. Remember that the bash shell is case sensitive when typing commands and providing names.

By the above svn checkout command you are making changes in a local subversion working copy of the gnucash-docs library of modules.

Since you are making changes in a local working copy, subversion already keeps track of changes you make. It's just a matter of letting subversion output those changes in a easily understood patch format. For your patch to be useful, the command finding differences (discussed below) should be executed within as large a context as possible. To be sure of that context carry out this command:

Change directory to the top-level directory of the gnucash-docs project. Using my directory name given above to illustrate: "cd gc-docs-09302010".

svn checkout

generates a very long listing of modules. At the end it lists a revision number, e.g., "checked out revision 19612". The revision number is important for reference.

Avoid merge conflicts as much as possible. Run "svn update" regularly, so repository changes are pulled in frequently and in manageable sizes.

Reference [1] (in the next section) is a very good introduction to subversion and how to perform basic tasks.

Step 2 - find update location

This means you have to read the documentation to find exactly where the error is or the best place to insert the additional information that improves the understanding of how the feature works or what its purpose is in the software.

Experienced developers instruct that you should focus first on the modules in either of these two directories (found in the step 1 downloaded files): gnucash-docs/help/C or gnucash-docs/guide/C.

Trying to open each file in each of those directories will show whether there are any errors in the modules you downloaded. If you find errors, ask a more experienced person whether these should first be corrected before proceeding with your updates. You can do that by email to gnucash-devel@gnucash.org. If you choose this method, be sure to be a subscriber to that list in order to receive a prompt answer. If you are not a subscriber, then your email will wait for the list manager to find the time to address emails received from non-subscribers.

It will be useful to have either a printed copy or a PDF copy [3] of the documentation available for reference. The PDF is often useful, because it allows using FIND (ctrl-F) to search for key words. This can be important to assure yourself that you have covered the existing places in the documentation where the issue you are interested in has already had a mention or treatment.

Step 3 - draft your update in a text file

If your changes are few and easily formulated, then you should be able to skip this step and proceed to #Step 4 - place the draft changes in XML files.

If your update is adding something new or reworking existing text rather extensively, it will be very helpful to translate your ideas into words by using a text file not part of the existing documentation as a scratch pad to hone your expression of your ideas.

When your ideas are clear and expressed as you think appropriate, then proceed to #Step 4 - place the draft changes in XML files.

Step 4 - place the draft changes in XML files

Because the source documents are saved in XML - or to be more precise DocBook - code, all changes need to be added to the source modules in that manner. Small changes can be made directly into the XML file itself. Larger and extensive changes may first be prepared in a text editor and later inserted into the module(s) in their proper places. Resources for XML are listed in the References section for this step.

Review the inserted and corrected text to verify that it is presented within the proper XML tags, using existing tags as a guide. To read about XML and its tags, entities, and attributes, see the References section for links to resources.

If text exceeds the vertical text border guides, you should not be alarmed that text outside the vertical border guides would be lost. These border guides show up when the XML module is opened, but are length of line indicators and not warnings that text should be moved within the guides.

Apply the modules structural concepts to your own text after you have cut and pasted it into the XML file. This is done by using the various XML tags in the existing text: chapter, segment, sect1, sect2, orderedlist, list item, para (to name just a few) and the corresponding closing tags. You should also use the Definitions <!ENTITY ...> from the main file where ever possible. See the references below these step notes for information about XML and docbook.

Note

if your update adds new modules to the full set of documentation, you should review all modules in the directory in which you are working (gnucash-docs/help/C or gnucash-docs/guide/C) to determine what changes,if any, need to be made to modules outside your original assessment in step 2.

Publish your Authorship

The first page, which can also be shown as About of the document is in the file gnucash-{guide|help}-C.omf. OMF means Open Media Framework. Add a maintainer section with your data and check the other items like the date, which also needs an update.

Add your name and email address to the file AUTHORS. Create a separate patch for this change and ask to apply this patch also on gnucash/DOCUMENTERS - both in trunk and stable. The AUTHORS file can usually be shown in the packet manager while gnucash/DOCUMENTERS is shown in GnuCashs About->Credits->Documenters

Step 5 - validate xml changes

Execute the 'xmllint' command in a terminal after changing directory to the place where the changed modules are located. For example, if the module you are changing is in the guide/C directory, and you had downloaded the documentation files to a directory called GC-docs, then you would cd to the directory GC-docs/guide/C. It is when you are inside that high-level directory that you execute the command.

The file gnucash-guide.xml is found in the C subdirectory of GC-docs/guide/C. Similarly, the file gnucash-help.xml would be in GC-docs/help/C.

If your module(s) are free of XML errors, then the command returns a blank screen (if running in a terminal) or a blank file (if redirecting output to a file.

XML errors must be removed before completing the remaining steps. If you are not able to determine the source of the error, then help could be available via the developers list (gnucash-devel@gnucash.org). If asking for help, provide as much information as possible, including the results of the 'xmllint' command.

Step 6 - svn diff

A patch should always be made against the most recent revision of the gnucash-docs project in subversion. The command "svn diff" below uses the local working copy's metadata (which can be found in the hidden directory ".svn") to determine what has changed since the last time you ran "svn update". If new changes have occurred since you downloaded your working copy, you should run "svn update" to connect to the online repository to retrieve any new changes.

For the patch to be useful this command should be executed within as large a context as is appropriate. For that reason, first

cd to the top-level directory of the gnucash-docs project.

then, run:

svn update

As a side-note

to avoid merge conflicts as much as possible, it is wise to run "svn update" regularly, so repository changes are pulled in frequently and in smaller chunks.

"svn update" will pull in all changes and patches that have been committed to the gnucash-docs module since you checked out your own working copy from subversion. If those changes don't conflict with your local changes, they will be merged automatically into your local working copy.

If there are conflicting changes, you will have to figure out which changes to keep and which ones to discard. Recently, svn has some tools to help you with this. Should conflicts occur, it will ask you what to do. See [10] for more information on conflict resolution. You can also request help from the developers' list should you not be successful in resolving identified conflicts.

Once the conflicts are resolved, run

svn status

This command will list all files that are different between your local working copy and the project in subversion. There can be files that have been deleted, new files or modified files. A single patch can actually contain all three kinds of changes: adding a new file, modifying an existing file, and deleting an existing file. Again, see reference [1] to understand the output of this command.

To create a patch, you have to make sure that subversion will consider your changes for commit. In practice, only files that have status "A" (Added), "M" (Modified) or "D" (Deleted) will be taken into account. If you see files in the list that you know have changes you want to include, but that are not in this state, you should deal with this next.

1. Newly created files (the ones in state "?") you wish to include in the patch should first be added via "svn add".
2. Files you removed from your working copy with a plain "rm" command (the ones in state "!") should be properly removed via "svn rm".

When all modules have been recognized by subversion (svn status lists all with either "A", "D", or "M" status), then run

svn help diff

to learn the function of this command and its options. You can skim through the options and can ignore most of them.When ready, run

svn diff > changes.patch

"svn diff" will look through all subdirectories for changes and integrate everything into a single patch. The command compares all files (in the checked out set of modules to the same modules in the trunk set) for changes. It then places changes found in a difference file. Names used for the difference file are entirely up to the person making the update. Note that the "svn diff" command doesn't require you to give file names. It will go through your working copy and write a proper patch, containing all new files, deleted files, and file modifications.

If you wish to be more selective, you can also specify exactly which files you wish to add to the patch like so:

svn diff <list-of-files-and-or-directories> > changes.patch

For example:

svn diff guide/C/ch_capgain.xml AUTHORS > changes.patch

will only include changes to the files guide/C/ch_capgain.xml and the AUTHORS file into the patch.

Likewise the command:

svn diff guide > changes.patch

will only include any changes in any file below the guide directory.

Finally, XML and HTML don't really care about trailing whitespace. It's mostly a coding habit to remove them. There are even text editors that do this automatically sometimes. If such a file with white spaces is committed to subversion together with actual code/documentation changes, you may have a harder time reading the differences later on.

For example, when you are looking at a Trac difference page, the whitespace changes distract from the actual changes. That's what is meant by "cluttering up the repository". So being strict in removing trailing whitespace is not a matter of proper syntax, but rather a matter of making it easier for humans to read changes made. You are recommended highly to remove white spaces.

For that reason also, pure whitespace fixes should be done in separate patches from actual changes. Frequent calls of "svn up" will ease your work. If you wait too long, you risk conflicts when someone else and you are working on the same file. Especially if the other person has just committed a patch that you sent in for review, you should run "svn update" so your local working copy knows that the patch is now in subversion and only new changes should be added to a future patch.

Other resources available to discern differences and review them are listed in the resources below at items [8] and [9].

Step 7 - build the HTML version of the documentation

This step means that after XML has been tested for integrity and the difference file has been determined to contain correct changes and only those, then the Guide must be recreated in HTML and the results examined to verify that the online version of the Guide presents an appearance and reads as expected. The command to make this conversion is

xsltproc -o output_html/ ../../xsl/general-customization.xsl gnucash-guide.xml

NOTE

there is a space following 'output_html/ and preceeding '../'

"output_html" is a directory that will automatically be created and filled with the files the command creates. The directory name can be anything that makes sense to the person executing the command (output_html or something you choose).

Note the '/' following the file name 'output_html'. When that character is in place, the directory (output_html) is created and HTML modules placed in it. When not present, the output_html modules are placed in the current directory. Be sure to retain that '/' in its proper place!.

The command segment (“../../xsl/general-customization.xsl”) is a relative path to the XSL stylesheet used to turn the raw input XML into the output HTML that comprises the online version of the Guide. This command segment must be used exactly as written here.

If your changes involved no images, screenshots, icons, figures of any kind, then you are done at this point. However, if your work does involve figures of any kind, they will not be viewable in the HTML files created up to this point. In that case you should run this quick fix (3 command lines in sequence) in a terminal:

cd output_html

ln -s ../figures

ln -s ../../../stylesheet

After making this fix, any page containing any figure when reloaded should show the missing figure(s).

Once your inspection shows that the online Guide is now acceptable in all respects, you should make certain that the output_html directory and its contents are not included in any respect in your patch. To do that, before building the patch, remove the directory by this terminal command:

rm -rf output_html

Step 8 - Create the documentation change as a bugzilla bug

See reference.

References to Supporting Technologies Used

Step 1

[1] http://svnbook.red-bean.com/en/1.5/svn.tour.html

[2] http://wiki.gnucash.org/wiki/Subversion

Step 2

[3] http://svn.gnucash.org/docs/guide/

Step 3

[4] http://www.jedit.org/

Step 4

[5] http://en.wikipedia.org/wiki/DocBook

[6] http://www.docbook.org/ DocBook: The Definitive Guide

Some Distributions have it as a package named like docbook-tdg.

[7] http://www.tldp.org/LDP/LDP-Author-Guide/html/tools-edit.html

[8] http://www.netlingo.com/tips/html-code-cheat-sheet.php

[9] http://svn.gnucash.org/trac/timeline

[10] http://wiki.gnucash.org/wiki/Git

Step 6

[11] http://svnbook.red-bean.com/en/1.5/svn.tour.cycle.html#svn.tour.cycle.resolve

Step 8

[12] http://wiki.gnucash.org/wiki/Bugzilla

Images and screenshots

Screenshots for GnuCash documentation must be submitted in .png format or in .svg where applicable. The screenshots and images added to the GnuCash documentation must fit for two purposes: video printing (e.g. GNOME yelp) and paper printing (pdf creation). While the former has limits on image width in pixel (generally 510px) this limitation should be avoided for the latter. Both requirements are met by using a doubled <imageobject> tag as showed next:

           <imageobject role="html">
             <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
                        srccredit="Cristian Marchi" width="510px"></imagedata>
           </imageobject>
           <imageobject role="fo">
             <imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
                        srccredit="Cristian Marchi"></imagedata>
           </imageobject>

The "html" attribute refers to display visualization of the screenshots (the width is limited to 510px) while the "fo" attribute refers to pdf printing.

So when you take a screenshot for inclusion in the GnuCash documentation, this should not be resized to 510 pixel width. Instead you could add the "html" attribute and fix the width to 510px as showed above and leave the image's width as is. You need to accomplish another step in order to prepare the captured screenshot for printing: change the dpi (dot per inch) of the image. The dpi is a printing resolution and is just a tag in the image (the higher the dpi is, the better the image will be printed on paper). The printing size, dpi and image pixel dimension are in this relation:

size = pixels / dpi

So if you have a screenshot that is 800x560 pixels with a dpi of 80 you will have the screenshot in the pdf output displayed as 800/80 x 560/80 inches = 10 x 7 inches = 25 x 17,5 cm. (1 inch is about 2,5 cm) The available space in the A4 format pdf output is at max 15 cm so you can resize the screenshot by changing it's dpi. Normally (if you take a screenshot when the GnuCash window is almost at it's minimum) this value is set to 144 (see the GnuCash help figures). When the dpi is 144 our example screenshot will be printed as 800/144 x 560/144 inches = 14 x 10 cm and will stay inside the available areas.

If the screenshot you are going to add to documentation is wider than 850 pixels, you should increase the dpi above 144 so that it's printed size remains less than 15 cm.

So how can the dpi of an image be changed? Two ways:

• Open the screenshot in The Gimp and select Image->Print Size. In the dialog that will open set the X and Y resolution to the desired dpi (check that the unit in the right is set to the desired value - normally pixels/in). Press "Ok" and save the image.

• A faster approach uses Imagemagick a library for images manipulation. From a terminal window issue the following command:

 convert -units PixelsPerInch -density DPI IN OUT 

where DPI is the desired dpi value (e.g. 144), IN is the input image filename and OUT the output filename (that could be the same as IN).

• To convert the dpi of a bunch of images do this from a linux terminal:

ls *.png > list
for i in `cat list`; do convert -units PixelsPerInch -density 144 "$i" "$i"; done

The first line creates the file "list" with a list of all png files in the current directory The second and third lines applies a dpi of 130 to all images listed in the "list" file

Imagemagick let's you also see sizes and Pixels per inch from the command line:

 identify -format "%w x %h %x x %y" IMAGE_NAME.FORMAT

The following bash script can be used to automatically calculate and assign the right value of dpi to a list of png files. To use it create a new file and copy the following text into it. Save it with a descriptive name (e.g. adjust-dpi), close and make the file executable (chmod +x adjust-dpi). Move this file in the "figures" folder and run it from the command line (i.e. type ./adjust-dpi).

# make a list file of all the png figures
ls *.png > list

for figure in `cat list`;
do
# read width in pixel for the figure
width=$(identify -format "%w" "$figure")
# if the width is less than 90x14cm/2,54 
if [ "$width" -lt 496 ]; then
  dpi=90
  # convert dpi from pixelsperinch to pixelspercentimeter
  dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
  # read the existing dpi from figure as XX PixelsPerCentimeter
  existing_dpi=$(identify -format "%x" "$figure")
  # set the future dpi of figure as XX PixelsPerCentimeter
  future_dpi="$dpi_cm PixelsPerCentimeter"
  # apply new dpi only if it's changed from the existing
  if [ "$existing_dpi" != "$future_dpi" ]; then
    convert -units PixelsPerInch -density "$dpi" "$figure" "$figure"
    echo "File $figure converted to $dpi dpi"
  fi
# if the width is more than 144x14cm/2,54
else
  if [ "$width" -gt 793 ]; then
    # set the new dpi in function of the image size
    dpi=$(echo "scale=0; $width*2.54/14" | bc)
    # convert dpi from pixelsperinch to pixelspercentimeter
    dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
    # read the existing dpi from figure as XX PixelsPerCentimeter
    existing_dpi=$(identify -format "%x" "$figure")
    # set the future dpi of figure as XX PixelsPerCentimeter
    future_dpi="$dpi_cm PixelsPerCentimeter"
    # apply new dpi only if it's changed from the existing
    if [ "$existing_dpi" != "$future_dpi" ]; then
      convert -units PixelsPerInch -density "$dpi" "$figure" "$figure"
      echo "File $figure converted to $dpi dpi"
    fi
# for figures with width between 496px and 793px use a dpi of 144
  else
    dpi=144
    # convert dpi from pixelsperinch to pixelspercentimeter
    dpi_cm=$(echo "scale=2; $dpi/2.54" | bc)
    # read the existing dpi from figure as XX PixelsPerCentimeter
    existing_dpi=$(identify -format "%x" "$figure")
    # set the future dpi of figure as XX PixelsPerCentimeter
    future_dpi="$dpi_cm PixelsPerCentimeter"
    # apply new dpi only if it's changed from the existing
    if [ "$existing_dpi" != "$future_dpi" ]; then
      convert -units PixelsPerInch -density 144 "$figure" "$figure"
      echo "File $figure converted to 144 dpi"
    fi
  fi
fi
done
echo "Done!"

Maintenance

In this section are collected all the standards used to work on documentation.

Text conventions

• There are variable definitions in the main file, wich must be used e.g. for the in future changing revision numbers.
• All accounts name must be tagged with <emphasis>: e.g. <emphasis>Expenses:Tax</emphasis>

• In the current state of this page there are many more. Have a look at the recently reworked chapters. If you have some free time, add them here.

Graphics conventions

all screenshots of the GnuCash windows must be captured under a GNOME Desktop environment with the following settings:

• GNOME desktop environment
• Clearlooks theme
• text besides icon
• font: Sans. 9 point for application and 11 point for window title