[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [platform-doc-dev] Eclipse documentation styles
|
The CSS file generally gives the Eclipse documentation a consistent look.
However, the HTML markup 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. 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
