Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 622a.lha / ADoc_v7.04 / ADoc.doc.pp / ADoc.doc

Wrap

Text File | 1992-04-03 | 23.7 KB | 576 lines

ADoc v7.04 - Manuel d'utilisation Ce manuel décrit la version 7.04 de l'utilitaire ADoc. Ce programme est placé dans le domaine public, avec autorisation de le copier librement et de le diffuser par n'importe quel moyen, à condition que le produit soit diffusé dans son intégralité, et sans aucune modification. ADoc est (c)1990-1991-1992 par Denis GOUNELLE, toute utilisation commerciale ou vente de ce programme (sans autorisation écrite) est STRICTEMENT INTERDITE. Serge HAMMOUCHE est autorisé à diffuser ADoc aux conditions qu'il voudra. "PowerPacker 2.3b" est (c)1989 par PowerPeak et Nico FRANCOIS, "PowerPacker Pro 3.0b" est (c)1990 par PowerPeak et par UGA Software. La bibliothèque "powerpacker.library" est (c)1990 par Nico FRANCOIS. AREXX est (c)1987 par Bill Hawes. Malgrès de nombreux tests, je ne peux garantir qu'ADoc ne contient aucune erreur. VOUS UTILISEZ CE PROGRAMME A VOS RISQUES ET PERILS. Je ne pourrai en aucun cas être tenu responsable de tout dommage, direct ou indirect, résultant de l'utilisation d'ADoc. Sommaire : ---------- 1. Introduction 2. Principe de fonctionnement 3. Mode d'emploi 3.1 Appel depuis le CLI 3.2 Appel depuis le WorkBench 3.3 Mode d'emploi 3.4 La requête de terme 4. Concepts avancés 4.1 Utilisation de plusieurs fichiers de documentation 4.2 Association de fichiers 4.3 Génération de plusieurs index 4.4 Extension du jeux de caractères 4.5 Utilisation de la bibliothèque "powerpacker.library" 4.6 Le mode AREXX 4.7 Utilisation des fichiers AutoDoc 4.8 Le menu "Spécial" 5. Messages d'erreur 1.Introduction : ---------------- ADoc est un utilitaire permettant de gérer des documentations sur n'importe quel sujet. Il dispose d'une fonction de recherche d'un mot désigné à la souris, et peut travailler sur plusieurs fichiers à la fois. ADoc peut également lire les fichiers AutoDoc de Commodore ainsi que des fichiers compactés par "PowerPacker 2.3b" ou "PowerPacker 3.0b", et dispose d'un port compatible AREXX. +-------------------------------------------------------+ | ATTENTION !! | | | | Le format des fichiers de documentation n'est plus le | | même que pour les versions 3.xx et 4.xx. Pour pouvoir | | utiliser vos anciens fichiers, lisez la documentation | | pour savoir quel est le nouveau format, modifiez les | | anciens fichiers (cela devrait vous prendre très peu | | de temps...) et re-générez les fichiers d'index. | +-------------------------------------------------------+ Vous pouvez me faire part de vos remarques ou critiques sur ADoc, en écrivant à l'adresse suivante : M. GOUNELLE Denis Boite 71 6, rue des cailloux 92110 CLICHY - FRANCE Merci à Jean-Yves PROUX, Jean-Philippe RAPP, et Helmut J. ESENWEIN pour leurs nombreuses suggestions, à Simon HEWINSON pour la traduction en anglais du fichier "Amiga.doc". Merci également à Jean-Philippe RAPP pour m'avoir permis de tester ADoc sur les fichiers AutoDoc version 2.02. 2. Principe de fonctionnement : ------------------------------- ADoc travaille à partir d'un fichier de documentation, que vous créez vous-même au moyen d'un éditeur de texte. Ce fichier contient une suite de termes, chaque terme ayant la syntaxe suivante : terme ligne explication 1 ligne explication 2 . . . . . . ligne explication n Il est absolument indispensable que la première lettre de terme soit sur la colonne 1, et que les lignes d'explications commencent par au moins un espace ou une tabulation, car c'est le seul moyen pour ADoc de distinguer un terme de son explication. De plus, les deux premières lignes du fichier doivent absolument être vides, ou commencer par un espace ou une tabulation (voir §4.2 et §4.4). Un terme ne peut pas faire plus de 32 caractères, et ne peut contenir ni espaces ni tabulations : les seuls caractères permis sont les lettres minuscules et majuscules, les chiffres, les caractères accentués minuscules (codes ASCII entre 217 et 246) et le caractère souligné. Il est cependant possible d'étendre le jeu de caractères autorisés (voir §4.4). Si un même terme est défini plusieurs fois dans un fichier, aucune erreur ne sera annoncée : ADoc se contentera de mettre à la suite les lignes d'explication lorsqu'il affichera le texte correspondant à ce terme. Si vous définissez un terme "AboutThisDoc", le texte correspondant à ce terme sera automatiquement affiché lors du démarrage d'ADoc. On ne peut mettre plus de 32767 termes par fichier. La longueur maximale des lignes d'explication est de 256 caractères (bien que seul le début soit affiché). Le nombre de lignes d'explication par terme n'est pas limité. Les lignes d'explication peuvent éventuellement comprendre les séquences ANSI suivantes : ESC[0m caractères normaux ESC[1m début gras ESC[3m début italique ESC[22m fin gras ESC[23m fin italique Une fois le fichier de documentation constitué, ADoc construit un fichier d'index, qui permet d'accéder presque instantanément au terme recherché. Le mon de cet index est obtenu en ajoutant le suffixe ".index" au nom du fichier de documentation. +-------------------------------------------------------+ | ATTENTION !! | | | | Vous devez reconstruire l'index à chaque modification | | du fichier de documentation. | +-------------------------------------------------------+ 3. Mode d'emploi : ------------------ ADoc peut s'utiliser depuis le CLI ou depuis le WorkBench. Le fichier de documentation par défaut est "Amiga.doc" mais on peut, dans les deux cas, indiquer un autre fichier. 3.1 Appel depuis le CLI ----------------------- Depuis le CLI, la syntaxe de l'appel est la suivante : ADoc -i [-f<fichier>] ou ADoc [-c][-e][-f<fichier>][-l][-n][-q][-A][<terme>] La première forme demande la création de l'index d'un fichier de documentation, la seconde permet de consulter la documentation. Voici la description des options : -i Indique que la seule opération à faire est la création de l'index. Doit OBLIGATOIREMENT être la première option sur la ligne de commande. -c Demande à ADoc de ne pas différencier minuscules et majuscules, aussi bien lors des recherches que lors de la requête de terme. Devrait être indiqué avant une éventuelle option -f. -e Demande à ADoc d'ouvrir son propre écran, plutôt que d'utiliser l'écran WorkBench. Notez que ADoc ouvrira automatiquement son propre écran si la police par défaut de l'écran WorkBench n'est pas "topaz8". -f<fichier> Permet de préciser le fichier de documentation à utiliser. Si vous n'indiquez pas de chemin d'accès, le fichier doit se trouver dans le répertoire courant ou dans le répertoire "ADOC:". -l Permet de travailler en mode entrelacé. Si on n'indique pas l'option -e et que l'écran WorkBench n'est pas en mode entrelacé, ADoc ouvre son propre écran. -n Demande à ADoc de ne pas trier l'index lors de la requête de terme. Cette option doit être indiquée avant une éventuelle option -f. -q Empèche l'affichage du texte correspondant au terme "AboutThisDoc" lors du démarrage. -A Met ADoc en mode AREXX (voir §4.6). Les options -i et -e ne peuvent être utilisées en même temps que cette option Dans la seconde forme on peut indiquer le terme sur lequel on désire voir la documentation, mais ce n'est pas obligatoire. 3.2 Appel depuis le WorkBench ----------------------------- Depuis le WorkBench, on peut appeler ADoc de quatre façons : - en double-cliquant sur l'icône d'ADoc (on utilise alors le fichier de documentation par défaut) - en double-cliquant sur l'icône d'un fichier qui a ADoc comme outil par défaut ("Default tool") - en cliquant sur l'icône d'ADoc puis en double-cliquant sur l'icône d'un fichier de documentation, le tout en gardant la touche SHIFT appuyée - en cliquant sur l'icône d'un fichier de documentation puis en double-cliquant sur l'icône d'ADoc, le tout en gardant la touche SHIFT appuyée Quand ADoc est utilisé à partir du WorkBench, il ouvre toujours son propre écran. Il est possible d'indiquer des options, dans le champ "TOOL TYPES" de l'icône d'ADoc ou de l'icône d'un fichier de documentation. La syntaxe est la suivante : ADOC=[INTERLACE]|[NOSORT]|[CASE]|[QUICK] Le paramêtre INTERLACE indique à ADoc qu'il doit ouvrir un écran en mode entrelacé, le paramêtre NOSORT demande de ne pas trier l'index lors de la requête de terme, et le paramêtre CASE demande de ne pas différencier minuscules et majuscules (aussi bien pour les recherches que pour la requête de terme). Le paramêtre QUICK empèche l'affichage du texte correspondant au terme "AboutThisDoc" lors du démarrage. 3.3 Mode d'emploi ----------------- Lors de l'ouverture du fichier d'aide, ADoc cherche automatiquement le terme "AboutThisDoc". Si ce terme existe, le texte correspondant est affiché dans une fenêtre, et ADoc attend que vous fermiez cette fenêtre pour continuer. Si vous appelez ADoc depuis le WorkBench, ou depuis le CLI mais sans indiquer le terme à chercher, une boite de requête apparait, avec la liste des termes connus (voir §3.4 pour l'utilisation de cette requête). Dès que vous indiqué un terme à chercher, une fenêtre apparait, avec le texte d'explication correspondant. Si ce texte est trop long pour tenir dans la fenêtre, la première page est affichée, et deux gadgets (flèche vers le haut et flèche vers le bas) apparaissent sur la barre de titre de la fenêtre. Ces gadgets vous permettent de faire défiler le texte dans la fenêtre, page par page. Pour fermer la fenêtre, cliquez sur le gadget de fermeture, ou appuyez sur la touche ESCAPE. Vous pouvez cliquer deux fois sur un mot du texte d'explication, ce qui lancera automatiquement la recherche de ce terme. Si le terme n'est pas trouvé l'écran flashe, sinon le texte correspondant est affiché dans une nouvelle fenêtre placée au premier plan. Si vous désirez voir le texte associé à un terme qui n'apparait dans aucun des textes d'explication déjà affichés, vous devez utiliser la commande "Autre terme" du menu "Projet" : une boite de requête apparait, avec la liste des termes connus (voir §3.4 pour l'utilisation de cette requête). Dans les deux cas, si vous sélectionnez un terme pour lequel une fenêtre est encore présente, cette fenêtre sera simplement mise au premier plan. Vous pouvez imprimer le texte correspondant à un terme en appelant la commande "Imprime" du menu "Projet". Les éventuelles séquences ANSI présentes dans le texte seront correctement interprétées par l'imprimante. Vous pouvez iconifier ADoc, à l'aide de la commande "Iconifie" du menu "Projet". Toutes les fenêtres sont alors fermées (l'écran aussi si ADoc avait ouvert son propre écran) et une petite fenêtre apparait dans le coin supérieur gauche de l'écran WorkBench. Vous pouvez alors quitter ADoc en cliquant sur le gadget de fermeture de cette fenêtre, ou le réveiller en appuyant sur le bouton droit de la souris. ADoc vous propose alors de ré-ouvrir toutes les fenêtres qui étaient ouvertes lors de l'iconification Si vous répondez "NON", la boite de requête contenant la liste des termes connus s'affiche. Vous pouvez changer ADoc d'écran, à l'aide de la commande "Ecran avant" du menu "Projet". Il vous suffit de mettre l'écran sur lequel vous voulez placer ADoc au premier plan, de le faire glisser vers le bas, et de placer l'écran où est ADoc juste derrière. Activez alors la commande "Ecran avant", et toutes les fenêtres ouvertes seront déplacées sur l'écran au premier plan. Notez que cette commande ne marchera pas si la police par défaut de l'écran cible n'est pas "topaz8", ou si l'écran d'ADoc est en mode entrelacé alors que l'écran cible ne l'est pas. Pour quitter ADoc, vous pouvez soit fermer toutes les fenêtres une par une (NOTE : ADoc s'arrête automatiquement quand la dernière fenêtre est fermée), soit utiliser la commande "Quitte" du menu "Projet". Lorsqu'une requête OUI/NON est affichée, vous pouvez appuyez sur la touche RETURN pour répondre "oui", ou sur la touche ESCAPE pour répondre "non". 3.4 La requête de terme : ------------------------- La requête de terme vous permet de choisir un terme à la souris. Cliquez une première fois sur le terme sur lequel vous voulez de l'aide : ce terme s'affiche en rouge. Cliquez une deuxième fois sur le terme pour confirmer votre choix, ou sur un autre terme si vous avez changé d'avis. Vous pouvez utiliser le clavier pour faire votre sélection. Si vous tapez sur une lettre quelconque, cette lettre sera ajoutée au préfixe courant (affiché dans le rectangle en bas de la fenêtre), et l'affichage de la liste des termes se fera à partir du premier terme commençant par ce préfixe. ADoc complètera automatiquement le préfixe le plus possible. Si vous appuyez sur BACKSPACE, la dernière lettre du préfixe sera supprimée et l'affichage de la liste mis à jour. Si vous appuyez sur RETURN, le premier terme correspondant au préfixe sera pris comme terme à afficher. Si vous appuyez sur ESCAPE, la requête de terme sera fermée. 4.Concepts avancés : -------------------- 4.1 Utilisation de plusieurs fichiers de documentation : -------------------------------------------------------- Il suffit pour cela de préciser le nom des fichiers à utiliser lors de l'appel du programme : depuis le WorkBench, sélectionnez les icônes de ces fichiers, et depuis le CLI tapez une ligne de commande de la forme : ADoc [autres options] -fnom1,nom2,...nomn [<terme>] Vous pouvez indiquez plusieurs options -f, et intercaler les autres options. Par exemple : ADoc -fnom1,nom2 -c fnom3 -n -fnom4 provoquera le chargement des fichiers nom1, nom2, nom3 et nom4. Les index des fichiers nom1, nom2 et nom3 seront triés dans la requête de terme (sans différencier minuscules et majuscules pour le fichier nom3), alors que l'index du fichier nom4 ne sera pas trié. Si vous ne donnez pas de chemin d'accès, les fichiers doivent être dans le répertoire courant, ou dans le répertoire "ADOC:". Si vous indiquez un nom de répertoire (ou, depuis le WorkBench, sélectionnez l'icône d'un répertoire) tous les fichiers de ce répertoire (sauf ceux dont le nom se se termine par ".info" ou par ".index") seront utilisés. Comme dans le cas normal, si un ou plusieurs fichiers d'index n'existent pas, ADoc vous proposera de les créer. Le fonctionnement d'ADoc est presque le même qu'avant. Voici les possibilités supplémentaires : - lors de l'ouverture de CHAQUE fichier, ADoc cherche le terme "AboutThisDoc" et affiche le texte correspondant, puis attend que la fenêtre soit fermée pour continuer. - ADoc cherche le terme désigné à la souris dans TOUS les fichiers de documentation utilisés - Si un terme est défini dans plusieurs fichiers, toutes les lignes d'explication seront mises à la suite et affichées dans une seule fenêtre - Lorsque la requête de terme est affichée, l'appui du bouton droit de la souris permet de changer la "page" affichée : on obtient alternativement la liste des termes du fichier de documentation courant et la liste des fichiers utilisés. On peut de la sorte choisir un terme dans n'importe lequel des fichiers de documentation. ADoc ne chargera pas deux fois un même fichier. Deux fichiers sont considérés comme identiques s'ils ont le même nom, OU si leurs index ont été générés à la même date et heure. Cette date est stockée dans le fichier d'index lors de sa création, et ne changera donc que si vous recréez cet index. 4.2 Association de fichiers : ----------------------------- Il est également possible d'associer automatiquement un ou plusieurs fichiers à un fichier de documentation. Dans ce cas, lorsque ADoc ouvrira ce fichier, il chargera automatiquement le (ou les) fichiers associés. Pour utiliser cette fonction, il suffit de mettre la liste des noms des fichiers à associer (séparés par des virgules) sur la première ligne du fichier de documentation principal. Si cette ligne reste vide, commence par un espace ou par une tabulation, aucun fichier n'est associé. Sauf si vous indiquez un chemin d'accès, les fichiers associés sont cherchés dans le répertoire du fichier principal, puis dans le répertoire ADOC:. Si vous indiquez un nom de répertoire, tous les fichiers de ce répertoire (sauf ceux dont le nom se termine par ".info" ou par ".index") seront associés. 4.3 Génération de plusieurs index : ----------------------------------- Il est possible d'indiquer plusieurs fichiers même lorsque l'on utilise l'option -i, c'est-à-dire que la ligne de commande peut être : ADoc -i -fnom1,nom2,...nomn Dans ce cas, les index des tous les fichiers indiqués sont créés, puis ADoc s'arrête. 4.4 Extension du jeu de caractères : ------------------------------------ Dans certains cas, il peut être nécessaire d'étendre le jeu des caractères pouvant être utilisés dans la désignation d'un terme. La seconde ligne des fichiers de documentation est réservée à cet effet : si elle ne commence ni par un espace, ni par une tabulation, tous les caractères de la ligne sont ajoutés aux caractères autorisés, jusqu'à ce que ADoc rencontre un des caractères suivants : espace, retour, tabulation, saut de page, ou barre de fraction. Notez que cette extension est faite fichier par fichier, c'est-à- dire que si que si vous utilisez simultanément plusieurs fichiers de documentation, les caractères autorisés changeront d'un fichier à l'autre, en fonction de ce que vous avez indiqué sur la seconde ligne de chaque fichier. 4.5 Utilisation de la bibliothèque "powerpacker.library" : ---------------------------------------------------------- ADoc est capable de charger des fichiers compactés par les logiciel "PowerPacker 2.3b" ou par "PowerPacker Pro 3.0b", à condition que vous ayez placé la bibliothèque "powerpacker.library" dans le répertoire LIBS: de votre disque dur ou de votre disquette WorkBench. Il n'est pas nécessaire de créer l'index avant le compactage, mais cela est recommandé. ADoc refusera de charger un fichier crypté. Après décompactage, le fichier sera recopié dans un fichier temporaire placé dans le répertoire T:. Ce fichier temporaire sera détruit en fin d'exécution. L'utilisation de fichiers compactés peut donc s'avérer gourmande en mémoire (surtout si le répertoire T: est sur le disque RAM:). Je vous conseille, quand c'est possible, de compacter plusieurs "petits" fichiers (30 à 50 Ko) plutôt qu'un seul gros fichier (plus de 100 Ko). 4.6 Le mode AREXX : ------------------- Si vous indiquez l'option -A lors de l'appel d'ADoc, celui-ci passe en mode AREXX : un port compatible AREXX nommé "ADoc_rexx" est ouvert, et le programme attend des messages sur ce port. ADoc ne pourra fonctionner en mode AREXX s'il doit ouvrir son propre écran : vous ne pouvez donc utiliser l'option -e en même temps que l'option -A. De plus, si vous lancez ADoc depuis le WorkBench, ou indiquez l'option -l alors que l'écran WorkBench n'est pas en mode entrelacé, le mode AREXX sera automatiquement désactivé. Les messages peuvent être : quit : ADoc ferme le port AREXX et termine wakeup : ADoc lance la requête de terme et revient en mode normal ?terme : ADoc cherche le terme indiqué et, s'il le trouve, affiche le texte correspondant avant de repasser en mode normal Tout autre message sera ignoré. Voici un exemple de programme AREXX, qui demande de l'aide sur le terme "alias", et termine ADoc : /* Demande de l'aide sur "alias" */ address "ADoc_rexx" "?alias" "quit" Notez les guillemets autour des commandes ! Depuis le mode normal, vous pouvez placer ADoc en mode AREXX à l'aide de la commande "Mode AREXX" du menu "Projet". Toutes les fenêtres sont alors fermées, et ADoc attend des messages sur son port AREXX. Si vous avez lancé ADoc en mode AREXX, n'oubliez pas que ADoc repassera automatiquement dans ce mode quand vous fermerez la dernière fenêtre ouverte. Pour être sûr de quitter ADoc dans tous les cas, utilisez la commande "Quitte" du menu "Projet". 4.7 Utilisation des fichiers AutoDoc ------------------------------------ Cette version d'ADoc est capable de reconnaitre et d'utiliser les fichiers AutoDoc de Commodore. Dans la plupart des cas, aucune modification de ces fichiers n'est nécessaire, mais il est fortement conseillé de vérifier leur format : il doit y avoir au moins deux lignes blanches au début, et chaque terme doit commencer en colonne 1. Dans certains cas, il manquera les lignes blanches au début, et les termes seront précédés par un caractère "saut de page" (CTRL-L). Le programme AutoConvert, distribué avec ADoc, vous permettra de convertir automatiquement ces fichiers dans le bon format (NOTE: ce programme ne peut s'utiliser que depuis le CLI). Dans tous les autres cas, il vous faudra corriger à la main le ou les fichiers AutoDoc. Un test a été effectué sur les 45 fichiers AutoDoc de la version 2.02 du système : 27 ont été acceptés directement, 11 ont dû être convertis par le programme AutoConvert, et les 7 derniers ont dû être corrigés à la main. 4.8 Le menu "Spécial" : ----------------------- L'item "Info" vous permet de savoir combien de fichiers, de termes, de fenêtres, et de lignes sont disponible en ce moment. L'item "Ouvre fichier" vous permet d'ouvrir un fichier d'aide à tout moment (en plus des fichiers déjà ouvert). Une requête de fichier apparait, et vous permet de choisir le fichier à ouvrir. Les fichiers dont le nom se termine par ".info" ou ".index" ne sont pas affichés. Cliquez sur "ANNULER" ou fermez la fenêtre pour annuler l'opération. L'item "Ferme fichier" vous permet de fermer un fichier d'aide dont vous n'avez plus besoin, afin de libérer de la mémoire. ADoc vous demandera confirmation, mais de toute façon vous pourrez recharger le fichier grâce à l'item "Ouvre fichier". L'item "Ferme fenêtres" vous permet de fermer toutes les fenêtres d'aide ouvertes en ce moment. ADoc vous demandera confirmation, et la requête de terme apparaitra une fois que toutes les fenêtres auront été fermées. 5. Messages d'erreur : ---------------------- Le paragraphe indiqué après le message d'erreur contient les explications nécessaires pour résoudre le problème rencontré. Arguments incorrects (§3.1) Il y a une erreur dans la ligne de commande. Impossible d'ouvrir <nom> La ressource <nom> n'a pas pu être allouée. Il peut s'agir d'un fichier de documentation (dans ce cas vérifiez l'existence du fichier) ou d'un fichier d'index (voir §3.1 et §3.3 pour le créer). Ligne trop longue <ligne> (§2) La ligne dont le début est indiqué fait plus de 256 caractères. Terme trop long <terme> (§2) Le terme dont le début est indiqué fait plus de 32 caractères. Pas de texte pour <terme> (§2) Il n'y a pas de lignes d'explication pour le terme indiqué. Fichier vide <nom> Le fichier indiqué est vide, ou aucun terme n'a été trouvé dans le fichier. Erreur de lecture <nom> Erreur lors d'une lecture du fichier indiqué. Erreur d'écriture <nom> Erreur lors d'une écriture dans le fichier indiqué. Fichier d'index incorrect <nom> (§2, §3.1, §3.3) Le fichier d'index indiqué est incorrect. Vous devez le recréer. Association incorrecte pour <nom> (§4.2) La première ligne du fichier indiqué, qui donne la liste des fichiers associés, est incorrecte (mal écrite). Fichier crypté <nom> (§4.5) Le fichier indiqué a été crypté par PowerPacker.