AboutThisDoc Ce manuel décrit la version 1.00 de l'utilitaire ADoc2. Ce programme est placé dans le domaine public, avec autorisation de le copier librement et de le diffuser par n'importe quels moyens, à 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. "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 William Hawes. Malgré 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. >>> FERMEZ CETTE FENETRE POUR CONTINUER <<< Introduction ADoc2 est une nouvelle version de ADoc, qui a été ré-écrit entièrement afin de supprimer certaines limitations et de pouvoir ajouter plusieurs améliorations. Notez que certaines incompatibilités sont apparues, notamment au niveau des arguments. Ce programme fonctionne de la même façon sous les versions 1.3 et 2.04 du système. ADoc est un utilitaire permettant de gérer des documentations sur n'importe quel sujet. Il est capable de lancer automatiquement la recherche d'un mot désigné à la souris, et peut travailler sur plusieurs fichiers à la fois. ADoc peut également utiliser directement les fichiers AutoDoc de Commodore, ainsi que des fichiers compactés à l'aide de l'utilitaire "PowerPacker". 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 et à Helmut J. ESENWEIN pour leurs nombreuses suggestions, ainsi qu'à Simon HEWINSON pour la traduction en anglais du fichier "amiga.doc". Remerciements particuliers à Jean-Philippe RAPP pour ses idées, et pour m'avoir permis de tester ADoc sur les fichiers AutoDoc. PrincipesDeFonctionnement ADoc travaille à partir de fichiers de documentation, qui associent un texte à un mot-clé (appelé "terme" dans cette documentation). A chaque fichier de documentation est associé un fichier d'index, qui permet d'accéder presque instantanément aux termes recherchés (notez que ceci a pour conséquence qu'il faudra reconstruire le fichier d'index à chaque modification du fichier de documentation). Seul le fichier d'index est chargé en mémoire lors de l'utilisation. Le nom du fichier d'index est obtenu en ajoutant le suffixe ".index" au nom du fichier de documentation. Les fichiers de documentation, que vous pouvez créer vous-même à l'aide de votre éditeur de texte favori, sont constitués d'une série de définitions, chaque définition ayant la syntaxe suivante : terme première ligne de texte seconde ligne de texte etc... n-ième ligne de texte Dans un premier temps, considérez que les deux premières lignes du fichier doivent être vides (ou à la rigueur commencer par un espace ou une tabulation). Il est absolument indispensable que le premier caractère du terme soit en colonne 1, et que les lignes de texte commencent par un espace ou une tabulation. Les lignes vides sont autorisées. NOTE IMPORTANTE : Le format des fichiers de documentation n'est plus le même que pour les version 3.xx et 4.xx. Un terme ne peut faire plus de 32 caractères, et ne peut contenir ni espaces ni tabulations : les caractères autorisés sont les lettres minuscules et majuscules, les chiffres, le souligné et les caractères accentués (codes ASCII compris entre 217 et 246). Il est cependant possible d'étendre le jeu des caractères autorisés si besoin (voir paragraphe ConceptsAvancés). Le nombre de termes par fichier, et de lignes de texte par terme, ne sont pas limités (ou plutôt, cette limite est si grande que vous serez à court de mémoire bien avant). La longueur maximale d'une ligne de texte est de 256 caractères. Afin de mettre en valeur certaines parties du texte, vous pouvez utiliser les séquences ANSI suivantes : ESC[1m début caractères gras ESC[3m début caractères italiques ESC[4m début caractères soulignés ESC[22m fin caractères gras ESC[23m fin caractères italiques ESC[24m fin caractères soulignés ESC[0m caractères normaux AppelDepuisLeCLI ADoc peut s'utiliser aussi bien depuis le CLI que depuis le Workbench. Dans les deux cas, le fichier de documentation par défaut est "Amiga.doc" mais vous pouvez évidemment choisir un autre fichier. Lors de l'appel depuis le CLI, vous pouvez indiquer les arguments suivants : WBENCH Demande à ADoc d'utiliser l'écran du Workbench. Si cet argument est omis, ADoc ouvrira son propre écran, de la même taille que l'écran du Workbench. En cas d'erreur lors de l'ouverture de cet écran, ADoc passera automatiquement sur l'écran du Workbench. LACE Demande à ADoc d'utiliser un écran en mode entrelacé. Si vous avez demandé à utiliser l'écran du Workbench, et que cet écran n'est pas en mode entrelacé, cet argument sera ignoré. FONT nom Demande à ADoc d'utiliser la police de caractères indiquée, plutôt que la police par défaut. Le nom doit être de la forme , par exemple "topaz8". ADoc est capable d'utiliser n'importe quelle police non proportionnelle, pourvu que sa taille soit d'au moins 8. Si ADoc ne peut ouvrir la police demandée, il essayera d'utiliser la police par défaut. Si cette police ne convient pas, ou si ADoc ne peut l'ouvrir, il essayera d'accéder à la police Topaz, en taille 8. S'il échoue, le programme s'arrêtera immédiatement. MAKEIDX Indique à ADoc que la seule opération à effectuer est la création des fichiers d'index. QUICK Demande à ADoc de ne pas afficher le texte associé au terme "AboutThisDoc" au démarrage. Normalement, à chaque fois que ADoc ouvre un fichier, il cherche le terme "AboutThisDoc" dans ce fichier puis, s'il existe, affiche le texte correspondant et attend que l'utilisateur ferme la fenêtre pour continuer. AREXX Demande à ADoc de passer en mode AREXX. L'utilisation avec AREXX est détaillée au paragraphe ModeAREXX. NOCASE Demande à ADoc de ne pas différencier minuscules et majuscules lors de la gestion des fichiers. Cela ne concernera que les fichiers dont le nom est indiqué après cette option. NOSORT Demande à ADoc de ne pas trier l'index des fichiers dont le nom est indiqué après cette option. TABSIZE n Indique la taille des tabulations pour les fichiers dont le nom est indiqué après cette option. La taille par défaut est de 8. Tout autre argument est considéré comme un nom de fichier de documentation à utiliser. Vous pouvez indiquer plusieurs fichiers, en séparant les noms par des espaces ou par une virgule (par exemple "ADoc fichier1 fichier2" ou "ADoc fichier1,fichier2"). Vous pouvez mélanger noms de fichiers et options, mais n'oubliez pas que les options NOCASE, NOSORT, et TABSIZE ne concerneront que les fichiers indiqués après ces options. ADoc ouvrira les fichiers dans l'ordre indiqué. A moins que vous n'indiquiez un chemin complet, les fichiers sont recherchés d'abord dans le répertoire courant, puis dans le répertoire "ADOC:". Si vous indiquez un nom de répertoire au lieu d'un nom de fichier, tous les fichiers de ce répertoire (à l'exception des fichiers ".info" et ".index") seront ouverts. AppelDepuisLeWorkbench Depuis le Workbench, vous pouvez appeler ADoc de plusieurs façons : - en double-cliquant sur l'icône de ADoc (le fichier de documentation par défaut sera utilisé) - en double-cliquant sur l'icône d'un fichier qui a ADoc comme outil par défaut (champ "DEFAULT TOOL") - en cliquant sur les icônes de plusieurs fichiers, tout en gardant la touche SHIFT appuyée, puis en double-cliquant sur l'icône de ADoc. Dans tous les cas, ADoc commence par examiner le champs "TOOL TYPES" de l'icône du programme, qui peut contenir : FONT=nom OPTIONS=[WBENCH][LACE][MAKEIDX][QUICK][AREXX] Pour plus de détails sur ces options, voir le paragraphe AppelDepuisLeCLI. Notez que les noms des options doivent être séparés par un caractère "|". ADoc ouvre ensuite les fichiers de documentation éventuellement indiqués exactement de la même façon que lors de l'appel depuis le CLI (notamment vous pouvez indiquer un répertoire au lieu d'un fichier), à la différence que le champ "TOOL TYPES" de chaque icône est examiné, et peut contenir : TABSIZE=n OPTIONS=[NOCASE][NOSORT] Pour plus de détails sur ces options, voir le paragraphe AppelDepuisLeCLI. Notez que ces trois options ne concerneront que le fichier correspondant à l'icône. DémarrageDuProgramme Comme expliqué dans les deux paragraphes précédents, ADoc commence par ouvrir le (ou les) fichier(s) indiqué(s). Lors de cette phase, ADoc tente également de charger le fichier d'index correspondant à chaque fichier de documentation. Si le fichier d'index est introuvable, ADoc vous proposera de le créer. Si vous refusez, ce fichier de documentation ne sera pas utilisable, mais ADoc essayera quand même d'ouvrir les autres fichiers. Si ADoc détecte que le fichier de documentation a été modifié après la création de l'index, il vous proposera de mettre le fichier d'index à jour. Si vous refusez, le fichier de documentation sera quand même ouvert, mais ADoc pourra détecter des erreurs ultérieurement si le contenu de ce fichier a été changé. Notez que la date de création du fichier d'index est mémorisée dans le fichier d'index lui-même. Une fois tous les fichiers ouverts, ADoc affiche une boite de requête, indiquant la liste des termes du premier fichier ouvert. L'utilisation de cette boite de requête est décrite au paragraphe RequêteDeTerme. RequêteDeTerme Vous pouvez désigner un terme à l'aide de la souris, en cliquant dessus. Le terme s'affiche alors dans une autre couleur. Si vous cliquez une seconde fois sur ce terme, la requête disparait et ADoc affiche le texte correspondant au terme dans une fenêtre. L'utilisation de ces fenêtres est décrite au paragraphe GestionDesFenêtres. Vous pouvez également vous servir du clavier pour faire votre choix. Si vous appuyez sur une lettre quelconque, cette lettre sera ajoutée au "préfixe" courant (affiché dans le rectangle en dessous de la liste des termes), et l'affichage de la liste des termes se fera à partir du premier terme commençant par ce préfixe. ADoc complètera ce préfixe le plus possible. Si vous appuyez sur la touche (au dessus de la touche ), le dernier caractère du préfixe sera effacé et l'affichage de la liste mis à jour également. Si vous appuyez sur la touche , ADoc affichera le texte correspondant au premier terme commençant par le préfixe. Notez que ADoc ne différenciera pas minuscules et majuscules si le fichier courant a été indiqué après une option NOCASE. Vous pouvez fermer la requête sans rien choisir, en appuyant sur la touche ou en cliquant sur le gadget de fermeture. Si aucune autre fenêtre n'est ouverte à ce moment, le programme s'arrêtera. La requête de terme est en fait capable de vous permettre un choix parmis trois listes : la liste des termes du fichier courant, la liste des fichiers (à condition qu'il y ait plusieurs fichiers ouverts) et la liste des termes trouvés lors de la dernière recherche (à condition qu'une recherche ait déjà été effectuée, voir paragraphe Recherche). La lettre écrite dans le coin inférieur droit de la requête vous indique quelle liste est affichée : liste des termes (T), liste des fichiers (F), liste des termes trouvés (S). Pour passer d'une liste à l'autre, appuyez sur le bouton droit de la souris tout en appuyant sur une des touches SHIFT. Lorsque la liste des fichiers est affichée et que sélectionnez un des fichiers de cette liste, ADoc repasse automatiquement à la liste des termes et affiche la liste des termes du fichier que vous avez choisi. Si aucune autre fenêtre n'est ouverte, la requête de terme dispose d'un menu avec trois options. La premiere vous permet de lancer une recherche (voir paragraphe Recherche), la seconde vous permet d'iconifier ADoc (voir paragraphe LeMenuProjet) et la dernière vous permet de quitter ADoc. GestionDesFenêtres Lorsque vous sélectionnez un terme, ADoc ouvre une fenêtre pour afficher le texte correspondant. Si le terme est défini plusieurs fois dans le même fichier, ou dans plusieurs fichiers différents, toutes les lignes de texte seront mises à la suite les unes des autres, et affichées dans une seule fenêtre. La hauteur de la fenêtre dépend du nombre de lignes à afficher. S'il y a trop de lignes, seule la première page sera affichée et ADoc ajoutera deux gadgets en forme de flèches (dans le coin supérieur droit) à la fenêtre, pour vous permettre de faire défiler le texte. Bien entendu, il est possible d'avoir plusieurs fenêtres ouvertes à la fois. Par défaut, les fenêtres disposent des gadgets standards de fermeture, de déplacement, de changement de plan, et de changement de taille. Si vous modifiez la taille d'une fenêtre, ADoc ajoutera ou enlevera automatiquement les gadgets en forme de flèches suivant les besoins. Chaque fenêtre dispose également de trois menus, les menus "Projet", "Outils" et "Spécial" (ces menus sont décrits aux paragraphes LeMenuProjet, LeMenuOutils et LeMenuSpécial). Notez enfin que vous pouvez fermer une fenêtre en appuyant sur la touche , et utiliser les touches et du curseur pour faire défiler le texte page par page. Si vous cliquez sur un mot quelconque, ce mot sera affiché dans une couleur différente. Si vous cliquez une seconde fois sur ce mot, ADoc lancera automatiquement la recherche du terme correspondant, dans tous les fichiers ouverts. En cas d'échec l'écran flashera, sinon une nouvelle fenêtre apparaitra. LeMenuProjet Autre terme Fait apparaitre la requête de terme (voir paragraphe RequêteDeTerme). Imprime Imprime le texte contenu dans la fenêtre active. Notez que les éventuelles séquences ANSI seront correctement interprétées par l'imprimante. Iconifie Met ADoc en sommeil : si ADoc avait ouvert son propre écran celui-ci est fermé, puis toutes les fenêtres disparaissent et ADoc ouvre une petite fenêtre en haut de l'écran du Workbench. Si vous cliquez sur le gadget de fermeture de cette fenêtre, ADoc vous demandera confirmation avant de quitter. Pour "réveiller" ADoc, activez la fenêtre et appuyez sur le bouton droit de la souris. Normalement, ADoc garde en mémoire toutes les lignes de texte afin de pouvoir remettre rapidement toutes les fenêtres en place lors de son réveil. Ceci a l'inconvénient de ne pas libérer toute la mémoire possible aussi, lorsque vous lui demanderez de s'iconifier, ADoc vous demandera si vous voulez fermer toutes les fenêtres. Si vous répondez oui, la mémoire sera complètement libérée, et lorsque vous réveillerez ADoc, il affichera la requête de terme. A propos... Affiche quelques informations sur ADoc. Cliquez à l'intérieur de la fenêtre ou appuyez sur une touche pour continuer. Quitter Vous permet de quitter ADoc (avec confirmation). LeMenuOutils Ecran avant Permet d'utiliser ADoc sur un écran déjà ouvert (par exemple celui de votre éditeur de texte). Il vous suffit de mettre l'écran sur lequel vous voulez placer ADoc au premier plan, puis de le faire glisser vers le bas pour dévoiler l'écran où est ADoc. Sélectionnez alors cette option : ADoc ferme toutes les fenêtres ouvertes, ferme éventuellement son écran, et ré-ouvre les fenêtres sur l'écran au premier plan. NOTE IMPORTANTE : Vous aurez certainement droit à une visite du "Gourou" si l'écran où vous avez placé ADoc est fermé avant que vous ayez quitté ADoc (ou que vous l'ayez placé sur un autre écran) Notez que cette commande ne marchera pas si vous n'avez pas indiqué de police de caractères à utiliser (voir paragraphe AppelDepuisLeCLI) et que la police de l'écran au premier plan ne convient pas. Ferme tout Vous permet de fermer toutes les fenêtres d'un seul coup. Après vous avoir demandé confirmation, ADoc fermera les fenêtres et affichera la requête de terme. Cherche Vous permet de lancer une recherche (voir le paragraphe Recherche). Information Affiche le nombre de fichiers et de termes disponibles, ainsi que le nombre de fenêtres ouvertes et de lignes affichées. Cliquez sur le gadget "Ok" pour continuer. LeMenuSpécial Ouvre fichier Vous permet d'ouvrir un fichier de documentation supplémentaire. Une requête de fichier apparait afin que vous puissiez indiquer le fichier à ouvrir. Notez que les fichiers ".info" et ".index" ne sont pas affichés dans cette requête. Ferme fichier Vous permet de fermer le fichier courant (c'est-à-dire le fichier où est défini le terme affiché dans la fenêtre active). Après vous avoir demandé confirmation, ADoc fermera toutes les fenêtres correspondant à ce fichier puis fermera le fichier. Notez que cette commande ne marchera que si au moins deux fichiers sont ouverts. Recherche ADoc est capable de chercher jusqu'à quatre chaines simultanément dans les lignes de texte, puis d'afficher la liste des termes correspondants. Lorsque vous sélectionnez l'option "Cherche" du menu "Outils", une fenêtre apparait avec quatre gadgets de chaine. Il y a également un gadget "ANNULER" pour abandonner l'opération, un gadget "VALIDER" pour lancer la recherche, et un menu "Options" : min = MAJ Demande à ADoc de ne pas différencier les minuscules des majuscules lors de la recherche. Toutes chaines Normalement, ADoc cherche tous les termes qui contiennent une des chaines que vous avez entré. Cette option vous permet de chercher au contraire les termes qui contiennent TOUTES les chaines indiquées. Tous fichiers Demande à ADoc de faire la recherche dans tous les fichiers ouverts, et non seulement dans le fichier courant. Lorsque vous lancez la recherche, ADoc fait défiler les noms des termes au fur et à mesure. Le gadget "Arrêter" vous permet d'interrompre la recherche. Une fois la recherche terminée, l'écran flashera si aucun terme n'a été trouvé. Sinon, la requête de terme apparaitra, et affichera la liste des termes trouvés. Cette liste est triée, et elle est conservée en mémoire jusqu'à ce que vous lanciez une autre recherche. ConceptsAvancés ADoc est capable d'associer automatiquement plusieurs fichiers de documentation. Il vous suffit d'indiquer le (ou les) noms des fichiers à associer sur la première ligne du fichier auquel vous voulez les associer. Si cette ligne reste vide, ou commence par un espace ou une tabulation, son contenu est ignoré. Les noms peuvent être séparés par des espaces ou par une virgule. Vous pouvez indiquer un nom de répertoire, auquel cas tous les fichiers de ce répertoire seront ouverts (sauf les fichiers ".info" et ".index"). Pour étendre le jeu des caractères pouvant être utilisés dans un terme, il vous suffit d'indiquer les caractères supplémentaires sur le seconde ligne du fichier de documentation. Si cette ligne reste vide, ou commence par un espace ou une tabulation, son contenu est ignoré. Sinon, tous les caractères de cette ligne (jusqu'au premier espace, tabulation, barre de fraction ou saut de page) sont ajoutés au jeu de caractères par défaut. Notez que cette extension du jeu de caractères ne concernera que ce fichier. ADoc est capable de charger directement des fichiers compactés par "PowerPacker", à condition que la bibliothèque "powerpacker.library" se trouve dans le répertoire "LIBS:". Il n'est pas nécessaire de créer le fichier d'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:". L'utilisation de fichiers compactés peut donc poser des problèmes de mémoire, particulièrement si le répertoire "T:" se trouve sur le disque "RAM:". Le fichier temporaire sera détruit après sa fermeture. 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 quand même conseillé de vérifier leur format : il doit y avoir au moins deux lignes vides au début, suivies de la table des matières, et chaque terme doit commencer en colonne 1. Dans certains cas, il manque les lignes vides au début, et les termes commencent en colonne 2, précédés par un caractères "saut de page" (CTRL-L). Le programme "AutoConvert", distribué avec ADoc, vous permettra de convertir ces fichiers au bon format (Note: ce programme ne peut s'utiliser que depuis le CLI). Dans tous les autres cas, il vous faudra convertir les fichiers "à la main". ModeAREXX ADoc ouvre systématiquement un port compatible AREXX, nommé "ADoc_rexx". Les messages sur ce port sont attendus en même temps que les messages Intuition sur les fenêtres de texte, et peuvent prendre les formes suivantes : quit quitte ADoc request fait apparaitre la requête de terme fscreen fait passer ADoc sur l'écran au premier plan ?terme lance la recherche du terme indiqué, et affiche le texte correspondant s'il est trouvé Tout autre message sera ignoré. Voici un exemple de programme AREXX, qui demande de l'aide sur le terme "alias" : /* Demande de l'aide sur "alias" */ address "ADoc_rexx" "?alias" Notez les guillemets autour des commandes ! Si vous lancez ADoc avec l'option AREXX, le fonctionnement du programme sera un peu différent : une fois le(s) fichier(s) de documentation ouvert(s), ADoc n'ouvrira pas la requête de terme mais affichera le message "En attente d'un message AREXX" et attendra des messages sur le port AREXX (ou CTRL-C pour quitter). De plus, lorsque la dernière fenêtre sera fermée, le programme ne se terminera pas mais repassera en attente de messages AREXX. LesMessagesDeADoc Lorsqu'une erreur se produit, ADoc affiche dans une petite fenêtre un nom (de fichier en général) et un code d'erreur. Ce code d'erreur est soit un code d'erreur AmigaDOS soit un code interne. Dans le premier cas, reportez-vous à votre manuel de l'AmigaDOS (ou utilisez la commande "Fault") pour avoir plus de détails sur ce code d'erreur. Les codes d'erreur internes sont : -1 fichier vide -2 erreur de lecture -3 fichier incorrect (mauvais format, etc...) -4 fichier compacté, et "powerpacker.library" absente -5 problème lors du décompactage Vous pouvez répondre à toutes les requêtes de ADoc soit, normalement, à la souris, soit à l'aide d'équivalents clavier : appuyez sur la touche correspondant à l'initiale du texte dans le gadget (par exemple "o" ou "O" pour "Oui"). Vous pouvez aussi appuyer sur pour sélectionner la réponse "positive" ou sur pour sélectionner la réponse "négative".