[kde-guidelines] Docs finally in CVS

[Frans Englich]

On Wednesday 08 December 2004 23:42, Ellen Reitmayr wrote:
> Hi everybody,
>
> we finally added the existing HIG files to CVS. You can find the source
> files under www/areas/guidelines/src/usability, and you can view them
> under www/areas/guidelines/html. The chapter 'Menus' and 'Keyboard
> Operations' is quite filled with contents, but of course there is still
> a lot of work to do.. btw: missing parts are marked with <todo> tags
> (which are currently not defined in the dtd -> see below).
>
> All of the sect1's and sect2's are there, including ids. sect3's should
> be labelled according to the same scheme, which is explained in
> guidelines/src/USABILITY_GUIDELINES. I will still add a summarised
> USABILITY_TODO file.
>
> I copied some of Frans tables to the Keyboard Operations chapter which
> was very helpful 8-) However, who ever wants to contribute does not
> necessarily need to write in docbook format. As written in the
> USABILITY_GUIDELINES, you can also send OpenOffice or KWord files.
>
>
> Some comments/questions:
>
> - Currently, there is one file per chapter. This will probably not
> suffice when the amount of text is going to increase. But splitting will
> be done later...
>
> - I tried to link within one file (e.g. in keyboard.xml from
> keyboard_shortcuts_basics_guidelines to
> keyboard_shortcuts_standard_guidelines) -> seems that is not possible,
> is it?
>
> - Shouldn't we mark guimenus, guimenuitems and possibly actions in a
> special way (also make them bold)? I know that's not the case in the KDE
> docs, but I think it would be useful.

Yes, I also think it's useful, and it should always be done. If a certain 
visual appearance is of interest, the stylesheets should be changed(not 
excluding markup, as some think). Here's a snippet from 
www/areas/usability/hig/src/input.xml;

<para>If several windows are to be closed at once, <action>Quit</action> 
should not be used for that, but instead a <guimenuitem>Close All 
Views</guimenuitem> in the <guimenu>View</guimenu> menu, should be 
used.</para>

FYI, the <accel> tag, for marking shortcuts:
<guimenuitem>C<accel>u</accel>t</guimenuitem>
has no default rendering(at least vanilla Docbook), so it has to be 
customized.

>
> - I added <todo></todo> tags to mark where contents are missing. As they
> are not in the dtd, they are marked red in the html output. I think
> that's quite fine because you can immediately see where something is
> missing. Should we define the todo tags and assign a certain color to
> them, or just leave everything as it is currently?

The remark tag is useful for this purpose:
http://www.docbook.org/tdg/en/html/remark.html


Cheers,

		Frans