[platform-doc-dev] HTML comments policy

[Maxime Daniel <maxime_daniel@xxxxxxxxxx>]

I wonder if we want to use HTML comments for doc consolidation purposes.
(Could find no mention of HTML comments in the Eclipse Doc Style Guide.)

I have a very specific example in mind: I'd like to mark the help topic
about the batch compiler options with something like <!-- default options
cross-checked with batch compiler -h text by maxime 20060517 -->. There are
a few issues with such an approach (because the end user can read such
notes if she wants, to start with; also proliferation would be a pain), but
clear benefits as well. (Yes, commit comments could hold this information
as well, but I believe that decorating the doc contents is a stronger
proposition for such a case.)

BTW, I don't want to launch a heated debate on the subject. Just asking if
it sounds acceptable to the community.

Maxime DANIEL
Developer, Eclipse JDT Core
IBM Paris Laboratory
69, rue de la Vecquerie
44600 Saint-Nazaire
maxime_daniel@xxxxxxxxxx / +33 (0) 2 51 16 40 13 / tl 87 40 13 / FAX - 40
01 / Mob. +33 (0) 6 84 63 99 62
' It takes nine months to make a baby, and it takes focused concentration
to make great breakthroughs.' - Stever Robbins - in HBS Working Knowledge,
Jan 2005
'The easiest way to predict the future is to invent it.' - Alan Kay