├── .gitignore ├── AUTHORS ├── COPYING ├── COPYING.GPL ├── MAINTAINERS ├── NEWS ├── README.md ├── help ├── C │ ├── index.page │ ├── yelp-build.page │ ├── yelp-check.page │ ├── yelp-new.page │ └── yelp.m4.page └── meson.build ├── meson.build ├── meson_options.txt ├── templates ├── concept.duck ├── concept.page ├── guide.duck ├── guide.page ├── info.ducktype.include ├── info.mallard.include ├── meson.build ├── reference.duck ├── reference.page ├── task.duck └── task.page ├── tools ├── .gitignore ├── meson.build ├── yelp-build.in ├── yelp-check.in ├── yelp-new.in └── yelp.m4 ├── xslt ├── mal-ncx.xsl.in ├── mal-opf.xsl.in ├── mal-rng.xsl └── meson.build └── yelp-tools.doap /.gitignore: -------------------------------------------------------------------------------- 1 | *~ 2 | INSTALL 3 | Makefile 4 | Makefile.in 5 | 6 | /aclocal.m4 7 | /autom4te.cache 8 | /ChangeLog 9 | /config.guess 10 | /config.log 11 | /config.status 12 | /config.sub 13 | /configure 14 | /install-sh 15 | /intltool-extract.in 16 | /intltool-merge.in 17 | /intltool-update.in 18 | /missing 19 | 20 | /tools/yelp-build 21 | /tools/yelp-check 22 | /tools/yelp-new 23 | /xslt/mal-ncx.xsl 24 | /xslt/mal-opf.xsl 25 | -------------------------------------------------------------------------------- /AUTHORS: -------------------------------------------------------------------------------- 1 | Shaun McCance 2 | -------------------------------------------------------------------------------- /COPYING: -------------------------------------------------------------------------------- 1 | yelp-tools is a collection of scripts and build utilities to help create, 2 | manage, and publish documentation for Yelp and the web. 3 | 4 | This package is free software; you can redistribute it and/or modify 5 | it under the terms of the GNU General Public License as published by 6 | the Free Software Foundation; either version 2 of the License, or 7 | (at your option) any later version. See the file COPYING.GPL. 8 | 9 | As an exception to the GPL, if you use the included yelp.m4 file as 10 | part of your build process, you may redistribute it along with your 11 | package without any restriction. 12 | 13 | Note that this package builds heavily on the yelp-xsl package. For 14 | example, it provides command-line utilities to build HTML using the 15 | XSLT, Javascript, CSS, and images from yelp-xsl. The yelp-xsl license 16 | grants exceptions to the GPL for redistribution of some of these files 17 | when distributed as part of a built document using its tools. These 18 | exceptions are also granted when using the tools in this package. 19 | -------------------------------------------------------------------------------- /COPYING.GPL: -------------------------------------------------------------------------------- 1 | GNU GENERAL PUBLIC LICENSE 2 | Version 2, June 1991 3 | 4 | Copyright (C) 1989, 1991 Free Software Foundation, Inc. 5 | 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 6 | Everyone is permitted to copy and distribute verbatim copies 7 | of this license document, but changing it is not allowed. 8 | 9 | Preamble 10 | 11 | The licenses for most software are designed to take away your 12 | freedom to share and change it. By contrast, the GNU General Public 13 | License is intended to guarantee your freedom to share and change free 14 | software--to make sure the software is free for all its users. This 15 | General Public License applies to most of the Free Software 16 | Foundation's software and to any other program whose authors commit to 17 | using it. (Some other Free Software Foundation software is covered by 18 | the GNU Library General Public License instead.) You can apply it to 19 | your programs, too. 20 | 21 | When we speak of free software, we are referring to freedom, not 22 | price. Our General Public Licenses are designed to make sure that you 23 | have the freedom to distribute copies of free software (and charge for 24 | this service if you wish), that you receive source code or can get it 25 | if you want it, that you can change the software or use pieces of it 26 | in new free programs; and that you know you can do these things. 27 | 28 | To protect your rights, we need to make restrictions that forbid 29 | anyone to deny you these rights or to ask you to surrender the rights. 30 | These restrictions translate to certain responsibilities for you if you 31 | distribute copies of the software, or if you modify it. 32 | 33 | For example, if you distribute copies of such a program, whether 34 | gratis or for a fee, you must give the recipients all the rights that 35 | you have. You must make sure that they, too, receive or can get the 36 | source code. And you must show them these terms so they know their 37 | rights. 38 | 39 | We protect your rights with two steps: (1) copyright the software, and 40 | (2) offer you this license which gives you legal permission to copy, 41 | distribute and/or modify the software. 42 | 43 | Also, for each author's protection and ours, we want to make certain 44 | that everyone understands that there is no warranty for this free 45 | software. If the software is modified by someone else and passed on, we 46 | want its recipients to know that what they have is not the original, so 47 | that any problems introduced by others will not reflect on the original 48 | authors' reputations. 49 | 50 | Finally, any free program is threatened constantly by software 51 | patents. We wish to avoid the danger that redistributors of a free 52 | program will individually obtain patent licenses, in effect making the 53 | program proprietary. To prevent this, we have made it clear that any 54 | patent must be licensed for everyone's free use or not licensed at all. 55 | 56 | The precise terms and conditions for copying, distribution and 57 | modification follow. 58 | 59 | GNU GENERAL PUBLIC LICENSE 60 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 61 | 62 | 0. This License applies to any program or other work which contains 63 | a notice placed by the copyright holder saying it may be distributed 64 | under the terms of this General Public License. The "Program", below, 65 | refers to any such program or work, and a "work based on the Program" 66 | means either the Program or any derivative work under copyright law: 67 | that is to say, a work containing the Program or a portion of it, 68 | either verbatim or with modifications and/or translated into another 69 | language. (Hereinafter, translation is included without limitation in 70 | the term "modification".) Each licensee is addressed as "you". 71 | 72 | Activities other than copying, distribution and modification are not 73 | covered by this License; they are outside its scope. The act of 74 | running the Program is not restricted, and the output from the Program 75 | is covered only if its contents constitute a work based on the 76 | Program (independent of having been made by running the Program). 77 | Whether that is true depends on what the Program does. 78 | 79 | 1. You may copy and distribute verbatim copies of the Program's 80 | source code as you receive it, in any medium, provided that you 81 | conspicuously and appropriately publish on each copy an appropriate 82 | copyright notice and disclaimer of warranty; keep intact all the 83 | notices that refer to this License and to the absence of any warranty; 84 | and give any other recipients of the Program a copy of this License 85 | along with the Program. 86 | 87 | You may charge a fee for the physical act of transferring a copy, and 88 | you may at your option offer warranty protection in exchange for a fee. 89 | 90 | 2. You may modify your copy or copies of the Program or any portion 91 | of it, thus forming a work based on the Program, and copy and 92 | distribute such modifications or work under the terms of Section 1 93 | above, provided that you also meet all of these conditions: 94 | 95 | a) You must cause the modified files to carry prominent notices 96 | stating that you changed the files and the date of any change. 97 | 98 | b) You must cause any work that you distribute or publish, that in 99 | whole or in part contains or is derived from the Program or any 100 | part thereof, to be licensed as a whole at no charge to all third 101 | parties under the terms of this License. 102 | 103 | c) If the modified program normally reads commands interactively 104 | when run, you must cause it, when started running for such 105 | interactive use in the most ordinary way, to print or display an 106 | announcement including an appropriate copyright notice and a 107 | notice that there is no warranty (or else, saying that you provide 108 | a warranty) and that users may redistribute the program under 109 | these conditions, and telling the user how to view a copy of this 110 | License. (Exception: if the Program itself is interactive but 111 | does not normally print such an announcement, your work based on 112 | the Program is not required to print an announcement.) 113 | 114 | These requirements apply to the modified work as a whole. If 115 | identifiable sections of that work are not derived from the Program, 116 | and can be reasonably considered independent and separate works in 117 | themselves, then this License, and its terms, do not apply to those 118 | sections when you distribute them as separate works. But when you 119 | distribute the same sections as part of a whole which is a work based 120 | on the Program, the distribution of the whole must be on the terms of 121 | this License, whose permissions for other licensees extend to the 122 | entire whole, and thus to each and every part regardless of who wrote it. 123 | 124 | Thus, it is not the intent of this section to claim rights or contest 125 | your rights to work written entirely by you; rather, the intent is to 126 | exercise the right to control the distribution of derivative or 127 | collective works based on the Program. 128 | 129 | In addition, mere aggregation of another work not based on the Program 130 | with the Program (or with a work based on the Program) on a volume of 131 | a storage or distribution medium does not bring the other work under 132 | the scope of this License. 133 | 134 | 3. You may copy and distribute the Program (or a work based on it, 135 | under Section 2) in object code or executable form under the terms of 136 | Sections 1 and 2 above provided that you also do one of the following: 137 | 138 | a) Accompany it with the complete corresponding machine-readable 139 | source code, which must be distributed under the terms of Sections 140 | 1 and 2 above on a medium customarily used for software interchange; or, 141 | 142 | b) Accompany it with a written offer, valid for at least three 143 | years, to give any third party, for a charge no more than your 144 | cost of physically performing source distribution, a complete 145 | machine-readable copy of the corresponding source code, to be 146 | distributed under the terms of Sections 1 and 2 above on a medium 147 | customarily used for software interchange; or, 148 | 149 | c) Accompany it with the information you received as to the offer 150 | to distribute corresponding source code. (This alternative is 151 | allowed only for noncommercial distribution and only if you 152 | received the program in object code or executable form with such 153 | an offer, in accord with Subsection b above.) 154 | 155 | The source code for a work means the preferred form of the work for 156 | making modifications to it. For an executable work, complete source 157 | code means all the source code for all modules it contains, plus any 158 | associated interface definition files, plus the scripts used to 159 | control compilation and installation of the executable. However, as a 160 | special exception, the source code distributed need not include 161 | anything that is normally distributed (in either source or binary 162 | form) with the major components (compiler, kernel, and so on) of the 163 | operating system on which the executable runs, unless that component 164 | itself accompanies the executable. 165 | 166 | If distribution of executable or object code is made by offering 167 | access to copy from a designated place, then offering equivalent 168 | access to copy the source code from the same place counts as 169 | distribution of the source code, even though third parties are not 170 | compelled to copy the source along with the object code. 171 | 172 | 4. You may not copy, modify, sublicense, or distribute the Program 173 | except as expressly provided under this License. Any attempt 174 | otherwise to copy, modify, sublicense or distribute the Program is 175 | void, and will automatically terminate your rights under this License. 176 | However, parties who have received copies, or rights, from you under 177 | this License will not have their licenses terminated so long as such 178 | parties remain in full compliance. 179 | 180 | 5. You are not required to accept this License, since you have not 181 | signed it. However, nothing else grants you permission to modify or 182 | distribute the Program or its derivative works. These actions are 183 | prohibited by law if you do not accept this License. Therefore, by 184 | modifying or distributing the Program (or any work based on the 185 | Program), you indicate your acceptance of this License to do so, and 186 | all its terms and conditions for copying, distributing or modifying 187 | the Program or works based on it. 188 | 189 | 6. Each time you redistribute the Program (or any work based on the 190 | Program), the recipient automatically receives a license from the 191 | original licensor to copy, distribute or modify the Program subject to 192 | these terms and conditions. You may not impose any further 193 | restrictions on the recipients' exercise of the rights granted herein. 194 | You are not responsible for enforcing compliance by third parties to 195 | this License. 196 | 197 | 7. If, as a consequence of a court judgment or allegation of patent 198 | infringement or for any other reason (not limited to patent issues), 199 | conditions are imposed on you (whether by court order, agreement or 200 | otherwise) that contradict the conditions of this License, they do not 201 | excuse you from the conditions of this License. If you cannot 202 | distribute so as to satisfy simultaneously your obligations under this 203 | License and any other pertinent obligations, then as a consequence you 204 | may not distribute the Program at all. For example, if a patent 205 | license would not permit royalty-free redistribution of the Program by 206 | all those who receive copies directly or indirectly through you, then 207 | the only way you could satisfy both it and this License would be to 208 | refrain entirely from distribution of the Program. 209 | 210 | If any portion of this section is held invalid or unenforceable under 211 | any particular circumstance, the balance of the section is intended to 212 | apply and the section as a whole is intended to apply in other 213 | circumstances. 214 | 215 | It is not the purpose of this section to induce you to infringe any 216 | patents or other property right claims or to contest validity of any 217 | such claims; this section has the sole purpose of protecting the 218 | integrity of the free software distribution system, which is 219 | implemented by public license practices. Many people have made 220 | generous contributions to the wide range of software distributed 221 | through that system in reliance on consistent application of that 222 | system; it is up to the author/donor to decide if he or she is willing 223 | to distribute software through any other system and a licensee cannot 224 | impose that choice. 225 | 226 | This section is intended to make thoroughly clear what is believed to 227 | be a consequence of the rest of this License. 228 | 229 | 8. If the distribution and/or use of the Program is restricted in 230 | certain countries either by patents or by copyrighted interfaces, the 231 | original copyright holder who places the Program under this License 232 | may add an explicit geographical distribution limitation excluding 233 | those countries, so that distribution is permitted only in or among 234 | countries not thus excluded. In such case, this License incorporates 235 | the limitation as if written in the body of this License. 236 | 237 | 9. The Free Software Foundation may publish revised and/or new versions 238 | of the General Public License from time to time. Such new versions will 239 | be similar in spirit to the present version, but may differ in detail to 240 | address new problems or concerns. 241 | 242 | Each version is given a distinguishing version number. If the Program 243 | specifies a version number of this License which applies to it and "any 244 | later version", you have the option of following the terms and conditions 245 | either of that version or of any later version published by the Free 246 | Software Foundation. If the Program does not specify a version number of 247 | this License, you may choose any version ever published by the Free Software 248 | Foundation. 249 | 250 | 10. If you wish to incorporate parts of the Program into other free 251 | programs whose distribution conditions are different, write to the author 252 | to ask for permission. For software which is copyrighted by the Free 253 | Software Foundation, write to the Free Software Foundation; we sometimes 254 | make exceptions for this. Our decision will be guided by the two goals 255 | of preserving the free status of all derivatives of our free software and 256 | of promoting the sharing and reuse of software generally. 257 | 258 | NO WARRANTY 259 | 260 | 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY 261 | FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN 262 | OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES 263 | PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED 264 | OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 265 | MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS 266 | TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE 267 | PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, 268 | REPAIR OR CORRECTION. 269 | 270 | 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING 271 | WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR 272 | REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, 273 | INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING 274 | OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED 275 | TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY 276 | YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER 277 | PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE 278 | POSSIBILITY OF SUCH DAMAGES. 279 | 280 | END OF TERMS AND CONDITIONS 281 | 282 | How to Apply These Terms to Your New Programs 283 | 284 | If you develop a new program, and you want it to be of the greatest 285 | possible use to the public, the best way to achieve this is to make it 286 | free software which everyone can redistribute and change under these terms. 287 | 288 | To do so, attach the following notices to the program. It is safest 289 | to attach them to the start of each source file to most effectively 290 | convey the exclusion of warranty; and each file should have at least 291 | the "copyright" line and a pointer to where the full notice is found. 292 | 293 | 294 | Copyright (C) 295 | 296 | This program is free software; you can redistribute it and/or modify 297 | it under the terms of the GNU General Public License as published by 298 | the Free Software Foundation; either version 2 of the License, or 299 | (at your option) any later version. 300 | 301 | This program is distributed in the hope that it will be useful, 302 | but WITHOUT ANY WARRANTY; without even the implied warranty of 303 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 304 | GNU General Public License for more details. 305 | 306 | You should have received a copy of the GNU General Public License 307 | along with this program; if not, write to the Free Software 308 | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA 309 | 310 | 311 | Also add information on how to contact you by electronic and paper mail. 312 | 313 | If the program is interactive, make it output a short notice like this 314 | when it starts in an interactive mode: 315 | 316 | Gnomovision version 69, Copyright (C) year name of author 317 | Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'. 318 | This is free software, and you are welcome to redistribute it 319 | under certain conditions; type `show c' for details. 320 | 321 | The hypothetical commands `show w' and `show c' should show the appropriate 322 | parts of the General Public License. Of course, the commands you use may 323 | be called something other than `show w' and `show c'; they could even be 324 | mouse-clicks or menu items--whatever suits your program. 325 | 326 | You should also get your employer (if you work as a programmer) or your 327 | school, if any, to sign a "copyright disclaimer" for the program, if 328 | necessary. Here is a sample; alter the names: 329 | 330 | Yoyodyne, Inc., hereby disclaims all copyright interest in the program 331 | `Gnomovision' (which makes passes at compilers) written by James Hacker. 332 | 333 | , 1 April 1989 334 | Ty Coon, President of Vice 335 | 336 | This General Public License does not permit incorporating your program into 337 | proprietary programs. If your program is a subroutine library, you may 338 | consider it more useful to permit linking proprietary applications with the 339 | library. If this is what you want to do, use the GNU Library General 340 | Public License instead of this License. 341 | -------------------------------------------------------------------------------- /MAINTAINERS: -------------------------------------------------------------------------------- 1 | # Primary Maintainer: 2 | Shaun McCance 3 | E-mail: shaunm@gnome.org 4 | Userid: shaunm 5 | -------------------------------------------------------------------------------- /NEWS: -------------------------------------------------------------------------------- 1 | 42.1 2 | ==== 3 | * Fixed issue with DocBook when path is missing trailing slash, #22 4 | 5 | 42.0 6 | ==== 7 | * No changes since beta, stable release only 8 | 9 | 42.beta 10 | ======= 11 | * yelp.m4: Avoid argument list too long error when cleaning (Dan Nicholson) 12 | 13 | 41.0 14 | ==== 15 | * No changes since beta, stable release only 16 | 17 | 41.beta 18 | ======= 19 | * Updates documentation (Andre Klapper) 20 | * Updates to build files (Jan Tojnar) 21 | 22 | 40.0 23 | ==== 24 | * Stable release. No updates since 40.rc. 25 | 26 | 40.rc 27 | ===== 28 | * Removed comment about revision version attrs from templates 29 | * Use /usr/bin/python3 as shebang 30 | 31 | 40.beta 32 | ======= 33 | * Added --skip option to skip files in yelp-check 34 | * Custom checkers in yelp-check return 1 on failure 35 | 36 | 40.alpha 37 | ======== 38 | * First release using the meson build system 39 | * Converted yelp-build, yelp-check, and yelp-new to python 40 | * New and improved templates for yelp-new 41 | * Support for .yelp-tools.cfg config file 42 | * Config file can specify custom checkers, like Schematron but easier 43 | * yelp-check hrefs takes a configurable allow list 44 | 45 | 3.38.0 46 | ====== 47 | * Stable release. No changes since 3.37.90 48 | 49 | 3.37.90 50 | ======= 51 | * yelp-new: Added new templates 52 | 53 | 3.32.2 54 | ====== 55 | * yelp-build: Fix spurious warning about missing stack files 56 | 57 | 3.32.1 58 | ====== 59 | * yelp-check: Fix validation for DocBook 5 with https redirects 60 | 61 | 3.32.0 62 | ====== 63 | * Stable release. No changes since 3.31.90 64 | 65 | 3.31.90 66 | ======= 67 | * Initial support for Mallard 1.2 stack files 68 | 69 | 3.28.0 70 | ====== 71 | * Stable release. No changes since 3.27.90 72 | 73 | 3.27.90 74 | ======= 75 | * Adapt to recent major changes in yelp-xsl 76 | * yelp.m4: Disable net access in make check 77 | * yelp-check: Add --jing option to validate command to use jing 78 | * yelp-check: Add style command to list page styles 79 | * yelp-check: Remember URLs we already checked in `hrefs` 80 | 81 | 3.18.0 82 | ====== 83 | * Stable release. No changes since 3.17.4 84 | 85 | 3.17.4 86 | ====== 87 | * yelp-check: Sites support for orphans, links, media, status 88 | 89 | 3.17.3 90 | ====== 91 | * yelp-build: Fix some broken and non-portable expr usage, #743911 92 | * yelp-build: Fixed media copying with -i for Mallard 93 | * yelp-build: Added support for Mallard Sites to cache generator 94 | * yelp-check: Sites support for ids, hrefs, validate, comments, license 95 | * yelp-check: Accept -h as well as --help 96 | 97 | 3.16.1 98 | ====== 99 | * yelp-check: Check media correctly in subdirs, #727557 100 | 101 | 3.14.1 102 | ====== 103 | * yelp.m4: Fixed issues with make distcheck and install not running correclty 104 | unless make is run first, #701959 and #738142 (Sebastian Geiger) 105 | 106 | 3.14.0 107 | ====== 108 | * Stable release. No changes since 3.13.3 109 | 110 | 3.13.3 111 | ====== 112 | * Added support for .page.stub files in yelp-check 113 | 114 | 3.12.1 115 | ====== 116 | * yelp-check: Return non-zero exit status when there are broken hrefs 117 | 118 | 3.12.0 119 | ====== 120 | * Stable release. No changes since 3.11.5 121 | 122 | 3.11.5 123 | ====== 124 | * yelp-build: Added -i option to ignore missing media files 125 | * yelp-build: Added -p option to provide path for external files 126 | * yelp-build: Set LC_ALL instead of LANG for awk, #709354 127 | * yelp-check: Added check for missing media files 128 | * yelp-check: Added tool to check Mallard page licenses 129 | * yelp.m4: Use AS_HELP_STRING instead of AC_HELP_STRING, #709657 130 | 131 | 3.11.3 132 | ====== 133 | * yelp.m4: no-lc-dist option to disable disting the generated lc files (Christian Persch) 134 | 135 | 3.11.2 136 | ====== 137 | * yelp.m4: Added no-lc-media-links option for YELP_HELP_INIT 138 | * yelp.m4: Reverted HELP_MEDIA_NODUP and YELP_INIT_HELP 139 | 140 | 3.11.1 141 | ====== 142 | * yelp-build: Handle conditional processing and other logic when copying 143 | media and other external files, #709951 144 | * yelp-check: Support validate on DocBook 5 documents 145 | * yelp-check: Support explicitly allowed namespaces in strict validation 146 | * yelp-check: Fixed POSIX shell syntax error, #710331 (Michael Biebl) 147 | * yelp-new: Now much smarter about output file paths and extensions 148 | * yelp.m4: Added HELP_MEDIA_NODUP to install media without locale symlinks 149 | * yelp.m4: Added YELP_INIT_HELP as version-checking replacement for 150 | YELP_HELP_INIT 151 | 152 | 3.10.0 153 | ====== 154 | * Stable release. No changes since 3.9.90 155 | 156 | 3.9.90 157 | ====== 158 | * yelp-build: Fix directionality issues for Mallard 159 | * yelp-check: Allow xml: attributes when validating in strict mode 160 | 161 | 3.9.1 162 | ===== 163 | * Fixed BSD compatibility issue in calling mktemp 164 | * Fixed 'make pot' when srcdir != builddir (Michael Terry) 165 | * yelp-check validate: Validate cache files 166 | * yelp-check ids: New command to check Mallard page IDs 167 | * yelp-build epub: Fixed issue with directory for media 168 | 169 | 3.6.1 170 | ===== 171 | * yelp-check: Added 'links -i' to ignore xrefs with hrefs 172 | * yelp-check: Fixed extra angle brack in 'comments' 173 | 174 | 3.6.0 175 | ===== 176 | * Stable release for 3.5.x series 177 | 178 | 3.5.92 179 | ====== 180 | * yelp-check: Updated usage for 'yelp-check status' 181 | * yelp-build: Fixed 'yelp-build epub --help' 182 | 183 | 3.5.91 184 | ====== 185 | * yelp-check: Handle local files in hrefs, #673746 186 | * yelp.m4: Unbreak dist when using the LINGUAS envar 187 | * Fixed xmllint/xsltproc version checks (Edward Sheldrake) 188 | 189 | 3.4.0 190 | ===== 191 | * yelp-check: links and hrefs commands now work for DocBook 192 | 193 | 3.3.4 194 | ===== 195 | * yelp-check: Added --strict option to validate 196 | 197 | 3.3.3 198 | ===== 199 | * yelp.m4: Fixed install/uninstall targets with lots of files 200 | * yelp.m4: Only call mkdir_p once per directory (Christian Persch) 201 | * yelp.m4: Dist all linguas, regardless of LINGUAS (Christian Persch) 202 | * yelp-build: Call html.js.custom 203 | 204 | 3.3.2 205 | ===== 206 | * yelp.m4: Custom distdir target to work around "Argument list too long" 207 | 208 | 3.3.1 209 | ===== 210 | * yelp.m4: Use stamp files to reduce rebuilds, #651252 #659421 211 | * yelp-check: Add hrefs command to test external links 212 | 213 | 3.2.1: 214 | ====== 215 | * yelp-check status: Accept commas as a delimiter for options (Shaun McCance) 216 | 217 | 3.2.0: 218 | ====== 219 | * No changes since 3.1.7 220 | 221 | 3.1.7: 222 | ====== 223 | * yelp.m4: Do not use $(DESTDIR) when linking figures (Vincent Untz) 224 | 225 | 3.1.6: 226 | ====== 227 | * Sped up cache generation in yelp-build (Shaun McCance) 228 | * Added HELP_POT variable to specify pot name (Michael Terry) 229 | * Fixed --pkgversion lookup in 'yelp-check status' (Shaun McCance) 230 | 231 | 3.1.5: 232 | ====== 233 | * Sped up yelp-build html by doing single-pass transforms 234 | * Check for itstool 235 | 236 | 3.1.4: 237 | ====== 238 | * Added comments subcommand to yelp-check 239 | 240 | 3.1.3: 241 | ====== 242 | * Added Mallard page status checker to yelp-check 243 | * Added EPUB builder to yelp-build 244 | * Changes for yelp-xsl upgrade to jQuery.syntax 3.0 245 | * Copy images in yelp-build for e:mouseover 246 | * Fixed HTML namespace issues in yelp-build 247 | 248 | 3.1.2: 249 | ====== 250 | * Use YELP_ namespace in AC macro and variable 251 | * Check for itstool and xmllint in build tools 252 | * Build tools work without AM_SILENT_RULES 253 | 254 | 3.1.1: 255 | ====== 256 | * Initial release 257 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Yelp Tools 2 | 3 | yelp-tools is a collection of scripts and build utilities to help create, 4 | manage, and publish documentation for Yelp and the web. Most of the heavy 5 | lifting is done by packages like yelp-xsl and itstool. This package just 6 | wraps things up in a developer-friendly way. 7 | 8 | 9 | ## ORGANIZATION 10 | 11 | - `templates/` 12 | The templates directory contains page templates used by yelp-new. 13 | 14 | - `tools/` 15 | The tools directory contains scripts like yelp-build and yelp-check, 16 | as well as the yelp.m4 file that provides autotools integration. 17 | 18 | - `xslt/` 19 | The xslt directory contains small utility XSLT files that are used 20 | by the various scripts shipped with yelp-tools. These stylesheets 21 | are not intended to be built upon. 22 | -------------------------------------------------------------------------------- /help/C/index.page: -------------------------------------------------------------------------------- 1 | 4 | 5 | 6 | 7 | Yelp Tools 8 | 9 |

