remove hyphens from anchor links when creating from <h3>subtitles

[mkoo]

Here's the problem: in the current site the anchors were not necessarily the subheader/subtitle phrase: https://arctosdb.org/documentation/agent/#namesearch BUT the subheader is "Searching Agents"

Opt#1 I can go through and update the subheaders to match but in some cases like this one is leaves wtih some awkward phrasing. Opt#2? Anyway to create anchors not from <h3>tags?

In any case we need to get rid of hyphens when constructing the anchors from subtitles (readability pfft!) This blocks the launch if we dont have a solid fix

[dustymc]

I've been playing with just this - seems like the GH page-generator-thingee is just exceptionally weird. The "anchors" are some sort of JS-magic or etc. - there are no actual anchors in the page as rendered.

I don't really have any problem with hyphens or whatever - characters are characters....

I'm re-routing ALL links through the documentation handler. It now

1. HEADs the page. If 404, throw an error and send email to "us" (we can talk about who gets that - I may want to send it directly to CC and MK for a while).
2. if there's an anchor, GET the page and look for the (fake) anchor. This is necessary because handbook.arctosdb.org/documentation and handbook.arctosdb.org/documentation#icantypeanythinghere return exactly the same thing (because of the weird JS-magic). -- if the anchor is found, yay -- if the anchor is NOT found, open the base page (eg, silently ignore the missing anchor) and send more email (to "us")

The broken links and anchors will need fixed SOMEWHERE - if that can't be done on GH it can happen in the Arctos code, and I can show ya'll how to do that if you want.

Or we could create a lookup table in Arctos - instead of changing stuff in the code (lots of help links are called from many pages) we could just maintain a "translation service." That's probably The Correct Approach but I'm not sure it's necessary - how often are links/anchors likely to change?

And on that note, we will need to be exceptionally paranoid about changing whatever it is that generates the fake anchors on GH.

The doc handler itself needs a makeover and perhaps some few functionality to handle this increased load, but we can talk about that on /arctos/issues.

[mkoo]

For the whole Docs subdirectory, there will be few changes and by few editors, as far as I see it.

Show me how in Arctos if it's set up to do that now. I dont think you need to make a look-up service/table just for anchors given this is (hopefully) more or less a migration headache done simply once. As long as we know how they are made for future new Doc pages.

I could be very wrong but GH fix seems more involved.

[tigerhawkvok]

They're not really "anchors" in the old-school way of things. Modern browsers will link unique IDs to an anchor automatically.

So, for example, this link will jump the page to the nav bar on the old site:

https://arctosdb.org/documentation/agent/#menu-item-57

This one will scroll all the way down, trying to anchor to the "Like" button:

https://arctosdb.org/documentation/agent/#jp-post-flair

That's the real issue. If need be, manual anchors synonymizing locations with the old entries can be added (eg, the old <a name="foobar"/> style) but that hasn't been practically used as an anchor since IE6.

[dustymc]

few changes and by few editors

I hope not! Having at least "trusted us" be able to easily write/edit documentation is a major part of the appeal to me.

Show me how

Once this all gets cleaned up and pushed to prod, you should start getting emails from two users:

1. doc_not_found@arctos... is cause for panic; if you're getting that, a user saw....

2. busted_anchor@arctos.... - less panic is called for - the user just got sent to a page instead of a section of a page - but it still needs fixed.

Both should contain everything you need to find and fix the problem....

• the page from which the doc call was made (thing you'll need to fix if you're changing Arctos)
• the URL to which the doc call was made (because clicking it is useful)
• the filename from the called URL (eg, first parameter of the getDocs() function)
• the anchor (second parameter of the getDocs() function)

