Le manuel de référence canonique de Csound

Le manual de référence de Csound est écrit en DocBook v4. Pour apprendre à utiliser Docbook aller sur docbook.org.

Si vous rencontrez des problèmes ou si vous avez des suggestions, ouvrez un ticket, ou faites un fork de cet entrepôt et un pull request.

Instructions spécifiques au manuel de Csound

Les instructions des sections suivantes se rapportent à DocBook en général, pas au manual de Csound en particulier. Pour produire le manuel de Csound à partir des sources, il faut adapter ces instructions générales. Après s'être assuré que l'on a installé les outils et dépendances nécessaires (comme indiqué dans les sections suivantes), il faut obtenir les fichiers sources pour le manuel de Csound et lancer ensuite la commande make pour générer une version du manuel à partir de ces fichiers source. Les fichiers source comprennent un fichier Makefile qu'il faudra peut-être adapter à votre configuration.

Si l'on a installé Csound dans ~/csound/csound et que l'on veuille (1) installer les sources du manuel de Csound dans ~/csound/manual-fr et (2) construire une version html dans ~/csound/manual/html, il faut exécuter les commandes suivantes :

$ cd ~/csound
$ git clone https://github.com/csound/manual-fr.git manual-fr
$ cd manual-fr
$ make html # En supposant que le Makefile fonctionne. Sinon, il faut l'éditer
            # puis réexécuter cette ligne.

Note: sur Ubuntu, le Makefile peut ne pas fonctionner car il appelle Python avec la commande python au lieu de python3. Dans ce cas, il faut soit (1) mofidier le Makefile afin d'appeler python3 (le nom de l'exécutable pour Python dans Ubuntu) ou (2) installer python-is-python3, un paquet d'adaptation pour Debian et Ubuntu qui crée un lien symbolique de python à python3.

Après avoir suivi les instructions ci-dessus, il sera possible d'ouvrir le manuel localement dans un navigateur avec un lien comme file:///home/(username)/csound/manual-fr/html/index.html.

General Instructions for Docbook and Related Programs

En plus d'autres outils spécifiques à ce qu'on construit, on a besoin de Docbook, Python avec Pygments v2.3 ou ultérieure ; et xsltproc.

Linux

Pour installer DocBook, les feuilles de style requises et xsltproc, sur un système basé sur Debian (y compris Ubuntu), exécuter

sudo apt-get install -y docbook docbook-xsl xsltproc

Python est préinstallé sur la plupart des distributions Linux. Si l'on a pas Python, aller sur https://www.python.org/downloads/ pour apprendre comment installer Python ou le construire à partir des sources.

Pour installer Pygments v2.3 ou ultérieure, exécuter

sudo pip install 'pygments>=2.3'

ou si l'on a pas pip,

sudo easy_install 'pygments>=2.3'

MacOS

La manière la plus simple d'installer DocBook est sans doute via Homebrew. Pour installer Homebrew, suivre les instructions sur https://brew.sh). Puis taper brew install docbook docbook-xsl dans un terminal.

Pour installer Pygments v2.3 ou ultérieure, taper dans un terminal

sudo easy_install 'pygments>=2.3'

Python et xsltproc sont préinstallés sur macOS.

Windows

La manière la plus simple d'installer DocBook est sans doute via Cygwin. Pour installer Cygwin aller sur https://www.cygwin.com et télécharger et exécuter un installeur pour la dernière version de Cygwin.

Pour installer Python, aller sur https://www.python.org/downloads/windows/ et télécharger et exécuter un installeur de Python 2.7. Ne pas oublier d'ajouter python.exe dans le path de Windows.

Aller sur http://pygments.org/download/ pour apprendre comment installer Pygments.

Construire le manuel

Exécuter make ⟨cible⟩ pour construire une ⟨cible⟩. Par exemple, pour construire une collection de pages HTML, exécuter make html.

On peut voir cette erreur : “The XSL_BASE_PATH variable must be set to the XSL stylesheets installation directory.” Pour indiquer à make où trouver les feuilles de style XSL de DocBook, exécuter

make XSL_BASE_PATH=path/to/docbook/stylesheets ⟨cible⟩

au lieu de make ⟨cible⟩. Par exemple, sur macOS exécuter