The yelp-tools package contains small programs that help you 10 | create, edit, manage, and publish your 11 | Mallard or 12 | DocBook documentation.

13 | 14 | 15 | -------------------------------------------------------------------------------- /help/C/yelp-build.page: -------------------------------------------------------------------------------- 1 | 3 | 4 | 5 | Create HTML, EPUB, and other files from source documents. 6 | 7 | 8 | <cmd>yelp-build</cmd> 9 | 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 |

Command

Mallard

DocBook 4

DocBook 5

yelp-build cache

Yes

No

No

yelp-build epub

Yes

No

No

yelp-build html

Yes

Yes

Yes

yelp-build xhtml

Yes

Yes

Yes

46 | 47 |
48 | <cmd>yelp-build cache</cmd> 49 | 50 |

Create a Mallard cache 51 | file from a Mallard document. A cache file is necessary to build 52 | other formats from Mallard documents. The other build commands generate a 53 | cache file automatically, but sometimes it's useful to provide a cache file 54 | explicitly. For example, if you only want to output the HTML for one page, 55 | you might run:

56 | 57 | yelp-build html foo.page 58 | 59 |

But then yelp-build will assume that foo.page is 60 | the entirety of the document, and will create a cache file for just that page. 61 | If you have a cache file with the cache for all pages, say index.cache, 62 | you can instead run:

