#+TITLE: Autoconf Archive    -*- mode: org; coding: utf-8; fill-column: 79; -*-
#+STARTUP: hidestars odd

* Maintainer's Guide

*** How to check-out the 'maint' branch

    : git clone ssh://git.sv.gnu.org/srv/git/autoconf-archive
    : cd autoconf-archive
    : git checkout -b maint origin/maint
    : git submodule update -i

    : cvs -z3 -d:ext:cvs.savannah.nongnu.org:/web/autoconf-archive co -d html autoconf-archive

*** How to build the distribution.

    The build system depends on the following external packages:

    - Git (1.6.x.x or later)

    - Python (2.6 or later)

      Python 2.6 is needed for textwrap.TextWrapper break_on_hypens option only.
      This is being worked on decrease python version requirements.

    - Python StringTemplate Library: http://www.stringtemplate.org/

    - SCons (optional, but recommended): http://www.scons.org/

    - Pandoc: http://johnmacfarlane.net/pandoc/

      Pandoc is currently required for Markdown-to-HTML conversion. In
      future, this won't be necessary anymore, because StringTemplate can
      generate HTML directly just fine; there is no reason to go through
      Markdown as an intermediate format (except that I was too lazy so far).


* THINGS TO DO

*** TODO Document the newly mailing lists.

***** autoconf-archive-maintainers
***** autoconf-archive-commits
***** autoconf-archive-announce

*** TODO Figure out how to handle quoting in Markdown output

    Macro descriptions frequently contain words like "numeric_limits<T>", but
    in Markdown this is a literal HTML tag. The initial '<' character would
    need to be quoted.

    In indented blocks of text, however, use of the '<' character does not need
    to be quoted.

*** TODO Decide how to handle non-ASCII content in m4 files

   Several macros contain non-ASCII characters, for example:

   : $ grep@ Ludo m4/*.m4
   : m4/_ac_c_ifdef.m4:#   Copyright (c) 2008 Ludovic Courtès <ludo@chbouib.org>
   : m4/ac_cxx_compiler_vendor.m4:#   Copyright (c) 2008 Ludovic Courtès <ludo@chbouib.org>
   : m4/ac_cxx_cppflags_std_lang.m4:#   Copyright (c) 2008 Ludovic Courtès <ludo@chbouib.org>
   : m4/ac_cxx_cxxflags_std_lang.m4:#   Copyright (c) 2008 Ludovic Courtès <ludo@chbouib.org>
   : m4/ac_cxx_ldflags_std_lang.m4:#   Copyright (c) 2008 Ludovic Courtès <ludo@chbouib.org>
   : m4/ac_libtoolize_cflags.m4:#   Copyright (c) 2008 Ludovic Courtès <ludo@chbouib.org>

   The encoding currently in use is "latin1", but the m4 files don't expose
   that information. The situation can be improved as follows:

   1) Add machine-readable charset declarations (i.e. for Emacs) to all m4
      files. (Or just to those that actually use non-ASCII?)

   2) Encode all files in UTF-8, like everyone else seems to do. (But add
      charset declarations anyway?)

   3) Restrict m4 files to ASCII.

   Pure ASCII is my favorite.

*** TODO Improve submission guide lines on the web site

***** New submissions should use an AX_ prefix.

      Other prefixes are fine, too, but use of AX_ inside of the Autoconf
      Archive is encouraged. The AC_ prefix should definitely be avoided,
      because it's reserved for the GNU Autoconf distribution.

***** Patch submissions should put the original authors on Cc.

      Everyone is welcome to submit patches, bug reports, or suggestions to the
      Autoconf Archive. If you do, please add the original authors to
      carbon-copy list in the patch tracker. You don't have to, if you don't
      want to look their addresses up, but it's considered good practice to
      give the other authors a heads up when the macro is being changed.

***** If possible, submit patches with Git.

      Give a usage example for git format-patch.

      If you have an account Savannah, simply request access to the Autoconf
      Archive's repository so that you can use git push.

*** TODO Customize quoting function

    String templates can be registered with a quoting function that adapts the
    generated output for a target format, i.e. HTML.