4

When mentioning names of programs or LaTeX 2e-packages or document classes or files within questions/answers—what is the best way of typesetting/emphasizing them?

I often see such names emphasized by means of backtick escapes in situations where they are not (parts of) a snippet of code.

I tend to refrain from using backtick escapes in such situations.

Is it sufficient in such situations to turn such names into links that point to resources where more information about the programs/packages/document classes/files in question can be found?

Should emphasizing in such situations be done by means of italic ?

Should emphasizing in such situations be done by means of bold?

E.g., the following phrase does not exhibit whatsoever code but it refers to the document class article:

"The document class article does not provide means for dividing documents into chapters."

E.g., the following phrases do also exhibit snippets of code:

"The document class article does not provide means for dividing documents into chapters. You can have LaTeX 2e load that document class by placing the command \documentclass{article} into the preamble of the source code of your document."

  • Er, they are code: for example, in \usepackage{siunitx} the name is clearly siunitx. Granted, in package documentation I'd use \textsf, but that's not an option here ... – Joseph Wright♦ May 25 '19 at 15:01
  • 3
    @UlrichDiez: Why not? "The document class article does not have the \chapter-command." works just as well. – Werner May 25 '19 at 16:05
  • @Werner Because here the word "article" is not (part of) a snippet of code while the word "\chapter" can be taken for a snippet of code. – Ulrich Diez May 25 '19 at 16:11
  • 1
    I always use backticks to things that would relate to code (much on the reasoning of Joseph's comment). I confess, however, that I don't follow a rule strictly, and sometimes write article and some times article. I could agree with using italics as well but not with bold (I think it's too much and would be distracting). And I think that providing links for each package mentioned in an answer would be tiresome. I do so only when I feel that it's necessary, like a little known, or recently released package. – Phelype Oleinik May 25 '19 at 20:33
  • 1
    @UlrichDiez: It's part of \documentclass{article}. In a similar way, one would probably use ieeetran compared to IEEE Transactions document class/template; elsarticle compared to Elsevier journal article class. – Werner May 25 '19 at 20:56
  • 1
    Related on SO Meta: meta.stackoverflow.com/questions/266239/… (against code formatting), meta.stackoverflow.com/questions/369566/… (neutral wrt. to code formatting) meta.stackoverflow.com/questions/303145/… (favors italics). And on SE Meta meta.stackexchange.com/questions/246900/… (code formatting), – Marijn May 27 '19 at 7:56
  • 1
    meta.stackexchange.com/questions/215472/… (no formatting). But both SO Meta and SE Meta are usually rather rigid in interpreting rules, in this case "if it's not code it should not use code formatting". – Marijn May 27 '19 at 8:02
  • 2
    I myself think that it is not code (because it is the name of a package or class, the fact that these names can be used as an argument in code is not very relevant), but still I use code formatting for it because it makes the name stand out and it conveys the idea that a package is a 'technical' thing. – Marijn May 27 '19 at 8:05
  • @Marijn Thanks for those links. I think the problem with the SO position is they are mainly talking about clearly 'technical' terms, whereas something like 'article' , 'beamer' or even 'siunitx' doesn't really work without some form of markup. (As I've noted, in LaTeX documentation, most people use \textsf for package names, but that's in a roman body text situation.) – Joseph Wright♦ May 27 '19 at 10:16
4

On linking to CTAN specifically, I tend to think that the first occurrence of a package or class name may need to linked. This will come down to how well-known the package is, whether the context suggests the reader may need the link, etc.

For example, for core LaTeX material, I would only link if there was a strong reason: say pointing to clsguide. For an answer where the question already mentions a package or class, I would not link (the reader presumably knows about the package), again unless there is a strong reason. On the other hand, if I'm suggesting a package that the question does not mention, and that is not so well-known as to be trivial, I would generally link on the first mention.

  • 1
    When a question mentions a package, very often I link to the documentation in my answer, something like "as mentioned on page 6 in the siunitx manual". Arguably the formatting is not ideal, but I think it is still (marginally) better than linking only the word manual or siunitx. – Marijn May 27 '19 at 13:23
9

I think backticks such as article are fine, the word is not the usual English word "article", it is a fragment of latex syntax, the argument to \documentclass. Linking to ctan is (a) harder to achieve as you have to look up the link and add it by hand, and (b) is not clearly helpful to the reader as for most classes (and certainly article) if you are fetching it from ctan then something is wrong.

  • Perhaps a user might nonetheless find the link helpful if they want to fetch the package's documentation from ctan? – Rosie F Jun 8 '19 at 15:26
  • @RosieF they almost certainly have it installed locally already if they have the package. texdoc article in texlive for example will open a copy of the documentation for article class. – David Carlisle Jun 8 '19 at 15:28
0

One option is to link to the tag here, ie: (using [tag:tagging]).

  • A possible disadvantage is that the site thinks it is a tag, it has a tooltip show questions tagged 'tagging' and when clicked it leads to a page without questions (unless the highlighted term is a tag, of course, which for many packages coincidentally is the case). – Marijn Jun 6 '19 at 14:56
  • @Marijn Yes, I meant for existing tag, I thought I picked the tagging-tag from the tag-list but weirdly it comes out empty. – morbusg Jun 6 '19 at 15:19
  • But usually you don't want to link to the tag I think? The idea of highlighting a package name is to make clear it is a package name, which looks strange if you just type it as regular text - and maybe link to CTAN, or to the manual, or to Github, maybe even to another specific question about the package, but not very often to the general list of questions that have the tag corresponding to the package. – Marijn Jun 6 '19 at 16:24
  • @Marijn Well my thought was specifically to link to the tag. A short, well thought-out description with possibly a link to CTAN; I mean, what else one could hope for? – morbusg Jun 6 '19 at 18:18
  • 4
    -1 I can understand for disagreeing, but a vote to DELETE?!? What the hell?!? – morbusg Jun 6 '19 at 18:22
  • 1
    +1 for learning about the [tag:...] syntax – siracusa Jun 7 '19 at 11:23

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .