Description des Principaux Macros Trac

TOC(inline)

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 :

BackLinks(titleindex)

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

BackLinks()

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]

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.

Il est possible de rediriger une page Wiki sur quelque chose d'autre qu'une page Wiki (fichier, ticket...).

[[Redirect]]

This Trac plug-in implements a server sided redirect functionality. The user interface is the wiki macro Redirect (alternatively redirect).

Description

Website: ​https://trac-hacks.org/wiki/ServerSideRedirectPlugin

This plug-in allow to place a redirect macro at the start of any wiki page which will cause an server side redirect when the wiki page is viewed.

This plug-in is compatible (i.e. can be used) with the client side redirect macro TracRedirect but doesn't depend on it. Because the redirect is caused by the server (using a HTTP redirect request to the browser) it is much faster and less noticeable for the user. The back-link feature of TracRedirect can also be used for server side redirected pages because both generate the same URL attributes.

To edit a redirecting wiki page access its URL with ?action=edit appended. To view the page either use ?action=view, which will print the redirect target (if TracRedirect isn't active, which will redirect the wiki using client side code), or ?redirect=no which disables redirection of both the ServerSideRedirectPlugin and TracRedirect plug-in.

Direct after the redirect target is added (or modified) Trac will automatically reload it, as it does with all wiki pages. This plug-in will detect this and not redirect but display the wiki page with the redirect target URL printed to provide feedback about the successful change. However, further visits will trigger the redirect.

Usage Examples

The following 'macro' at the begin of the wiki page will cause a redirect to the OtherWikiPage.

[[redirect(OtherWikiPage)]]
[[Redirect(OtherWikiPage)]]

Any other TracLink can be used:

[[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/)]]

[[redirect]]

See macro Redirect.

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.