63 | 64 | yelp-build html -c index.cache foo.page 65 | 66 |

You can pass yelp-build cache a list of page files, or just pass 67 | it a directory to have it cache all page files in that directory.

68 | 69 | yelp-build cache *.page 70 | yelp-build cache . 71 | 72 |

By default, the output cache file name is index.cache. Use the -o 73 | option to output a different file name.

74 | 75 | yelp-build cache -o foo.cache . 76 |
77 | 78 |
79 | <cmd>yelp-build epub</cmd> 80 | 81 |

Output an EPUB file, currently for 82 | Mallard documents only. An EPUB file is a special zip file containing XHTML files, 83 | stylesheets and other supporting files, and EPUB-specific files that specify the 84 | document structure. You can pass yelp-build epub a list of page files, 85 | or just pass it a directory to have it use all page files in that directory.

86 | 87 |

Just as for yelp-build html or yelp-build xhtml, you can 88 | pass a custom cache file with the -c option, a customization stylesheet 89 | with the -x option, a path for external files with the -p 90 | option, and the option to ignore missing media files with -i. See the 91 | documentation for yelp-build html for more information. Note that 92 | setting URL roots for JavaScript, CSS, and icon files is usually not a good idea 93 | for EPUB, because yelp-build epub places those files in a fixed 94 | location inside the zip file.

