"Fossies" - the Fresh Open Source Software Archive

Member "texinfo-6.5/README-hacking" (23 Jun 2017, 11616 Bytes) of package /linux/misc/texinfo-6.5.tar.xz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file. See also the latest Fossies "Diffs" side-by-side code changes report for "README-hacking": 6.4_vs_6.5.

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