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