README-maint: renamed for consistency

1 files changed, 106 insertions, 0 deletions

diff --git a/README-maint b/README-maint
new file mode 100644
index 0000000..c0546ab
--- /dev/null
+++ b/README-maint
@@ -0,0 +1,106 @@
+#+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.