[Date Index] [Thread Index] [Author Index]

Re: paclet type documentation / cpu usage w. Help Browser

• To: mathgroup at smc.vnet.net
• Subject: [mg114543] Re: paclet type documentation / cpu usage w. Help Browser
• From: "Vivek J. Joshi" <vivekj at wolfram.com>
• Date: Tue, 7 Dec 2010 06:46:38 -0500 (EST)
• References: <4CFD2628.1010604@cox.net>

A colleague of mine describes the process of generating documentation in 
detail as below. Copying mathgroup to serve as a general reference for 
other application developers working on generating documentation.

Building Documentation with Workbench

Make sure DocumentationTools is not installed somewhere else on your 
system.

***********>> Below replace the name Docstest with the name of your 
application. <<***********

Workbench Settings

Window > Show View > Package Explorer
Window > Show View > Paclet Build Tools

Window > Preferences > Mathematica (set M- for use -- 7 if you have it)
Window > Preferences > Mathematica > Paclet Development -- Check: 
Configure Mathematica for Developing Documentation
Click OK

In Workbench go to File > New > Project

Click on Mathematica > Application Project

Click Next

Enter Project name - Docstest -- and click Next

We will not reference any existing projects - click Next

Check Create PacletInfo.m and Create documentation

Click Finish

Make sure the init.m is properly set up -- for Docstest I just have 
Get["Docstest`Docstest`"] in my init.m which is in the Kernel directory 
visible in the Package Explorer

Replace Docstest.m just generated by Workbench by the Docstest packages.

Start Mathematica by double clicking Docstest.nb. Wait for the menu to 
refresh. (Workbench contains a FronEnd Job progress indicator in the 
lower right.)

Go to Palettes > DocumentationTools in Mathematica

If a Dynamic Content Warning dialog comes up, click the button: Enable 
Dynamic.

===> The ref pages created in the next step copy the usage 
messages from the .m's into the usage cells of the ref pages.
The usage messages in the .m's should not have newlines (\n), linear 
syntax or other formatting in them. Some formatting
is done in the creation of usage cells. Also option tables are created 
for functions with options.

Using F > Utilities > Generate Function Pages create ref pages in the 
Symbols directory.

Go back to Workbench -- Package Explorer pane > Docstest > Docstest > 
Documentation > English > ReferencePages and click on the Symbols 
directory.

Refresh (using F5 under Windows or right click and go down to Refresh 
and click) Package Explorer Pane to see Ref pages.

You may now go and add material to these pages - for example: from your 
existing material.

Extracting Tutorials from existing User Guides - Use button: T > 
Utilities > Extract Tutorials

Make a main guide page -- DocumentationTools > G > New Guide.

Enter the guide title Docstest Functions in the input field of the 
resulting dialog and click OK.

Other guides may be also made in the Guides directory using 
functionality available on the G tab of DocumentationTools.

Close Mathematica.

Refresh the Guides directory.

Double click PacletInfo.m

Click on Documentation in the lower left of the upper right pane.

Navigate to the main guide and click on it. Then click on Set Main 
Guide.

Save PacletInfo.m

Choose Project > Docstest in the Paclet Build Tools pane.

Click: Run Build

When the build has completed click: Create Paclet.

Check $UserBaseDirectory or $BaseDirectory. Click Next. Check 
Docstest::documentation. Click Finish.

Start Mathematica. Open Documentation Center. At bottom click on Add-Ons 
and Packages.

Docstest is listed. Click Docstest and also the guillemet (>>).

The main guide page should open.

---------------------------------------------------------------

For additional information on DocumentationTools see the tutorials on

http://reference.wolfram.com/workbench/index.jsp

under Mathematica Development User Guide > Reference > Documentation 
Tools

Vivek J. Joshi
Wolfram Research

On Dec 6, 2010, at 12:06 PM, Ron Burns wrote:

> Dear Sir,
>
> Thank you for your reply to my MathGroup question about creating my 
own paclet documentation. I watched the video but I did not catch a 
comment on upgrading i.e converting earlier packages with Help Browser 
type notebooks to the paclet system.  Is there a tool for this or is it 
a going to be a massive "cut and paste" operation?
>
> My main interest in this "upgrading" is because the Help Browser does 
not seem to work properly on my system.  I posted the following (and got 
no reply):
>
> I am using Mathematica 7.0 on a dual processor Linux system and am 
seeing that if I bring up the Function Navigator - Add Ons & Packages -
> Add Ons and then select the Help for AddOn packages from version 5.2 
(a
> bunch of nb under the Documentation/English directory) the cpu usage
> increases to unacceptable values - Mathematica usage from about 10% to
> 20% and Xorg usage from a few % to 80-100% (as reported by running 
top.)  Currently I just open and then close the help browser which is 
inconvenient.  I would like to keep it open as I work.
>
> As a bit of further information:  The problem does not seem to be 
specific to a particular set of documentation but I have not 
systematically investigated this. I am using 2.6.32-26-generic 
#48-Ubuntu Linux. The Mathematica is the "Home Edition" which I 
purchased since I no longer have my workplace Mathematica now that I 
retired.
>
> Can you or someone else at Wolfram research comment on and suggest 
solutions for this excessive CPU usage by Help Browser?
>
> Thank you for your consideration.
> 	Ron Burns
>
> --
> R. R. Burns
> Physicist (Retired)
> Oceanside, CA