Chapitre 9 Accès à la documentation en ligne

Ce chapitre explique comment installer et utiliser AnswerBook2^TM pour parcourir la documentation en ligne, y effectuer des recherches et l'imprimer. Il est divisé en plusieurs sections :

• "Présentation du produit AnswerBook2"

• "Où se trouve la documentation ?"

• "Pour commencer"

• "Installation d'un logiciel serveur de documentation"

• "Résolution des problèmes d'AnswerBook2"

Remarque - Le nom de ce produit est Solaris 7 mais le code et le chemin, ou les noms de chemin des modules, peuvent utiliser Solaris 2.7 ou SunOS 5.7. Utilisez toujours le code ou le chemin tel qu'il est \351crit.

Présentation du produit AnswerBook2

Le produit AnswerBook2 est le système de documentation en ligne de Sun. Il utilise une interface de type navigateur Web qui vous permet d'afficher et d'imprimer différentes informations relatives à Solaris^TM, y compris les collections AnswerBook^TM au format SGML, les collections AnswerBook Display PostScript^TM et les pages de manuel.

AnswerBook2 fournit un moteur de recherche qui vous permet d'effectuer des recherches dans l'ensemble de la bibliothèque de documentation. Vous pouvez installer les collections de documents sur un serveur de documentation centralisé ou sur un serveur local.

Dans la documentation relative à AnswerBook2, le terme AnswerBook1 désigne la version du produit AnswerBook fournie avec les versions antérieures à la version 2.6 de l'environnement d'exploitation Solaris.

Caractéristiques et fonctionnalités

AnswerBook2 offre les fonctionnalités et caractéristiques suivantes :

• Vous pouvez visualiser la documentation en ligne à partir de toute plate-forme (et de tout système d'exploitation) capable d'exécuter un navigateur Web compatible HTML 3.2.

• Selon les capacités de votre navigateur Web, vous pouvez copier des informations des documents AnswerBook2 et les coller ailleurs, par exemple sur une ligne de commande.

• Le moteur de recherche permet d'effectuer des recherches sur des mots et des expressions dans l'ensemble de la bibliothèque de documentation.

• Vous pouvez imprimer des chapitres et des manuels directement à partir de l'interface AnswerBook2 dans un format PostScript de grande qualité.

• Une même interface vous permet de visualiser tous les documents AnswerBook, anciens et nouveaux.

• Vous pouvez définir un sous-ensemble de collections de documents (une bibliothèque personnelle) qui s'affichera lorsque vous utiliserez un serveur de documents spécifique.

• Vous pouvez choisir la langue d'affichage des instructions et des informations d'aide.

• L'architecture client-serveur d'AnswerBook2 permet de stocker les documents dans un même emplacement (le serveur) et d'y accéder à partir du bureau de l'utilisateur (client).

• AnswerBook2 fournit une interface de ligne de commande (CLI) et une interface de type navigateur (GUI) pour l'exécution des tâches administratives.

Fonctions introduites avec cette version

La liste suivante répertorie les fonctions ajoutées ou améliorées dans cette version du logiciel AnswerBook2.

• Pages de manuel (Manuel de référence) au format AnswerBook2.

  Les pages de manuel (man) UNIX® traditionnelles sont disponibles au format AnswerBook2. L'interface de recherche vous permet de limiter la recherche aux pages de manuel SGML sur le serveur de documentation.

• Prise en charge des contenus multimédia

  Le système AnswerBook2 vous permet d'accéder aux fichiers audio ou vidéo de la source du document, à condition que votre navigateur soit configuré pour les prendre en charge.

• Exécution d'un serveur d'AnswerBook2 directement à partir du Solaris 7 Documentation CD (administrateurs de serveurs uniquement).

  Vous pouvez exécuter le serveur d'AnswerBook2 directement à partir du Solaris 7 Documentation CD en utilisant le script ab2cd. Vous devez pour cela disposer du CD et d'un accès superutilisateur au système auquel le CD est connecté. Pour plus d'informations sur cette fonction, reportez-vous à la section "Exécution d'un serveur de documentation à partir du Solaris 7 Documentation CD".

• Utilisation de différents serveurs Web basés CGI (administrateurs de serveurs uniquement).

  Le serveur d'AnswerBook2 peut s'exécuter de deux manières : en tant qu'extension NSAPI (en utilisant le serveur inclus dans les modules serveur d'AnswerBook2), ou en tant qu'application basée CGI (en utilisant un serveur httpd supportant CGI, tel que Netscape Server^TM ou Sun WebServer^TM). Pour plus d'informations sur le fonctionnement en tant que serveur Web basé CGI et ses éventuelles restrictions, reportez-vous à la section "Exécution du serveur d'AnswerBook2 en tant que processus CGI".

• Contrôle de l'affichage des erreurs de feuille de style (administrateurs de serveurs uniquement).

  Pour indiquer si le mot "BUG" doit s'afficher en rouge en cas d'erreur de feuille de style, activez ou désactivez la fonction de débogage d'AnswerBook2. Ce réglage est effectué lors du lancement du serveur de documents. Pour plus d'informations, reportez-vous à Lancement et arrêt du serveur de documentation dans l'aide d'AnswerBook2.

Composants

Le produit AnswerBook2 est constitué des éléments suivants :

• Un navigateur Web client : Solaris 7 est fourni avec le navigateur de Netscape ; vous pouvez également utiliser tout navigateur compatible HTML 3.2 pour afficher la documentation en ligne de Sun.

  ---

  Remarque :

  Si vous souhaitez simplement visualiser la documentation en ligne et que vous avez accès à l'URL d'un serveur de documentation, vous n'avez besoin que de cet élément. Tous les autres composants font partie du système serveur de documentation (une machine sur laquelle les collections de documents sont installées et qui exécute un serveur basé Web pour vous les fournir). Si vous n'avez pas accès à un serveur de documentation sur votre site, vous pouvez consulter toute la documentation Solaris publiée à l'adresse suivante : http://docs.sun.com

  ---