95 | 96 |

By default, the output file name is index.epub. Use the -o 97 | option to specify a different output file.

98 |
99 | 100 |
101 | <cmd>yelp-build html</cmd> 102 | 103 |

Output HTML files from a Mallard or DocBook document. The output file 104 | names are taken from the IDs in the XML, regardless of the input file names. 105 | For Mallard, you can pass yelp-build html a list of page files, 106 | or just pass it a directory to have it create HTML for all page files in 107 | that directory. For DocBook, pass the top-level XML file.

108 | 109 | 110 | yelp-build html index.page foo.page bar.page 111 | yelp-build html . 112 | yelp-build html index.docbook 113 | 114 | 115 |

By default, files are output to the current working directory. Use the 116 | -o option to specify an output directory.

117 | 118 | 119 | mkdir html_out 120 | yelp-build html -o html_out . 121 | 122 | 123 |

If you use the -o option, yelp-build html will also 124 | copy media files to the output directory and create the appropriate directory 125 | structure under the output directory. It will look inside the XML for tags 126 | like media and imagedata to find media files to copy.

127 | 128 |

Sometimes, some media files and external resources are not under the same 129 | path. This happens, for example, when you generate translated files in another 130 | directory but don't create copies of untranslated files. Pass a path of other 131 | base directories to use for files lookups with the -p option to 132 | resolve these files.

133 | 134 |

If a referenced media file does not exist (potentially anywhere within the 135 | path), yelp-build will still attempt to copy it, which will produce 136 | warnings on stderr. To make yelp-build check for the file's existence 137 | before copying, use the -i option. Be careful: without the warnings, 138 | you could easily end up with broken images in your document.

139 | 140 |

For Mallard documents, a cache file is created for you by default from the 141 | pages you pass on the command line. You can also pass a cache file explicitly 142 | with the -c option. This is useful if you only want to rebuild a 143 | few pages, but you want yelp-build to know about all the pages in 144 | the document for linking purposes. See yelp-build cache above.

145 | 146 |

When creating HTML, yelp-build also outputs CSS and JavaScript 147 | files, as well as PNG files for icons and watermarks. What it outputs depends 148 | on what's in your document. For JavaScript, a static set of files are copied, 149 | as well as additional JavaScript files for syntax highlighting. Which files 150 | are copied depends on what syntaxes you use in program listings and code 151 | blocks. For CSS, yelp-build creates a separate CSS file for each 152 | top-level language. For icons and watermarks, which images are copied depends 153 | on what types of admonitions and other elements you use.

154 | 155 |

The stylesheets that do the conversion to HTML are flexible and customizable. 156 | You can add customizations to affect the layout and presentation. You can pass 157 | a customization stylesheet to yelp-build html using the -x option.

158 | 159 | yelp-build html -x custom.xsl . 160 | 161 |

The customization stylesheet should not include or import the Yelp stylesheets. 162 | The yelp-build command will automatically create a wrapper stylesheet 163 | that includes the customization and imports the Yelp stylesheets.

164 | 168 | 169 |

The stylesheets allow you to specify URL roots for CSS, JavaScript, and icon 170 | files. By default, it's the same directory as the output HTML files. You can 171 | override these by setting parameters in a customization stylesheet, but 172 | yelp-build html does not change where it outputs those files. If you 173 | set these parameters to use common files on your web site, you must manage those 174 | files manually.

175 |
176 | 177 |
178 | <cmd>yelp-build xhtml</cmd> 179 | 180 |

Output XHTML files from a Mallard or DocBook document. This works exaclty 181 | like the yelp-build html command and allows the same options, but 182 | it serializes the files as XML. See the documentation for 183 | yelp-build html for details.

184 |
185 | 186 | 187 | -------------------------------------------------------------------------------- /help/C/yelp-check.page: -------------------------------------------------------------------------------- 1 | 3 | 4 | 5 | Validate documents, check link integrity, find orphaned 6 | pages, and perform various other checks. 7 | 8 | 9 | <cmd>yelp-check</cmd> 10 | 11 | 12 | 13 | 14 | 15 | 16 | 17 | 18 | 19 | 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 |

Command

Mallard

DocBook 4

DocBook 5

yelp-check comments

Yes

Yes

Yes

yelp-check hrefs

Yes

Yes

Yes

yelp-check ids

Yes

No

No

yelp-check license

Yes

No

No

yelp-check links

Yes

Yes

Yes

yelp-check media

Yes

Yes

Yes

yelp-check orphans

Yes

No

No

yelp-check status

Yes

No

No

yelp-check validate

Yes

Yes

Yes

