RE: Cross-reference style question

Subject: RE: Cross-reference style question
From: "Combs, Richard" <richard -dot- combs -at- Polycom -dot- com>
To: "Nancy Allison" <maker -at- verizon -dot- net>, <techwr-l -at- lists -dot- techwr-l -dot- com>
Date: Tue, 1 Dec 2009 09:21:43 -0700

Nancy Allison wrote:

> I'm working in a long document that has internal TOCs at the beginning
of
> each chapter.
>
> They are presented in a simple list format, using the same x-ref
formatting
> that is used in sentences. It's quick and easy but possibly not really
> stylistically acceptable. By that I mean, not stylistically acceptable
TO
> ME. I'm wondering if my ideas of acceptability are stuck in, say, the
80s.
> It looks like this:
>
> This chapter contains the following sections:
>
> -- "Opening Your Toaster Box" on page 37
> -- "Plugging in Your Toaster" on page 42
> -- "Burning Your Toast" on page 67
>
>
> Each bulleted item is a hyperlink and is formatted in blue ink, so
that
> when people read the PDF online, they know they can click to go
directly to
> that section. When the document is printed on a color printer, the
text is
> blue, which may seem slightly odd, but the page number is provided so
the
> reader can find the section.
>
> Although it looks a bit kludgy to me, it is much easier to maintain
than
> having two lists marked with conditional text:
>
> --One has the blue hyperlink, no quotation marks, and no page numbers
> --One has the quotation marks and page numbers, but no hyperlink
>
> The two-formats-marked-with-conditional-text is what I have done in
other
> documents, but I'm wondering if I am making work for myself and anyone
else
> who has to maintain the docs.

I think your current setup is _superior_ to omitting the page numbers in
the online PDF. After all, people _print_ PDFs that they access online.
And then the blue link with no page numbers is pretty much useless to
them.

Save the page-numberless hyperlinks for the online help.

IIRC, you're working in FrameMaker. You can save yourself a lot of time
creating and maintaining chapter TOCs by getting Rick Qatro's ChapterTOC
script ($40; requires FrameScript;
http://www.frameexpert.com/scripts/chaptertoc.htm)

Check out Sharon Burton's testimonial in the FrameUsers list archives:
http://lists.frameusers.com/pipermail/framers/2008-July/013030.html

I haven't used ChapterTOC myself, so I can't say from personal
experience. But Sharon's contention that you'd save the cost of the
script plus FrameScript on the first manual sounds reasonable to me.


Richard G. Combs
Senior Technical Writer
Polycom, Inc.
richardDOTcombs AT polycomDOTcom
303-223-5111
------
rgcombs AT gmailDOTcom
303-777-0436
------






^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

Are you looking for one documentation tool that does it all? Author,
build, test, and publish your Help files with just one easy-to-use tool.
Try the latest Doc-To-Help 2009 v3 risk-free for 30-days at:
http://www.doctohelp.com/

Help & Manual 5: The all-in-one help authoring tool. True single- sourcing --
generate 8 different formats and as many different versions as you need
from just one project. Fast and intuitive. http://www.helpandmanual.com/

---
You are currently subscribed to TECHWR-L as archive -at- web -dot- techwr-l -dot- com -dot-

To unsubscribe send a blank email to
techwr-l-unsubscribe -at- lists -dot- techwr-l -dot- com
or visit http://lists.techwr-l.com/mailman/options/techwr-l/archive%40web.techwr-l.com


To subscribe, send a blank email to techwr-l-join -at- lists -dot- techwr-l -dot- com

Send administrative questions to admin -at- techwr-l -dot- com -dot- Visit
http://www.techwr-l.com/ for more resources and info.

Please move off-topic discussions to the Chat list, at:
http://lists.techwr-l.com/mailman/listinfo/techwr-l-chat


Follow-Ups:

References:
Cross-reference style question: From: Nancy Allison

Previous by Author: Re: job market Q4 2009
Next by Author: RE: Chapter-page numbering, reasons for
Previous by Thread: Re: Cross-reference style question
Next by Thread: RE: Cross-reference style question


What this post helpful? Share it with friends and colleagues:


Sponsored Ads