make XSL_BASE_PATH="$(brew --prefix docbook-xsl)/docbook-xsl" ⟨target⟩

Si un message d'erreur indiquant que CsoundDocumentLexer est introuvable pour construire une ⟨cible⟩, c'est que vous utilisez probablement Pygments v2.0.2 ou antérieure, et vous avez besoin de [Pygments v2.3 ou ultérieure](#Outils nécessaires).

HTML

Exécuter make html (ou seulement make) pour créer un répertoire nommé html contenant une collection de fichiers HTML.

PDF

En plus des outils nécessaires, la construction des fichiers PDF nécessitent FOP d'Apache. Il peut être aussi nécessaire de télécharger et d'installer un Java Runtime Environment.

Pour installer FOP sur Linux, exécuter

sudo apt-get install -y fop

Pour installer FOP sur macOS avec Homebrew, exécuter

brew install fop

Exécuter make pdf pour créer un fichier PDF adapté à l'impression sur du papier letter.

Exécuter make pdfA4 pour créer un fichier PDF adapté à l'impression sur du papier A4.

Aide HTML compilée

On ne peut construire une [aide HTML compilée] (https://en.wikipedia.org/wiki/Microsoft_Compiled_HTML_Help) que sur Windows. En plus des outils nécessaires il faut utiliser le HTML Help Workshop. Pour installer le HTML Help Workshop, aller sur https://go.microsoft.com/fwlink/?LinkId=14188 pour télécharger htmlhelp.exe et double-cliquer ensuite sur htmlhelp.exe.

Exécuter make htmlhelp pour créer un fichier d'aide HTML compilée (.chm).

Editer le manuel

DocBook est en XML. Lorsque l'on écrit du XML, il ne faut pas oublier de fermer les balises. Voici du XML valide :

<para>texte</para>

alors que celui-ci ne l'est pas :

<para>texte</ERROR>

DocBook v4 a une définition de type de document (DTD) qui décrit les éléments valides de DocBook et leurs attributs. Voir DocBook: The Definitive Guide pour en savoir plus.

Ajouter une entrée d'opcode

En général, une entrée pour un nouvel opcode nommé newopcodename sera un fichier XML nommé newopcodename.xml contenant

<refentry id="newopcodename">
    <!-- More mark-up… -->
</refentry>

On peut commencer à documenter un opcode en prenant une entrée existante comme modèle. Toutes les entrées des opcodes sont dans le répertoire opcodes. On peut aussi utiliser opcodes/templates.xml comme point de départ.

Pour incorporer une nouvelle entrée dans le manuel :

1. Ajouter l'entrée comme une entité dans manual.xml. Par exemple, si l'on dépose newopcodename.xml dans le répertoire opcodes, il faut ajouter cette entité dans manual.xml :

   <!ENTITY opcodesnewopcodename SYSTEM "opcodes/newopcodename.xml">

2. Utiliser l'entité pour ajouter l'entrée de l'opcode à opcodes/top.xml. Les entrées des opcodes y étant rangées par ordre alphabétique, trouver où insérer l'opcode dans la liste et ajouter :

   &opcodesnewopcodename;

3. Faire un lien vers cet opcode depuis une section appropriée du manuel. Par exemple, si newopcodename doit être inclus avec les opcodes de traitement spectral en temps réel, ajouter un élément link à spectral/realtime.xml, comme ceci :

   <link linkend="newopcodename"><citetitle>newopcodename</citetitle></link>

Répéter cette étape pour chaque section dans laquelle votre opcode devrait être inclus.

4. On peut aussi utiliser facultativement un élément refentryinfo pour que l'opcode soit correctement référencé dans la référence rapide. Utiliser une des catégories dans categories.py. Si l'on omet l'élément refentryinfo, l'opcode sera référencé dans la catégorie Divers.)

5.Si possible, ajouter un élément link à l'opcode dans la section appropriée de Opcodes Overview.

Maintenance

Il y a plusieurs cibles pour préparer les fichiers d'une distribution. Bien mettre à jour le numéro de version dans manual.xml et dans Makefile afin que les fichiers soient générés avec ce numéro. Il est aussi utile de mettre à jour la section Les nouveautés … pour chaque distribution.