# Listing all usage messages from a loaded package

I am writing several packages in collaboration with others. In order to help the group use my packages, I want to provide them with a simple reference of function names and usage messages. How can I best do this?

Although I didn't originally ask for it, I'd like to be able to do the following:

1. save the function names with their usage messages
2. into some text-based file (e.g. LaTeX, HTML, markdown, plain text)
3. that organizes the functions under section headings that specify which package they came from.

Here's what it might look like in plain text:

PackageName1

function1 :: does something
function2 :: does something else

PackageName2

function3 :: does it do something?
function4 :: does, perhaps, something


Formatted versions like LaTeX that require compiling are, perhaps, less useful to the community, but they just look so nice :)

-
If you type in ?Your-package-context* and evaluate, you will get all your symbols listed as links, which, when clicked, will open usage message for a given symbol. Depending on what you want, this may or may not be sufficient. – Leonid Shifrin May 11 '14 at 21:00
You could #::usage & /@ Names["context*"] too. Related topic: 38605 – Kuba May 11 '14 at 21:17
Thank you both. @LeonidShifrin, that's great to know. I still want something more like Kuba's response. It didn't quite work for me, though. Here's how I got it working: (#::usage) & /@ Symbol /@ Names["entropy*"] (had to convert the heads to Symbol). I'm going to adapt this and answer my question with a one-liner. +1 to you both, and thanks, again. – Rico Picone May 11 '14 at 22:55
@RicoPicone You're right, I should have tried it :P – Kuba May 11 '14 at 22:57

A bit cleaner I believe:

Cases[
MakeExpression @@ {Names @ "entropy*"},
_[s_] :> Row[{HoldForm[s], " :: ", s::usage}]
]

• If you need a String rather than a Row expression you can use ToString @ Row[ but first try it this way.

• Unlike your code this will work even if Symbols have OwnValues assignments.

-
Wizard, this is great. I'm exporting the result to a file for my collaborators, so I believe I need the String version. – Rico Picone May 11 '14 at 23:47
@Rico What kind of file / format? There may be a more direct way than ToString. – Mr.Wizard May 11 '14 at 23:48
Wizard, I'm still trying to decide. I was considering a nicely formatted LaTeX, but I'm open to anything (html, markdown, plain text). Do you have a good suggestion? I also need to solve the problem of adding sections to the document based-on which package it comes from. – Rico Picone May 11 '14 at 23:55
@Rico No suggestion off hand. Why don't you update your question with an example of the output you'd like (graphically if nothing else). (Normally changing the nature of your question after you receive answers is discouraged, but I'm the only one to answer so far and I'm OK with that.) – Mr.Wizard May 11 '14 at 23:58
Mr. Wizard, I edited my original question. – Rico Picone May 12 '14 at 0:14

Thanks to the comment by @Kuba, I was able to write this complex "one" line, which is what I wanted.

(#::usage) & /@ Symbol /@ Names["entropy*"] //
MapThread[StringJoin, {(# <> " :: ") & /@ Names["entropy*"], #}] &


If you have any suggestions to make the solution more elegant solution, please comment and I'll update it. In particular, my method of combining the strings feels clunky, as does calling Names[] twice.

## Edit:

I agree that Mr. Wizard's answer is better. Here's how I used it to export the usage messages for a list of packages to a plain text file.

packageNameList =
{
"utility",
"greenSheet",
"entropy"
};
packageList =
( # <> "*") & /@
packageNameList;
doc = OpenWrite["doc.txt"];
For[i = 1, i <= Length[packageList], i++,
Export[doc, "\n\nPackage: " <> packageNameList[[i]] <> "\n\n"];
Cases[
MakeExpression @@ {Names@packageList[[i]]}, _[s_] :>
ToString@Row[{"\n\n", HoldForm[s]," :: ", s::usage}]
] //
Export[doc, #, "List"] &
]

-
# <> ":: " <> (#::usage &@Symbol[#]) & /@ Names["entropy*"] – Kuba May 11 '14 at 23:18
@Kuba, very nice. – Rico Picone May 11 '14 at 23:43