Writing an Application Manual/fr: Difference between revisions
ChristianW (talk | contribs) No edit summary |
ChristianW (talk | contribs) No edit summary |
||
Line 72: | Line 72: | ||
* Notez sur la page de discussion tout ce à quoi vous aurez besoin de faire référence ultérieurement, comme des liens qui ne peuvent pas encore être créés. | * Notez sur la page de discussion tout ce à quoi vous aurez besoin de faire référence ultérieurement, comme des liens qui ne peuvent pas encore être créés. | ||
{{Remember/fr|1=Il est important d'être cohérent, particulièrement pour les manuels, il existe donc quelques règles générales :}} | {{Remember/fr|1=Il est important d'être cohérent, particulièrement pour les manuels, il existe donc quelques règles générales : <!--}}--> | ||
* Attention aux niveaux des entêtes - nous commençons au niveau deux (Médiawiki utilise le niveau un pour les noms de pages), en utilisant <nowiki>==</nowiki> | * Attention aux niveaux des entêtes - nous commençons au niveau deux (Médiawiki utilise le niveau un pour les noms de pages), en utilisant <nowiki>==</nowiki> |
Revision as of 11:03, 4 June 2018
Notes
Les manuels seront inclus comme des sous-pages de la page principale de l'application. Pour faire court, je parlerai de cette page principale comme Appname. La structure, devra en conséquence avoir la forme suivante :
- Appname
- Appname/Trucs et astuces
- Appname/Manuel # Page de description du contenu
- Appname/Manuel/Introduction sur Appname
- Appname/Manuel/Choix de configurations
- Appname/Manuel/Première utilisation de Appname
- Appname/Manuel/section 1
- Appname/Manuel/section xxx
- Appname/Manuel/Trucs et astuces
- Appname/Manuel/Disfonctionnements
- Appname/Manuel/Déclarer les bogues
- Appname/Manuel/Contribuer #lien vers techbase etc
Si certaines de vos sections grossissent trop, vous pouvez mettre les sous-sections sur des pages séparées. Ce qui pourrait ressembler à :
- Appname/Manual # Votre page Table des matières
- Appname/Manual/Une introduction à Appname
- Appname/Manual/Choix des configurations
- Appname/Manual/La première fois que vous utilisez Appname
- Appname/Manual/section 1
- Appname/Manual/section 1/sous-section 1
- Appname/Manual/section 1/sous-section 2
et ainsi de suite.
Pour que le Docbook généré automatiquement ait la même page de contenu que celle que vous avez créée sur UserBase et pour que les liens fonctionnent dans le Docbook, il y a quelques règles à suivre :
- La table des matières de Docbook répertorie toutes les sections et sous-sections, qu'elles possèdent ou non une page. D'un autre côté, les sous-sous-sections ne seront pas listées dans la table des matières Docbook même si elles ont leur propre page.
- Toutes les pages doivent avoir une entête tout en haut, ou bien une section (== ... ==), ou une sous-section (=== ... ===), ou encore une sous-sous-section (==== ... ====), sinon la structure du Docbook sera perturbée.
- Le titre de la section/sous-section doit être le même que le nom de la page, sinon les liens Docbook ne fonctionneront pas.
- Les titres des sous-sections doivent être écrits comme ceci :
===titre===
, même s'il s'agit du niveau principal d'une page. Sinon cela perturbera la structure Docbook. De la même manière, si vous avez une section très longue avec des sous-sous-sections sur des pages ces pages doivent avoir leur titre écrit comme ceci :====titre====
.
- Les sous-sections qui ne doivent pas apparaître dans la table des matières ni individuellement sur une page du Docbook, doivent être de niveau quatre ou inférieur c'est à dire ==== ou plus.
- Les liens vers les pages du manuel doivent correspondre exactement au nom de la page name (c'est à dire pas de liens par redirection !)
- Si vous créez un lien vers une sous-section d'une page, vous devez avoir défini une ancre à l'emplacement cible. Si ce n'est pas le cas, cela perturbera les liens Docbook ainsi que les traductions.
Vous aurez besoin d'un brouillon pour expérimenter les titres des sections et des pages. Vous pouvez utiliser soit votre page de discussion utilisateur, ou la page de discussion attachée au domaine dans lequel vous travaillez. Il est utile d'enlever le superflu, une fois que le travail est terminé.
Réaliser un manuel
Pendant que vous rédigez votre manuel il est préférable de le tenir séparé du contenu courant de UserBase. Certains préfèrent écrire leurs brouillons en tant que sous-pages de leur page utilisateur de discussion. Il existe aussi un espace de noms Draft: pour cela.
Pour créer le sommaire de votre manuel, écrivez simplement http://userbase.kde.org/Draft:Appname/Manuel sur la ligne d'adresse de votre explorateur, ou placez le lien [[Draft:Appname/Manual]] sur une page et cliquez dessus. Dans les deux cas vos serez dirigés vers une page qui vous dira que la page n'existe pas, mais que vous pourrez créer en cliquant sur un lien.
Contenu
- Une fois que vous avez pris les décisions (ce qui peut prendre du temps), créez les liens appropriés vers la page de la table des matières. Il est bien sûr possible d'insérer une section ultérieurement dans le cas où vous auriez oublié quelque chose.
Concevoir votre manuel
- Utilisez les liens rouges pour créer les pages, et écrivez une section à la fois.
- Notez sur la page de discussion tout ce à quoi vous aurez besoin de faire référence ultérieurement, comme des liens qui ne peuvent pas encore être créés.
- Faire en sorte que les noms d'applications aient un format cohérent (évitez d'utiliser Amaroks, mais préférez Amarok's).
- Vérifiez bien que toutes les images sont au format PNG (vous pouvez aussi utiliser le JPEG, mais dans ce cas elles devraient être converties en PNG par le script). Sauvegardez le travail en les convertissant avant de démarrer .
- Enlever dans les noms d'images, tous les caractères non imprimables.
Chercher dans votre manuel
A un certain moment, vous pourriez avoir besoin de rechercher quelque chose que vous avez écrit précédemment, mais vous ne savez plus où. L'utilisation de la boîte de recherche de wiki peut ne pas être idéale à moins que la chaîne que vous recherchez est très spécifique. Vous pouvez avoir un meilleur contrôle sur les recherches en utilisant l'extension DPL. Par exemple, pour trouver les pages de votre manuel qui contiennent une chaîne donnée, vous pouvez ajouter ceci a n'importe quelle page:
<DPL> titlematch = %Appname/Manual% namespace = Draft include = * includematch = /chaîne à rechercher/ resultsheader = Manual Pages: format = ,\n* [[%PAGE%|%TITLE%]]\n,, </DPL>
Vous trouverez d'autres exemples utilisant DPL sur User:Claus_chr/DPL.
Préparer le manuel pour la traduction
- Les étapes pour réaliser le marquage peuvent être consultées sur Modifier le marquage des pages. Veuillez suivre les indications de ce guide, parce que l'ancienne manière de faire le marquage peut ne plus être significative.
Produire un manuel DocBook
Une fois que votre manuel est écrit vous pouvez le convertir en manuel DocBook, afin que votre travail soit utilisable comme n'importe quel manuel KDE ordinaire. La procédure est décrite sur cette page.