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

Question

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:", 
 ":Package Version:", ":Copyright:", ":Keywords:", ":Source:", 
 ":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.

Answer 1

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.

Answer 2

Here are some findings after I investigated a bit.

Header/tag information

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.