| T.R | Title | User | Personal
Name | Date | Lines |
|---|
| 162.1 | Try coding the <X> tags inside the examples... | NAVIGO::GRANT | I've saved $2001.00 since I quit smoking. | Fri Jun 30 1989 15:41 | 16 |
| In the latest version of the manual Coding Documentation Source Files for
the DECwindows Bookreader, section 2.3.2, it suggests that you code formal
figures, tables and examples as follows to ensure that clicking on the
index entry takes you to the graphic:
<FIGURE>(Figure One\fig_one)
<FIGURE_FILE>(...)
<X>(Index entry)
<ENDFIGURE>
Try this and see if it helps.
By the way, note 64.7 will tell you where you can get the latest version
of the Coding Doc.... manual.
Wayne
|
| 162.2 | Where to Place Index Tags | ELUDE::GREMBOWICZ | | Tue Jul 11 1989 16:59 | 63 |
| > <FIGURE>(Figure One\fig_one)
> <FIGURE_FILE>(...)
> <X>(Index entry)
> <ENDFIGURE>
I tried this and it takes me directly to the formal popup. That's
OK in this case, but it may not be acceptable all the time.
However, I don't understand why the coding I used didn't work.
I was *really* surprised to find out that clicking on an index
entry placed before a <head> tag took me to the next section.
I've read Coding Documentation..., Producing Manuals..., and
the Document User Manual, but I still don't understand what,
if anything, was wrong with my coding.
The DOCUMENT User Manual V1.0, p. 9-252, says:
"Do not place <X> tags within any kind of example. Doing so will
interfere with the formatting of the examples.
Be sure <x> tags follow headings, commands, and other text elements
that are likely to begin a new page."
However, Coding Documentation Source Files..., Section 2.3.2 says:
"You should code index entries in formal figures, tables, examples
as follows to ensure that clicking on the index entry takes you
to the graphic:
<FIGURE>(Figure One\fig_one)
<FIGURE_FILE>(...)
<X>(Index entry)
<ENDFIGURE> "
Then, Producing Online Documentation, Section 2.3 says:
"Make sure that index entries referring to information within a
given section appear within that section and not before its head
tag."
"Make sure that index entries are not coded within a formal figure,
table, or example -- or within any online popup sequence. If a
reader clicks on an index entry resulting from this type of coding,
the DECwindows Bookreader displays the popup window alone. Without
additional context, such index entries are not useful to a reader."
If you read the DOCUMENT User Manual and Producing..., you'd assume
that I coded my index entries correctly. Even Coding Documentation...
doesn't imply that the way I coded the entries would make the
BOOKREADER take me to the wrong section. It only advises how to
code to get directly to the popup.
Can anyone provide some guidelines about where to put index entries
so that they point to the right section (and so that they will continue
to work in subsequent versions of DOCUMENT, both hardcopy and online)?
Thanks,
Helen
|
| 162.3 | | VAXUUM::UTT | | Mon Jul 17 1989 17:33 | 71 |
| I have done some experimentation with coding index entries in formal
tables, figures, and examples.
Index entries can be coded almost anywhere in tables -- after table
row, after table_setup, after table heads. HOWEVER, if they are coded
directly after the <table> tag, the online entries will point to the
previous text, not the table popup.
For example, the following coding will produce index entries that
point to the table (popup):
<table>(Table One\one)
<table_setup>(2\2)
<x>(Index entry)
<table_heads>(One\Two)
<x>(Index entry)
<table_row>(Three\Four)
<x>(Index entry)
<endtable>
In figures and examples, the index tags should be coded before
the <endfigure> or <endexample> tag. In the case of examples, the
index tags would follow <endcode_example> or <endinteractive>:
<figure>(Figure One\one)
<figure_file>(bookreader\fig.decw$bookfig\4)
<figure_file>(...)
...
<x>(Index entry)
<endfigure>
<example>(Example One\one)
<code_example>
<s>($) <u>(input)
...
<endcode_example>
<x>(Index entry)
<endfigure>
Why won't putting <x> tags elsewhere in formal tables, figures, and
examples work? The 'chunks' that the Bookreader assembles and displays
as topics are, to the text formatter, pages. Page breaks occur at
every header and before and after formal figures, tables, and examples.
That's why index tags coded after a formal table point to the next
topic. The formatting for tables, figures, and examples is quite
complex: for examples and figures, most of the action actually takes
place in the <endexample> and <endfigure> tags. That appears to be why
the placement of the <X> tag is critical.
I tested use of the <X> tag in examples. The coding shown above works
fine for examples in both hardcopy and online forms. It does not
interfere with the formatting. Putting <X> and <Y> tags withing
<code_example>/<endcode_example> and <interactive>/<endinteractive>
pairs does generate an error. That's the reason for the restriction in
the User Manual.
As for the restriction in Producing Online Documentation, that is a
guideline based on the fact that if you go to a formal popup from the
table of contents or index in the Bookreader, you have no context. That
is, you cannot then go to the text associated with it (the text
containing the reference). This is on the list for future Bookreader
functionality.
I will clarify the information in the 'Coding Documentation Source
Files...' document.
Mary
|
| 162.4 | Thanks! Now one more index question | ELUDE::GREMBOWICZ | | Wed Jul 19 1989 10:55 | 30 |
| Mary,
Thanks for clarifying how to index examples, figures, and tables.
You've cleared up a lot of questions.
I have one question remaining:
If I have the following code, where should the BOOKREADER take me
if I click on the index entry?
<head1>(Section One\sect1)
<p>
text text text text text text text text text
text text text text text text text text text
<x>(Index)
<head1>(Section two\sect2)
Currently, the BOOKREADER takes me to Section Two. Should it?
Thanks,
Helen
|
| 162.5 | | CLOSET::UTT | | Thu Jul 20 1989 08:57 | 5 |
| It should take you to Section One, as you would expect. This was a
bug but has been fixed: I just extracted your note and tried it
and the index entry took me to Section One.
Mary
|
| 162.6 | Yet another table indexing question | AITG::CARRASCO | Perfection is not success | Thu Jul 20 1989 12:27 | 34 |
| Mary,
I noticed in .3 you didn't mention the possibility of the index hit being
_inside_ the table row. There are several long and complex tables in the
VAX LISP docset coded this way, I forget why. Do you think they'll work?
For example:
<table>(GET-DEVICE-INFORMATION Keywords \get_dev_info_tab)
<table_setup>(2\18)
<table_heads>(Keyword \Return Value)
<X>(<symbol>(GET-DEVICE-INFORMATION) function <xs>keywords (table)\master\BEGIN)
<table_row>(<symbol>(:ACP-PID) \An integer that specifies the ACP
process ID.
<X>(<symbol>(:ACP-PID) keyword <xs><symbol>(GET-DEVICE-INFORMATION)
function\master)
)
<table_row>(<symbol>(:ACP-TYPE) \An integer that specifies the ACP type
code.
<X>(<symbol>(:ACP-TYPE) keyword <xs><symbol>(GET-DEVICE-INFORMATION)
function\master)
)
<comment>(*********** And so on, and so forth *********************************
)
<table_row>(<symbol>(:VOLUME-PROTECTION) \A vector of 32 bits that
specifies the volume protection mask.
<X>(<symbol>(:VOLUME-PROTECTION) keyword
<xs><symbol>(GET-DEVICE-INFORMATION) function\master)
)
<X>(<symbol>(GET-DEVICE-INFORMATION) function <xs>keywords (table) \master\END)
<endtable>
|
| 162.7 | | VAXUUM::UTT | | Fri Jul 21 1989 13:41 | 6 |
| Hmmm. Forgot about that case. I think that will work. Will you try it
and let us know in a reply?
Thanks,
Mary
|
| 162.8 | | AITG::CARRASCO | Perfection is not success | Fri Jul 21 1989 16:39 | 5 |
| I have not yet dared try to put a LISP book online, but Ross Warner says it
will work.
Pilar.
|