Description des Principaux Macros Trac

Table of Contents

1. BackLinks
2. FootNote
3. Image
4. Redirect
5. TitleIndex
6. TOC

Vous avez utilisé un macro, il vous semble utile, n'hésitez pas à mettre quelques lignes décrivant son utilisation et un exemple. Les macros décrits ici ne sont que les quelques macros les plus couramment utilisés par les sites Trac hébergés au LAL. La liste complète des macros installés au LAL peut être obtenu en utilisant le macro suivant dans une page wiki:

[[?]]

Pour utiliser un macro dans une page Trac, il faut mettre le nom du macro entre [[ ]]. Si un macro reçoit des arguments, les mettre entre parenthèses après le nom du macro. Par exemle :

[[TOC(inline)]]

Pour connaitre l'ensemble des arguments acceptés par un macro, utiliser la syntaxe suivante:

[[Macro?]]

Par exemple, pour le macro TOC:

[[TOC?]]

BackLinks

Ce macro permet d'afficher une liste de référence à d'autres pages du projet qui référence la page indiquée en argument. Par exemple :

[[BackLinks(titleindex)]]

retourne la liste de tous les documents qui référencent une page titleindex (sans distinction minuscule/majuscule). Par exemple :

Exemple pour afficher les références à la page courante :

---

Pages linking to Doc/Wiki/Macros:

• Doc/Macros
• Doc/ProjStruct
• Doc/Wiki
• TOC

FootNote

Le Macro FootNote permet de gérer des notes de bas de page. Il permet à la fois de créer de nouvelles notes en les indexant automatiquement et de référencer une note existance en donnant son index. Il faut appeler le macro sans argument pour causer l'insertion des notes de bas de page dans le texte (à la fin du texte par exemple). Ci-dessous un exemple illustrant l'utilisation de ce macro :

Some text [[FootNote(This is a footnote)]]

This foot-note refers to the first[[FootNote(1)]].

...

Listing the foot-notes in this page:

[[FootNote]]

Image

Le macro Image permet d'afficher une image dans la page. Il peut être utilisé avec les pages WiKi ou les tickets. Les images doivent se trouver soit dans l'attachement d'une page, soit dans le repository Subversion.

Le premier argument est obligatoire et doit contenir le nom du fichier. Sans chemin, cela correspond à un fichier attaché à la page courante. Si l'image correspond à un fichier attaché à une autre page, un ticket, au repository subversion, il faut spécifier son chemin en utilisant une des notations décrites dans les exemples.

On peut indiquer d'autres paramètres pour spécifier la taille ou la position. Les différents types d'arguments possibles sont :

• Un nombre éventuellement suivi d'une unité (accolée) est interprété comme la taille ou l'échelle de l'image (ex. 120, 25%).
• right, left, top or bottom indiquent l'alignement de l'image.
• key=value indique un attribut de l'image.
• key:value indique le style de l'image.

Quelques exemples :

  [[Image(photo.jpg)]]                          # simplest
  [[Image(photo.jpg,120px)]]                    # with size
  [[Image(photo.jpg,right)]]                    # aligned by keyword
  [[Image(photo.jpg,align=right)]]              # aligned by attribute
  [[Image(photo.jpg,float:right)]]              # aligned by style
  [[Image(photo.jpg,border:solid 5px green)]]   # with any style

  [[Image(OtherPage/foo.bmp)]]                  # if current module is wiki
  [[Image(base/sub/bar.bmp)]]                   # from hierarchical wiki page
  [[Image(3/baz.bmp)]]                          # if in a ticket, point to #3
  [[Image(ticket/36/boo.jpg)]]
  [[Image(file/images/bee.jpg)]]

Si on souhaite inclure des images dans la page courante sans qu'elles apparaissent dans la liste des fichiers attachés de la page, une solution est de créer une page dédiée à l'attachement des images, par exemple Images et de référencer les images de cette page.

Voilà ce que ça peut donner :

