Improve code translating chapter / section titles to filenames

[fingolfin]

The documentation for @chapter and @section should state explicitly that : and \ are not allowed in them.

[sebasguts]

Does this depent on the operation system? Maybe we should write something like: Those names are used for filenames, only put suitable characters in it.

[fingolfin]

Aha, I see -- I thought the error was caused by AutoDoc, but it isn't:

Generating documentation in Directory("/Users/mhorn/Projekte/GAP/repos/pkg/SingularInterface/doc/")
Error, <name> must not contain '\' or ':' called from
Filename( arg[1], arg[2] ) called from
AUTODOC_OutputTextFile( path_to_xmlfiles, filename ) called from
WriteDocumentation( i, stream, path_to_xmlfiles ); called from
WriteDocumentation( tree, doc_dir ); called from
<function "AutoDoc">( <arguments> )
 called from read-eval loop at line 23 of makedoc.g
you can 'quit;' to quit to outer loop, or
you can 'return;' to continue

So the real problem is that chapter names etc. are used as filenames. And indeed, what constitutes a valid filename is operating system dependant. On Mac OS X, colons are not allowed; using slashes and backslashes is a bad idea in general, too. Instead of a black list, I'd recommend using a whitelist: I.e. specifying a list of characters that are known to work everywhere, and restrict to those.

But this should not translate into a restriction of what the user may use as chapter titles! So there should be a function which takes a chapter titles, and "mangles" it into a valid filename. We probably already have such a function (which translates spaces into underscores?). This function should simply remove any characters outside a certain set. Ffor starters, perhaps just allow A-Z, a-z, 0-9, _, -, +

Other characters can cause all kinds of problems. E.g. white space could in principle be used, but in HTML links should then be replaced by %20; *, !, \ have special meaning in bash; non-ASCII chars may cause more cross-platform problems; etc.