[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [platform-doc-dev] Eclipse documentation styles
|
Mike, I think a style guide and a more sophisticated CSS are both excellent
ideas. We have done some work on both of these fronts at IBM for products
based on Eclipse. Does anybody else have anything similar?
Thanks, Jeanette
-------------------------------------------------------------------------------------
Jeanette Deupree
IBM WebSphere Information Strategy
RTP NC
919-254-1149 (tieline 444-1149)
deupree@xxxxxxxxxx
Mike Behm
<mbehm@redhat.c
om> To
Sent by: platform-doc-dev@xxxxxxxxxxx
platform-doc-de cc
v-admin@eclipse
.org bcc
Subject
12/02/2002 Re: [platform-doc-dev] Eclipse
04:13 PM documentation styles
Please respond
to
platform-doc-de
v
The CSS file generally gives the Eclipse documentation a consistent look.
However, the HTML is not consistent. Some examples:
Images are set in a variety of tags:
<p align="center"><img ...></p>
<P CLASS="Para"><img ...></P>
<blockquote><p CLASS="Para"><img ...></p></blockquote>
There is no standard for "menu > submenu > setting" instructions: should
they be bold or not, quoted or not, with > or -> arrows (and are
the arrows bolded or not).
Are filenames and paths in the default font, bold, or code font? Quoted
or not?
Paragraphs may or may not have class attributes (CLASS="Head",
CLASS="Para"), but in any case these attributes aren't actually used by
the CSS file. Of course the class attributes could be used by a given
vendor with a customized CSS file, but even within a given file the
coding is not always applied uniformly.
That last point is important: if the HTML code had more structure and
the "optional" markup was more uniformly applied, there would be a
number of benefits:
-the current documentation would look more coherent and would
be easier to read
-vendors could apply the documentation conventions they use with
their other manuals to their version of the Eclipse manuals
-if there was any interest in converting to SGML at some point,
it would be much easier to do.
Basically you'd need a style guide written for HTML and CSS, and written
with an awareness of SGML issues. It would mean that the text
the Repositories view
would not be coded as
the <em>Repositories</em> view
the <b>Repositories</b> view
the "Repositories" view
the Repositories view
but instead would be coded as
the <span class="viewname">Repositories</span> view
Is there any interest in a style guide of that type? Would the benefits
I mentioned be of benefit to you or you organization?
I noticed that some authors use WYSIWYG editors, not raw HTML editors.
Even if there is some interest in a style guide, WYSIWYG editors would
be a problem. But I'd like to start some discussion, not end it. If you
like the idea or if you think that it is too much work for too little
benefit, do let me know.
Best regards,
Mike
birsan@xxxxxxxxxx wrote:
> Mike, each documentation plugin contains a book.css stylesheet that is
> linked by all the topics. The same file is duplicated to all the docs
> plugins, although one could probably do some cross plugin linking (using
> relative paths such as ../../common_doc_plugin_id/book.css).
>
> -Dorian
>
> |---------+---------------------------------->
> | | Mike Behm |
> | | <mbehm@xxxxxxxxxx> |
> | | Sent by: |
> | | platform-doc-dev-admin@|
> | | eclipse.org |
> | | |
> | | |
> | | 12/02/2002 03:15 PM |
> | | Please respond to |
> | | platform-doc-dev |
> | | |
> |---------+---------------------------------->
>
>-------------------------------------------------------------------------------------------------------------|
> |
|
> | To: platform-doc-dev@xxxxxxxxxxx
|
> | cc:
|
> | Subject: Re: [platform-doc-dev] Eclipse documentation styles
|
> |
|
> |
|
>
>-------------------------------------------------------------------------------------------------------------|
>
> Hi Mike,
>
> What I had in mind was a style guide that would make use of cascading
style
> sheets. With proper HTML markup and CSS files, each vendor could ship
> Eclipse
> documentation that has the same look and feel as the rest of their
> documentation.
>
> Can you tell me what the tool you mention does to canonicalize the html
> source?
>
> Mike Wilson wrote:
>
> > The SWT team had a couple of co-ops which wrote a tool for validating
and
> > canonicalizing the html source for the platform user doc. If there is
an
> > effort afoot to fix the coding styles, it should take that tool into
> > account.
> >
> > McQ.
> >
> >
> > Mike Behm
> > <mbehm@xxxxxxxxxx
> > >
> To
> > Sent by: platform-doc-dev@xxxxxxxxxxx
> > platform-doc-dev-
> cc
> > admin@xxxxxxxxxxx
> >
> Subject
> > [platform-doc-dev] Eclipse
> > 02/12/02 12:17 documentation styles
> >
> >
> > Please respond to
> > platform-doc-dev@
> > eclipse.org
> >
> >
> >
> > Looking over the raw HTML for the Eclipse help, I see that there are
> > many coding styles. Is there a style guide? If not, would there be any
> > interest in developing one?
> >
> > _______________________________________________
> > platform-doc-dev mailing list
> > platform-doc-dev@xxxxxxxxxxx
> > http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
> >
> > _______________________________________________
> > platform-doc-dev mailing list
> > platform-doc-dev@xxxxxxxxxxx
> > http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
>
> _______________________________________________
> platform-doc-dev mailing list
> platform-doc-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
>
> _______________________________________________
> platform-doc-dev mailing list
> platform-doc-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
_______________________________________________
platform-doc-dev mailing list
platform-doc-dev@xxxxxxxxxxx
http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
