[OPEN-ILS-DOCUMENTATION] Problem with the smaller docs manuals

[Remington Steed]

Hi DIG,

A recent change made by Jane Sandberg caused me to realize a larger problem
with our current multi-manual setup.

TL;DR

We should manually create real anchors for every section.  Otherwise, when
we include some sections in one manual (e.g. "Cataloging") but not in
another, our auto-created anchors get different names.  Trouble!

The Details:

* Our current process of building HTML files automatically creates section
"anchors" that we can use for internal links.  These are of the form
"_section_name" (or if there are multiple sections with the same name, one
will be "_section_name_2").  These have always been a bit tricky, since
adding a new section called "Section Name" can change the other sections'
anchors without warning, causing links to go to the wrong section.  But it
gets worse with our new setup of multiple subject-specific manuals.

* If, say, the Cataloging manual only has one of those same-named sections,
then "_section_name_2" might end up getting the anchor "_section_name"
instead.  But it will still get "_section_name_2" in the consolidate manual.

* Wherever we link to that section, we need to know the exact anchor name,
or the link will be broken.  And if the name is inconsistent in different
manuals, we're in trouble!

I suggest we officially adopt a new approach to creating anchors:

1. Every section gets a manual anchor.  I suggest a similar format to the
auto-created anchors, but without the starting "_".  That way, if we ever
see an anchor link starting with "_", we can say "Hey, we forgot to update
that."

2. When there's multiple sections with the same name, instead of just
adding "_2" to the end, let's be more descriptive.  Maybe one is the
"_intro" and the other is the "_details", for example.  Or one might be
from the Acquisitions perspective ("section_name_acq") while the other is
within the Circ docs ("section_name_circ").  That way, they'll still make
sense even in manuals where the other section isn't included.

As usual, I've gotten way too detailed.  Comments?  Ideas?  If this sounds
good to everyone, I bet the main conversion work could be automated.  I'll
sketch up some ideas for the process for our next meeting.

(Hey Joe, when is our next meeting?)

Remington
--

Remington Steed
Electronic Resources Specialist
Hekman Library, Calvin College
http://library.calvin.edu/
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://list.georgialibraries.org/pipermail/open-ils-documentation/attachments/20180709/f2cae8d5/attachment.html>