README
1############################################################
2 GnuCash Docs README file
3------------------------------------------------------------
4
5This is the user documentation (docs) module for GnuCash. Written in
6DocBook v4.5 (not 5.x series) they can be accessed under
7* directly without any conversion:
8** Linux: from Yelp (the Gnome help browser)
9
10* after conversion:
11** MacOs: html
12** Windows: chm
13** mobiles: mobi
14** eBook readers: epub
15** paper: pdf
16
17If you wish to obtain a copy of the documentation in one of the latter formats,
18see below under Other Formats.
19
20Requirements
21############
22* cmake with
23** ninja or
24** make
25
26* libxml2
27* libxslt [Debian packed the required xsltproc in a separate package,
28 which depends on libxslt]
29* docbook-xsl
30* docbook-dtds
31* yelp (for viewing)
32
33Optional for ranslators:
34* gnome-doc-utils (contains xml2po for the use of po editors like in the italian translation)
35
36Additional Requirements for Generating Mobipocket:
37
38* Calibre (https://www.calibre-ebook.com/)
39
40Additional Requirements for Generating chm on Windows:
41
42* MSYS2 (https://www.msys2.org/)
43** MinGW32 or MinGW64
44** cmake on MinGW32 or MinGW64 (not cmake for MSYS2)
45** libxsl on MinGW32 or MinGW64 (not libxsl for MSYS2)
46** docbook-xsl on MinGW32 or MinGW64 (not docbook-xsl for MSYS2)
47* HTML Help Workshop (https://www.microsoft.com/en-us/download/details.aspx?id=21138 for Win XP - 8)
48Microsoft stopped providing HTML Help Workshop installer files. You can download from WayBack Machine instead.
49https://web.archive.org/web/20110712222004/http://msdn.microsoft.com:80/en-us/library/ms669985
50
51They are installed by windows bootstrap scripts for GnuCash except HTML Help Workshop. See
52 https://github.com/Gnucash/gnucash-on-windows/
53for details.
54
55Additonal Requirements for Generating PDF:
56
57* Apache fop >= 0.95
58
59** FontBox
60 from the Apache PDFBox [https://pdfbox.apache.org/download.cgi]
61 can handle OpenType fonts, which are as default used for the russian PDF.
62 Some distributions call it [lib]fontbox[-java].
63
64Notes
65#####
66
67The GnuCash docs team is actively seeking contributors. Even if you
68only have time for reviewing, editing or translating the existing docs this
69can help. PLEASE let us know via IRC or the gnucash-devel mailing list what
70you can work on or help with.
71
72See also:
73* http://wiki.gnucash.org/wiki/Documentation_Update_Instructions
74* http://wiki.gnucash.org/wiki/Translation
75
76Other Formats
77#############
78
79GnuCash-docs is written using docbook-xml. This allows it to be
80outputted to alternative formats using external tools.
81
82The documentation source can be converted into HTML, PDF, EPUB, or MOBI
83format using such tools as xsltproc and fop.
84
85
86Note: if you use external tools to render HTML, remember to bring the images
87from figures and icons along with the final HTML. The browser will expect to find
88the figures and images directory directly beneath the HTML directory as follows:
89/path_to/gnucash-docs/html/
90/path_to/gnucash-docs/html/figures/
91/path_to/gnucash-docs/html/images/
92
93--------------------------
94
95You can generate the documentation in html, pdf, epub and mobi
96using the build system that comes with the sources.
97
98For cmake the commands are
99 cd gnucash-docs
100 mkdir build && cd build
101 # If you don't need mobi
102 cmake [options…]
103 # or, if you need mobi
104 cmake -DWITH_MOBI=ON [options…]
105
106To generate the documentation in html format, run
107
108 make html
109
110To generate the documentation in pdf format, instead run
111
112 make pdf
113
114To generate the documentation in epub format, instead run
115
116 make epub
117
118To generate the documentation in mobi format, instead run
119
120 make mobi
121 (Note: mobi is generated from epub, so this generates epub files as well.)
122
123If you only wish to generate a subset of the documentation, you can. However
124the way to do so depends on the build system:
125
126- CMake
127There are specific targets for each document. The target is of the form
128<language>-gnucash-<doc>-<type>.
129
130For example to only generate the English concepts guide:
131
132 make C-gnucash-guide-html
133 make C-gnucash-guide-pdf
134 make C-gnucash-guide-epub
135 make C-gnucash-guide-mobi
136
137depending on the output format you require.
138
139In addition one could generate these formats for one document in all
140languages at once by omitting the language specifier in the target.
141
142For example:
143
144 make gnucash-help-html
145
146will generate the html version of the help document in all supported
147languages.
148
149depending on the output format you require.
150
151* Running syntax checks by xmllint
152-----------------
153You can also run xmllint on all documents or a specific document with the command
154
155 make check # for toplevel check
156 make de-gnucash-help-check # for a cmake check for one specific document
157 # in this example - the German help guide
158
159* XML/XSL-based tools:
160----------------------
161
162If you have xmlto installed, this can be used to convert to other formats
163but problems have been experienced with PDF generation. If you output
164an XML-FO format using xmlto, you could use FOP to convert to PDF - this
165step requires Java. See man xmlto for more information.
166
167Formats available with xmlto include:
168dvi fo html htmlhelp html-nochunks javahelp man
169pdf ps txt xhtml xhtml-nochunks
170
171The problems with pdf apply equally to dvi AND ps output. Each gives a
172long error output ending with: ! Emergency stop.
173
174manpage output only works if manpages are outlined in the XML.
175There are no manpages in gnucash-docs.
176
177xmlto uses xsltproc - the same tool and the same stylesheets as the main
178make and install.
179
180Examples:
181
182To convert the GnuCash Tutorial and Concepts Guide DocBook XML document
183to HTML and store the resulting HTML files in a separate directory use:
184
185cd guide/C/
186xmlto -o html-dir html gnucash-guide.xml
187
188(html-dir/ will be created if it does not already exist.)
189
190To convert the GnuCash Help Manual DocBook XML document to a single
191HTML file in the current directory use:
192cd help/C/
193xmlto html-nochunks gnucash-help.xml
194
195
196Known Problems
197##############
198
199- See the full list:
200https://bugs.gnucash.org/buglist.cgi?quicksearch=product%3DDocumentation
201
202- Please report any new problems to Gnucash's Bugzilla at
203https://bugs.gnucash.org/describecomponents.cgi?product=Documentation. Then
204choose a component.
205
206- Feel free to append your fixes and improvements also there or open a pull
207request. Only docs about future features should go in branch master.
208So here is the link for branch stable:
209https://github.com/Gnucash/gnucash-docs/.
210
211- With any problems you have, you can contact us in the following ways:
212
213* quick questions via IRC
214** en: irc://irc.gnome.org/gnucash
215: see http://wiki.gnucash.org/wiki/IRC
216
217* translation related questions preferable via the local mailing lists
218** de: https://lists.gnucash.org/mailman/listinfo/gnucash-de
219** es: https://lists.gnucash.org/mailman/listinfo/gnucash-es
220** fr: https://lists.gnucash.org/mailman/listinfo/gnucash-fr
221** it: https://lists.gnucash.org/mailman/listinfo/gnucash-it
222** nl: https://lists.gnucash.org/mailman/listinfo/gnucash-nl
223** pt: https://lists.gnucash.org/mailman/listinfo/gnucash-br
224: or your recent translator
225
226* other user questions should go to
227** en: https://lists.gnucash.org/mailman/listinfo/gnucash-user
228
229* finally contributor questions via
230** en: https://lists.gnucash.org/mailman/listinfo/gnucash-devel
231
232Thanks
233your GnuCash Documentation Team
234
235
236Original Author:
237Chris Lyttle
238<chris@wilddev.net>
239