diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/texinfo/texinfo/README-hacking |
Initial commit
Diffstat (limited to 'macros/texinfo/texinfo/README-hacking')
-rw-r--r-- | macros/texinfo/texinfo/README-hacking | 259 |
1 files changed, 259 insertions, 0 deletions
diff --git a/macros/texinfo/texinfo/README-hacking b/macros/texinfo/texinfo/README-hacking new file mode 100644 index 0000000000..a6062b2aa2 --- /dev/null +++ b/macros/texinfo/texinfo/README-hacking @@ -0,0 +1,259 @@ +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 + +After the initial autogen && configure, simply running make should suffice. + +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. + +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. |