Re: [Inkscape-docs] Documentation conventions

Le Tuesday 09 October 2007 23:37:53 radar.map35@...6..., vous avez écrit :

I made no convention as long i've done it alone, sometimes quite quickly and the best i could (especially at the beginning where i even didn't know docbook and other stuffs).

usually, i tryed to follow tool or command name but there are sometimes sub-section not realted to some UI object.

I see no trouble in doing a convention. I don't know if there is already one in gnome-doc project, but may be somethings like gnome icon naming project (or tango which is the same now i guess) could be a basis.

"

Icon Naming Guidelines

Here we define some guidelines for when creating new icons that extend the standardized list of icon names defined here, in order to provide icons for more specific MIME types, devices, or international flags.

*

  Icon names are in the en_US.US_ASCII locale. This means that the
  allowable characters in the icon names, must fall withing the
  US-ASCII character set. As a further restriction, all icon names
  may only contain lowercase letters, numbers, underscore, dash, or
  period characters. Spaces, colons, slashes, and backslashes are
  not allowed. Also, icon names must be spelled as they are in the
  en_US dictionary.

*

  The dash “-” character is used to separate levels of specificity
  in icon names, for all contexts other than MimeTypes. For
  instance, we use “input-mouse” as the generic item for all mouse
  devices, and we use “input-mouse-usb” for a USB mouse device.
  However, if the more specific item does not exist in the current
  theme, and does exist in a parent theme, the generic icon from the
  current theme is preferred, in order to keep consistent style.

*

  Icons for branded applications should be named the same as the
  binary executable for the application."

for ex :

document-new

edit-find

object-flip-vertical

we could at the same time do it for section ID but also for pictures. our trouble is were we wish to have several picture in a section : should we add a number or "--extrascomment"

Any opinion ?

in french : Si on veut insérer une nouvelle image lors d'une nouvelle fonctionnalité, il faudra modifier tous les chiffres...ça risque d'être pénible. --extracomment me paraît une meilleure solution, plus facile pour maintenir un manuel toujours d'acutalité.

in english : "--extracomment" is more easier to maintain.

Resum : i vote --extracomment.

Elisa who have to learn speak english.