This file describes the development environment for Texinfo. Copyright 2002-2019 Free Software Foundation, Inc. Copying and distribution of this file, with or without modification, are permitted in any medium without royalty provided the copyright notice and this notice are preserved. The development sources for GNU Texinfo are available through git at Savannah: https://savannah.gnu.org/git/?group=texinfo This distribution uses whatever versions of Automake, Autoconf, and Gettext are listed in NEWS; usually the latest official releases. If you are getting the sources from the development repository (or change configure.ac), you'll need to have these tools installed to (re)build. You'll also need help2man. If you modify texindex/ti.twjr, you'll need gawk >= 4.0. All of these programs are available from http://ftp.gnu.org/gnu. After getting the development sources, and installing the tools above, you can run ./autogen.sh and then, for example, ./configure -C CFLAGS='-g -Wdeclaration-after-statement' and then make The -C tells configure to cache test results, which usually speeds things up a bit. That particular -W is useful because a) intermixing declarations with statements is an easy thing to do accidentally, b) gcc doesn't warn about it by default, and c) other compilers that don't support it are still widespread. If you're not using gcc, of course you shouldn't specify that option. Other -W options can be useful too, and patches are welcome to resolve diagnostics; however, removing all possible warning messages, or warnings with nonfree compilers, is explicitly not a goal. After the initial autogen && configure, simply running make should suffice. Gettext or help2man not installed do not cause configure to fail, though configure shows if they were found. This is because a release does not require those tools. Indeed, both prerequisites and result files are shipped in a release, such that the tools are only needed if the prerequisite changed. The tools are needed when building from developpement sources, however, as result files are not under version control. Make will fail with an explicit missing command for help2man, and with a command not found error for a Gettext utility command. Running make in one particular subdirectory is possible, for example make -C info. However there are interdependencies between the subdirectories, notably on gnulib, so if you don't want to run "make", you may have to run "make -C gnulib/lib" first. Additionally, make dist may not work until make has been run at least once, because of rules to create man pages under the man/ directory. "make dist" will fail if the use of Perl XS extension modules is disabled and there is no Makefile in the XSParagraph subdirectory. Gnulib ------ This distribution also uses Gnulib (http://www.gnu.org/software/gnulib) to share common files. Gnulib files used in Texinfo are checked in to the repository. If you get automake/conf/etc. errors from ./autogen.sh, please try getting a checkout of gnulib (in a separate directory from the texinfo checkout), and then run, say, ../gnulib/gnulib-tool --add-import in your top-level Texinfo directory. (gnulib-tool is in the gnulib source tree.) The currently-used gnulib modules and other gnulib information are recorded in gnulib/m4/gnulib-cache.m4. Given a source checkout of gnulib, you can update the files with gnulib-tool --add-import. When running gnulib-tool --add-import or otherwise adding modules, it is necessary to check what files were added or removed (e.g., run "git status -u") and add new files to the repository with "git add". Add any new generated files (typically gnulib/lib/foo.h from foo.h.in) to the ignore list in .gitignore. Subdirectories in repository ---------------------------- In addition to the subdirectories listed in README, there is the following directory in the source control repository: js/ - Work on enhanced browsing of HTML manuals with JavaScript About running the Texinfo programs from a development source tree: - Once the distribution is built, you can run the compiled programs (info, install-info) out of the build tree without special settings; they don't try to read any installed data files. - The texi2dvi script and texinfo.tex can be run as-is, since they are standalone and don't require compilation. For the same reasons, they are officially updated between full Texinfo releases, at http://ftpmirror.gnu.org/texinfo. - Regarding texi2any (aka makeinfo), you can run tp/texi2any.pl directly. This is the original source file for the program, so it's convenient to be able to make changes and then run it. To run the output "tp/texi2any" instead, you can set the environment variable TEXINFO_DEV_SOURCE to 1. Otherwise, it will try to use Texinfo's Perl modules in the installed locations. "tp/texi2any" uses the Perl interpreter found by configure, so you might want to run that instead of texi2any.pl if it's different to the default interpreter in your environment. References for working on various parts of the system: If you want to delve into making a new backend for the Perl makeinfo, the documentation in tp/Texinfo/Convert/Converter.pm is a good starting point, as it describes the existing backends and other places to look. If you want to delve into texinfo.tex, a thorough plain TeX reference is available under the GFDL: TeX by Topic - http://www.eijkhout.net/texbytopic/texbytopic.html Another book on plain TeX, also available under the GFDL, is a GNU package: TeX for the Impatient - http://www.gnu.org/software/teximpatient/ Occasionally you may need to know about the details of the PDF format. A reference for this is the PDF reference, Sixth Edition, version 1.7, downloadable at http://www.adobe.com/devnet/pdf/pdf_reference_archive.html The texindex program is implemented using the TexiWebJR literate programming system, combining Texinfo and Awk (https://github.com/arnoldrobbins/texiwebjr). Running "make ti.pdf" in the texindex/ subdirectory creates the printable form of the program. All the usual Texinfo output formats are possible. Steps for making a release (pretest or official): - When close to official release: check at latest automake/autoconf/gettext version, and mention in NEWS (to upgrade gettext, run gettextize -f --po-dir=po --po-dir=po_document after installing new version of gettext) special pleading with bug-texinfo / beebe / platform-testers to try. check OpenCSW build reports at https://buildfarm.opencsw.org/buildbot/waterfall?category=texinfo try groff.texinfo from groff source repo. process doc/texinfo-tex-test.texi with TeX and check that output is good. - First checks: Ensure texinfo.tex, texi2dvi, and htmlxref.cnf are updated on ftp.gnu.org. Ensure TXI_XLATE in doc/Makefile.am matches actual file list. Check that LINGUAS under po and po_document match actual file list. Have a look at the output of "git status -u" to check for files that should be tracked in git or ignored. Check that TEXINFO_DTD_VERSION has been updated to the next version in configure.ac if the DTD has been modified since the last release. See comments in configure.ac, and run (at the top level) make dtd-check. Check "make ccheck" and "make vcheck" work in "doc/refcard". Check "dist-xz" is in the option list in configure.ac (often removed for speed when testing). Update copyright years in many files for release; best to grep -r for the previous year. See also ChangeLog entries for "copyright years". No need (though it's ok) to change every source file at once, just the ones relevant to --version calls, etc., such as texindex.awk and info.c. make po-check # update po/POTFILES.in as needed check for C compiler warnings by configuring with -Wall (not all have to be fixed) # Under the top level, and also under tp/Texinfo/XS, which uses # a separate gnulib import. gnulib-tool --add-import util/srclist-txi # for pretest, to sync files with other sources - Official releases only: version and date in NEWS. version number in texi2dvi, texi2pdf, txirefcard.tex. (cd tp && maintain/regenerate_documentlanguages.pl) -- regenerates tp/Texinfo/Documentlanguages.pm make V=1 pdf and fix underfull/overfull boxes. - Changes to sources: update version in configure.ac, notice in ChangeLog. (cd tp && ./maintain/change_perl_modules_version.sh auto) -- this updates all the version numbers in the Perl modules check that texindex version is updated properly (rm texindex.awk ; make) Check that translations have been updated, e.g.: rsync -Lrtzv translationproject.org::tp/latest/texinfo/ po rsync -Lrtzv translationproject.org::tp/latest/texinfo_document/ \ po_document # note the trailing slashes in these commands make make update-po # both po and po_document needed, build a dist first TEXINFO_XS_PARSER=1 make distcheck # to check XS parser is good (export MALLOC_CHECK_=2; make distcheck) # repeat until clean git commit and push - To do the actual upload: pkg=texinfo ver=6.0 then do one of: gnupload --to alpha.gnu.org:$pkg $pkg-$ver.tar.xz #pretest gnupload --to ftp.gnu.org:$pkg $pkg-$ver.tar.{gz,xz} *.diff.xz #official Use --user option if not using default key texinfo.tex and texi2dvi should already be up to date, but check. Use gnupload --replace --to ftp.gnu.org:texinfo texi2dvi # Official releases only: tag source tree git tag texinfo-6.6 git push --tags # ... set up dtd directory on web pages: cd $HOME/gnu/www/texinfo/dtd # or wherever webpages checkout is mkdir $ver && cvs add $ver cp $tutil/texinfo.dtd $ver cvs add -kb $ver $ver/texinfo.dtd cvs commit -m$ver $ver # ... make diffs at official release: prev=5.2 ver=6.0 tar xf texinfo-$ver.tar.gz tar xf texinfo-$prev.tar.gz diff -Nrc2 texinfo-$prev texinfo-$ver | xz >texinfo-$prev-$ver.diff.xz ls -l !$ gnupload --to ftp.gnu.org:texinfo !$ - When official release is out there ... update home page (texinfo.html) and commit as needed. including: pod2html $txi/Pod-Simple-Texinfo/pod2texi.pl \ | fgrep -v 'rev="made"' >manual/pod2texi.html Build web documentation with make -C doc wwwdoc-build Copy documentation files to web checkout with, e.g. make -C doc \ wwwdoc-install www_target=../../TEXINFO_WEB_PAGES/texinfo/manual/ Check for removed files with, e.g. ls -ltu $(www_target)/*/html_node, followed by cvs rm -f. Likewise, check for added files with cvs -qn update, followed by cvs add. When done, run cvs commit. # Official releases only: Contact root@tug.org to update texinfo at tug.org # For pretest release, send announcement to bug-texinfo and bcc coordinator@translationproject.org. # For official releases: send announcement to info-gnu, cc bug-texinfo and bcc coordinator@translationproject.org. news item at savannah. # ... post-release, or when development resumes: configure.ac, util/texi2dvi: add "dev" to versions for clarity, until it's time to do pretests again.