RE: FM72. Tool to quickly makes loads of cross-refs?
For a clipboard utility, I can also recommend Yankee Clipper III. I've used that utility and its predecessor for years. Also just read a great review of Ditto, which I'll be taking for a test drive. Both are free. HTH, Jim -Original Message- From: framers-boun...@lists.frameusers.com [mailto:framers-boun...@lists.frameusers.com] On Behalf Of Art Campbell Sent: Tuesday, June 15, 2010 9:57 AM To: Avraham Makeler Cc: framers@lists.frameusers.com Subject: Re: FM72. Tool to quickly makes loads of cross-refs? I misunderstood what you were saying -- you're asking about each unique object reference, but I read what you wrote to mean the global definitions of the type of object. And, as far as: 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. Download a copy of ClipMate, Great utility and it'll let you do other stuff too. Quicker than cutting and pasting between FM docs. Cheers, Art Art Campbell art.campb...@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 10:27 AM, Avraham Makeler amake...@gmail.comwrote: 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.campb...@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.campb...@gmail.com ... In my opinion, there's nothing in this world
Re: FM72. Tool to quickly makes loads of cross-refs?
you have text objects turned on, right? You mean FM7.2 Menu View View Options Text Symbols ? On Tue, Jun 15, 2010 at 4:05 PM, Art Campbell art.campb...@gmail.comwrote: 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.campb...@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 amake...@gmail.comwrote: 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.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: FM72. Tool to quickly makes loads of cross-refs?
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.campb...@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 amake...@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.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
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.campb...@gmail.comwrote: 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.campb...@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 amake...@gmail.comwrote: 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.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com
Re: FM72. Tool to quickly makes loads of cross-refs?
I misunderstood what you were saying -- you're asking about each unique object reference, but I read what you wrote to mean the global definitions of the type of object. And, as far as: 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. Download a copy of ClipMate, Great utility and it'll let you do other stuff too. Quicker than cutting and pasting between FM docs. Cheers, Art Art Campbell art.campb...@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 10:27 AM, Avraham Makeler amake...@gmail.comwrote: 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.campb...@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.campb...@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 amake...@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
RE: FM72. Tool to quickly makes loads of cross-refs?
Avraham Makeler wrote: 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. Agreed. In online programmer/API documentation, users expect references to other classes, methods, functions, etc., to be links to them. Although I suspect/hope every other word is something of an exaggeration. :-) 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. If you use FM cross-references, I don't see why it would ever become a maintenance problem. Presumably, all these cross-references would use the $paratext building block to retrieve the text of a heading pgf that contains the name of the software object being referenced. If a function's name changes from getAnotherFoo to getNextFoo, you change the name in the heading, and FM updates all the xrefs to that heading automagically. As for automating your task, it could be done with FrameScript (www.framescript.com) or FrameAC (www.mekon.com/index.php/pages/knowledge_zone/frameac/products/technologies/manage). Since you have VB experience, the latter makes more sense for you if you want to roll your own. Alternatively, you might want to get a quote from Rick Quatro (www.frameexpert.com) for a custom FrameScript solution. Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-903-6372 -- ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
RE: FM72. Tool to quickly makes loads of cross-refs?
I agree... There's no reason for this to me a maintenance issue. I would implement a solution that flushes all the auto-generated xrefs, and re-establishes them each time I invoke the task. By keeping it clean, there's no issue... That's the standard approach to this type of thing. It should be fairly easy to do, given a config file that identifies what the XRef targets should be. cud ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: FM72. Tool to quickly makes loads of cross-refs?
The last FM 7.x projects I worked on were perennially losing cross-refs, just in day-to-day book building operations. Not to mention changes in chapters themselves. If it could be truly automated, maybe... but sitting down to a list of hundreds of unresolved cross-refs isn't a great way to start your day. Art Campbell art.campb...@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 12:56 PM, Combs, Richard richard.co...@polycom.comwrote: Avraham Makeler wrote: 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. Agreed. In online programmer/API documentation, users expect references to other classes, methods, functions, etc., to be links to them. Although I suspect/hope every other word is something of an exaggeration. :-) 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. If you use FM cross-references, I don't see why it would ever become a maintenance problem. Presumably, all these cross-references would use the $paratext building block to retrieve the text of a heading pgf that contains the name of the software object being referenced. If a function's name changes from getAnotherFoo to getNextFoo, you change the name in the heading, and FM updates all the xrefs to that heading automagically. As for automating your task, it could be done with FrameScript ( www.framescript.com) or FrameAC ( www.mekon.com/index.php/pages/knowledge_zone/frameac/products/technologies/manage). Since you have VB experience, the latter makes more sense for you if you want to roll your own. Alternatively, you might want to get a quote from Rick Quatro (www.frameexpert.com) for a custom FrameScript solution. Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-903-6372 -- ___ You are currently subscribed to framers as art.campb...@gmail.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/art.campbell%40gmail.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info. ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: FM72. Tool to quickly makes loads of cross- refs?
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:amake...@gmail.com] To: framers@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.campb...@gmail.comwrote: 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.campb...@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 amake...@gmail.comwrote: 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
RE: FM72. Tool to quickly makes loads of cross-refs?
Art Campbell wrote: The last FM 7.x projects I worked on were perennially losing cross-refs, just in day-to-day book building operations. Not to mention changes in chapters themselves. If it could be truly automated, maybe... but sitting down to a list of hundreds of unresolved cross-refs isn't a great way to start your day. Barring operator error, FM xrefs are pretty nearly bullet-proof. I'm not sure what you mean by day-to-day book building operations, but there are basically only two ways that an FM xref becomes unresolved: 1) FM can't open the destination file (because it's been moved, deleted, renamed, or can't be opened silently due to missing fonts, etc.) to find the marker that the xref points to. 2) FM can't find the marker itself (because it's been deleted, the marker text that identifies it was changed, or it's tagged with a condition that's currently hidden). If one of these things was happening routinely to hundreds of xrefs, there was something seriously wrong with the process/workflow being used, probably because the person who created it didn't understand how FM xrefs work. Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-903-6372 -- ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: FM72. Tool to quickly makes loads of cross-refs?
Not disagreeing, Richard, but I suffered through months of this on a contract job where the files were shared among several writers. And it's recurred occasionally in other 7.x environments. Ain't saying it couldn't have been resolved, but it occurred far too often to be hapinstance. Cheers, Art Art Campbell art.campb...@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 4:07 PM, Combs, Richard richard.co...@polycom.comwrote: Art Campbell wrote: The last FM 7.x projects I worked on were perennially losing cross-refs, just in day-to-day book building operations. Not to mention changes in chapters themselves. If it could be truly automated, maybe... but sitting down to a list of hundreds of unresolved cross-refs isn't a great way to start your day. Barring operator error, FM xrefs are pretty nearly bullet-proof. I'm not sure what you mean by day-to-day book building operations, but there are basically only two ways that an FM xref becomes unresolved: 1) FM can't open the destination file (because it's been moved, deleted, renamed, or can't be opened silently due to missing fonts, etc.) to find the marker that the xref points to. 2) FM can't find the marker itself (because it's been deleted, the marker text that identifies it was changed, or it's tagged with a condition that's currently hidden). If one of these things was happening routinely to hundreds of xrefs, there was something seriously wrong with the process/workflow being used, probably because the person who created it didn't understand how FM xrefs work. Richard G. Combs Senior Technical Writer Polycom, Inc. richardDOTcombs AT polycomDOTcom 303-223-5111 -- rgcombs AT gmailDOTcom 303-903-6372 -- ___ You are currently subscribed to framers as arch...@mail-archive.com. Send list messages to fram...@lists.frameusers.com. To unsubscribe send a blank email to framers-unsubscr...@lists.frameusers.com or visit http://lists.frameusers.com/mailman/options/framers/archive%40mail-archive.com Send administrative questions to listad...@frameusers.com. Visit http://www.frameusers.com/ for more resources and info.
Re: FM72. Tool to quickly makes loads of cross-refs?
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:amake...@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 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 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
