FM72. Tool to quickly makes loads of cross-refs?

[Avraham Makeler]

Hi Art. Thanks for the response.

>> First, if I were you, I'd resist this. I think it's unnecessary and could
become a potential maintenance nightmare.

>> I think it's unnecessary
I think this is standard fare in programmer's and API reference guides. So
they want what they see elsewhere.

>> could become a potential maintenance nightmare.
That is definitely a point. It never occurred to me before; maybe because
none such document that I ever worked on ever actually realized that
horrifying potential in practice.

I think it could be more likely to be a maintenance nightmare if this API
had a reputation for its objects' names being changed every now and again,
as well as their positions in the document being changed. However, in the
year and half I have known this API document it has only ever grown---it is
now over 700 pages long---it has never *changed*. But you know what - I
could them about this.

>> The SME seems to be under the impression that if a reader, probably
another coder, will forget what a basic programming object is in less than
90 seconds... If the SME forgets, there may be a reason to do it, but if he
or she can hold on to the concept for an hour or so, your readers probably
can.

As I mentioned, I think this is standard fare in programmer's and API
reference guides, and at 720 pages there is plenty to forget...

>> If I had to do this, I'd probably use a glossary entry for these because
they are, in fact, definitions and glossary entries are lighter weight.

I will have to check that out. Thanks.

>> With all that said, if you must do this, you _should_ be able to define
one of the cross-refs and embed it with its text string hotspot. Then copy
the word, including the cross-ref marker (you have text objects turned on,
right?) and do a search-and-replace for the text string, pasting from the
clipboard.

Thanks for the idea. That's useful in cases where the same text is repeated
many times. In the updates to this document, all the cross-refs are
different. (At 720 pages, there are so many link targets to choose from, why
repeat the same ones...?! ha ha.)

Another idea I use is to define one of the cross-refs and copy+paste it into
an FM utility document I keep open on the side in a small window
and copy+paste from there every time I need it again as and when I meet a
repeat instance.

Great thanks,

  - avi




On Tue, Jun 15, 2010 at 4:05 PM, Art Campbell <art.campbell at gmail.com>wrote:

> First, if I were you, I'd resist this. I think it's unnecessary and could
> become a potential maintenance nightmare. The SME seems to be under the
> impression that if a reader, probably another coder, will forget what a
> basic programming object is in less than 90 seconds... If the SME forgets,
> there may be a reason to do it, but if he or she can hold on to the concept
> for an hour or so, your readers probably can.
>
> If I had to do this, I'd probably use a glossary entry for these because
> they are, in fact, definitions and glossary entries are lighter weight.
>
> With all that said, if you must do this, you _should_ be able to define one
> of the cross-refs and embed it with its text string hotspot. Then copy the
> word, including the cross-ref marker (you have text objects turned on,
> right?) and do a search-and-replace for the text string, pasting from the
> clipboard.
>
> Art Campbell
>            art.campbell at gmail.com
>  "... In my opinion, there's nothing in this world beats a '52 Vincent and
> a redheaded girl." -- Richard Thompson
>                                                      No disclaimers apply.
>                                                               DoD 358
>
>
> On Tue, Jun 15, 2010 at 8:52 AM, Avraham Makeler <amakeler at gmail.com>wrote:
>
>> Hi all,
>>
>>  RE: FM72. Tool to quickly makes loads of cross-refs?
>>
>> I just a received some whole new sections for updating an FM book. The
>> book
>> is a large reference guide for an API. Every other word in the new
>> material
>> is in fact the name of some software object (function, structure, or type)
>> that's defined somewhere else as its own section. The new material talks
>> about those already defined software objects and how to use them. So the
>> SME
>> wants every mentioning of those already defined software objects to be
>> converted to a cross-reference. (Anyone who has documented APIs knows what
>> I
>> am talking about.) Is there some sort of tool that allows you to
>> type+select
>> the name of the section (function) or even just its legal number and then
>> click, and hey presto, the cross-reference appears?
>>
>> Once, during a slow period, I programmed exactly that tool for Word using
>> VBA. Took me about a week. Works great.
>>
>> TIA
>>
>>     - avi
>> _______________________________________________
>>
>>
>> You are currently subscribed to framers as art.campbell at gmail.com.
>>
>> Send list messages to framers at lists.frameusers.com.
>>
>> To unsubscribe send a blank email to
>> framers-unsubscribe at lists.frameusers.com
>> or visit
>> http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com
>>
>> Send administrative questions to listadmin at frameusers.com. Visit
>> http://www.frameusers.com/ for more resources and info.
>>
>
>


-- 
Regards,

avraham
~~~~~~~~~
054-3084886