[CALL FOR REVIEW] doc and www converted to XML

[Gabor Kovesdan]

Em 29-08-2012 15:10, Hiroki Sato escreveu:
> 1. Convert ids to upper-case and use them.  No compatibility
> problem.
> 
> 2. Use lower-case ids.  Links from pages outside of
> www.FreeBSD.org may be broken.
> 
> 3. Convert the existing ids to upper-case but use lower case for 
> newly-added ones.  It works but not consistent.

4. Use some kind of redirection at the HTTP level.

I'd prefer (2) or (4). I think we already carry a lot of legacy stuff
and people frequently come up with the idea of using some kind of
markdown or wiki system for documentation and try to recruit more
people to support this idea because the current situation is much more
complicated than it could. I think going to XML and dropping character
entities highly helps people writing docs and simplifying things. So
I'd prefer avoiding one more not really sensible policy and confusion
factor. Using upper-case names affects readability and suggests that
it is a policy or a practice to follow even if we go for (3). Besides,
please take into account that we never care of broken links when we
remove a chapter or section and that links may still bring you to the
proper page just not to the proper part. The user may still find the
part she is looking for.

This whole thing could be mitigated with some HTTP redirection. We
could rewrite http://freebsd.org/doc/\([^#]*\)#\(.*\) to
http://freebsd.org/doc/\1#\2 where \2 is converted to lower-case. I'm
not sure what www.freebsd.org runs and whether such rewriting is
supported but theoretically it should be possible.

Gabor