README-hacking 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295
  1. $Id$
  2. This file describes the development environment for Texinfo.
  3. Copyright 2002, 2003, 2005, 2006, 2007, 2008, 2010, 2011, 2012, 2013,
  4. 2014, 2015, 2016 Free Software Foundation, Inc.
  5. Copying and distribution of this file, with or without modification,
  6. are permitted in any medium without royalty provided the copyright
  7. notice and this notice are preserved.
  8. The development sources for GNU Texinfo are available through anonymous
  9. Subversion at Savannah:
  10. http://savannah.gnu.org/svn/?group=texinfo
  11. This distribution uses whatever versions of Automake, Autoconf, and
  12. Gettext are listed in NEWS; usually the latest official releases. If
  13. you are getting the sources from the development repository (or change
  14. configure.ac), you'll need to have these tools installed to (re)build.
  15. You'll also need help2man. If you modify texindex/ti.twjr, you'll need
  16. gawk >= 4.0. All of these programs are available from
  17. http://ftp.gnu.org/gnu.
  18. After getting the development sources, and installing the tools above,
  19. you can run
  20. ./autogen.sh
  21. and then, for example,
  22. ./configure -C CFLAGS='-g -Wdeclaration-after-statement'
  23. and then
  24. make
  25. After the initial autogen && configure, simply running make should suffice.
  26. The -C tells configure to cache test results, which usually speeds
  27. things up a bit.
  28. That particular -W is useful because a) intermixing declarations with
  29. statements is an easy thing to do accidentally, b) gcc doesn't warn
  30. about it by default, and c) other compilers that don't support it are
  31. still widespread. If you're not using gcc, of course you shouldn't
  32. specify that option.
  33. Other -W options can be useful too, and patches are welcome to resolve
  34. diagnostics; however, removing all possible warning messages, or
  35. warnings with nonfree compilers, is explicitly not a goal.
  36. Running make in one particular subdirectory is possible, for example
  37. make -C info. However there are interdependencies between the
  38. subdirectories, notably on gnulib, so if you don't want to run "make",
  39. you may have to run "make -C gnulib/lib" first.
  40. Additionally, make dist may not work until make has been run at least
  41. once, because of rules to create man pages under the man/ directory.
  42. "make dist" will fail if the use of Perl XS extension modules is
  43. disabled and there is no Makefile in the XSParagraph subdirectory.
  44. Gnulib
  45. ------
  46. This distribution also uses Gnulib (http://www.gnu.org/software/gnulib)
  47. to share common files. Gnulib files used in Texinfo are checked in to
  48. the repository. If you get automake/conf/etc. errors from ./autogen.sh,
  49. please try getting a checkout of gnulib (in a separate directory from
  50. the texinfo checkout), and then run, say,
  51. ../gnulib/gnulib-tool --add-import
  52. in your top-level Texinfo directory.
  53. (gnulib-tool is in the gnulib source tree.)
  54. The currently-used gnulib modules and other gnulib information are
  55. recorded in gnulib/m4/gnulib-cache.m4. Given a source checkout of
  56. gnulib, you can update the files with gnulib-tool --add-import.
  57. When running gnulib-tool --add-import or otherwise adding modules, it is
  58. necessary to check what files were added (e.g., run "svn status
  59. build-aux gnulib") and add them to the repository with "svn add";
  60. likewise for removals, likewise for adding new generated files
  61. (typically gnulib/lib/foo.h from foo.h.in) to the ignore list (e.g.,
  62. svn propedit svn:ignore gnulib/lib).
  63. Subdirectories in repository
  64. ----------------------------
  65. In addition to the subdirectories listed in README, there are these
  66. directories in the source control repository:
  67. makeinfo/ - Implementation of makeinfo in C, distributed before version 5.0
  68. texi2html/ - Perl program to generate HTML from Texinfo, superseded by texi2any
  69. About running the Texinfo programs from a development source tree:
  70. - Once the distribution is built, you can run the compiled programs
  71. (info, install-info) out of the build tree without special settings;
  72. they don't try to read any installed data files.
  73. - The texi2dvi script and texinfo.tex can be run as-is, since they
  74. are standalone and don't require compilation. For the same reasons,
  75. they are officially updated between full Texinfo releases, at
  76. http://ftpmirror.gnu.org/texinfo.
  77. - Regarding texi2any (aka makeinfo), you can run tp/texi2any.pl
  78. directly. This is the original source file for the program, so it's
  79. convenient to be able to make changes and then run it.
  80. To run the output "tp/texi2any" instead, you can set the environment
  81. variable TEXINFO_DEV_SOURCE to 1. Otherwise, it will try to use
  82. Texinfo's Perl modules in the installed locations. "tp/texi2any" uses
  83. the Perl interpreter found by configure, so you might want to run that
  84. instead of texi2any.pl if it's different to the default interpreter in
  85. your environment.
  86. References for working on various parts of the system:
  87. If you want to delve into making a new backend for the Perl makeinfo,
  88. the documentation in tp/Texinfo/Convert/Converter.pm is a good starting
  89. point, as it describes the existing backends and other places to look.
  90. If you want to delve into texinfo.tex, a thorough plain TeX reference
  91. is available under the GFDL:
  92. TeX by Topic - http://www.eijkhout.net/texbytopic/texbytopic.html
  93. Another book on plain TeX, also available under the GFDL, is a GNU package:
  94. TeX for the Impatient - http://www.gnu.org/software/teximpatient/
  95. Occasionally you may need to know about the details of the PDF format.
  96. A reference for this is the PDF reference, Sixth Edition, version 1.7,
  97. downloadable at http://www.adobe.com/devnet/pdf/pdf_reference_archive.html
  98. The texindex program is implemented using the TexiWebJR literate
  99. programming system, combining Texinfo and Awk
  100. (https://github.com/arnoldrobbins/texiwebjr). Running "make ti.pdf"
  101. in the texindex/ subdirectory creates the printable form of the
  102. program. All the usual Texinfo output formats are possible.
  103. Steps for making a release (pretest or official):
  104. - When close to official release:
  105. check at latest automake/autoconf/gettext version, and mention in NEWS
  106. (to upgrade gettext, run
  107. gettextize -f --po-dir=po --po-dir=po_document
  108. after installing new version of gettext)
  109. special pleading with bug-texinfo / beebe / platform-testers to try.
  110. check OpenCSW build reports at
  111. https://buildfarm.opencsw.org/buildbot/waterfall?category=texinfo
  112. try groff.texinfo from groff source repo.
  113. process doc/texinfo-tex-test.texi with TeX and check that output is good.
  114. - First checks:
  115. Ensure texinfo.tex, texi2dvi, and htmlxref.cnf are updated on ftp.gnu.org.
  116. Ensure TXI_XLATE in doc/Makefile.am matches actual file list.
  117. Check that LINGUAS under po and po_document match actual file list.
  118. Have a look at the output of "svn status ." to check for files that
  119. should be tracked in SVN or ignored.
  120. Check that TEXINFO_DTD_VERSION has been updated to the next version in
  121. configure.ac if the DTD has been modified since the last release.
  122. See comments in configure.ac, and run (at the top level) make dtd-check.
  123. Check "make ccheck" and "make vcheck" work in "doc/refcard".
  124. Check "dist-xz" is in the option list in configure.ac (often removed
  125. for speed when testing).
  126. Update copyright years in many files for release; best to grep -r for
  127. the previous year. See also ChangeLog entries for "copyright years".
  128. No need (though it's ok) to change every source file at once, just the
  129. ones relevant to --version calls, etc., such as texindex.awk and info.c.
  130. make po-check # update po/POTFILES.in as needed
  131. # Under the top level, and also under tp/Texinfo/Convert/XSParagraph, which
  132. # uses a separate gnulib import.
  133. gnulib-tool --add-import
  134. util/srclist-txi # for pretest, to sync files with other sources
  135. - Official releases only:
  136. version and date in NEWS.
  137. version number in texi2dvi, texi2pdf, txirefcard.tex.
  138. (cd tp && ./maintain/change_perl_modules_version.sh auto)
  139. -- this updates all the version numbers in the Perl modules
  140. (cd tp && maintain/regenerate_documentlanguages.pl)
  141. -- regenerates tp/Texinfo/Documentlanguages.pm
  142. make V=1 pdf and fix underfull/overfull boxes.
  143. - Changes to sources:
  144. update version in configure.ac, notice in ChangeLog.
  145. check that texindex version is updated properly
  146. (rm texindex.awk ; make)
  147. Check that translations have been updated, e.g.:
  148. rsync -Lrtzv translationproject.org::tp/latest/texinfo/ po
  149. rsync -Lrtzv translationproject.org::tp/latest/texinfo_document/ \
  150. po_document # note the trailing slashes in these commands
  151. pod2man Pod-Simple-Texinfo/pod2texi.pl >man/pod2texi.1 # until we fix deps
  152. check that the svn checkout is up-to-date (run "svnversion" and "svn update")
  153. make
  154. make update-po # both po and po_document needed, build a dist first
  155. (export MALLOC_CHECK_=2; make distcheck) # repeat until clean
  156. svn commit # when clean, then distcheck to be sure
  157. - To do the actual upload:
  158. pkg=texinfo
  159. ver=6.0
  160. then do one of:
  161. gnupload --to alpha.gnu.org:$pkg $pkg-$ver.tar.xz #pretest
  162. gnupload --to ftp.gnu.org:$pkg $pkg-$ver.tar.{gz,xz} *.diff.xz #official
  163. Use --user option if not using default key
  164. texinfo.tex and texi2dvi should already be up to date, but check. Use
  165. gnupload --replace --to ftp.gnu.org:texinfo texi2dvi
  166. # Official releases only: tag source tree (use your own username before @):
  167. svn copy -r 6363 -m'texinfo_6_0 tag based on r6363' \
  168. svn+ssh://gavin@svn.savannah.gnu.org/texinfo/trunk \
  169. svn+ssh://gavin@svn.savannah.gnu.org/texinfo/tags/texinfo_6_0
  170. [for karl: /srv/svn/texinfo]
  171. # ... set up dtd directory on web pages:
  172. cd $HOME/gnu/www/texinfo/dtd # or wherever webpages checkout is
  173. mkdir $ver && cvs add $ver
  174. cp $tutil/texinfo.dtd $ver
  175. cvs add -kb $ver $ver/texinfo.dtd
  176. cvs commit -m$ver $ver
  177. # If -kb is forgotten, CVS will do its own $Id expansion.
  178. # Recover by editing and committing a new version of texinfo.dtd in svn,
  179. # copying it again to the cvs dir, then:
  180. # cvs admin -kb texinfo.dtd; cvs update -A
  181. # (See the "How to store binary files" node in the CVS manual.)
  182. # ... make diffs at official release:
  183. prev=5.2
  184. ver=6.0
  185. cd $misc/archive/$pkg/prod
  186. tar xf $txi/texinfo-$ver.tar.gz
  187. tar xf texinfo-$prev.tar.gz
  188. diff -Nrc2 texinfo-$prev texinfo-$ver | xz >texinfo-$prev-$ver.diff.xz
  189. ls -l !$
  190. gnupload --to ftp.gnu.org:texinfo !$
  191. rm -rf texinfo-$ver texinfo-$prev
  192. ro texinfo-*$ver*
  193. - To save in local archives:
  194. pkg=texinfo
  195. ver=6.0
  196. mv -v $pkg-$ver.tar.xz* $misc/archive/$pkg/alpha/ #pretest
  197. mv -v $pkg-$ver.tar.{gz,xz}* *.diff.xz $misc/archive/$pkg/prod/ #official
  198. - When official release is out there ...
  199. update home page (texinfo.html) and commit as needed.
  200. including:
  201. pod2html $txi/Pod-Simple-Texinfo/pod2texi.pl \
  202. | fgrep -v 'rev="made"' >manual/pod2texi.html
  203. Build web documentation with
  204. make -C doc wwwdoc-build
  205. Copy documentation files to web checkout with, e.g.
  206. make -C doc \
  207. wwwdoc-install www_target=../../TEXINFO_WEB_PAGES/texinfo/manual/
  208. Check for removed files with, e.g. ls -ltu $(www_target)/*/html_node,
  209. followed by cvs rm -f. Likewise, check for added files with
  210. cvs -qn update, followed by cvs add. When done, run cvs commit.
  211. # Official releases only: ... update texinfo at tug.org
  212. # (contact root@tug.org):
  213. prev=6.0
  214. ver=6.1
  215. cd ~ftp/tex
  216. rm -rf texinfo-$prev*
  217. cp ~/texinfo-$ver.tar.{gz,xz} .
  218. tar xzf texinfo-$ver.tar.gz
  219. ln -s texinfo-$ver.tar.gz texinfo.tar.gz
  220. !!:gs/gz/xz
  221. relink texinfo $ver
  222. # For pretest release, send announcement to bug-texinfo and
  223. bcc coordinator@translationproject.org.
  224. # For official releases:
  225. send announcement to info-gnu,
  226. cc bug-texinfo and bcc coordinator@translationproject.org.
  227. news item at savannah.
  228. # ... post-release, or when development resumes:
  229. configure.ac, util/texi2dvi: add "dev" to versions for clarity,
  230. until it's time to do pretests again.
  231. # ... [personal for karl] move mail:
  232. mv ~/mail/txi.done $ver.mail
  233. bzip2 $ver.mail