Message Boards Message Boards

6
|
15322 Views
|
6 Replies
|
18 Total Likes
View groups...
Share
Share this post:

[?] How to add example links to documentation pages?

Szabolcs Horvát
Posted 8 years ago

This is a cross-post from StackExchange.

The Details section of documentation pages often contains ">>" links to the examples below. Is there a quick and easy way to add these links using the Workbench documentation tools when creating my own documentation? Usually, there is a button for these things in the Documentation Tools palette. However, I cannot find one for these links.

enter image description here
POSTED BY: Szabolcs Horvát
6 Replies
Sort By:

So it turns out that there is a mechanism for doing this in Workbench's DocumentationTools:

  • On the F tab, click "Links", then "More Link Tools". You should see a "Make Sel" and a "Make Link" button, among some others.
  • Select the cell you want to link to.
  • Click "Make Sel".
  • Select the text you want for your link's button contents. If you want a » as in the docs, put one of those where you want the link to be. (That character is [RightGuillemet].)
  • Highlight that » (or whatever text) and click the "Make Link" button in DocumentationTools.

The link should immediately be live; test and make sure, etc.
POSTED BY: Brian Van Vertloo

I asked one of our doc developers, and this was their response (slightly edited):

Looks like the docs tools in WB don't support it. This code will make a small palette that does mostly the same thing as what we have in our internal tools.

CreatePalette[Button["Create Link", 
 Module[{cell = SelectedCells[InputNotebook[]][[1]], cellid}, 
  cellid = "CellID" /. Developer`CellInformation[cell]; 
  CopyToClipboard[
     Cell[TextData[
       ButtonBox[ToString@cellid, BaseStyle -> "ExampleLink",
       ButtonData -> cellid]]]]]]]

Select the cell you want to link to, click the button in the palette. That copies to the clipboard a link to that cell. Simply paste that link in your notes (yes, it should look like a series of numbers; those numbers are the CellID of the cell you're linking to). Of course, anyone using this should test it in their own applications to make sure that it works how they want before going nuts with it.
POSTED BY: Stefan Ragnarsson

That would be my expectation. But I'm not very familiar with Workbench. Can you do a test build to verify CellID preservation?
POSTED BY: Larry Adelston

Yes, I did a test build, and in the cells I checked the option was preserved. I will just go on with the assumption that it is always preserved, and if there is a problem, I will report back. I will add the links manually, as you suggested.
POSTED BY: Szabolcs Horvát

I don't use Workbench. But you can add such links manually:

  1. copy an existing link button from a documentation page like ref/Sum.

  2. paste the button into the cell in which it is to appear.

  3. unformat the target cell by placing your cursor in that cell and choosing the menu command Cell > Show Expression. Copy the rhs value of the option CellID. That value should be a long-ish integer. Again, choose Cell > Show Expression to reformat the cell.

  4. place your cursor in the cell that contains the hyperlink that was pasted in step 2.

  5. unformat that cell via the same menu command as in step 3. In the cell expression there will be a ButtonBox with the option BaseStyle->"ExampleLink". So the expression will look something like: ButtonBox["[NonBreakingSpace][RightGuillemet]", BaseStyle->"ExampleLink", ButtonData->270825173]

  6. select the rhs of ButtonData and paste the CellID value you copied. And reformat the cell via Cell > Show Expression.
POSTED BY: Larry Adelston

Thank you for the response. Can I fully trust that CellIDs will never change between the documentation source notebooks and the built documentation pages?

I looked at a few examples, and it does seem that at least with the current version of DocumentationBuild, they are preserved.
POSTED BY: Szabolcs Horvát
Reply to this discussion
Community posts can be styled and formatted using the Markdown syntax.
Tag limit exceeded
Note: Only the first five people you tag will receive an email notification; the other tagged names will appear as links to their profiles.
Reply Preview
Attachments
Remove
or Discard

Group Abstract Group Abstract