This makes since to me.
Lynn Floyd <mailto:[email protected]> [email protected] Anderson County Library Anderson, SC From: OPEN-ILS-DOCUMENTATION <[email protected]> On Behalf Of Remington Steed Sent: Monday, July 09, 2018 9:13 AM To: Documentation discussion for Evergreen software <[email protected]> Subject: [OPEN-ILS-DOCUMENTATION] Problem with the smaller docs manuals 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/ Lynn Floyd Head of Information Technology Anderson County Library Anderson, SC [email protected]
_______________________________________________ OPEN-ILS-DOCUMENTATION mailing list [email protected] http://list.georgialibraries.org/mailman/listinfo/open-ils-documentation
