Re: [platform-doc-dev] HTML comments policy

[John Arthorne <John_Arthorne@xxxxxxxxxx>]

I see no problem with using HTML comments
in specific cases like this if you find it useful.  I don't think
we would adopt this for all doc, because in most cases the CVS history
is sufficient.  With this kind of document that needs to be updated
every release (command line args list, icon list, etc), I can see how this
would be useful.

John

Maxime Daniel <maxime_daniel@xxxxxxxxxx>
Sent by: platform-doc-dev-bounces@xxxxxxxxxxx

17/05/2006 04:41 AM

Please respond to
"Platform Documentation discussions."

To	platform-doc-dev@xxxxxxxxxxx
cc
Subject	[platform-doc-dev] HTML comments policy

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 optionscross-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

_______________________________________________
platform-doc-dev mailing list
platform-doc-dev@xxxxxxxxxxx
https://dev.eclipse.org/mailman/listinfo/platform-doc-dev