• Un serveur de documentation : exécute les fonctions de requête et fournit les documents au navigateur client. Le serveur contient des modèles fournissant une interface cohérente pour l'affichage et l'impression des documents ; il fournit par ailleurs des interfaces d'administration de type navigateur et de type ligne de commande pour les bases de données, l'authentification des mots de passe et autres tâches administratives.

• Des collections de documents : il peut s'agir d'anciens documents (Display PostScript) ou de nouveaux documents (SGML).

Questions les plus fréquentes

Cette section regroupe quelques-unes des questions les plus fréquemment posées sur AnswerBook2 et fournit les réponses correspondantes.

Qu'est-ce qu'AnswerBook2 ?

AnswerBook2 recourt à un serveur de documents normalisé pour vous permettre d'accéder à la documentation en ligne à partir de votre navigateur Web. L'interface d'AnswerBook2 vous permet de parcourir, rechercher et imprimer différents types d'informations Solaris, y compris les collections AnswerBook1 et les pages de manuel.

En quoi AnswerBook2 est-il différent d'AnswerBook ?

La version précédente d'AnswerBook (désormais appelée AnswerBook1) recourait au format Display PostScript pour afficher les versions électroniques de documents initialement conçus pour être imprimés. AnswerBook2 utilise un navigateur Web pour afficher de la documentation au format SGML, conçue pour une consultation en ligne, et pour afficher des documents AnswerBook1 existants.

Les principales différences entre les deux produits sont les suivantes :

• Interface de type navigateur Web : grâce à cette interface, vous pouvez utiliser n'importe quel navigateur compatible HTML 3.2 pour visualiser la documentation en ligne AnswerBook2.

• Souplesse du format des documents source : le serveur d'AnswerBook2 peut fournir des documents AnswerBook1 (Display PostScript^TM) aussi bien que des documents AnswerBook2 (SGML).

• Prise en charge client-serveur : AnswerBook2 vous permet d'installer le serveur et les collections de documents sur un système central et de visualiser les documents à partir d'autres systèmes. Il comprend en outre un mécanisme de "reprise après panne" grâce à laquelle l'administrateur des documents peut définir plusieurs serveurs de documentation pour que les liens entre documents soient toujours fonctionnels.

• Interplates-formes : pour cette version le serveur de documents AnswerBook2 doit s'exécuter dans l'environnement d'exploitation Solaris 7 (SPARC ou Intel). Cependant, les clients d'AnswerBook2 peuvent s'exécuter sur n'importe quelle plate-forme et les futures versions pourront assurer des fonctionnalités de serveur sur d'autres plates-formes.

• Comportement de recherche par défaut : AnswerBook2 utilise ET comme opérateur par défaut pour les recherches au lieu de OU (qui était le comportement de recherche par défaut dans AnswerBook1).

AnswerBook2 me permet-il de visualiser mes anciennes collections AnswerBook ?

Oui, excepté si vos anciens documents AnswerBook ont été créés avant la version 2.2 de l'environnement d'exploitation. Pour ajouter des collections AnswerBook1 à la base de données du serveur d'AnswerBook2, utilisez la fonction d'ajout de collections d'AnswerBook2 et pointez sur le répertoire contenant le fichier ab_cardcatalog d'AnswerBook1.

AnswerBook2 assure-t-il les mêmes fonctionnalités pour les documents AnswerBook1 et les documents AnswerBook2 ?

Non. Dans un souci de cohérence, l'interface d'AnswerBook2 pour les documents AnswerBook1 est semblable à l'interface d'AnswerBook1. Par conséquent, AnswerBook2 présente les différences de fonctionnement suivantes entre les collections d'AnswerBook1 et les collections d'AnswerBook2 :

• Vous ne pouvez pas afficher ou masquer tous les niveaux d'une table des matières d'AnswerBook1, mais seulement une section spécifique de la table.

• Les pages de sommaire AnswerBook1 ne comprennent pas de sections Autres sujets. Pour naviguer d'une page à une autre, vous pouvez utiliser le lien Sujet suivant ou revenir à la table des matières et sélectionner une autre section du livre.

• Les pages de sommaire AnswerBook1 affichent la totalité d'un chapitre en même temps, non des sous-sections du chapitre.

• Les icônes de résultat des recherches reflètent assez mal la probabilité de détection d'informations AnswerBook1 correspondantes ; elles sont le plus souvent soit pleines, soit vides.

• Dans un texte au format AnswerBook1, les termes recherchés ne sont pas mis en évidence.

• Certains graphiques d'AnswerBook1 ne peuvent pas être affichés dans le texte ; ils sont identifiés par une icône qui, lorsque vous cliquez dessus, affiche une image PostScript du graphique.

• Les recherches Pages de manuel par mot clé couvrent uniquement les pages de manuel d'AnswerBook2 (SGML) sur le serveur, pas les pages de manuel d'AnswerBook1.

• Les pages de manuel AnswerBook1 utilisent la même interface que les autres documents AnswerBook1 ; il n'existe pas d'interface spécifique aux pages de manuels.

Où se trouve la documentation ?

Le logiciel du serveur de documents et les collections de documents Solaris 7 se trouvent sur le Solaris 7 Documentation CD. Les schémas de la Figure 9-1 à la Figure 9-6 récapitulent les collections de documents disponibles et identifient les documents qui n'existent qu'en version imprimée.

Figure 9-1 Documentation relative au bureau

Figure 9-2 Documentation de référence (pages de manuel)

Figure 9-3 Documentation d'administration système -- Partie 1

