[CALL FOR REVIEW] doc and www converted to XML

[Hiroki Sato]

Gabor Kovesdan <gabor at FreeBSD.org> wrote
  in <503E7E70.2050504 at FreeBSD.org>:

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

 Let's forget about HTTP level solution.  On the mirror servers it
 does not work.

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

 One compromise solution would be adding an additional anchor with
 upper-case ids just after the normal (lower-case) one by XSLT only
 for HTML output.  It is relatively easy and should not be harmful.
 How about this?

 Hmm, I agree that upper-case ids are annoying but cannot agree that
 we never took care of anchors and/or we can ignore the negative
 impact from changing them.  We should take care of them as far as we
 can.  Just converting them to lower-case is different from the case
 of removal of a section because it is not non-avoidable.

-- Hiroki
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 196 bytes
Desc: not available
URL: <http://lists.freebsd.org/pipermail/freebsd-doc/attachments/20120831/c6af14e2/attachment.sig>