Copyright 2002-2023 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 See also files: tp/README, tp/t/README, tp/tests/README, TODO, TODO.HTML Development tools ----------------- 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' PERL_EXT_CFLAGS='-g' and then make The -C tells configure to cache test results, which usually speeds things up a bit. 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, however, when building from development sources, 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 XS subdirectory. Using git --------- This section is if you have write access to the git repository. Usually commits to the git repository should include a ChangeLog entry. Please follow the existing style (the GNU Coding Standards has a guide). You can automatically use the contents of the most recent ChangeLog entry with a git commit hook .git/hooks/prepare-commit-msg ------------------------------------ #!/bin/sh # $1 - file that contains commit log message # $2 - source of commit message outfile="$1" case $2 in message|template|merge|squash|commit) ;; *) # Use latest ChangeLog entry as commit message sed -n -e '1,/^\w*$/d' -e '/^[^ ]/q' -e '{s/^ //;p}' ChangeLog >"$outfile" ;; esac ------------------------------------ When unable to push commits due to other commits being made, please use "git pull --rebase" (the default for "git pull" complicates the git history). To deal with conflicts in the ChangeLog, you should install the git-merge-changelog program. You can get better output from "git diff" for Texinfo files by putting the following section in your .gitconfig file: [diff "texinfo"] xfuncname = "^(@node .*)$" This shows which node each change occurred in. Gnulib ------ This distribution uses Gnulib (http://www.gnu.org/software/gnulib) to share common files. Gnulib files used in Texinfo are checked in to the repository. A Gnulib directory is setup in two locations, in the main directory and in tp/Texinfo/XS/. To update the gnulib files, get a checkout of gnulib in a separate directory, then run, say ../gnulib/gnulib-tool --add-import in your top-level Texinfo directory and ../../../../gnulib/gnulib-tool --add-import under tp/Texinfo/XS. (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. gnulib-tool --add-import may also be used to add another gnulib module: ../gnulib/gnulib-tool --add-import other_gnulib_module After 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. When adding new modules, or sometimes even just when upgrading gnulib, it may be necessary to update the LDADD variables in info/Makefile.am or install-info/Makefile.am. Check for any unfamiliar Makefile variables in the output of "gnulib-tool --add-import", and work out which program needs them. You can look at the modules/* files in the gnulib checkout to help work out which gnulib module is demanding which variable. For the gnulib checkout in the XS directory, it is just tp/Texinfo/XS/Makefile.am that may need to be updated. Subdirectories in repository ---------------------------- In addition to the subdirectories listed in README, there is the following directory in the source control repository: infog/ - HTML-Info reader using WebKitGTK library Finally, the contrib/ directory contains additional files from users provided for your reading and/or hacking pleasure. They aren't part of Texinfo proper or maintained by the Texinfo developers. 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. - Updating copyright years in files It may be simplest just to update them all at once. First, look for lone copyright years: find . -type f \ \( -name '*' \) \ -not -name 'Makefile.in' \ -execdir perl -wnl -e '/ 20\d\d Free/ && print "$ARGV:$_"' '{}' \; Adjust list of files as necessary, adding or excluding names. (Note that program help messages should only have a single year.) Once you are happy with the list of files, can update lone years to ranges with by changing the -execdir argument: find . -type f \ \( -name '*' \) \ -not -name 'Makefile.in' \ -execdir \ perl -wpli -e 's/( 20\d\d) Free/$1-2023 Free/' '{}' \; Then use a similar approach to update copyright ranges: find . -type f \( -name '*.c' -o -name '*.pm' -o -name '*.h' \ -o -name '*.sh' -o -name Makefile.am \) \ -execdir perl -wpli -e 's/-20\d\d Free/-2023 Free/' '{}' \; Run git diff after each tranche of files to check the changes, followed by git add. Look for omissions and anomalies by running, e.g. find . \ -name autom4te.cache -prune -o \ -name .git -prune -o \ -wholename ./tp/maintain/lib -prune -o \ -name test -prune -o \ -type f \ \( -name '*' \) \ -not -name 'Makefile.in' \ -not -name Makefile \ -not -name "*.m4" \ -not -name configure \ -not -name "config.*" \ -not -name "*~" \ -exec perl -wnl -e '/20\d[^3] Free/ && print "$ARGV:$_"' '{}' \; at the top level. (We should automate this process in the future.) - When close to making a release: NYTProf profiling for Perl code * e.g. 'perl -d:NYTProf ../tp/texi2any.pl FILE.texi'. See Devel::NYTProf man page. callgrind profiling for XS code * e.g. 'LD_BIND_NOW=1 valgrind --tool=callgrind perl ../tp/texi2any.pl \ FILE.texi' then 'kcachegrind callgrind.out.*'. run all tests with valgrind: * under info/t, put valgrind in $ginfo, then check t/*.val.log files after running test suite * edit install-info/tests/defs.in, uncomment valgrind line and run config.status to regenerate defs * XS modules memory leak check checking with valgrind Add line "use Perl::Destruct::Level level => 1;" to texi2any.pl when running 'valgrind --leak-check=full' to make perl clean it its allocations. Run e.g. valgrind --log-file=val.log --leak-check=full \ perl ../tp/texi2any.pl ../doc/info-stnd.texi and other input files. Add line "use Perl::Destruct::Level level => 1;" to t/test_utils.pl Check tests with e.g. for f in t/*.t ; do valgrind --log-file=val.log-${f#t/} --leak-check=full \ perl -w $f ; done (could take 1-2 hours to finish). check log files one by one afterwards. Manual testing: . try groff.texinfo from groff source repo. . process doc/texinfo-tex-test.texi with TeX and check that output is good. . process some manuals with INFO_JS_DIR and check the JS interface is not broken. check for C compiler warnings by configuring with our_CFLAGS='-Wall -Wno-parentheses -Wno-missing-braces' ./configure "CFLAGS=$our_CFLAGS" "PERL_EXT_CFLAGS=$our_CFLAGS" unset our_CFLAGS Not all compiler warnings have to be fixed, though. check if po_document/adjust_translations.pl script is still needed (check progress of translations at , and check whether script is working as intended.) check at latest automake/autoconf/gettext/help2man version: . to upgrade gettext, run gettextize -f --po-dir=po --po-dir=po_document after installing new version of gettext. (check that this does not actually downgrade files due to files also being updated from gnulib --add-import) . (note upgrade to gettext 0.22 is stalled - see https://lists.gnu.org/archive/html/bug-gettext/2023-07/msg00008.html) . After upgrading automake/autoconf/gettext, run ./autogen.sh and/or "autoreconf --verbose --force --install" to update ancilliary files in build-aux and elsewhere. Check changes before committing. . mention new versions in NEWS Update gnulib: # Under the top level, and also under tp/Texinfo/XS, which uses # a separate gnulib import. gnulib-tool --add-import 'git status -u' and add untracked files Use util/srclist-txi for checking files to be copied from gnulib make po-check # update po/POTFILES.in as needed make po_document-check # update po_document/POTFILES.in as needed check indices of Texinfo manuals and check for duplicates (with <1> in Info) Check "make ccheck" and "make vcheck" work in "doc/refcard". - Official releases only: make V=1 pdf and fix underfull/overfull boxes. ------------------------------------------------------------------------- - Final steps for making a release (Keep a copy of README-hacking open in a text editor to update these release instructions.) Check on correct branch (master or release/*) and rebuild. ./autogen.sh ; ./configure ; make Have a look at the output of "git status -u" to check for files that should be tracked in git or ignored. Check for leftover result files under tp/tests which should be removed. check "git stash list" for any work in progress Check if "make tex-html-checks" results have been updated under tp/tests. check OpenCSW build reports at https://buildfarm.opencsw.org/buildbot/waterfall?category=texinfo (for master branch only) 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 "dist-xz" is in the option list in configure.ac (often removed for speed when testing). Update version number: update version number in configure.ac, util/texi2dvi, util/texi2pdf, js/info.js version number in txirefcard.tex (offical releases only) (cd texindex ; rm texindex.awk ; make) (cd tp && ./maintain/change_perl_modules_version.sh auto) -- this updates all the version numbers in the Perl modules check up to date copyright years in files relevant to --version calls (tp/texi2any.pl, info/info.c, install-info/install-info.c, texindex/ti.twjr, Pod-Simple-Texinfo/pod2texi) Ensure texinfo.tex, htmlxref.cnf are updated on ftp.gnu.org. Upload texi2dvi, texi2pdf (official releases only) (cd tp ; maintain/regenerate_file_lists.pl) # list all test results For release/7.0 series only - need to update result of test_scripts/layout_formatting_epub_nodes.sh test (delete this note once we are on release/7.1) Update translations: 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 git status -u to check for new translations Ensure TXI_XLATE in doc/Makefile.am matches actual file list. Check that LINGUAS under po and po_document match actual file list. make make update-po # both po and po_document needed, build a dist first ( cd po_document ; for f in *.po ; do ./adjust-translations.pl $f ; done ) - Official releases only: version and date in NEWS. (cd tp && maintain/regenerate_documentlanguages-loc.pl) -- regenerates tp/Texinfo/Documentlanguages.pm (requires Text::CSV) notice in ChangeLog. one last "git diff" to check release commit looks good make distcheck (export MALLOC_CHECK_=2; make distcheck) # repeat until clean git commit and push (If on a release branch, copy the NEWS message to NEWS on master) ------------------------------------------------------------------------- - To do the actual upload: pkg=texinfo ver=7.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 gnupload --replace --to ftp.gnu.org:texinfo texi2dvi #official gnupload --replace --to ftp.gnu.org:texinfo texi2pdf #official (Use --user option if not using default key) pretest announcement -> bug-texinfo / beebe / platform-testers to try. bcc coordinator@translationproject.org. For official releases: send announcement to info-gnu, cc bug-texinfo and bcc coordinator@translationproject.org. news item at savannah. # 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 ------------------------------------------------------------------------- - When official release is out there ... update home page (texinfo.html) and commit as needed. including: pod2html $txi/Pod-Simple-Texinfo/pod2texi.pl \ | grep -Fv 'rev="made"' >manual/pod2texi.html Make sure texi2any and texinfo.tex are both installed, then 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=../../CVS_WEB/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. # If root@tug.org doesn't reply, can try webmaster@tug.org, # or (last resort) board@tug.org. # ... post-release, or when development resumes: configure.ac, util/texi2dvi: add "dev" to versions for clarity, until it's time to do pretests again.