ADoc - Manuel de référence AboutThisDoc Ce manuel décrit la version 5.02 de l'utilitaire ADoc. Ce programme est Copyright ©1990-1998 par Denis GOUNELLE. Toute utilisation commerciale ou vente sans autorisation écrite de son auteur est strictement interdite. Vous pouvez copier et diffuser ce programme aux conditions suivantes : - l'ensemble des fichiers doit être fourni - aucun fichier ne doit avoir été modifié - vous ne devez pas demander plus de 40FF pour cela Malgré de nombreux tests, je ne peux garantir que ADoc ne contient aucune erreur. VOUS UTILISEZ CE PROGRAMME A VOS RISQUES ET PERILS. Je ne pourrai en aucun cas être tenu pour responsable de tout dommage, direct ou indirect, résultant de l'utilisation de ADoc. Introduction ADoc est un utilitaire permettant de consulter des documents de type "hypertexte". Pour comprendre ce que cela signifie et voir ce dont ADoc est capable, cliquez deux fois sur le mot en gras qui suit : Explication. Vos critiques et suggestions sur ce programme seront toujours les bienvenues. N'hésitez pas à m'écrire, à l'adresse suivante : M. GOUNELLE Denis 27, rue Jules GUESDE 45400 FLEURY-LES-AUBRAIS FRANCE denis.gounelle@wanadoo.fr http://perso.wanadoo.fr/denis.gounelle/index.html Explication FELICITATIONS ! Vous venez de tout comprendre ! Lorsque vous avez cliqué deux fois sur un mot du texte, ADoc est allé chercher automatiquement le texte associé à ce mot dans le fichier de documentation, et a ouvert une nouvelle fenêtre pour vous le montrer. Ce qui rend ADoc différent des autres programmes de ce type : - vous pouvez double-cliquer sur n'importe quel mot du texte, et ADoc partira à sa recherche (adieu les problèmes à cause d'un lien hypertexte non défini par l'auteur du document !) - par conséquent, il n'y a pas besoin de définir de liens dans le document (adieu le casse-tête pour l'auteur, qui devait maintenir les liens hypertexte dans son document !) - ADoc affiche simultanément plusieurs textes à la fois (sauf demande contraire de votre part), gère simultanément plusieurs documents à la fois. - ADoc peut utiliser directement les fichiers aux formats AutoDoc et AmigaGuide. - ADoc contient de nombreuses astuces et fonctions utiles comme la recherche d'un mot dans tous les documents ouverts, un port AREXX, etc... (lisez la documentation, pour une fois !) Installation ADoc est utilisable sur tout Amiga équipé du système 2.04 (V36) ou supérieur. ADoc est désormais localisé, c'est-à-dire qu'il peut s'adapter à la langue par défaut si vous avez le système 2.1 ou plus. Il vous faudra alors copier le fichier catalogue désiré dans le répertoire correspondant à votre langue par défaut. Par exemple, s'il s'agit du français, copiez le fichier "français.catalog" dans le répertoire "SYS:Locale/Catalogs/Français", sous le nom "ADoc.catalog" Normalement, ADoc est fournit avec un script d'installation qui se charge de copier tous les fichiers nécessaires au bon endroit. FormatDesFichiersADoc 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. 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 192 et 253). 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 limités que par la mémoire disponible sur votre système. 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. Lors de l'appel depuis le CLI, vous pouvez indiquer les arguments suivants : PUBSCREEN nom Demande à ADoc d'utiliser l'écran public indiqué. Si cet argument est omis, ADoc ouvrira son propre écran, de la même taille que l'écran du Workbench. REXXPORT nom Indique le nom du port AREXX à ouvrir (sera forcé en majuscules). Si cet argument est omis, ADoc ouvrira un port nommé "ADOC_REXX". ICONNAME titre Indique le nom de l'icône lorsque ADoc est iconifié. OPTIONS MAKEIDX|QUICK|AREXX|ONEWINDOW Précise les options de fonctionnement du programme. 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. AREXX Demande à ADoc de passer en mode AREXX. L'utilisation avec AREXX est détaillée au paragraphe ModeAREXX. ONEWINDOW Demande à ADoc de n'ouvrir qu'une seule fenêtre à la fois. 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. Si le nom indiqué est "REQUEST", ADoc ouvrira une requête de police afin de vous permettre de choisir la police à utiliser. CASE YES|NO Indique à ADoc s'il doit 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. SORT YES|NO Indique à ADoc s'il doit 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 FONT, CASE, SORT, 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 champ "TOOL TYPES" de l'icône du programme, qui peut contenir : PUBSCREEN=nom REXXPORT=nom ICONNAME=titre OPTIONS=[MAKEIDX|QUICK|AREXX|ONEWINDOW] FONT=nom TABSIZE=n SORT=YES|NO CASE=YES|NO 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 : FONT=nom TABSIZE=n SORT=YES|NO CASE=YES|NO Pour plus de détails sur ces options, voir le paragraphe AppelDepuisLeCLI. Notez que ces 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). Si vous n'avez indiqué aucun nom de fichier à ouvrir, ADoc regarde si la variable "ADocFile" est définie : si oui, sa valeur est utilisée. Notez que vous pouvez indiquer plusieurs fichiers dans la variable "ADocFile", de la même façon que depuis la ligne de commande (par exemple: setenv ADocFile "exec.doc dos.doc"). 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 essaiera 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 boîte de requête, indiquant soit la liste des fichiers ouverts, soit la liste des termes de l'unique fichier ouvert. L'utilisation de cette boîte 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 en bas de la requête. 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 , 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 CASE=NO. 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 (sauf en mode AREXX). La requête de terme est en fait capable de vous permettre un choix parmi 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). Pour passer d'une liste à l'autre, appuyez sur la touche . 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. La requête de terme dispose d'un menu avec quatre options : Ouvrir fichier voir paragraphe LeMenuProjet Cherche voir paragraphe Recherche A propos voir paragraphe LeMenuProjet Quitte vous permet de quitter ADoc La requête de terme utilise la police indiquée par le dernier argument FONT. Pour utiliser une police particulière pour cette requête, il suffit donc de rajouter un argument FONT supplémentaire après la liste des fichiers. GestionDesFenêtres Lorsque vous sélectionnez un terme, ADoc ouvre une nouvelle fenêtre pour afficher le texte correspondant. 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. L'ascenseur à droite de la fenêtre vous permettra de faire défiler le texte. Par défaut, les fenêtres disposent des gadgets standards de fermeture, de déplacement, de changement de plan, et de changement de taille. Chaque fenêtre dispose également de trois menus, les menus "Projet", "Outils" et "Options" (ces menus sont décrits aux paragraphes LeMenuProjet, LeMenuOutils et LeMenuOptions). Vous pouvez également contrôler ADoc à l'aide du clavier : ESC ferme la fenêtre courante HAUT défilement d'une ligne vers le haut BAS défilement d'une ligne vers le bas SHIFT-HAUT défilement d'une page vers le haut SHIFT-BAS défilement d'une page vers le bas ALT-HAUT positionnement sur la première page ALT-BAS positionnement sur la dernière page CTRL-HAUT affiche le terme précédent CTRL-BAS affiche le terme suivant Si vous cliquez sur un mot quelconque du texte, 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. Toutes les fenêtres de termes (ainsi que la requête de termes) sont des "AppWindow" (fenêtres d'application). Ceci veut dire que vous pouvez déposer des icônes dessus : le ou les fichiers correspondants à ces icônes seront alors examinés, et ajoutés à la liste des fichiers ouverts. LeMenuProjet Ouvrir fichier Vous permet d'ouvrir un fichier de documentation supplémentaire. Une requête de fichier apparait afin que vous puissiez choisir le fichier à ouvrir. Ouvrir terme Fait apparaître la requête de terme (voir paragraphe RequêteDeTerme). Chercher Vous permet de lancer une recherche (voir le paragraphe Recherche). Iconifier Met ADoc en sommeil : toutes les fenêtres ouvertes disparaissent et ADoc place une icône sur l'écran du Workbench. Pour "réveiller" ADoc, il vous suffit de double-cliquer sur cette icône : toutes les fenêtres seront alors ré-ouvertes. Notez que l'icône utilisée sera celle correspondant au programme : si vous lancez deux fois ADoc depuis deux répertoires différents, avec des icônes différentes, chaque programme aura donc une icône distincte. L'icône est automatiquement déclarée en "AppIcon" (icône d'application). Ceci veut dire que vous pouvez déposer des icônes dessus : le ou les fichiers correspondants à ces icônes seront alors examinés, et ajoutés à la liste des fichiers ouverts. A propos... Affiche quelques informations sur ADoc. Quitter Vous permet de quitter ADoc (avec confirmation). LeMenuOutils Imprimer Imprime le texte contenu dans la fenêtre active. Notez que les éventuelles séquences ANSI seront correctement interprétées par l'imprimante. Sauver en Sauvegarde le texte contenu dans la fenêtre active dans un fichier. Notez que les éventuelles séquences ANSI ne sont pas écrites dans ce fichier. Fermer toutes les fenêtres Vous permet de fermer toutes les fenêtres d'un seul coup. LeMenuOptions Une seule fenêtre Si cette option est sélectionnée, ADoc n'ouvrira qu'une seule fenêtre à la fois. Recherche ADoc est capable de chercher une chaine : - dans le terme courant (demande de recherche depuis le menu d'une fenêtre de texte). Dans ce cas, si vous aviez sélectionné un mot du texte affiché, ce mot sera proposé comme chaine à rechercher. - dans tous les termes d'un fichier (demande de recherche alors que la requête de terme affiche la liste des termes de ce fichier) - dans tous les termes de tous les fichiers (demande de recherche alors que la requête de terme affiche la liste des fichiers). Dans le premier cas, une fois la recherche terminée, le texte est ré-affiché avec toutes les occurences en gras. De plus, l'affichage est décalé pour que la ligne contenant la première occurence apparaisse en haut de la fenêtre. Dans les deux autres cas, une boîte de requête vous informera de l'avancement de la recherche. Le gadget "Arrêter" de cette requête 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 est conservée en mémoire jusqu'à ce que vous lanciez une autre recherche. ConceptsAvancés ADoc permet de définir un alias, c'est-à-dire un moyen d'associer un même texte à plusieurs termes différents, sans avoir à répéter le texte plusieurs fois. Une application pratique de ces alias est par exemple la documentation d'une bibliothèque de fonctions : il arrive souvent que plusieurs fonctions soient définies ensemble. Avec le mécanisme des alias on peut accéder à cette définition par le nom de chacune des fonctions, alors que le texte n'est défini qu'une seule fois. Pour créer un alias, il vous suffit de définir un terme de la façon suivante : nom1 alias nom2 Le premier caractère de "nom1" doit, comme pour toute définition de terme, se trouver en colonne 1. Il doit y avoir au moins un espace ou une tabulation entre les trois mots. Le mot "alias" doit être écrit en minuscules. L'effet de cette définition est le suivant : si l'utilisateur demande à accéder au terme "nom1", ADoc affichera automatiquement le terme "nom2". Les alias apparaissent dans la requête de terme, et sont pris en compte par la fonction de recherche. Notez qu'il n'y a *AUCUN* test de récursivité entre les différents alias ! -------------------- 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"). Sauf si vous avez indiqué un chemin d'accès complet, les fichiers ou répertoires associés sont d'abord cherchés dans le répertoire du fichier qui les appelle, puis dans le répertoire "ADOC:". -------------------- 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 la 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. ModeAREXX ADoc ouvre systématiquement un port AREXX, nommé "ADOC_REXX". Les messages envoyés sur ce port peuvent prendre les formes suivantes : QUIT quitte ADoc HIDE iconifie ADoc SHOW "réveille" ADoc s'il est iconifié REQUEST fait apparaître la requête de terme TOFRONT fait passer l'écran de ADoc au premier plan TOBACK fait passer l'écran de ADoc au dernier plan FIND terme lance la recherche du terme indiqué, et affiche le texte correspondant s'il est trouvé OPEN fichier ouvre le (ou les) fichier(s) de documentation indiqué(s) CLOSEALL ferme toutes les fenêtres Voici un exemple de programme AREXX, qui demande de l'aide sur le terme "alias" : /* Demande de l'aide sur "alias" */ ADDRESS "ADOC_REXX" "FIND alias" IF RC = 10 THEN SAY "non trouvé !" 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 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. Support_des_fichiers_AutoDoc ADoc est capable de reconnaitre et d'utiliser directement les fichiers au format AutoDoc. Les différentes variantes du format de ces fichiers sont gérées de façon transparente. Support_des_fichiers_AmigaGuide ADoc est capable de reconnaitre et d'utiliser les fichiers au format AmigaGuide. Comme ADoc ne permet pas d'utiliser des espaces dans les noms de termes, ceux-ci sont remplacés par un caractère souligné. Les liens dans le texte sont affichés en gras. Les noms étant tronqués à 32 caractères, il pourra arriver que certains liens ne fonctionnent pas. Les commandes @TAB et @FONT (globales et locales), la commande @TITLE, les changements de style de police, les liens vers un fichier externe, et le caractère d'échappement '\' sont automatiquement pris en compte. Sauf si l'option "QUICK" a été indiquée au démarrage, ADoc affichera automatiquement le noeud "MAIN" à l'ouverture du fichier. Historique v5.00, 06-Apr-97, 75108 octets o Programme entièrement ré-écrit en C++ avec le SAS/C 6.57. o Nouvelle interface utilisant la "gadtools.library". o Peut être lancé sur n'importe quel écran public. o Possibilité d'utiliser une police différente pour chaque fichier. o Nouvelle gestion de l'iconification. o Support des fichiers AutoDoc et AmigaGuide amélioré. o Toutes les fenêtres sont des "AppWindow". o Montre la progression de la construction de l'index, de la recherche d'une chaine. v5.01, 25-Aug-97, 75188 octets o Erreur corrigée dans la gestion des arguments reçus du Workbench (chargeait tous les "tool types", sans vérifier s'il s'agissait d'options reconnues par ADoc). o Gadgets OK/CANCEL de la requête de recherche et gadget CANCEL de la requête de progression agrandis. v5.02, 24-Jan-97, 75460 octets o Détermine la taille des fenêtres à partir de la taille visible de l'écran (et non de la taille totale). o Si aucun fichier n'est indiqué au démarrage et que la variable ADocFile n'est pas définie, ouvre une requête de fichier.