summaryrefslogtreecommitdiff
path: root/macros/texinfo/texinfo/README-hacking
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /macros/texinfo/texinfo/README-hacking
Initial commit
Diffstat (limited to 'macros/texinfo/texinfo/README-hacking')
-rw-r--r--macros/texinfo/texinfo/README-hacking259
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.