Merge with main branch

2 files changed, 224 insertions, 3 deletions

diff --git a/docs/design/wiki.rst b/docs/design/wiki.rst
index 11b3058..e8ed1bf 100644
--- a/docs/design/wiki.rst
+++ b/docs/design/wiki.rst
@@ -250,8 +250,8 @@ Here's where we want the files to end up in a typical Linux distribution:
 ==  ====================================  ===================================================================================================
 1   mailman/database/schemas/blah.schema  /var/mailman/schemas/blah.schema
 2   some.tpl                              /var/mailman/templates/some.tpl
-3   path/to/some.tpl                      /var/mailman/templates/path/to/some.tpl
-4   mailman/database/mailman.db           /var/mailman/database/mailman.db
+3   path/to/some.tpl                      /var/mailman/templates/path/to/some.tpl !
+4   mailman/database/mailman.db           /var/mailman/database/mailman.db !
 5   developer-docs/index.txt              /usr/share/doc/mailman/developer-docs/index.txt
 6   developer-docs/api/toc.txt            /usr/share/doc/mailman/developer-docs/api/toc.txt
 7   README                                /usr/share/doc/mailman/README
@@ -259,7 +259,7 @@ Here's where we want the files to end up in a typical Linux distribution:
 9   mailman/foo/some/path/bar/my.cfg      /etc/mailman/baz/some/path/bar/my.cfg AND
                                           /etc/mailman/hmm/some/path/bar/my.cfg + 
                                           emit a warning
-10  mailman/foo/some/path/other.cfg       /etc/mailman/some/path/other.cfg
+10  mailman/foo/some/path/other.cfg       /etc/mailman/some/path/other.cfg !
 11  some-new-semantic.sns                 /var/funky/mailman/some-new-semantic.sns
 ==  ====================================  ===================================================================================================
 
diff --git a/docs/source/setupcfg.rst b/docs/source/setupcfg.rst
index d8d316b..68a37eb 100644
--- a/docs/source/setupcfg.rst
+++ b/docs/source/setupcfg.rst
@@ -149,6 +149,227 @@ Example::
     extra_files =
             setup.py
 