77 | 78 |
79 | <cmd>yelp-check comments</cmd> 80 | 81 |

Print the editorial comments in a Mallard or DocBook document. Both 82 | Mallard and DocBook allow editors to embed remarks in a document that 83 | are not normally shown when formatting the document. (These remarks 84 | are displayed by Yelp when using the --editor-mode option.) 85 | Mallard uses the comment element, and DocBook uses the 86 | remark element.

87 | 88 |

For Mallard documents, you can pass yelp-check comments 89 | a list of page files, or you can pass it a directory to process all 90 | page files in that directory. For DocBook, you can pass any DocBook 91 | file, including any well-formed files that are included in a top-level 92 | file.

93 | 94 |

Mallard comments are printed with the enclosing page and section ID, 95 | the author of the comment, and the date the comment was made. Mallard 96 | comments allow any block content, but yelp-check comments 97 | cannot format all block content in plain text. Any content that is not 98 | in a p element currently results in a FIXME statement.

99 | 100 |

DocBook comments are printed with the closest enclosing ID and the 101 | value of the revisionflag attribute.

102 |
103 | 104 |
105 | <cmd>yelp-check hrefs</cmd> 106 | 107 |

Check the target of all external links in a Mallard or DocBook 108 | document. For Mallard documents, yelp-check hrefs uses 109 | all href attributes in the document. For DocBook 110 | documents, it uses the url attribute of all 111 | ulink elements as well as all xlink:href 112 | attributes in the document. In both cases, mailto: 113 | links are excluded.

114 | 115 |

For Mallard documents, you can pass yelp-check hrefs 116 | a list of page files, or you can pass it a directory to process all 117 | page files in that directory. For DocBook, you can pass any DocBook 118 | file, including any well-formed files that are included in a top-level 119 | file.

120 | 121 |

If a URL is relative, yelp-check hrefs checks for the 122 | file locally. If a URL is absolute, it uses curl to check 123 | the HTTP status of the resource.

124 |
125 | 126 |
127 | <cmd>yelp-check ids</cmd> 128 | 129 |

Check if the id attributes of pages match the base 130 | file name (without the .page extension) of the page 131 | files they're defined in. It is not mandatory for them to match in 132 | Mallard, but it's generally considered a best practice.

133 |
134 | 135 |
136 | <cmd>yelp-check license</cmd> 137 | 138 |

Report the license of Mallard page files, taken from the 139 | license element. The license is reported based on 140 | the href attribute. The block content of the 141 | license element is not used at all. For certain known licenses 142 | (such as those from GNU and Creative Commons), a shortened 143 | identifier is shown instead of the full URL. If a license 144 | element does not have an href attribute, it is 145 | listed as unknown.

146 | 147 |

Pages may have multiple license elements. If 148 | they do, the license identifiers will all be reported, joined 149 | with a comma. If a page has no license element, it is reported 150 | as none.

151 | 152 |

You can restrict which licenses are shown using the following 153 | options:

154 | 155 | 156 | 157 | <cmd>--only <var>LICENSES</var></cmd> 158 |

Only show pages that have a license from the space-separated 159 | list LICENSES.

160 | 161 | 162 | 163 | <cmd>--except <var>LICENSES</var></cmd> 164 |

Only show pages that do not any license in the 165 | space-separated list LICENSES.

166 | 167 | 168 | 169 |

You can also get a summary of which licenses are in a document:

170 | 171 | 172 | 173 | <cmd>--totals</cmd> 174 |

Instead of the normal output of "page: license", 175 | print a list of licenses along with the number of pages that have 176 | each license. All of the options above can still be used to filter 177 | the pages that are used to calculate the totals.

178 | 179 | 180 |
181 | 182 |
183 | <cmd>yelp-check media</cmd> 184 | 185 |

Check for references to external media files that do not exist. For 186 | Mallard, media, ui:thumb, uix:thumb, 187 | and e:mouseover elements are used. For DocBook, audiodata, 188 | imagedata, and videodata elements are used.

189 |
190 | 191 | 222 | 223 |
224 | <cmd>yelp-check orphans</cmd> 225 | 226 |

Check for Mallard pages that cannot be reached by topic links. 227 | You may still be able to reach the page by other links, but they 228 | do not appear in the primary topic navigation of the document.

229 | 230 |

You can pass yelp-check orphans a list of page files, 231 | or you can pass it a directory to process all page files in that 232 | directory. If you pass only a set of pages, yelp-check 233 | orphans will only know about those pages, and will probably 234 | report many false positives. However, you can create a cache file 235 | with yelp-build cache that contains all the pages in 236 | the document and pass this to yelp-check orphans with 237 | the -c option.

238 |
239 | 240 |
241 | <cmd>yelp-check status</cmd> 242 | 243 |

Report the status of Mallard page files, taken from the status 244 | attribute of the revision elements for each page. You can pass a 245 | list of page files, or pass a directory to process all page files 246 | in that directory.

247 | 248 |

A page may have more than one revision element. When this happens, 249 | yelp-check status filters the elements based on the 250 | version, docversion, pkgversion, 251 | and date attributes, depending on the arguments below. 252 | It then sorts the revision elements primarily descending 253 | by the date attribute, then by document order, and uses 254 | the status attribute from the first. If the selected 255 | revision element has no status attribute, 256 | or if there are no matching revision elements, the status is 257 | "none".

258 | 259 | 260 | 261 | <cmd>--version <var>VERSIONS</var></cmd> 262 | <cmd>--docversion <var>VERSIONS</var></cmd> 263 | <cmd>--pkgversion <var>VERSIONS</var></cmd> 264 | 265 |

Only consider revision elements with a matching 266 | version, docversion, or pkgversion 267 | attribute, respectively. These options can be combined, and they 268 | must all match. In all cases, VERSIONS can be a list 269 | of versions separated by spaces or commas. The option matches if 270 | any version matches the corresponding attribute.

271 | 272 | 273 | 274 | <cmd>--older <var>DATE</var></cmd> 275 | <cmd>--newer <var>DATE</var></cmd> 276 | 277 |

Only consider revision elements with a date 278 | attribute that comes before (--older) or after 279 | (--newer) the specified date. Dates are expected 280 | to be in the form YYYY-MM-DD. These options may be 281 | combined to specify a range the revision dates must fall in.

282 | 283 | 284 | 285 |

There are also options that change what is output.

286 | 287 | 288 | 289 | <cmd>--only <var>STATUSES</var></cmd> 290 | <cmd>--except <var>STATUSES</var></cmd> 291 | 292 |

After the status is determined as above, only print those 293 | pages whose status matches (--only) or does not 294 | match (--except) the specified statuses. In both 295 | cases, STATUSES can be a list of statuses separated 296 | by spaces or commas.

297 | 298 | 299 | 300 | <cmd>--totals</cmd> 301 | 302 |

Instead of the normal output of "page: status", 303 | print a list of statuses along with the number of pages that 304 | have each status. All of the options above can still be used 305 | to filter the revision elements and to limit which statuses 306 | the report on.

307 | 308 | 309 |
310 | 311 |
312 | <cmd>yelp-check validate</cmd> 313 | 314 |

Validate files against a DTD or RNG schema.

315 | 316 |

For Mallard documents, yelp-check validate implements 317 | automatic 318 | schema merging based on the version attribute. If 319 | there is no version attribute on a page, it is assumed 320 | to be "1.0", and the base Mallard 1.0 schema is used.

321 | 322 |

The Mallard schema allows elements and attributes from unknown 323 | namespaces in many places, where the list of known namespaces is 324 | built from the merged schemas. You can pass the --strict 325 | option to disallow elements and attributes from unknown namespaces. 326 | This is useful if you want to prevent unknown extensions.

327 | 328 | 329 | 330 | <cmd>--strict</cmd> 331 | 332 |

Disallow elements and attributes from namespaces that aren't 333 | explicitly defined by the schemas imported based on the 334 | version attribute.

335 | 336 | 337 | 338 | <cmd>--allow <var>NAMESPACE</var></cmd> 339 | 340 |

When using strict validation, explicitly allow elements and 341 | attributes from the namespace NAMESPACE in places 342 | where any external-namespace nodes would normally be allowed. 343 | You can pass the --allow option multiple times to 344 | provide multiple namespaces that should be allowed.

345 | 346 | 347 | 348 |

For DocBook 4, yelp-check validate uses the DTD set 349 | by the DOCTYPE. If a document appears to be DocBook 4 350 | but does not contain a DOCTYPE, the 4.5 DTD is used.

351 | 352 |

For DocBook 5, yelp-check validate selects an RNG 353 | schema based on the version attribute.

354 |
355 | 356 | 357 | -------------------------------------------------------------------------------- /help/C/yelp-new.page: -------------------------------------------------------------------------------- 1 | 3 | 4 | 5 | Easily create new documents and pages from template files. 6 | 7 | 8 | <cmd>yelp-new</cmd> 9 | 10 |

