# Annotation specifier like :Author: and sectioning like ::Section:: in package code

In packages, there is a special way to make basic formatting and annotation within normal comments. Here is another question related to annotation. Package file headers usually contain information like this

(* :Name: BoundaryRegionPlot *)
(* :Title: Boundary Region Plot. *)
(* :Author: Mark Sofroniou *)


Most commonly used are the following

{":Name:", ":Title:", ":Author:", ":Summary:", ":Context:",
":Mathematica Version:", ":Limitation:", ":Discussion:"}


Additionally, you can create sections, and subsections in the following way

(* ::Section:: *)
(* Precedence *)


But even more obscure things like ::Section::Closed:: as described here seem possible.

Question: Is there a definite syntax guide about the rules, conventions and what is possible? I haven't found something on a quick search.

• Take a look here: mathematica.stackexchange.com/q/695/12 Mar 2, 2015 at 4:09
• @Szabolcs This didn't came up when I searched for it. Unfortunately, the answer by J.M. doesn't work anymore in 10. And it is still not exactly clear, what the rules for the annotations are. Restrictions in naming, etc.. But your post is still very helpful. Mar 2, 2015 at 4:25

I'm not aware of a definitive guide.

Something towards what is possible is at Stack Exchange which I use from a button to create a skeletons of notebooks & packages. From memory I was inspired by the report generation procedures which were introduced at the time.

Of course, YMMV.

Here are some findings after I investigated a bit.

In the case of the tag or header information that are in the form :Identifier:, there does not exist a definite rule. In fact, after searching the whole AddOns directory, it turns out that some packages use Author while others use Authors. The same is true for Example/Examples, Source/Sources or Warning/Warnings.

Additionally, there are some obscure tags like :STYLESHEETS: in the file NotebookDiff.m. This all looks like you can use them almost freely to tag some comment. Here is a list of the different tags I have found:

{"Author", "Authors", "Compute Clusters", "Context", "Copyright",
"CVS Keywords", "Discussion", "Example", "Examples", "Exports", "Future",
"History", "Keywords", "Limitation", "Limitations",
"Mathematica Version", "Name", "NewComputeKernels", "Note",
"Package Version", "Reference", "Requirements", "SGEJavaLibs", "Source",
"Sources", "STYLESHEETS", "Summary", "Tests", "Title", "Version",
"Warning", "Warnings"}


## Style/Section markup

In the case of e.g. ::Section::, it seems that you can use all styles that are available. Not only the sectioning style are possible, you can even use ::SubsubitemNumbered::. There is one important thing: You must put the markup in a single comment with exactly one space around it like here:

(* ::SubsubitemNumbered:: *)
(*Test*)


For me in Linux, this is vitally important if you want the Front End to render it correctly. Line breaks in the final front end output are possible by creating a new comment in the next line:

(* ::Chapter:: *)
(*Chapter with a*)
(*line break.*)
`

This will create

Do not try to span one single comment over several lines. That doesn't seem to work.

If a style you use does not exist, then it is displayed in the FE as a usual comment.