Figure 9-4 Documentation d'administration système -- Partie 2

Figure 9-5 Documentation pour le développeur -- Partie 1

Figure 9-6 Documentation pour le développeur -- Partie 2

Pour commencer

Pour visualiser la documentation en ligne en utilisant le système AnswerBook2, vous avez besoin d'un navigateur compatible HTML 3.2 (tel que HotJava^TM, Netscape Navigator^TM ou Lynx^TM) et d'un accès à un serveur de documentation (une URL identifiant une machine sur laquelle les collections de documents sont installées et qui exécute un serveur basé Web pour vous les fournir). Pour plus d'informations, reportez-vous à :

• "Que faut-il installer ?"

• "Lancement de l'afficheur AnswerBook2"

• "Affichage des informations"

Pour de plus amples détails sur l'utilisation d'AnswerBook2 ou sur l'administration d'un serveur de documentation, accédez à un serveur de documentation et consultez l'aide en ligne.

Que faut-il installer ?

Le tableau suivant vous indique ce que vous devez faire ou installer pour obtenir telle ou telle fonctionnalité d'AnswerBook2.

Lancement de l'afficheur AnswerBook2

Le système lance un navigateur Web avec l'URL du serveur de documents si vous exécutez l'environnement d'exploitation Solaris 2.6 (ou une version supérieure) et que vous :

• Sélectionnez l'icône AnswerBook2 dans le menu Aide du Tableau de bord CDE.

• Sélectionnez AnswerBook2 dans le menu Programmes d'OpenWindows.

• Entrez la commande answerbook2 sur la ligne de commande.

Le système parcourt votre chemin de recherche et lance Netscape Navigator^TM ou le premier navigateur Web qu'il trouve. Pour plus d'informations sur la manière dont le système trouve l'URL du serveur de documentation, reportez-vous à la section "Recherche d'un serveur de documentation".

Vous pouvez également accéder à AnswerBook2 à partir de n'importe quel navigateur Web compatible HTML 3.2. Lancez votre navigateur Web et entrez l'URL d'un serveur documentation approprié. Par exemple, si l'administrateur système a installé le serveur de documentation AnswerBook2 sur le système imaserver, entrez l'URL http://imaserver:8888/.

Affichage des informations

Après avoir lancé l'afficheur AnswerBook2, cliquez sur un texte souligné (si votre navigateur affiche les liens de cette manière) pour accéder à un livre ou un chapitre. Pour plus d'informations sur la navigation dans le système AnswerBook2, consultez l'aide correspondante.

Recherche d'un serveur de documentation

Lorsque vous lancez l'afficheur AnswerBook2 à partir de l'environnement d'exploitation Solaris, le logiciel affiche une liste des collections installées sur le serveur de documentation par défaut. Le serveur par défaut est identifié de la manière suivante :

1. Si vous avez défini la variable d'environnement AB2_DEFAULTSERVER, l'afficheur AnswerBook2 démarre en utilisant l'URL définie par cette variable.

   Par exemple, il est possible que votre fichier .cshrc contienne la ligne suivante :

   setenv AB2_DEFAULTSERVER http://imaserver.eng.sun.com:8888/

2. Si la machine à partir de laquelle vous avez démarré la fonction AnswerBook2 est un serveur de documentation, l'afficheur AnswerBook2 démarre en utilisant l'URL http://localhost:port.

   Où port est le numéro du port sur lequel le serveur de documentation s'exécute (8888 par défaut).

3. Si votre administrateur de documents a enregistré le serveur d'AnswerBook2 avec FNS (Federated Naming Service), l'afficheur AnswerBook2 utilise l'URL du serveur enregistré.

Si aucun serveur de documents n'est disponible, vous pouvez accéder au serveur de documents principal de Sun à l'adresse suivante : http://docs.sun.com/

Installation d'un logiciel serveur de documentation

Cette section décrit les exigences auxquelles vous devez répondre et les décisions que vous devez prendre avant de pouvoir installer le logiciel serveur d'AnswerBook2.

Cette section s'adresse uniquement aux personnes chargées de l'administration d'un système serveur d'AnswerBook2. Les utilisateurs qui souhaitent seulement consulter la documentation en ligne peuvent passer à la section suivante. Il n'y a pas d'installation particulière à faire pour être client d'AnswerBook2.

Ce produit n'effectue pas de contrôle d'accès au niveau client. Si une machine client peut accéder à l'URL de votre serveur de documentation, elle pourra afficher les documents résidant sur ce serveur.

Cette section se compose des paragraphes suivants :

• "Avant d'installer le logiciel serveur"

• "Installation du logiciel serveur d'AnswerBook2"

• "Installation des collections de documents sur le serveur"

• "Enregistrement du serveur"

• "Exécution d'un serveur de documentation à partir du Solaris 7 Documentation CD"

• "Exécution du serveur d'AnswerBook2 en tant que processus CGI"

Pour plus de détails sur l'administration d'un serveur de documentation, utilisez l'aide en ligne disponible à partir de l'interface AnswerBook2 une fois que vous avez installé le logiciel serveur de documentation.

Avant d'installer le logiciel serveur

Avant de lancer la procédure d'installation, vérifiez que votre système répond aux exigences répertoriées dans la section "Configuration matérielle et logicielle requise", et décidez de l'emplacement de votre logiciel en suivant les instructions de la section "Possibilités d'installation".

Configuration matérielle et logicielle requise

Avant de lancer la procédure d'installation, vérifiez que le système sur lequel vous souhaitez installez le serveur d'AnswerBook2 satisfait aux exigences répertoriées dans le Tableau 9-2 et le Tableau 9-3.

En outre, vous devez réserver une certaine quantité d'espace disque (600 Mo recommandés) pour les fichiers des manuels. La quantité exacte d'espace dépend des collections. Pour une liste des collections disponibles sur le Solaris 7 Documentation CD, consultez le fichier README situé sur ce CD.

Possibilités d'installation

Avant d'installer le logiciel serveur d'AnswerBook2, vous devez réfléchir aux différentes possibilités d'installation :

• Installation de tout le logiciel sur un seul système

  Le logiciel du serveur de documentation et les collections de documents Solaris 7 se trouvent sur le Solaris 7 Documentation CD. Si vous installez ces deux parties du serveur sur un même système, une fois que vous aurez terminé l'installation et que vous aurez lancé le serveur, il sera prêt à fournir les documents à tous les clients. Reportez-vous à la section "Installation du logiciel serveur d'AnswerBook2" pour plus d'informations.

• Installation du serveur et de la documentation sur des systèmes distincts

  Vous pouvez installer le logiciel serveur de documentation sur un système et le faire pointer sur des collections de documents se trouvant sur un autre système. Vous pouvez choisir cette option si vous disposez de peu de place sur votre système serveur ou si vous avez déjà des collections de documents sur un autre système. Pour cela, vous devez ajouter chaque collection manuellement dans la base de données du serveur ; la fonction Rechercher les collections installées localement ne les trouvera pas. Reportez-vous à la section "Installation du logiciel serveur d'AnswerBook2" pour plus d'informations.

• Exécution d'un serveur à partir du CD

  Si vous travaillez dans un environnement autonome (autrement dit, qui n'est pas en réseau), ou si vous ne consultez qu'occasionnellement la documentation en ligne, vous pouvez lancer le serveur d'AnswerBook2 directement à partir du Solaris 7 Documentation CD. Un serveur de documentation exécuté à partir du CD sera généralement plus lent qu'un serveur de documentation installé sur votre système. Cette solution est déconseillée si vous pensez que d'autres utilisateurs accéderont à ce serveur de documentation. Pour plus d'informations, reportez-vous à la section "Exécution d'un serveur de documentation à partir du Solaris 7 Documentation CD".

Installation du logiciel serveur d'AnswerBook2

Pour installer le logiciel serveur de documentation, vous pouvez utiliser l'interface de type pointer-cliquer disponible à partir de l'utilitaire Solaris Web Start^TM ou recourir à des outils d'installation standard tels que pkgadd.

1. Insérez le Solaris 7 Documentation CD dans votre lecteur de CD-ROM.

   Le système de gestion des volumes monte automatiquement le CD.

2. Si vous choisissez d'utiliser l'utilitaire Solaris Web Start pour installer vos produits, cliquez deux fois sur l'icône installer, suivez les instructions affichées à l'écran et passez à l'Étape 6.

   L'utilitaire Web Start vous propose d'installer des groupes de modules présélectionnés. Suivez les instructions des écrans de Web Start pour continuer.

3. Si vous choisissez d'utiliser pkgadd ou swmtool, connectez-vous en tant que superutilisateur sur la machine du serveur de documentation.

   Par exemple, entrez la commande suivante sur la ligne de commande :

   % su -

4. Placez-vous dans le répertoire des modules du serveur de documentation.

   Par exemple, vous pouvez entrer une commande similaire à la suivante pour ouvrir le répertoire des modules logiciels du serveur sur un serveur SPARC :

   # cd cdrom/Solaris_2.7_Doc/sparc/Product/

   Où cdrom est le point de montage du CD-ROM (/cdrom/sol_2_7_doc par défaut).

5. Lancez l'utilitaire d'installation et sélectionnez les modules logiciels du serveur à installer.

   Par exemple, utilisez la commande suivante pour lancer l'utilitaire pkgadd :

   # pkgadd -d .

   Sélectionnez les modules logiciels suivants :

   • SUNWab2r (0,25 Mo) : s'installe dans la partition racine et fournit des fichiers de configuration et de démarrage.

   • SUNWab2s (1 Mo) : fournit des fichiers partagés permettant le traitement des documents.

   • SUNWab2u (26 Mo) : fournit des fichiers de traitement exécutables et des fichiers de serveur pour les fonctions de serveur et d'administration.

6. Démarrez le serveur, si nécessaire.

   Suite à l'installation des modules, le serveur doit normalement démarrer sur le port par défaut 8888. Si ce n'est pas le cas, démarrez le serveur à l'aide de la commande suivante :

   # /usr/lib/ab2/bin/ab2admin -o start

7. Installez les collections de livres.

   Votre serveur de documentation ne peut pas remplir son rôle si aucun document n'est installé. Vous pouvez installer des collections de documents à partir du Solaris 7 Documentation CD ou à partir d'autres emplacements, tels que des collections de documents existantes ou des collections provenant d'autres CD. Pour plus d'informations sur l'installation des collections de documents, reportez-vous à la section "Installation des collections de documents sur le serveur".

8. (Facultatif) Modifiez les fichiers de configuration et créez des liens pour exécuter le serveur de documentation en tant que processus CGI sur un serveur httpd existant.

   Si vous exécutez déjà un serveur httpd sur votre système, vous pouvez exécuter le serveur de documentation en tant que processus CGI sur ce serveur. Vous devez installer les logiciels du serveur de documentation standard, puis modifier plusieurs fichiers de configuration et créer des liens pour exécuter le serveur de documentation en tant que processus CGI. Pour plus d'informations, reportez-vous à la section "Exécution du serveur d'AnswerBook2 en tant que processus CGI".

9. (Facultatif) Enregistrez le serveur.

   Si vous voulez que d'autres utilisateurs trouvent automatiquement votre serveur de documentation via les services FNS (Federated Naming Service), vous devez l'enregistrer. Pour enregistrer votre serveur, utilisez la commande suivante :

   # /usr/lib/ab2/bin/ab2regsvr url_serveur

   Où url_serveur est l'URL complète permettant d'accéder à ce serveur (par exemple, http://imaserver.eng.sun.com:8888/). Voir la section "Enregistrement du serveur" pour plus d'informations.

Installation des collections de documents sur le serveur

Votre serveur de documentation ne peut pas remplir son rôle si aucun document n'est installé. Vous pouvez installer des collections de documents à partir du Solaris 7 Documentation CD ou à partir d'autres emplacements, tels que des collections de documents existantes ou des collections provenant d'autres CD.

Pour installer des modules de collection de documents à partir du Solaris 7 Documentation CD, vous pouvez utiliser l'interface de type pointer-cliquer disponible à partir de l'utilitaire Solaris Web Start ou recourir à des outils d'installation standard tels que pkgadd. Pour installer des collections de documents :

1. Insérez le Solaris 7 Documentation CD dans votre lecteur de CD-ROM.

   Le système de gestion des volumes monte automatiquement le CD.

2. Si vous choisissez d'utiliser l'utilitaire Solaris Web Start pour installer vos produits, cliquez deux fois sur l'icône installer, suivez les instructions affichées à l'écran et passez à l'Étape 6.

   L'utilitaire Web Start vous propose d'installer des groupes de modules présélectionnés. Suivez les instructions des écrans de Web Start pour continuer.

3. Si vous choisissez d'utiliser pkgadd ou swmtool, connectez-vous en tant que superutilisateur sur la machine du serveur de documentation.

   Par exemple, entrez la commande suivante sur la ligne de commande :

   % su -

4. Placez-vous dans le répertoire des modules de collections de documents.

   Par exemple :

   # cd cdrom/Solaris_2.7_Doc/common/Product/

   Où cdrom est le point de montage du CD-ROM (/cdrom/sol_2_7_doc par défaut).

5. Lancez l'utilitaire d'installation et sélectionnez les modules de collection de documents à installer.

   Par exemple, pour lancer l'utilitaire pkgadd :

   # pkgadd -d .

   Pour une liste détaillée des collections de documents disponibles sur le Solaris 7 Documentation CD, consultez le fichier README situé sur ce CD.

6. Les modules de collection de documents du Solaris 7 Documentation CD comprennent un script qui peut être exécuté après l'installation pour ajouter des collections à la base de données du serveur et relancer le serveur.

   Si vous installez des modules de collection à partir d'un autre emplacement que le Solaris 7 Documentation CD, vous devrez peut-être utiliser la fonction Ajouter des collections à la liste de la GUI d'administration ou la commande ab2admin -o add_coll pour les ajouter à la base de données du serveur de documentation.

   Si des collections de documents sont déjà installées sur votre système, vous pouvez utiliser la fonction Rechercher les collections installées localement de la GUI d'administration ou la commande ab2admin -o scan pour les rechercher et les ajouter à la base de données du serveur de documentation. Cette fonction concerne uniquement les modules installés localement.

   Pour rendre disponibles des collections de documents résidant sur d'autres systèmes, utilisez la fonction Ajouter des collections à la liste ou la commande ab2admin -o add_coll et entrez le chemin d'accès complet du fichier ab_cardcatalog ou collinfo. Par exemple, si le serveur de documentation est imaserver et que vous voulez qu'il propose les collections de documents résidant sur le système ailleurs, utilisez la commande suivante :

   # /usr/lib/ab2/bin/ab2admin -o add_coll -d /net/ailleurs/books/SUNWdtad/collinfo

Enregistrement du serveur

Pour que vos utilisateurs puissent localiser votre serveur de documentation sans connaître son URL, vous pouvez enregistrer son nom avec le système FNS. Les utilisateurs peuvent toujours avoir accès à des serveurs de documentation non enregistrés s'ils connaissent leurs URL.

La méthode d'enregistrement de votre serveur dépend de deux paramètres :

• Votre connaissance des commandes FNS.

  Si vous connaissez bien les commandes FNS standard, par exemple fnbind, vous pouvez les utiliser pour enregistrer votre serveur. Cependant, pour simplifier la procédure d'enregistrement, vous pouvez utiliser la commande /usr/lib/ab2/bin/ab2regsvr, qui enregistrera votre serveur à votre place. Pour plus d'informations, reportez-vous aux sections "Enregistrement du serveur avec la commande ab2regsvr", et "Enregistrement du serveur à l'aide de commandes FNS standard".

• Le service de noms utilisé.

  NIS+ (Network Information Service Plus) est le principal service de noms utilisé pour les environnements d'exploitation Solaris 2.6 et ultérieurs. Si votre système utilise NIS+ et que vous disposez d'autorisations d'administration, vous pouvez enregistrer le serveur en étant connecté sur le système NIS+ maître ou sur le système NIS+ client.

  NIS (Network Information Service) était le service de noms standard fourni dans les environnements SunOS 4.x (Solaris 1.x). Si votre système utilise NIS, connectez-vous en tant que superutilisateur sur le système NIS maître pour enregistrer le serveur de documentation.

  AnswerBook2 fonctionne également avec un système de noms défini au niveau des systèmes de fichiers (files), dans lequel tous les noms doivent être entrés manuellement dans des fichiers de données. Ces fichiers sont stockés dans le répertoire /var/fn/. Dans ce cas, vous devez disposer d'un accès de superutilisateur au système pour pouvoir enregistrer le serveur. En outre, l'enregistrement s'applique uniquement sur la machine sur laquelle le serveur est enregistré. Les autres machines ne peuvent pas voir un serveur enregistré avec un mécanisme basé sur le système de fichiers.

Enregistrement du serveur avec la commande ab2regsvr

Pour enregistrer votre serveur, utilisez la commande ab2regsvr. La commande ab2regsvr examine la configuration de votre système et définit l'espace de noms approprié à votre serveur.

Pour enregistrer votre serveur, tapez :

# /usr/lib/ab2/bin/ab2regsvr url_serveur

Où url_serveur est l'URL complète permettant d'accéder à ce serveur (par exemple, http://imaserver.eng.sun.com:8888/).

La commande ab2regsvr accepte également quelques options qui peuvent s'avérer utiles :

• Pour afficher une liste des URL des serveurs d'AnswerBook2 enregistrés :

  # /usr/lib/ab2/bin/ab2regsvr -l

• Pour supprimer un serveur enregistré de la liste :

  # /usr/lib/ab2/bin/ab2regsvr -d

• Pour modifier l'URL du serveur d'AnswerBook2 actuellement enregistré :

  # /usr/lib/ab2/bin/ab2regsvr -r url_serveur

  Où url_serveur est la nouvelle URL permettant d'accéder à ce serveur (par exemple, http://aserver.eng.sun.com:8888/). L'URL existante est ainsi remplacée par l'URL spécifiée.

Pour plus d'informations sur la commande ab2regsvr, reportez-vous à la page de manuel ab2regsvr(1m).

Enregistrement du serveur à l'aide de commandes FNS standard

Si vous voulez utiliser des commandes FNS pour enregistrer votre serveur et que vous avez déjà installé FNS sur votre site, utilisez la commande suivante pour enregistrer l'URL spécifiée en tant que serveur de documentation pour votre service (domaine) :

"# fnbind -r  thisorgunit/server/answerbook2 onc_answerbook2 \ onc_addr_answerbook2 
serveur_url"

Où url_serveur est l'URL complète permettant d'accéder à ce serveur (par exemple, http://imaserver.eng.sun.com:8888/).

Pour savoir quels serveurs sont enregistrés, utilisez la commande suivante :

% fnlookup -v thisorgunit/service/answerbook2

Cette commande retourne une liste des serveurs enregistrés qui ressemble à la suivante :

Reference type: onc_answerbook2
 
Address type: onc_addr_answerbook2
 
  length: 19
 
  data: 0x68 0x74 0x74 0x70 0x3a 0x2f 0x2f 0x61 0x6e 0x73  http://ans
 
        0x77 0x65 0x72 0x73 0x3a 0x38 0x38 0x38 0x38       wers:8888

Dans cet exemple, le serveur enregistré est http://answers:8888/.

Une réponse semblable à celle qui suit signifie qu'aucun serveur de documentation n'est enregistré avec FNS.

"Lookup of 'thisorgunit/service/answerbook2' failed: \"" ""Name Not Found: 'answerbook2'"

Pour plus d'informations sur le système FNS, y compris son installation, reportez-vous à la documentation FNS.

Services de noms et utilisateurs d'AnswerBook2

Au lieu d'utiliser les services de noms qui viennent d'être décrits pour rechercher un serveur de documentation, l'utilisateur peut définir un serveur d'AnswerBook2 par défaut à l'aide de la variable d'environnement AB2_DEFAULTSERVER. Par exemple, il peut placer la ligne suivante dans le fichier .cshrc :

setenv AB2_DEFAULTSERVER http://imaserver.eng.sun.com:8888

Si l'utilisateur n'a pas défini de variable d'environnement, lorsqu'il lance AnswerBook2 à partir du bureau, le logiciel AnswerBook2 tente de déterminer si le système à partir duquel il a été lancé exécute un serveur de documentation. Le cas échéant, il s'ouvre en utilisant l'URL : http://localhost:port, où port vaut 8888 par défaut.

Si l'utilisateur n'a pas défini de variable d'environnement et que le système n'est pas un serveur de documentation, lorsqu'il lance AnswerBook2 à partir du bureau, le système exécute une commande fnlookup thisorgunit/service/answerbook2 pour rechercher les serveurs de documentation disponibles. Il en choisit alors un et lance le navigateur AnswerBook2 en utilisant ce nom de serveur comme URL.

Exécution d'un serveur de documentation à partir du Solaris 7 Documentation CD

1. Insérez le Solaris 7 Documentation CD dans votre lecteur de CD-ROM.

2. Vérifiez que vous êtes bien connecté en tant que superutilisateur :

   % su -

3. Placez-vous dans le répertoire racine du volume du CD-ROM (vous pouvez également ouvrir ce répertoire à partir du ).

   Le chemin de ce répertoire doit être similaire au suivant :

   /cdrom/sol_2_7_doc/

   Ce répertoire contient un répertoire, un fichier README, l'utilitaire installer et le script ab2cd. Utilisez le script ab2cd pour exécuter le serveur de documentation directement à partir du CD.

4. Tapez la commande suivante :

   # ./ab2cd

5. Accédez au serveur de documentation en utilisant l'URL :

   http://serveur:8888/

   Où serveur est le nom de la machine auquel le CD-ROM est connecté.

   Notez qu'un serveur de documentation exécuté à partir du CD est toujours exécuté sur le port 8888.

6. (Facultatif) Si des collections de documents sont déjà installées sur votre machine serveur et que vous voulez que le serveur basé CD les reconnaisse, utilisez la commande suivante  :

   # ab2cd -s

   Cette forme de la commande oblige le logiciel serveur basé sur le CD à rechercher les autres collections installées sur ce système et à les ajouter à sa base de données.

7. Pour arrêter l'exécution du serveur à partir du CD, tapez :

   # /cdrom/sol_2_7_doc/ab2cd stop

L'exécution du serveur de documentation directement à partir du CD est généralement assez lente. Cette solution est déconseillée si vous pensez que d'autres utilisateurs accéderont à ce serveur de documentation.

Remarques importantes relatives à l'exécution du serveur d'AnswerBook2 à partir du CD

Lorsque vous exécutez le serveur à partir du CD, n'oubliez pas que :

• Le serveur d'AnswerBook2 s'exécute toujours sur le port 8888 lorsqu'il est exécuté à partir du CD. Si un serveur d'AnswerBook2 s'exécute déjà sur votre système en utilisant le port par défaut (8888), le script ab2cd affichera le message suivant :

  
  
  
  A document server is already running on this system as server:8888.
  
  
  
  
  
  Please shut down the current server before running the ab2cd command.
  
  
  

  Utilisez la commande suivante pour arrêter le serveur en cours d'exécution :

  # /usr/lib/ab2/bin/ab2admin -o stop

• Vous devez toujours utiliser ab2cd stop pour arrêter le serveur exécuté à partir du CD. N'utilisez pas /etc/init.d/ab2mgr stop.

  La commande ab2cd stop arrête le processus du serveur d'AnswerBook2 et efface tous les fichiers des répertoires /tmp/ab2/ et /tmp/ab2cd_config/. La commande /etc/init.d/ab2mgr stop arrête bien tous les processus des serveurs, mais elle ne vide pas ces répertoires.

Remarques relatives à l'exécution de deux serveurs

Tenez compte des points suivants si vous voulez exécuter deux serveurs d'AnswerBook2 (un sur votre système, un à partir du CD) :

• Lancement du serveur

  • La commande /etc/init.d/ab2mgr start lance toujours le serveur sur votre système.

  • La commande ab2cd lance toujours le serveur à partir du CD.

• Arrêt du serveur

  • Utilisez toujours la commande ab2cd stop pour arrêter le serveur exécuté à partir du CD.

  • Pour arrêter les deux serveurs, utilisez d'abord la commande ab2cd stop pour arrêter le serveur exécuté à partir du CD, puis la commande /etc/init.d/ab2mgr stop ou /usr/lib/ab2/bin/ab2admin -o stop pour arrêter le serveur exécuté sur votre système.

Exécution du serveur d'AnswerBook2 en tant que processus CGI

Par défaut, le serveur de documentation AnswerBook2 s'exécute en tant qu'extension NSAPI au-dessus du serveur httpd fourni avec le module SUNWab2u. Le serveur d'AnswerBook2 étant conforme aux protocoles Web standard, vous pouvez exécuter le serveur de documentation en tant que processus CGI (Common Gateway Interface) au-dessus d'un autre serveur Web déjà installé sur votre système (par exemple, Netscape Server ou Sun Web Server).

Notez cependant que les fonctions suivantes seront inopérantes si vous n'utilisez pas le serveur Web d'AnswerBook2 par défaut :

• /usr/lib/ab2/bin/ab2admin -o start ;

• /usr/lib/ab2/bin/ab2admin -o stop ;

• /etc/init.d/ab2mgr start ;

• /etc/init.d/ab2mgr stop ;

• restart (à partir de la GUI d'administration).

Pour utiliser un serveur basé CGI

Les serveurs Web pouvant présenter de légères différences, cette procédure décrit les étapes générales que vous devez suivre pour utiliser un serveur Web basé CGI au lieu du serveur par défaut (extension NSAPI). Vous trouverez ci-dessous des exemples spécifiques aux serveurs Sun Web Server et Netscape Server.

1. Arrêtez le serveur d'AnswerBook2 s'il est en cours d'exécution.

   Utilisez l'une des commandes suivantes :

   "# /usr/lib/ab2/bin/ab2admin -o stop" " ""# /etc/init.d/ab2mgr stop"

2. Modifiez le fichier de configuration de votre serveur Web de façon que les icônes soient disponibles.

   Vous devriez trouver plus d'informations dans la documentation de votre serveur Web, par exemple l'emplacement du fichier de configuration. L'entrée /icons/ doit pointer sur /usr/lib/ab2/data/docs/icons/.

   Si l'entrée /icons/ est déjà utilisée, liez tous les fichiers de /usr/lib/ab2/data/docs/icons/ au répertoire /icons/ existant.

3. Liez les documents de l'aide d'AnswerBook2 au répertoire racine actuel de la documentation.

   Placez-vous dans le répertoire racine de la documentation de votre serveur Web et créez un lien symbolique vers /usr/lib/ab2/data/docs/.

4. Rendez les fichiers cgi-bin d'AnswerBook2 accessibles à votre serveur.

   Placez-vous dans le répertoire cgi-bin de votre serveur Web et créez des liens symboliques vers :

   "/usr/lib/ab2/bin/cgi/admin""""/usr/lib/ab2/bin/cgi/nph-dweb""""/usr/lib/ab2/bin/cgi/gettransbitmap""""/usr/lib/ab2/bin/cgi/getepsf""""/usr/lib/ab2/bin/cgi/getframe""""/usr/lib/ab2/bin/cgi/ab2srwrap"

5. Modifiez le fichier de configuration de votre serveur Web de façon que /ab2/ appelle les répertoires cgi d'AnswerBook2.

   Vous devriez trouver plus d'informations dans la documentation de votre serveur Web, par exemple l'emplacement du fichier de configuration. Vous devrez définir l'entrée /ab2/ à /usr/lib/ab2/bin/cgi/nph-dweb/ab2/.

6. Modifiez le fichier de configuration de l'administration d'AnswerBook2.

   Vous devez éditer le fichier /usr/lib/ab2/bin/cgi/nph-dweb et modifier les entrées de servertype, errorlog et accesslog .

Exécution d'un serveur d'AnswerBook2 en tant que processus CGI sur Sun WebServer

Par défaut, le fichier de configuration de Sun Web Server est /etc/http/httpd.conf et ses fichiers sont stockés dans /var/http/demo/. Si vous n'avez pas installé dans l'emplacement par défaut (/usr/), tous les chemins commençant par /usr/lib/ab2/ doivent être remplacés par des chemins commençant par le chemin où les fichiers sont installés (par exemple, /usr2/lib/ab2/).

1. Editez le fichier /etc/http/httpd.conf et placez la ligne suivante dans sa section server :

   map /icons /usr/lib/ab2/data/docs/icons

   Ensuite, utilisez la commande suivante pour relancer le serveur SWS :

   # /etc/init.d/httpd start

   Entrez l'URL suivante dans votre navigateur Web pour afficher une icône d'aide et vérifier vos modifications :

   http://localhost:port/icons/ab2_help.gif

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

2. Placez-vous dans le répertoire /var/http/demo/public/ et créez le lien symbolique suivant :

   # ln -s /usr/lib/ab2/data/docs/Help Help

   Entrez l'URL suivante dans votre navigateur Web pour afficher une icône d'aide et vérifier vos modifications :

   http://localhost:port/Help/C/Help/books/Help/figures/ab2_help.gif

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

3. Placez-vous dans le répertoire /var/http/demo/cgi-bin/ et créez les liens symboliques suivants :

   # ln -s /usr/lib/ab2/bin/cgi/admin # ln -s /usr/lib/ab2/bin/cgi/nph-dweb # ln -s /usr/lib/ab2/bin/cgi/gettransbitmap # ln -s /usr/lib/ab2/bin/cgi/getepsf # ln -s /usr/lib/ab2/bin/cgi/getframe # ln -s /usr/lib/ab2/bin/cgi/ab2srwrap

   Entrez l'URL suivante dans votre navigateur Web pour afficher la page de bibliothèques d'AnswerBook2 et vérifier vos modifications :

   http://localhost:port/cgi-bin/nph-dweb/ab2

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

4. Editez le fichier /etc/http/httpd.conf et ajoutez la ligne suivante dans sa section host :

   map /ab2 /var/http/demo/cgi-bin/nph-dweb/ab2 cgi

   Relancez le serveur SWS en utilisant la commande suivante :

   # /etc/init.d/httpd start

   Entrez l'URL suivante dans votre navigateur Web pour afficher la page de bibliothèques d'AnswerBook2 et vérifier vos modifications :

   http://localhost:port/ab2

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

5. Editez le fichier /usr/lib/ab2/bin/cgi/nph-dweb et modifiez les entrées suivantes :

   setenv servertype sws setenv errorlog setenv accesslog /var/http/logs/http.elf.1

Exécution d'un serveur d'AnswerBook2 en tant que processus CGI sur Netscape Server

Dans cet exemple, le fichier de configuration de Netscape Server est /ul/netscape/suitespot/httpd-threads1/config/obj.conf et ses fichiers résident dans /ul/netscape/suitespot/docs/. Si vous n'avez pas installé dans l'emplacement par défaut (/usr/), tous les chemins commençant par /usr/lib/ab2/ doivent être remplacés par des chemins commençant par le chemin où les fichiers sont installés (par exemple, /usr2/lib/ab2/).

1. Editez le fichier /ul/netscape/suitespot/httpd-threads1/config/obj.conf et ajoutez la ligne suivante :

   NameTrans fn="pfx2dir" from="/icons" dir="/usr/lib/ab2/data/docs/icons"

   Pour vérifier vos modifications, relancez Netscape Server. Ensuite, entrez l'URL suivante dans votre navigateur Web pour afficher une icône d'aide :

   http://localhost:port/icons/ab2_help.gif

2. Placez-vous dans le répertoire /ul/netscape/suitespot/docs/ et créez le lien symbolique suivant :

   # ln -s /usr/lib/ab2/data/docs/Help Help

   Entrez l'URL suivante dans votre navigateur Web pour afficher une icône d'aide et vérifier vos modifications :

   http://localhost:port/Help/C/Help/books/Help/figures/ab2_help.gif

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

3. Placez-vous dans le répertoire /ul/netscape/suitespot/cgi-bin/ et créez les liens symboliques suivants :

   # ln -s /usr/lib/ab2/bin/cgi/admin # ln -s /usr/lib/ab2/bin/cgi/nph-dweb # ln -s /usr/lib/ab2/bin/cgi/gettransbitmap # ln -s /usr/lib/ab2/bin/cgi/getepsf # ln -s /usr/lib/ab2/bin/cgi/getframe # ln -s /usr/lib/ab2/bin/cgi/ab2srwrap

   Entrez l'URL suivante dans votre navigateur Web pour afficher la page de bibliothèques d'AnswerBook2 et vérifier vos modifications :

   http://localhost:port/cgi-bin/nph-dweb/ab2

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

4. Editez le fichier /ul/netscape/suitespot/httpd-threads1/config/obj.conf et ajoutez l'entrée ligne suivante :

   NameTrans fn="pfx2dir" from="/ab2" dir="/ul/netscape/suitespot/cgi-bin/nph-dweb/ab2" name="cgi"

   Pour vérifier vos modifications, relancez le serveur Netscape et entrez l'URL suivante dans votre navigateur Web pour afficher la page de bibliothèques d'AnswerBook2 :

   http://localhost:port/ab2

   Où port est le numéro du port sur lequel votre serveur de documentation s'exécute (8888 par défaut).

5. Editez le fichier /usr/lib/ab2/bin/cgi/nph-dweb et modifiez les entrées suivantes :

   setenv servertype netscape setenv errorlog /ul/netscape/suitespot/httpd-threads1/logs/errors setenv accesslog /ul/netscape/suitespot/httpd-threads1/logs/access

Résolution des problèmes d'AnswerBook2

Le Tableau 9-4 décrit certains problèmes connus d'AnswerBook2 et suggère des solutions pour les résoudre.

"set"" ""ServerHost imaserver ;#"

"set ServerHost imaserver.eng.sun.com"" "";#"