6
$\begingroup$

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.

$\endgroup$
2
  • $\begingroup$ Take a look here: mathematica.stackexchange.com/q/695/12 $\endgroup$
    – Szabolcs
    Mar 2 '15 at 4:09
  • $\begingroup$ @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. $\endgroup$
    – halirutan
    Mar 2 '15 at 4:25
2
$\begingroup$

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.

$\endgroup$
1
$\begingroup$

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

enter image description here

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.

$\endgroup$

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.