/editIdentification.cfm is the problem page - open it in your editor (or browser - code is https://github.com/ArctosDB/arctos, that one is https://github.com/ArctosDB/arctos/blob/master/editIdentification.cfm) and splat-f "getDocs".

You should find something that looks like...

<span class="infoLink" onClick="getDocs('identification')">Documentation</span>

The function takes two parameters: the page (required, always first) and the anchor which may be something, or be open-close-quotes (''), or not be there at all (as in this example).

The bit in the span tag is the displayed "link" - 'Documentation' in this case. Looks like that should be pointing to http://handbook.arctosdb.org/documentation/identifications.html, so either lose the plural in the handbook URL or add it to the Arctos code and voilà - it'll be fixed with next release.

You'll occasionally get something like....

.... and from that you'll find there is no /name folder, and the nonexistent folder doesn't have any contents, what with not existing and all. You can check /errors/missing.cfm (https://github.com/ArctosDB/arctos/blob/master/errors/missing.cfm) - splat-f "name" and you should (eventually, I suck at naming variables) find....

Go find the template that's building the dynamic page on the fly - in this case https://github.com/ArctosDB/arctos/blob/master/taxonomy.cfm - and search for the missing thing (bad anchor here).

That content is available at http://handbook.arctosdb.org/documentation/taxonomy.html#source-arctos, so either change the anchor part of the function (to getDocs(''taxonomy'',''source-arctos'')) or figure out how to make http://handbook.arctosdb.org/documentation/taxonomy.html#arctos_source exist.

If you're changing Arctos, a global search of the code should be done - 'identification' is used in 5 pages.

I changed the handbook to http://handbook.arctosdb.org/documentation/identification.html which should have fixed all of those links, and I updated the Arctos code to use http://handbook.arctosdb.org/documentation/taxonomy.html#source-arctos, so my examples will be broken before you see them....

[dustymc]

manual anchors synonymizing locations with the old entries can be added

I could go either way, I think.

Creating/editing documentation should be accessible to Curators-n-such. We probably can't expect them to add anchors - I'm not sure what an anchor looks like in GH's MD editor, or if it can even exist there. I like "real" anchors just because they're obviously there for a reason - I wouldn't change one without figuring out why it was created, and there's no way to accidentally change them.

In the MD, the "anchors" are whatever's typed after ## (and other stuff?), plus whatever manipulation GH throws in. somehow magics into , and it's not terribly clear to me that curators can be expected to figure out that process. Perhaps more importantly, I wouldn't see much reason to NOT change ## Scientific Name to, say ## Identification (which would be more accurate given the current scope of Arctos), and I believe that doing so would break the anchors/help links.

I THINK I'm mostly leaning towards not adding explicit anchors - stuff PROBABLY won't get arbitrarily changed too often, Curators may not need to understand what's going on, and I REALLY like being able to have people edit simple MD without trying to figure out what an anchor is or why they should care. Maybe we need documentation-documentation though.

Unrelated, I just built https://github.com/ArctosDB/documentation-wiki/edit/gh-pages/_documentation/test.markdown and http://handbook.arctosdb.org/documentation/test.html is 404ing - what is the process to push new content to the handbook?

[tigerhawkvok]

@dustymc the test is missing the "Front Matter", see the first few lines of https://raw.githubusercontent.com/ArctosDB/documentation-wiki/gh-pages/_documentation/accession.markdown

See the Jekyll documentation:

The front matter is where Jekyll starts to get really cool. Any file that contains a YAML front matter block will be processed by Jekyll as a special file. The front matter must be the first thing in the file and must take the form of valid YAML set between triple-dashed lines. Here is a basic example:

---
layout: post
title: Blogging Like a Hacker
---

Between these triple-dashed lines, you can set predefined variables (see below for a reference) or even create custom ones of your own. These variables will then be available to you to access using Liquid tags both further down in the file and also in any layouts or includes that the page or post in question relies on.

For us, the "you should almost always use" required parameters are:

---
title: TITLE HERE
layout: default_toc
---

After adding something like that, http://handbook.arctosdb.org/documentation/test.html works correctly.

[dustymc]

front matter

derp/thanks - I once knew that, I think....

We (I!) definitely need the documentation-documentation.

[tigerhawkvok]

I should reset / set-up the wiki for this repo for a bit of meta-documentation ....

[tigerhawkvok]

@dustymc added a quick bit of meta-documentation in the wiki and nuked some of the redundant bits: https://github.com/ArctosDB/documentation-wiki/wiki/Creating-or-Editing-Documents

[mkoo]

OK a little bit related to above but a lot relevent to all the 404's from Arctos not finding its Doc pages.

Can the "-" dash default to "_" underscores instead from the Handbook side?

This would clear up a ton of links: http://handbook.arctosdb.org/documentation/collecting_event.html#verbatim_date is missing URI: collecting_event Anchor: verbatim_date Called From: http://arctos.database.museum/Locality.cfm?action=editCollEvnt&collecting_event_id=10241115

The link formed by the Handbook is: http://handbook.arctosdb.org/documentation/collecting-event.html#verbatim-date so dashes not underscores, which was a request from months ago too.

[tigerhawkvok]

It's not possible to do.

Not only is it not an option from the parser, but it's explicitly part of the internal steps in the parser.

While I can write a Javascript middleman to take existing anchors and scrollIntoView a "old_anchor".replace(/[\_\W]/g,"-") anchor (works on nearly all modern browsers), the CGI check on the Arctos side wouldn't pick up this Javascript magic and you'd still get the error -- so this would address bookmarked links, but not the error messages.

Something like:

# $.url() is a function to get URL parameters
fragment = $.url().attr("fragment")
unless isNull fragment
  if fragment.match /\_\W/
    replacementSelector = "##{fragment.replace /[\_\W]/g, "-"}"
    if $(replacementSelector).exists()
      $(replacementSelector).scrollIntoView()

should fix client link behaviour

[mkoo]

mostly resolved and now quite stale... the general issue will come up again no doubt but will require a new issue! closing for now....