Create a new file from a template. You can quickly create a new 11 | page or other file from a template. This is useful when many of your 12 | pages have a common layout or structure. You must pass at least two 13 | arguments: the identifier of the template, and the ID of the file to 14 | create. The second argument is used both for the base file name of 15 | the new file and for the id attribute. You can optionally pass a page 16 | title as the third argument.

17 | 18 |

Template files can be installed with yelp-new or they 19 | can be kept locally in the same directory. Local templates are useful 20 | if you have common page styles that are specific to your project. To 21 | get a list of available templates, run yelp-new --help.

22 | 23 |

You can create your own template files. Just create a file with the 24 | .tmpl extension appended. You can also use the --tmpl 25 | option on yelp-new to copy an existing template to the current directory 26 | without substituting, allowing you to build off of it for your own template.

27 | 28 |

Output files are created by substituting special markers in the template.

29 | 30 | 31 | 32 | <code>@ID@</code> 33 |

The ID value passed as the second argument to yelp-new, which is 34 | the same as the base file name of the output file.

35 | 36 | 37 | 38 | <code>@DATE@</code> 39 |

The current date in the format YYYY-MM-DD.

40 | 41 | 42 | 43 | <code>@YEAR@</code> 44 |

The current year in the format YYYY.

45 | 46 | 47 | 48 | <code>@NAME@</code> 49 |

The name of the person running the command. This value may come 50 | from either git or bzr. Failing that, the 51 | value "YOUR NAME" is used.

52 | 53 | 54 | 55 | <code>@EMAIL@</code> 56 |

The email address of the person running the command. This value 57 | may come from either git or bzr. Failing that, 58 | the value "YOUR EMAIL ADDRESS" is used.

59 | 60 | 61 | 62 | <code>@TITLE@</code> 63 |

The title as passed as the third argument to yelp-new. 64 | If you do not pass a title, the value "TITLE" is used.

65 | 66 | 67 | 68 |

You can also pass the --stub option to create a 69 | .page.stub file instead of a regular .page file.

70 | 71 | 72 | -------------------------------------------------------------------------------- /help/C/yelp.m4.page: -------------------------------------------------------------------------------- 1 | 4 | 5 | 6 | Automatically manage documentation in an autotools+make 7 | build environment. 8 | 9 | 10 | <file>yelp.m4</file> 11 | 12 |

The yelp-tools package contains build utilities that help you build 13 | and install your help files according to the 14 | freedesktop.org 15 | help specification. The freedesktop.org help specification was jointly 16 | created by GNOME and KDE developers to create a single help system that all 17 | desktop environments use. To date, Yelp is the only implementation.

18 | 19 |

The build utilities are contained in a single file, yelp.m4. 20 | To use it, add the following to your configure.ac file:

21 | 22 | YELP_HELP_INIT 23 | 24 |

You can also pass a space-separated list of options as the first argument 25 | to YELP_HELP_INIT:

26 | 27 | YELP_HELP_INIT([options...]) 28 | 29 |

The following options are currently recognized:

30 | 31 | 32 | 33 | <code>no-lc-media-links</code> 34 | 35 |

Normally, the build utilies create symlinks for localized media 36 | files when translators have not provided an actual localization. 37 | This means that copies of media files always exist in each locale's 38 | directory, even if there is no translation. Passing the 39 | no-lc-media-links option suppresses these symlinks.

40 | 41 |

For normal images and videos, Yelp is able to look up files 42 | according to a document search path, so the symlinks are actually 43 | unnecessary. This has been true since at least Yelp 3.0. If you are 44 | only installing images and videos that are embedded in pages, use 45 | this option. If you use HELP_MEDIA for other types of files, such 46 | as source code or other files that get linked to, only use this 47 | option if you have verified that it works in production.

48 | 49 |

Added in 3.12

50 | 51 | 52 | 53 | <code>no-lc-dist</code> 54 | 55 |

Normally, the build utilities dist the generated translated files, 56 | including the localized copies of HELP_FILES output by 57 | itstool and the stamp file used for tracking when the 58 | localized files were built. Using the no-lc-dist option 59 | makes these generated files not be included in the tarball. This 60 | reduces the size of the tarball, but increases the time it takes 61 | to build from the tarball.

62 | 63 | 64 |

Note that currently, help.gnome.org does not use any sort of 65 | build system, and only uses files found in tarballs. If you use 66 | no-lc-dist, translations of your documents will not 67 | show up correctly on help.gnome.org or any other site that uses 68 | the same code.

69 | 70 | 71 |

Added in 3.12

72 | 73 | 74 | 75 |

By default, the help directory is $PREFIX/help, 76 | and each language is installed to 77 | $PREFIX/help/$LANG/$HELP_ID/. 78 | The build utilities automatically provide a configure option 79 | --with-help-dir, allowing users to override the help directory.

80 | 81 |

The build utilities expect a layout that looks something like this:

82 | 83 | 84 | 85 | help/ 86 | Makefile.am 87 | 88 | C/ 89 | help files... 90 | 91 | media/ 92 | help media files... 93 | 94 | 95 | 96 | ll/ 97 | ll.po 98 | 99 | media/ 100 | help media files for ll... 101 | 102 | 103 | 104 | 105 | 106 |

There is a single Makefile.am file in the help directory 107 | that manages all translations. The help directory can have any name, or 108 | be arbitrarily deep. For projects with a single help document, it's common 109 | to simply use a top-level help directory.

110 | 111 |

The source files are expected to be in a directory called C. 112 | It's common to put images, videos, and other non-XML files in a subdirectory 113 | called media or figures. The actual name of the 114 | subdirectory doesn't matter, but examples on this page will use media.

115 | 116 |

Each translation has its own directory named according to the locale. 117 | That directory contains a PO file also named according to the locale. 118 | The name of the directory must match the base name of the PO file. For 119 | media files (those not translated using the PO files), translators add 120 | localized files using the same names and directory layout as the source 121 | files. If a media file does not need to be localized, you do not need to 122 | copy it. The build utilities take care of this automatically.

123 | 124 |

The Makefile.am file must start with the following line:

125 | 126 | @YELP_HELP_RULES@ 127 | 128 |

You can set the following variables:

129 | 130 | 131 | 132 | <code>HELP_ID</code> 133 |

The ID of the help document. This determines the install location, 134 | and will be referenced in the help: URIs used in your 135 | application. This variable is required.

136 | 137 | 138 | 139 | <code>HELP_POT</code> 140 |

A file name for a POT file to create when running make pot. 141 | This variable is optional. It defaults to ${HELP_ID}.pot. 142 | Note that make pot is not run as part of make. This 143 | is useful for Mallard page sets that are designed to merge into another 144 | document with the same HELP_ID. If make pot is 145 | used to generate a POT file for an external translation tool, that tool 146 | may expect POT file names to be globally unique.

147 | 148 | 149 | 150 | <code>HELP_FILES</code> 151 |

A space-separated list of the primary XML files. These files will be 152 | translated using the PO files and localized versions will be output when 153 | running make. This variable is appropriate for Mallard page 154 | files, top-level DocBook files, and any XML files that are included with 155 | XInclude. All files listed in HELP_FILES must be well-formed 156 | XML. List all files relative to the C directory.

157 | 158 | 159 |

Because of the way yelp.m4 calls itstool, 160 | currently files in HELP_FILES must be directly in the C 161 | directory, not a subdirectory. If you use a subdirectory, the directory 162 | structure will not be reproduced in translations. See 163 | bug 7.

164 | 165 | 166 | 167 | 168 | <code>HELP_EXTRA</code> 169 | 170 |

A space-separated list of files that are disted and installed for 171 | C, but are not in any way localized. This variable is 172 | appropriate for XML files that are included with SYSTEM 173 | entities and text files included with XInclude. These types of files 174 | are merged by default by itstool when creating PO files, 175 | so they are redundant in localizations. List all files relative to 176 | the C directory.

177 | 178 | 179 | 180 | <code>HELP_MEDIA</code> 181 |

A space-separated list of files that are disted and installed for 182 | C, and which translators may create localized copies of. 183 | If translators do not create localized copies, the build utilities 184 | automatically create symlinks to the C files on make 185 | install, unless you pass the no-lc-media-links 186 | option to YELP_HELP_INIT. This variable is appropriate 187 | for images, videos, and any external files that are linked to within 188 | the help. List all files relative to the C directory.

189 | 190 | 191 | 192 | <code>HELP_LINGUAS</code> 193 |

A space-separated list of locales that are enabled. The build 194 | utilities will only use translations listed in this variable.

195 | 196 | 197 | 198 |

