Talk:Conventions typographiques pour les pages Squeak

From OFSET Wiki

Message de Alain Plantec :

Il y a t-il quelque-part une description de normes à respecter pour l'ecriture des doc squeak. par exemple :

• utilisation du gras-italique-souligné
• nommage des pages,
• comment référencer une classe ou un mot clé dont on sait qu'un jour il y aura une page dédiée

(euh... pas clair... par exemple : j'écris dans ma doc PluggableTextMorph, c'est le nom d'une classe et on peut espérer qu'un beau jour, il y aura une page de référence pour cette classe. J'utilise quoi ? PluggableTextMorph ou encore PluggableTextMorph ....)

• comment doit-on présenter le code d'une méthode :

  PluggableTextMorph>>update: aSymbol
  ...

ou

  update: aSymbol
  ...

la première solution est plus explicite, la seconde permet le copier/coller.

• comment nomme t-on un message (#update: ou update)

---

J'ai posé une trame pour la structure de la page. Il faudrait sans doute faire le tour des pages et voir comment les contributeurs rédigent. Voir aussi du côté des bonnes pratiques. Thierry Pasquier

[edit] Pour du code dans le texte

Pour mettre du code Smalltalk dans une phrase, il y a aussi la possibilité d'utiliser : <code>RectangleMorph new openInWorld</code>, ce qui donne RectangleMorph new openInWorld. hilaire

Très bien. Ce serait bien de présenter différemment <tt> de <code>, de réserver ce dernier pour le code inséré dans le texte et logiquement de le surligner de la même façon qu'un bloc. As-tu accès à la feuille de style pour le faire ? Thierry

Oui ça doit être possible hilaire

[edit] Proposition de formatage

Je pensais que les hyperliens étaient graissés, ce qui n'est pas le cas. Je vous fais part tout de même de ma proposition.

Et donc en partant de l'idée de Alain de rédiger des pages de référence des classes, je me suis dis qu'il y avait une sorte de logique typographique derrière. Les expressions Squeak / Smalltalk seraient graissées.

• gras : les classes, objets et variables
• gras italique : les messages

Certe écrire WatchMorph new openInWorld - '''WatchMorph''' '''''new''''' '''''openInWorld''''' - est plus long que WatchMorph new openInWorld - <code>WatchMorph new openInWorld</code> - mais cette façon de faire est peut être plus lisible et intéressante sur le plan didactique (l'une n'empèche pas l'autre).

Traditionnellement :

• italique seul : les noms de fichiers, de fenêtres, de packages, etc.
• monospace : les commandes, les menus, les raccourcis claviers, etc...
• les crochets désignent les touches du clavier et les raccourcis, exemple : [alt]+[b] soit <tt>[alt]+[b]</tt>,
• les touches ->, en typo monospace, désignent des successions d'entrées et d'items de menus, exemple Fichier -> Ouvrir nom du fichier</tt> soit <tt>Fichier -> Ouvrir</tt> ''nom du fichier''</tt> .

Votre avis sur cette proposition ? Il y a sans doute des choses qui ont été oubliées ... ThierryPasquier