He/הנחיות עדכון תעוד
| שפות | Deutsch | English | Español | Français | עִברִית | [[pt/GnuCash|P
Contents
כלליThese instructions describe the process to change the Tutorial & Concepts Guide and the Help manuals. If you are interested in translating the documentation, you should read Translating the GnuCash Guide and Help, too. Preface and Introduction -- What to expectThe documentation update process uses the same software management tools that are used for updating the program itself. This ensures that changes are made consistently and reliably. This includes using a version control system (VCS) to coordinate contributions from disparate sources, as well as using eXtended Markup Language (XML) for the actual edits. It also requires contributors to check their contributions for compatibility by compiling the documentation before final submission. These aspects require that documentation contributors learn and use several specialized tools to engage the process. The tools and the process are outlined in this page. For background on these tools, see Build Tools. Any changes you make will be inserted into local copies of the source documentation files and subsequently transferred to the main documentation set. These source files use a special markup in XML to provide structure. Later in the process, the XML files are converted to other versions (HTML, PDF, etc.) for viewing. As a documentation support person, your task is to shepherd your modifications through all stages from start to finish. At each stage, you must validate your changes to assure that they are both valid and have the intended effect, and you must address any errors or unexpected changes that are found. 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. After your changes have been validated locally, you will submit your changes to the project either through a "patch," or by a git "pull request" (both of which will be explained later). For quality control, any changes you submit will be reviewed by a developer before your changes become official. If everything is accepted without requiring further work, your changes will be applied to the main set of documentation by a developer and you will be notified of that action. The above brief description outlines the general documentation update process. It may be helpful to become familiar with the references given in the REFERENCES section below. Setting Up Your SystemTo begin changing the documentation, you will need to set up your system with the proper software. Required SoftwareYou will need the following software:
Initial Steps
The Documentation Change ProcessTo write GnuCash documentation the following steps must be completed in the order given. When executing any command listed, do not use quotations of any sort around the commands. N.B.: The instructions below are for a non-committer preparing a patch. If you have commit privileges in the gnucash-docs repository, the git commands you use will be somewhat different. Please see Git. If you're not familiar with using git, you'll find more details on basic commands and links to documentation there as well. You may prefer one of the many Git GUIs to the command-line instructions here, especially if you use Microsoft Windows. Create a Place to Attach and Discuss Your ChangesThis can either be
While the devs would prefer PR's it is up to you to decide which is more comfortable for you.
Update Your Local CopySince others could be making changes to the documentation at the same time you are, the GnuCash documentation process employs git to coordinate the disparate contributions. Git ensures that your changes and those of any others are incorporated efficiently into one final set of source files. See Git to learn about using git. This section assumes that you have already obtained a clone of the GnuCash repository, as outlined in Setting Up Your System. Before you begin editing, you must make sure that your local copy is up to date and aligns with the GnuCash repository by following the instructions at An Introduction to Git. Ensure The Build Directory Is Up To Date(Autotools only; not relevant for CMake) As the source files get changed on your machine and on the remote repositories, the files configure.ac and Makefile.am can change. If either of these files changes, you should run autogen.sh and configure again to make sure that changes are incorporated. This might occur because you changed it yourself or because someone else committed a change in git. If you are not sure whether or not these files have changed, the safest course is to run these commands every time you pull. Remember that these commands are issued from the build directory; if you do not yet have your build directory set up, consult Initializing Documentation Build Environment. Identify Location for ChangesGnuCash stores documentation in one master sequence, but reformats the information in different ways for different platforms. When you build the documentation, you create a copy in final format. To make changes, you need to edit the local repository files, not the build directory files. Once you have located the correct source files, you must identify the passages that need to be changed. Your changes should roughly follow the GNOME Documentation Style Guide of the GNOME Documentation Project. Read the documentation carefully to find exactly where your change belongs. The English Help Manual source XML files are in
The English Tutorial and Concepts Guide source XML files are in
The non-english files are in the corresponding locations with C replaced by a 2 character language code. It may 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. Draft Your ChangesIf your changes are few and easily formulated, you should be able to make your changes directly in the source XML files. If your changes are more extensive, you may find it helpful to develop your ideas in a separate temporary text file. If you use this approach, you will need to insert your changes into the XML file(s) affected. Doing this might be easier by using a specific XML Editor. Additional resources for XML are listed in the References section for this step. Note: Remember to edit the source files in the repository directories, not in the build directories. The various make commands (run from the build directories), will copy the files from the repository to the build directories. The source documents are saved in the XML flavour of DocBook code, so all changes need to follow those formatting rules. DocBook enforces strict rules about tags and markup, so be sure to make your changes fit the XML tags in the manner of the existing documentation.
ConventionsExamples of commonly-used tags include: chapter, sect1 ... sect5, simplelist, orderedlist, list item, para and their corresponding closing tags. You can find a complete reference to DocBook in The Definitive Guide. Chapter 2: Creating DocBook Documents may be of particular assistance.
In particular, note that:
There are more in Docbook Conventions.
Adding or Removing FilesIf you are adding or deleting files from the documentation, for example adding a new chapter or appendix, you will need to announce it to several parts of the system to ensure that these new or deleted files get handled properly. This are:
Telling the Program of a New Help ContextIn gnucash/gnome-utils/gnc-ui.h are 2 important sections:
Ask a developer to
Validate Your ChangesIn every casexmllint is used to test that your xml file has no syntax errors or incorrect references to internal sections. The program xmllint is part of the package libxml.
The documentation build system comes with built-in rules to run xmllint. The way to invoke these depends on which build system you have chosen. Autotoolsxmllint is run by executing make check in the appropriate build directory or sub-directory. Depending on the level in the directory hierarchy you invoke make check one or more documents will be checked. For example, if you had downloaded the documentation files to a directory called /home/$USER/code/gnucash-docs and created a build directory called /home/$USER/code/gnucash-docs/build:
CMakexmllint is run by executing make [something-]check in the top level build directory. Depending on the [something-] part in that command one or more documents will be checked. For example, if you had downloaded the documentation files to a directory called /home/$USER/code/gnucash-docs and created a build directory called /home/$USER/code/gnucash-docs/build:
So generally the check parameter to make is of the form <language>-<document>-check. You can omit <language>- or <language>-<document>- to widen the scope of the check.
xmllint output
After Adding, Moving or Deleting FilesVerify a tarball can be builtcd ${BUILDDIR} # Adjust this
make distcheck
After success you can remove gnucash-docs-5.9.tar.gz from your ${BUILDDIR} again. Ensure Only Expected Changes Have Been MadeYou should double check that there are no accidental changes to the documentation. The following command will show any changes to unstaged files git diff
Git status will list all files with differences to the last commit, in categories staged, unstaged, and unknown to git but not matching an ignore pattern. git status
ProofreadingAfter you have tested the integrity of the XML using xmllint (make check) and have verified that the difference file shows the correct changes, it depends on your OS/installed software, how to proceed
In HTML and Other FormatsThe easiest way to check your changes is to view the HTML version in your browser. You should also review other formats as they have their own peculiarities:
The Guide or Help must be recreated in HTML and the results examined in your browser to verify that the online version appears and reads as expected. Build the Guide or Help file in HTML. Use this command exactly as written in a terminal, from the appropriate directory within the build directory structure:cd [appropriate directory or sub-directory within the '''build''' directory structure]
make html # Replace html by pdf, epub, mobi ...
The above make command will run xsltproc and use an XSL stylesheet (.../xsl/general-customization.xsl) to turn the raw input XML into the output HTML that comprises the online version of the Guide or Help. The built html files with be placed in an automatically created directory, which if using the example directories will be:/home/$USER/code/gnucash-docs/build/<guide|help>/C/gnucash-<guide|help>
Review the results in your browser. Calibre is a good choice as viewer for ebook formats (epub, mobi, ...). If you need to make changes, do so, then check, rebuild and review again. It's amazing how errors which are obscure in XML--everything is obscure in XML--become blindingly obvious when rendered in the browser. Look for spelling errors, formatting oddness, incomplete tags, and missing or incorrect entities. To view the results in a web browser, in a file manager (or for Windows: Windows Explorer/File Explorer) double click on either:/home/$USER/code/gnucash-docs/build/help/C/gnucash-help/help.html
# or
/home/$USER/code/gnucash-docs/build/guide/C/gnucash-guide/index.html
Once your inspection shows that the online Guide/Help is now acceptable in all respects, you should make certain that the build directory and its contents are not included in any respect in your patch. If you are using build as the name of your build subdirectory in your repository directory, as in this example, it is not necessary to remove the build directory as the <repository>/.gitignore file includes build*, so git will ignore it. To remove the build directory structure, before building the patch, use this terminal command:rm -rf "/home/$USER/code/gnucash-docs/build"
Add Extra FilesGit automatically tracks changes to files it knows are part of the repository. However, if you have added any files that should be included in your commit (xml or others, for example, illustrations), add (stage) them with the command: git add path/to/file Note: Do NOT add file(s) from your build directory structure. Here is another way to check your changes. Unless you're a programmer, you're probably not well practiced at examining diffs. If you have touched several files, the first thing to check is git status -uno The -uno tells it to show only the repository files affected by your changes; all of the build products are ignored. Of course, if you've made a new file, that's ignored too, so make sure that all of the files you worked on and only those files are in the list. You can add new files with git add path/to/new-file and revert files that you didn't mean to change with git checkout path/to/ignored-file Publish your AuthorshipThe 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 - in both maint and master branches. The AUTHORS file can usually be shown in the packet manager while gnucash/DOCUMENTERS is shown in GnuCashs About->Credits->Documenters Commit Your ChangesOnce you're satisfied with your changes, it's time to commit them. You can commit everything that's been changed with git commit -a
or you can commit a few files at a time with git add path/to/file git commit If you need to make further changes, you can update your commit instead of creating a new one with git commit -a --amend But --amend should only be used as long, as you did not publish your commit by pushing it to some public github repository. There are even finer-grained ways to pick out bits and pieces to group into a commit, but they're beyond the scope of this tutorial. When you make a commit git will open a screen editor; which one depends on how you set your environment. The default on most Unixes is vi, but you can select a different one with the $EDITOR environment variable. Use the editor to make a good commit message. It should have a one-line (< 80 character) summary followed by a blank line, and a brief description of the change and its motivation. Don't get carried away here: If you need more than a couple of lines it should have been a smaller change. The release announcement comes from commit messages, so include any information that should be passed on. You could even say This needs to be mentioned in the release announcement followed by the text you want in the announcement. To add extra information to a previously pushed commit message, make some trivial change to a comment and write a commit message using the same subject line as the previous commit. If required, you can check committed changes to a particular file with git log -p path/to/file Create a Pull Request or a PatchOnce you have finalized your changes, you will notify the developer team of your changes, either by creating a pull request, or by creating and uploading a patch. References to Supporting Technologies Used
Additional InformationScreenshots and ImagesDesktop Themes for Screenshots
Image Formats
IndexingTo add your image to the List of Figures at the start of the Help or Tutorial and Concepts Guide, put your screenshot in a figure tag, for example: <figure pgwide="1">
<title>This is the text that will appear in the List of Figures</title>
<screenshot>
<mediaobject>
<!-- insert the imageobjects here -->
<caption><para>Optionally you can here add a longer description than in the title.
If not required, remove the caption element.</para>
</caption>
</mediaobject>
</screenshot>
</figure>
Display and Print TargetsScreenshots and images added to the GnuCash documentation must fit two purposes: video display (e.g. online) and paper printing (pdf creation). Each has its own way of determining width:
Because we do not want to shrink the image itself, but want limit the width of
<imageobject>
<imagedata fileref="figures/Report_Screen.png" format="PNG"
srccredit="your name" />
</imageobject>
<imageobject role="html">
<imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
srccredit="your name" width="510px" />
</imageobject>
<imageobject role="fo">
<imagedata fileref="figures/Help_Pref_AccntPeriod.png" format="PNG"
srccredit="your name" />
</imageobject>
Now the image will fit on display and we can continue to adjust it for printing. Adjusting an Image's Dots Per InchYou must take another step to prepare a screenshot for print output: you must set the dots per inch (dpi) correctly. The dpi defines an image's dot density, and thus its overall quality; the higher the dpi, the better the printed image quality. The printing size, dpi and image pixel dimensions are in this relation: size = pixels / dpi
800/144 x 560/144 inches = 14 x 10 cm
Individual
All at onceNew Method
Old Method
Optimize the CompressionThe tool OptiPNG tries to minimize the size of png files lossless: cd guide/pt/figures # In the repo, NOT the build directory structure
optipng ${FILENAME}
If it is too hard for you, ask the developers in your pull enhancement request to do it for you. MaintenanceIn this section are collected all the standards used to work on documentation. Text conventions
Content ChecklistSome often missed parts:
Graphics conventionsAll screenshots of the GnuCash windows should be captured under the GNOME desktop environment with the following settings:
Updating StylesheetsSometimes maintainers update the XSL. If you do it, #Optimize the Compression of it's images. |
|---|
- ↑ https://bugs.gnucash.orgshow_bug.cgi?id=798143 - Different order of splits in instructions and screenshot
