5
$\begingroup$

I have the latest version of Wolfram Workbench plugin installed on Eclipse. But the Documentation Tools palette contained in this does not have all the styles that are part of the standard documentation. Is there a way to get the latest version of Documentation Tools in use by people at Wolfram Research?

For example, where can I find the red highlighted region?

enter image description here

I am getting this kind of section header. Also, I can't get the divider line and the guide title on the page. I suspect there is a newer version of Documentation Tools.

enter image description here

$\endgroup$
  • $\begingroup$ Could you specify what version of Workbench you have, and also what styles you're missing? $\endgroup$ – Chris K Jun 21 '18 at 14:50
  • $\begingroup$ My workbench version number is 10.1.822 and please see the updated question for one example of style i am missing. $\endgroup$ – user13892 Jun 22 '18 at 9:04
  • $\begingroup$ Frankly, I would be careful about investing too much into creating documentation this way. There are already several problems with the doc generation tools: it's clear that they're primarily made for internal use, and making them available for package authors was just an afterthought. I have to apply several monkey-patches to the doc tools to let them work well with the MaTeX documentation (e.g. not break MaTeX into Ma Te X), and then again several post-processing steps to the generated notebooks (e.g. remove URLs pointing to non-existing pages at wolfram.com) $\endgroup$ – Szabolcs Jun 22 '18 at 12:53
  • 4
    $\begingroup$ MaTeX is a small package with only a few doc pages. I could aways copy the content to another format if needed. But I wouldn't create docs this way for a large package with many functions until Wolfram shows some signs of being committed to Worbench and taking care of the practical needs of package authors (such as backwards compatibility). $\endgroup$ – Szabolcs Jun 22 '18 at 12:54
  • $\begingroup$ There are things to do after your question is answered. It's a good idea to stay vigilant for some time, better approaches may come later improving over previous replies. Experienced users may point alternatives, caveats or limitations. New users should test answers before voting and wait 24 hours before accepting the best one. Participation is essential for the site, please do your part. $\endgroup$ – rhermans Jun 28 '18 at 18:58
6
$\begingroup$

The current version of the Workbench / Documentation Tools still produces the style used in Mathematica 11.0 and earlier.

This style can also be displayed (mostly fine) in Mathematica 11.1 and later. The few problems (such as large font in See Also links) can be corrected by post-processing the generated documentation notebooks (this is what I do for MaTeX). You don't get the latest look, but you can get working documentation that is compatible with many M versions and still looks good.

However, the reverse is not true. At one point Wolfram accidentally pushed a Workbench update, which produced documentation that was not compatible with earlier versions. You can imagine that this is a big problem for anyone who develops Mathematica packages. WRI only needs their documentation generator to work with the latest Mathematica. But any useful package will need to be compatible with some earlier versions too (my impression is that at this point most, or at least a signification portion of, M users don't use the latest version).

Thus I very much hope that when Wolfram releases an update to the Workbench, it will still be capable of producing backwards compatible documentation (or at least make older Workbench versions available).

$\endgroup$
  • 2
    $\begingroup$ Conrad Wolfram mentioned in his opening talk at the recent EWTC conference in Oxford that WRI wants to take more care of developers. Hopefully this will happen soon. It would be interesting to know how many developers outside WRI actually do use Workbench ( I do, but other experienced programmers I know do not; because Workbench is unpredictable .... ). $\endgroup$ – Rolf Mertig Jun 23 '18 at 16:06
  • $\begingroup$ @RolfMertig Do you know whether the talk has been uploaded and if yes can you provide a link. Thank you. $\endgroup$ – user13892 Jun 24 '18 at 10:21
5
$\begingroup$

I'm also using Workbench 10.1.822 (although on a Mac with Mathematica 11.3). Here's a side-by-side of the unprocessed and processed forms of a test guide page I just made:

enter image description here

As you can see, I'm also missing the orange "Guide" tab at the top, but I do have the divider line and orange section text, which I made with the "Subsection" button in the DocumentationTools Palette.

Hope this helps you fix at least a couple of your problems.

EDIT:

To get rid of the Reference heading, I replaced the blank blue line with a "Delimiter" from the palette:

enter image description here

$\endgroup$
  • $\begingroup$ Thank you Chris your solution is perfect for the time being but can you remove the Reference heading with collapsible arrow. $\endgroup$ – user13892 Jun 23 '18 at 19:38
  • $\begingroup$ @user13892 see edit $\endgroup$ – Chris K Jun 23 '18 at 22:37

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.