The build utilities automatically handle make, make 199 | install, make uninstall, and make dist. 200 | Additionally, the following make targets are handled:

201 | 202 | 203 | 204 | <cmd>make check</cmd> 205 |

When running the standard make check target, all 206 | files in HELP_FILES are checked for well-formedness 207 | using xmllint. Note that make check does 208 | not automatically do validation against schemas.

209 | 210 | 211 | 212 | <cmd>make pot</cmd> 213 |

Create POT file using itstool from the files in 214 | HELP_FILES. The name of the POT file can be specified 215 | by the HELP_POT variable, and defaults to 216 | ${HELP_ID}.pot. This is not called as part 217 | of make all. However, some projects store the POT file 218 | in version control, even though it's auto-generated, so that it 219 | can easily be picked up by online translation tools. If you do 220 | this, it's a good idea to make the all target depends on 221 | pot.

222 | 223 | 224 | 225 | <cmd>make repo</cmd> 226 |

Updates all the languages' PO files using the latest sources. 227 | This is not called as part of make all.

228 | 229 | 230 | 231 | 232 | 233 | -------------------------------------------------------------------------------- /help/meson.build: -------------------------------------------------------------------------------- 1 | yelp_tools_help_sources = [ 2 | 'index.page', 3 | 'yelp-build.page', 4 | 'yelp-check.page', 5 | 'yelp-new.page', 6 | 'yelp.m4.page', 7 | ] 8 | 9 | gnome.yelp( 10 | package_name, 11 | sources: yelp_tools_help_sources, 12 | ) -------------------------------------------------------------------------------- /meson.build: -------------------------------------------------------------------------------- 1 | project('yelp-tools', 2 | version: '42.1', 3 | license: 'GPL-2.0-or-later', 4 | meson_version: '>= 0.51.0', 5 | ) 6 | 7 | gnome = import('gnome') 8 | 9 | python = import('python') 10 | pyinst = python.find_installation('python3', required: true, modules: ['lxml']) 11 | 12 | package_name = meson.project_name() 13 | 14 | # Paths 15 | prefix = get_option('prefix') 16 | 17 | bindir = join_paths(prefix, get_option('bindir')) 18 | datadir = join_paths(prefix, get_option('datadir')) 19 | 20 | autoconfdatadir = join_paths(datadir, 'aclocal') 21 | pkgdir = join_paths(datadir, package_name) 22 | pkgtemplatesdir = join_paths(pkgdir, 'templates') 23 | pkgxsltdir = join_paths(pkgdir, 'xslt') 24 | 25 | # Dependencies 26 | yelp_xsl_req = '>= 3.38.0' 27 | 28 | yelp_xsl_dep = dependency('yelp-xsl', version: yelp_xsl_req) 29 | 30 | xmllint_prg = find_program('xmllint', required: true) 31 | xsltproc_prg = find_program('xsltproc', required: true) 32 | itstool_prg = find_program('itstool', required: true) 33 | 34 | yelp_db2html_path = yelp_xsl_dep.get_pkgconfig_variable('db2html') 35 | yelp_db2xhtml_path = yelp_xsl_dep.get_pkgconfig_variable('db2xhtml') 36 | yelp_mal2html_path = yelp_xsl_dep.get_pkgconfig_variable('mal2html') 37 | yelp_mal2xhtml_path = yelp_xsl_dep.get_pkgconfig_variable('mal2xhtml') 38 | 39 | yelp_xslt_dir = yelp_xsl_dep.get_pkgconfig_variable('xsltdir') 40 | yelp_js_dir = yelp_xsl_dep.get_pkgconfig_variable('jsdir') 41 | yelp_templates_dir = pkgtemplatesdir 42 | yelp_icons_dir = join_paths( 43 | yelp_xsl_dep.get_pkgconfig_variable('icondir'), 44 | 'hicolor', '24x24', 'status', 45 | ) 46 | 47 | subdir('xslt') 48 | subdir('templates') 49 | subdir('tools') 50 | 51 | if get_option('help') == true 52 | subdir('help') 53 | endif 54 | 55 | summary = [ 56 | '', 57 | '------', 58 | 'yelp-tools @0@'.format(meson.project_version()), 59 | '', 60 | ' yelp.m4: @0@'.format(get_option('yelpm4')), 61 | ' help: @0@'.format(get_option('help')), 62 | '', 63 | 'Directories:', 64 | ' prefix: @0@'.format(prefix), 65 | ' datadir: @0@'.format(datadir), 66 | '------', 67 | ] 68 | 69 | message('\n'.join(summary)) 70 | -------------------------------------------------------------------------------- /meson_options.txt: -------------------------------------------------------------------------------- 1 | option('yelpm4', 2 | type: 'boolean', value: true, 3 | description: 'Install autotools macros') 4 | 5 | option('help', 6 | type: 'boolean', value: false, 7 | description: 'Install help files') 8 | -------------------------------------------------------------------------------- /templates/concept.duck: -------------------------------------------------------------------------------- 1 | @ducktype/1.0 2 | [-] yelp-tmpl-desc Explanation of a concept or background information 3 | 4 | = {{TITLE}} 5 | [topic .concept version=1.1] 6 | 7 | {{INCLUDE info.ducktype.include}} 8 | 9 | 10 | Provide as many paragraphs, lists, or media as necessary to explain. 11 | 12 | [list] 13 | . Next steps 14 | * Optionally, links to other things the user might do now. 15 | * But consider using seealso and other info links instead. 16 | -------------------------------------------------------------------------------- /templates/concept.page: -------------------------------------------------------------------------------- 1 | 2 | 5 | 6 | {{INCLUDE info.mallard.include}} 7 | 8 | 9 | {{TITLE}} 10 | 11 |

Provide as many paragraphs, lists, or media as necessary to explain.

12 | 13 | 14 | Next steps 15 |

Optionally, links to other things the user might do now.

 16 |

But consider using seealso and other info links instead.

 17 | 18 | 19 | -------------------------------------------------------------------------------- /templates/guide.duck: -------------------------------------------------------------------------------- 1 | @ducktype/1.0 2 | [-] yelp-tmpl-desc Navigational glue for Mallard documents 3 | 4 | = {{TITLE}} 5 | [guide version=1.1] 6 | 7 | {{INCLUDE info.ducktype.include}} 8 | 9 | 10 | Optionally, an introductory paragraph. 11 | 12 | [-- 13 | The links element is implicit, but you might want to add one 14 | explicitly if you want to do link grouping or styles. 15 | [links topic .STYLE groups="GROUPS"] 16 | . Optional title 17 | --] 18 | -------------------------------------------------------------------------------- /templates/guide.page: -------------------------------------------------------------------------------- 1 | 2 | 5 | 6 | {{INCLUDE info.mallard.include}} 7 | 8 | 9 | {{TITLE}} 10 | 11 |

Optionally, an introductory paragraph.

