Comment citer des symboles dans une chaîne de documentation?

8

Dans la documentation Emacs Lisp, je rencontre souvent des symboles entre guillemets comme à l' `buffer-file-name'intérieur de docstrings. Ce qui est intéressant ici, c'est le style de la citation, en entourant le nom du symbole d'un tiret et d'une citation. J'étais curieux de savoir d'où venait ce style. Selon cette réponse, cela pourrait être lié à un jeu de caractères limité.

Une autre chose à noter est que ces symboles entre guillemets sont surlignés dans la syntaxe emacs-lisp-mode, tandis que les symboles entre guillemets simples, par exemple, "nom-fichier-tampon", ne reçoivent pas de surbrillance syntaxique.

Cela indique donc que la syntaxe des guillemets inversés doit être une convention bien connue dans Emacs. Mais après avoir googlé la documentation, je n'ai pu la trouver mentionnée nulle part. Dans le manuel Emacs Lisp, il y a une section nommée "Astuces pour les chaînes de documentation" ; ça dit

Lorsqu'une chaîne de documentation fait référence à un symbole Lisp, écrivez-la comme elle serait imprimée (ce qui signifie généralement en minuscules), avec des guillemets simples autour d'elle.

mais il ne mentionne pas le style de citation.

Tapez C-h f thing-at-point RETpuis cliquez sur le lien vers le code source pour voir d'autres exemples du style de citation:

(defun thing-at-point (thing & optionnel no-properties) "Renvoie la
chose au point. THING doit être un symbole spécifiant un type d'
entité syntaxique. Les possibilités incluent` symbol ', `list',` sexp ',
`defun' , "nom de fichier", "url", "email", "mot", "phrase", "espace",
"ligne", "numéro" et "page".

Lorsque l'argument facultatif NO-PROPERTIES n'est pas nul, supprimez les
propriétés de texte de la valeur de retour.

Voir le fichier `thingatpt.el 'pour la documentation sur la façon de définir un
symbole comme une chose valide."

Donc, tout cela donne une indication qu'il faut utiliser le style de guillemet arrière pour citer des symboles, mais ce style est-il documenté quelque part?

Håkon Hægland
la source
1
Êtes-vous plus intéressé par la recherche de documentation sur les «symboles entre guillemets», ou voulez-vous savoir à quoi ils servent? Dans ce dernier cas, c'est à des fins de référence croisée: vous pouvez cliquer sur ces symboles dans le tampon d'aide, et cela vous amènera au tampon d'aide correspondant au symbole sur lequel vous avez cliqué.
Dan
1
Remarque: si vous utilisez une police avec des caractères unicode, vous pouvez modifier le tableau d'affichage pour utiliser de meilleurs caractères pour les guillemets. Alternativement, vous pouvez utiliser le verrouillage de police pour reconnaître le cas spécial du «symbole».
Lindydancer

Réponses:

11

La convention est documentée dans la section que vous avez déjà référencée (Tips for Documentation Strings). Le but des citations est mentionné et des exemples sont fournis:

 Help mode automatically creates a hyperlink when a documentation
 string uses a symbol name inside single quotes ... For example, if
 you write

      This function sets the variable `buffer-file-name'.

Cela ressemble à la chose qui vous intéresse, c'est pourquoi single quotesdans ce contexte signifie vraiment

`this' 

plutôt que

'this'

Cette représentation des guillemets gauche et droit utilisant le backtick ASCII (accent grave) et le guillemet simple (apostrophe) semble avoir été une convention UNIX commune à un moment donné, et en tant que tel, je soupçonne que cela ne valait pas la peine d'être expliqué davantage lorsque le manuel Emacs était écrit.

Selon cet article , les anciennes polices et polices à terme du système X Window faisaient ressembler ces symboles à de vraies citations.

glucas
la source