+data-files
+==========
+
+
+TODO :
+
+        ###
+        source -> destination
+        
+        final-path = destination + source
+        
+        There is an {alias} for each categories of datafiles
+        -----
+        source may be a glob (*, ?, **, {})
+        
+        order
+        
+        exclude
+        --
+        base-prefix
+        
+        ####
+        overwrite system config for {alias}
+        
+        ####
+        extra-categories
+
+This section describes the files used by the project which must not be installed in the same place that python modules or libraries.
+
+The format for specifing data files is :
+
+ **source** = **destination**
+ 
+Example::
+
+    scripts/script1.bin = {scripts}
+    
+It means that the file scripts/script1.bin will be placed 
+
+It means that every file which match the glob_syntax will be placed in the destination. A part of the path of the file will be stripped when it will be expanded and another part will be append to the destination. For more informations about which part of the path will be stripped or not, take a look at next sub-section globsyntax_.
+
+The destination path will be expanded at the installation time using categories's default-path in the sysconfig.cfg file in the system. For more information about categories's default-paths, take a look at next next sub-section destination_.
+
+
+.. _globsyntax:
+
+glob_syntax
+-----------
+
+The glob syntax is traditionnal glob syntax (with unix separator **/**) with one more information : what part of the path will be stripped when path will be expanded ?
+
+The special character which indicate the end of the part that will be stripped and the beginning of the part that will be added is whitespace, which can follow or replace a path separator.
+
+Example::
+
+    scripts/ *.bin
+    
+is equivalent to::
+
+    scripts *.bin
+
+Theses examples means that all files with extensions bin in the directory scripts will be placed directly on **destination** directory.
+
+This glob example::
+
+    scripts/*.bin
+    
+means that all files with extensions bin in the directory scripts will be placed directly on **destination/scripts** directory.
+
+.. _destination:
+
+destination
+-----------
+
+The destination is a traditionnal path (with unix separator **/**) where some parts will be expanded at installation time. These parts look like **{category}**, they will be expanded by reading system-wide default-path stored in sysconfig.cfg. Defaults categories are :
+
+* config
+* appdata
+* appdata.arch
+* appdata.persistent
+* appdata.disposable
+* help
+* icon
+* scripts
+* doc
+* info
+* man
+
+A special category exists, named {distribution.name} which will be expanded into your distribution name. You should not use it in your destination path, as they are may be used in defaults categories::
+
+    [globals]
+    # These are the useful categories that are sometimes referenced at runtime,
+    # using pkgutil.open():
+    # Configuration files
+    config = {confdir}/{distribution.name}
+    # Non-writable data that is independent of architecture (images, many xml/text files)
+    appdata = {datadir}/{distribution.name}
+    # Non-writable data that is architecture-dependent (some binary data formats)
+    appdata.arch = {libdir}/{distribution.name}
+    # Data, written by the package, that must be preserved (databases)
+    appdata.persistent = {statedir}/lib/{distribution.name}
+    # Data, written by the package, that can be safely discarded (cache)
+    appdata.disposable = {statedir}/cache/{distribution.name}
+    # Help or documentation files referenced at runtime
+    help = {datadir}/{distribution.name}
+    icon = {datadir}/pixmaps
+    scripts = {base}/bin
+    
+    # Non-runtime files.  These are valid categories for marking files for
+    # install, but they should not be referenced by the app at runtime:
+    # Help or documentation files not referenced by the package at runtime
+    doc = {datadir}/doc/{distribution.name}
+    # GNU info documentation files
+    info = {datadir}/info
+    # man pages
+    man = {datadir}/man
+
+So, if you have this destination path : **{help}/api**, it will be expanded into **{datadir}/{distribution.name}/api**. {datadir} will be expanded depending on your system value (ex : confdir = datadir = /usr/share/).
+
+
+Simple-example
+--------------
+
+Source tree::
+
+  babar-1.0/
+    README
+    babar.sh
+    launch.sh
+    babar.py
+    
+Setup.cfg::
+
+  [RESOURCES]
+  README = {doc}
+  *.sh = {scripts}
+  
+So babar.sh and launch.sh will be placed in {scripts} directory.
+
+Now let's create to move all the scripts into a scripts/directory.
+
+Second-example
+--------------
+
+Source tree::
+
+  babar-1.1/
+    README
+    scripts/
+      babar.sh
+      launch.sh
+      LAUNCH
+    babar.py
+    
+Setup.cfg::
+
+  [RESOURCES]
+  README = {doc}
+  scripts/ LAUNCH = {scripts}
+  scripts/ *.sh = {scripts}
+  
+It's important to use the separator after scripts/ to install all the bash scripts into {scripts} instead of {scripts}/scripts.
+
+Now let's add some docs.
+
+Third-example
+-------------
+
+Source tree::
+
+  babar-1.2/
+    README
+    scripts/
+      babar.sh
+      launch.sh
+      LAUNCH
+    docs/
+      api
+      man
+    babar.py
+
+Setup.cfg::
+
+  [RESOURCES]
+  README = {doc}
+  scripts/ LAUNCH = {doc}
+  scripts/ *.sh = {scripts}
+  doc/ * = {doc}
+  doc/ man = {man}
+  
+You want to place all the file in the docs script into {doc} category, instead of man, which must be placed into {man} category, we will use the order of declaration of globs to choose the destination, the last glob that match the file is used.
+
+Now let's add some scripts for windows users.
+  
+Final example
+-------------
+
+Source tree::
+
+  babar-1.3/
+    README
+    doc/
+      api
+      man
+    scripts/  
+      babar.sh
+      launch.sh
+      babar.bat
+      launch.bat
+      LAUNCH
+
+Setup.cfg::
+
+  [RESOURCES]
+  README = {doc}
+  scripts/ LAUNCH = {doc}
+  scripts/ *.{sh,bat} = {scripts}
+  doc/ * = {doc}
+  doc/ man = {man}
+
+We use brace expansion syntax to place all the bash and batch scripts into {scripts} category.    
 
 command sections
 ================