12 | 13 | 20 | 21 | 22 | -------------------------------------------------------------------------------- /templates/info.ducktype.include: -------------------------------------------------------------------------------- 1 | [-- 2 | Recommended statuses: stub incomplete draft outdated review candidate final 3 | --] 4 | @revision[version={{VERSION}} date={{DATE}} status=stub] 5 | 6 | @credit[author copyright] 7 | @name {{NAME}} 8 | @email {{EMAIL}} 9 | @years {{YEAR}} 10 | 11 | [-- 12 | This puts a link to this topic on the index page. 13 | Change the xref to link it from another guide. 14 | --] 15 | @link[guide >index] 16 | 17 | [-- 18 | Think about whether other pages should be in the seealso list. 19 | The target page will automatically get a seealso link back. 20 | @link[seealso >someotherid] 21 | --] 22 | 23 | [-- 24 | Think about whether external resources should be in the seealso 25 | list. These require a title. 26 | @link[seealso >>http://someurl] 27 | @title Link title 28 | --] 29 | 30 | @desc Write a short page description here. 31 | 32 | @keywords comma-separated list, of keywords, for search 33 | -------------------------------------------------------------------------------- /templates/info.mallard.include: -------------------------------------------------------------------------------- 1 | 4 | 5 | 6 | 7 | {{NAME}} 8 | {{EMAIL}} 9 | {{YEAR}} 10 | 11 | 12 | 16 | 17 | 18 | 23 | 24 | 31 | 32 | Write a short page description here. 33 | 34 | comma-separated list, of keywords, for search 35 | -------------------------------------------------------------------------------- /templates/meson.build: -------------------------------------------------------------------------------- 1 | yelp_tools_templates_data = [ 2 | 'concept.duck', 3 | 'concept.page', 4 | 'guide.duck', 5 | 'guide.page', 6 | 'reference.duck', 7 | 'reference.page', 8 | 'task.duck', 9 | 'task.page', 10 | 'info.ducktype.include', 11 | 'info.mallard.include' 12 | ] 13 | 14 | install_data( 15 | yelp_tools_templates_data, 16 | install_dir: join_paths( 17 | pkgtemplatesdir, 18 | ) 19 | ) 20 | -------------------------------------------------------------------------------- /templates/reference.duck: -------------------------------------------------------------------------------- 1 | @ducktype/1.0 2 | [-] yelp-tmpl-desc Lists or tables of information for quick lookup 3 | 4 | = {{TITLE}} 5 | [topic .reference version=1.1] 6 | 7 | {{INCLUDE info.ducktype.include}} 8 | 9 | 10 | Optionally provide introductory text. 11 | Use terms lists, tables, and bullet lists for reference material. 12 | 13 | 14 | [terms] 15 | . Example terms list (title optional) 16 | 17 | - Term 1 18 | * Description 19 | 20 | - Term 2 21 | * Terms can have multiple paragraphs. 22 | 23 | [screen] 24 | Or any other block element. 25 | 26 | - Term 3.1 27 | - Term 3.2 28 | * Terms can also have multiple titles. 29 | 30 | 31 | [table] 32 | . Example table (title optional) 33 | 34 | [thead] 35 | [tr] 36 | - Column 1 37 | - Column 2 38 | 39 | [tbody] 40 | [tr] 41 | * Row 1, column 1 42 | * Row 1, column 2 43 | 44 | [tr] 45 | * Row 2, column 1 46 | * Row 2, column 2 47 | 48 | 49 | [list] 50 | . Example list (title optional) 51 | 52 | * Item 1 53 | 54 | * Item 2 55 | * Subitem 2.1 56 | * Subitem 2.2 57 | 58 | * Item 3 59 | -------------------------------------------------------------------------------- /templates/reference.page: -------------------------------------------------------------------------------- 1 | 2 | 5 | 6 | {{INCLUDE info.mallard.include}} 7 | 8 | 9 | {{TITLE}} 10 | 11 |

Optionally provide introductory text. 12 | Use terms lists, tables, and bullet lists for reference material.

13 | 14 | 15 | Example terms list (title optional) 16 | 17 | Term 1 18 | Description 19 | 20 | 21 | Term 2 22 |

Terms can have multiple paragraphs.

23 | Or any other block element. 24 | 25 | 26 | Term 3.1 27 | Term 3.2 28 |

Terms can also have multiple titles.

29 | 30 | 31 | 32 | 33 | Example table (title optional) 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 | 42 | 43 | 44 | 45 | 46 | 47 | 48 | 49 | 50 |
Column 1Column 2
Row 1, column 1Row 1, column 2
Row 2, column 1Row 2, column 2
51 | 52 | 53 | Example list (title optional) 54 |

Item 1

 55 | 56 |

Item 2

57 | 58 |

Subitem 2.1

 59 |

Subitem 2.2

 60 | 61 | 62 |

Item 3

 63 | 64 | 65 | 66 | -------------------------------------------------------------------------------- /templates/task.duck: -------------------------------------------------------------------------------- 1 | @ducktype/1.0 2 | [-] yelp-tmpl-desc Description of how to accomplish a user task 3 | 4 | = {{TITLE}} 5 | [topic .task version=1.1] 6 | 7 | {{INCLUDE info.ducktype.include}} 8 | 9 | 10 | Short introductory text: Write a couple sentences about what the 11 | user is doing here, and why they might want to do it. 12 | 13 | [list] 14 | . Prerequisites 15 | * Optionally, list things the user needs to know or do first. 16 | * Use links to other pages whenever they make sense. 17 | 18 | [steps] 19 | . Optional title if different from page title or if prereqs present 20 | * First step... 21 | * Second step... 22 | * Third step... 23 | 24 | Optionally, write expected results if non-obvious. 25 | 26 | [list] 27 | . Next steps 28 | * Optionally, links to other things the user might do now. 29 | * But consider using seealso and other info links instead. 30 | -------------------------------------------------------------------------------- /templates/task.page: -------------------------------------------------------------------------------- 1 | 2 | 5 | 6 | {{INCLUDE info.mallard.include}} 7 | 8 | 9 | {{TITLE}} 10 | 11 |

Short introductory text: Write a couple sentences about what the 12 | user is doing here, and why they might want to do it.

13 | 14 | 15 | Prerequisites 16 |

Optionally, list things the user needs to know or do first.

 17 |

Use links to other pages whenever they make sense.

 18 | 19 | 20 | 21 | Optional title if different from page title or if prereqs present 22 |

First step...

 23 |

Second step...

 24 |

Third step...

 25 | 26 | 27 |

Optionally, write expected results if non-obvious.

28 | 29 | 30 | Next steps 31 |

Optionally, links to other things the user might do now.

 32 |

But consider using seealso and other info links instead.

 33 | 34 | 35 | 36 | -------------------------------------------------------------------------------- /tools/.gitignore: -------------------------------------------------------------------------------- 1 | gnome-doc-prepare 2 | gnome-doc-tool 3 | gnome-doc-utils.pc 4 | -------------------------------------------------------------------------------- /tools/meson.build: -------------------------------------------------------------------------------- 1 | yelp_tools_in = configuration_data() 2 | yelp_tools_in.set('DATADIR', pkgdir) 3 | 4 | yelp_tools_in.set('YELP_JS_DIR', yelp_js_dir) 5 | 6 | yelp_tools_in.set('XSL_DB2HTML', yelp_db2html_path) 7 | yelp_tools_in.set('XSL_DB2XHTML', yelp_db2xhtml_path) 8 | yelp_tools_in.set('XSL_MAL2HTML', yelp_mal2html_path) 9 | yelp_tools_in.set('XSL_MAL2XHTML', yelp_mal2xhtml_path) 10 | 11 | yelp_tools_in.set('XSL_MAL_CACHE', join_paths( 12 | yelp_xslt_dir, 13 | 'mallard', 14 | 'cache', 15 | 'mal-cache.xsl', 16 | ) 17 | ) 18 | 19 | configure_file( 20 | input: 'yelp-build.in', 21 | output: 'yelp-build', 22 | configuration: yelp_tools_in, 23 | install: true, 24 | install_dir: bindir, 25 | ) 26 | 27 | configure_file( 28 | input: 'yelp-check.in', 29 | output: 'yelp-check', 30 | configuration: yelp_tools_in, 31 | install: true, 32 | install_dir: bindir, 33 | ) 34 | 35 | configure_file( 36 | input: 'yelp-new.in', 37 | output: 'yelp-new', 38 | configuration: yelp_tools_in, 39 | install: true, 40 | install_dir: bindir, 41 | ) 42 | 43 | if get_option('yelpm4') == true 44 | install_data( 45 | 'yelp.m4', 46 | install_dir: join_paths( 47 | autoconfdatadir, 48 | ) 49 | ) 50 | endif 51 | -------------------------------------------------------------------------------- /tools/yelp-build.in: -------------------------------------------------------------------------------- 1 | #!/usr/bin/python3 2 | # 3 | # yelp-build 4 | # Copyright (C) 2010-2020 Shaun McCance 5 | # 6 | # This program is free software; you can redistribute it and/or modify 7 | # it under the terms of the GNU General Public License as published by 8 | # the Free Software Foundation; either version 2 of the License, or 9 | # (at your option) any later version. 10 | # 11 | # This program is distributed in the hope that it will be useful, but 12 | # WITHOUT ANY WARRANTY; without even the implied warranty of 13 | # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14 | # General Public License for more details. 15 | # 16 | # You should have received a copy of the GNU General Public License 17 | # along with this program; if not, write to the Free Software 18 | # Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. 19 | 20 | import configparser 21 | import os 22 | import sys 23 | import shutil 24 | import subprocess 25 | import tempfile 26 | import urllib.parse 27 | import uuid 28 | 29 | import lxml.etree 30 | import lxml.ElementInclude 31 | 32 | 33 | XSL_DB2HTML = '@XSL_DB2HTML@' 34 | XSL_DB2XHTML = '@XSL_DB2XHTML@' 35 | XSL_MALCACHE = '@XSL_MAL_CACHE@' 36 | XSL_MAL2HTML = '@XSL_MAL2HTML@' 37 | XSL_MAL2XHTML = '@XSL_MAL2XHTML@' 38 | XSL_MAL_OPF='@DATADIR@/xslt/mal-opf.xsl' 39 | XSL_MAL_NCX='@DATADIR@/xslt/mal-ncx.xsl' 40 | YELP_JS_DIR = '@YELP_JS_DIR@' 41 | 42 | XSLCOMMON = (''' 43 | 44 | 45 | 46 | {includes} 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57 | 58 | C 59 | 60 | 61 | 62 | 63 | 64 | 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73 | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 |