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

Tue Jun 15 07:42:47 PDT 2010

Hi Avraham

What you describe is normally, in my limited experience, generated automatically from code, using a tool such as Javadocs. I know that other programming languages (C# for example) will also generate such documentation from code comments. Wouldn't that be an easier way to go? Your job then would be to edit - and nag the developers to add the comments.

Roger

Roger Shuttleworth
Technical Documentation
AV-BASE Systems Inc.
1000 Air Ontario Drive, Suite 200
London, Ontario
N5V 3S4
Tel. 519 691-0919 ext. 330
  _____  

From: Avraham Makeler [mailto:amakeler at gmail.com]
To: framers at lists.frameusers.com
Sent: Tue, 15 Jun 2010 10:27:42 -0400
Subject: Re: FM72. Tool to quickly makes loads of cross-refs?

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
  _______________________________________________

  You are currently subscribed to framers as rshuttleworth at avbasesystems.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/rshuttleworth%40avbasesystems.com

  Send administrative questions to listadmin at frameusers.com. Visit
  http://www.frameusers.com/ for more resources and info.