[Note : l'option size sous la forme 120px semble ne pas marcher. -CH]

[[Image]]

Embed an image in wiki-formatted text.

The first argument is the file specification. The file specification may reference attachments in three ways:

• module:id:file, where module can be either wiki or ticket, to refer to the attachment named file of the specified wiki page or ticket.
• id:file: same as above, but id is either a ticket shorthand or a Wiki page name.
• file to refer to a local attachment named 'file'. This only works from within that wiki page or a ticket.

The file specification may also refer to:

• repository files, using the source:file syntax (source:file@rev works also).
• files, using direct URLs: /file for a project-relative, //file for a server-relative, or http://server/file for absolute location. An InterWiki prefix may be used.
• embedded data using the ​rfc2397 data URL scheme, provided the URL is enclosed in quotes.

The remaining arguments are optional and allow configuring the attributes and style of the rendered <img> element:

• digits and unit are interpreted as the size (ex. 120px, 25%) for the image
• right, left, center, top, bottom and middle are interpreted as the alignment for the image (alternatively, the first three can be specified using align=... and the last three using valign=...)
• link=some TracLinks... replaces the link to the image source by the one specified using a TracLinks. If no value is specified, the link is simply removed.
• inline specifies that the content generated be an inline XHTML element. By default, inline content is not generated, therefore images won't be rendered in section headings and other one-line content.
• nolink means without link to image source (deprecated, use link=)
• key=value style are interpreted as HTML attributes or CSS style indications for the image. Valid keys are:
  • align, valign, border, width, height, alt, title, longdesc, class, margin, margin-(left,right,top,bottom), id and usemap
  • border, margin, and margin-* can only be a single number (units are pixels).
  • margin is superseded by center which uses auto margins

Examples:

[[Image(photo.jpg)]]               # simplest
[[Image(photo.jpg, 120px)]]        # with image width size
[[Image(photo.jpg, right)]]        # aligned by keyword
[[Image(photo.jpg, nolink)]]       # without link to source
[[Image(photo.jpg, align=right)]]  # aligned by attribute

You can use an image from a wiki page, ticket or other module.

[[Image(OtherPage:foo.bmp)]]    # from a wiki page
[[Image(base/sub:bar.bmp)]]     # from hierarchical wiki page
[[Image(#3:baz.bmp)]]           # from another ticket
[[Image(ticket:36:boo.jpg)]]    # from another ticket (long form)
[[Image(source:/img/bee.jpg)]]  # from the repository
[[Image(htdocs:foo/bar.png)]]   # from project htdocs dir
[[Image(shared:foo/bar.png)]]   # from shared htdocs dir (since 1.0.2)

Adapted from the Image.py macro created by Shun-ichi Goto <gotoh@…>

Redirect

Le macro Redirect permet de renvoyer sur une autre page. Il est très utile quand on réorganise un site et qu'on souhaite que certaines anciennes URLs (correspondant aux anciennes pages) continuent à fonctionner. La syntaxe est:

[[Redirect(wiki:New/Page)]]

Ce macro doit absolument être la première ligne de la page. La redirection n'est pas exécutée lors de la modification de la page mais uniquement lors des consultations ultérieures. Pour éditer la page d'origine, il faut éditer l'URL en utilisant ce qui est indiqué dans le redirectedfrom et en ajoutant ?action=edit.

Note : par compatibilité avec un autre plugin qui implémentait différemment la même fonctionnalité, il est possible d'utiliser aussi bien redirect que Redirect.

Il est possible de rediriger une page Wiki sur quelque chose d'autre qu'une page Wiki (fichier, ticket...)n en utilisant une des syntaxes TracLinks. Par exemple :

[[redirect(wiki:OtherWikiPage)]]
[[Redirect(wiki:OtherWikiPage)]]
[[redirect(source:/trunk/file.py)]]
[[Redirect(source:/trunk/file.py)]]
[[redirect(http://www.example.com/)]]
[[Redirect(http://www.example.com/)]]

TitleIndex

Ce macro construit une liste de toutes les pages du wiki ou d'une arborescence de pages. Son utilisation typique est:

[[TitleIndex(format=hierarchy)]]

Ce macro s'enrichit beaucoup au fil des versions. Pour une liste de toutes les options:

[[TitleIndex?]]

[[TitleIndex]]

Insert an alphabetic list of all wiki pages into the output.

Accepts a prefix string as parameter: if provided, only pages with names that start with the prefix are included in the resulting list. If this parameter is omitted, all pages are listed. If the prefix is specified, a second argument of value hideprefix can be given as well, in order to remove that prefix from the output.

The prefix string supports the standard relative-path notation when using the macro in a wiki page. A prefix string starting with ./ will be relative to the current page, and parent pages can be specified using ../.

Several named parameters can be specified:

• format=compact: The pages are displayed as comma-separated links.
• format=group: The list of pages will be structured in groups according to common prefix. This format also supports a min=n argument, where n is the minimal number of pages for a group.
• format=hierarchy: The list of pages will be structured according to the page name path hierarchy. This format also supports a min=n argument, where higher n flatten the display hierarchy
• depth=n: limit the depth of the pages to list. If set to 0, only toplevel pages will be shown, if set to 1, only immediate children pages will be shown, etc. If not set, or set to -1, all pages in the hierarchy will be shown.
• include=page1:page*2: include only pages that match an item in the colon-separated list of pages. If the list is empty, or if no include argument is given, include all pages.
• exclude=page1:page*2: exclude pages that match an item in the colon- separated list of pages.

The include and exclude lists accept shell-style patterns.

TOC

TOC est un macro très puissant qui permet de construire une table des matières ou un title index.

Le macro TOC accepte les options suivantes :

Argument	Description
heading=<x>	Change la légende par défaut ("Table of Contents")
noheading	Supprime la légende
depth=<n>	Affiche les sections de niveau <= n
inline	Affiche le TOC dans le texte et non pas dans un menu
titleindex	Affiche le nom de la page et son titre (similaire à TitleIndex)

Ainsi :

        [[TOC(inline)]]

produira une table des matières de la page courante, en supprimant le titre de la page (contenu entre =), au fil du texte de la page. Sans le paramètre inline, la table des matières sera affiché dans une menu.

Tandis que :

        [[TOC(titleindex,inline)]]

affichera une liste de toutes les pages (leur nom) avec leur titre ayant le même parent que la page courante.

Dans les deux cas, les options peuvent être suivies d'une liste de pages explicite. Dans le premier cas, les sections de toutes les pages indiquées seront utilisées pour construire une table des matières unique. Dans le deuxième cas (title index), sera affiché l'ensemble des pages ayant pour parents les pages indiquées (il faut mettre un / à la fin du nom de la page si on ne veut pas afficher le parent).

Voir la liste des pages relatives à Trac pour un exemple.