[
Date Prev][
Date Next][
Thread Prev][
Thread Next][
Date Index][
Thread Index]
[
List Home]
|
Re: [platform-doc-dev] Eclipse documentation styles
|
Hi Jeanette,
Here is a short list of the coding that I would find useful:
For Notes
<p class="note"><span class="notetitle">Note:</span>...</p>
For Warnings
<p class="note"><span class="warningtitle">Warning:</span>...</p>
(Typically, notes, warnings, and cautions are similar in their
margins and visual effects such as text boxes, so for my purposes
the same paragraph class can server for all. I'd prefer to render
"Warning" in red and "Note" in black, so having different classes
there would be useful.)
For filenames and paths:
<span class="filename">name</span>
For text that appears on GUIs:
<span class="guilabel">Dialog Name</span>
For button names:
<span class="guibutton">OK</span>
For preformatted text:
<div class="screen">
<pre>
source code
</pre>
</div>
For Copyright notices
The IBM copyright graphic can be approximated in HTML and CSS:
<p class="copyright"><a href="../hglegal2002.htm"
class="copyright"> ©Copyright IBM Corporation 2000, 2002.
All Rights Reserved.</a>
and
p.copyright {
font-family: sans-serif, Helvetica, Verdana;
font-size: 7pt;
color: #3450ac;
}
a.copyright {
color: #3450ac;
text-decoration: none;
}
======================
Here is a tag that I've seen in the files and will use, but it would
be better to have the markup used consistently:
<span class="control">Edit > Find Next</span>
======================
Here are some of the tags that aren't useful to me, but I'll include them in files
I create if that would be useful to others:
<h2 class="Head">Key binding actions</h2>
<p CLASS="Intro">...</p>
<UL CLASS="UnorderedList">
<LI CLASS="Item">
<DIV CLASS="Subtopic"><H2 CLASS="Head">...
======================
Here are some of the tags and markup I've seen but have questions about:
<P CLASS="Para">
(From the way it is used, I don't think that this differs from <p>.)
<ol class="UnorderedList">
(It's odd to give the ordered list a class called "unorderedlist".)
<blockquote>
<p CLASS="Para">This is a 6th line</p>
</blockquote>
(It would be better to do this in CSS with something like
<p class="indented">...</p>)
<li><P CLASS="Para">...</p></li>
(The <p></p> tags are unnecessary; you can get the spacing
by using CSS.)
<P CLASS="Para" Label=Type>
(I'm not familiar with the 'label' attribute.)
<TABLE BORDER="0" cellspacing="0" cellpadding="3">
<THEAD></THEAD>
<TBODY>
<TR>
<TD COLSPAN="1" valign="top" align="left">
<P CLASS="Para"><b>1.</b></P>
</TD>
<TD COLSPAN="1" valign="top" align="left">
<P CLASS="Para">In the shortcut bar click on the Navigator fast view button.</P>
</TD>
</TR>...
It would be easier to use:
<ol><li>In the shortcut bar click on the Navigator fast view button.</li>
<p><em>Tip:</em>...</p>
(Acceptable, but <p class="note"><span class="tip">Tip:</span>...</p>
would be better.)
Jeanette Deupree wrote:
> 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
>
> _______________________________________________
> platform-doc-dev mailing list
> platform-doc-dev@xxxxxxxxxxx
> http://dev.eclipse.org/mailman/listinfo/platform-doc-dev
