Add cross-reference hyperlinks

[seancolsen]

Lot's of places in the User Guide have instructions like this:

See the Email section of this book

And most of these places don't have any sort of hyperlinks to help the reader find their way to that section. We should improve this content by adding hyperlinks.

Tips:

• Find offending content with this command

  $ grep -Prin '(see|refer\sto|go\sto|check\sout|read)\sthe\s(.{0,50}\s)?(chapter|section|page)' docs
  

• Follow the internal URL standards when fixing content

[wmortada]

I'm going to have a look at this as part of the Documentation Sprint.

[wmortada]

I've done a chunk of work on this but am going to have to call it a day. Others are welcome to carry on where I left off...

[abihazakariya]

I'm taking a stab at this now.

[dvhirst]

Where are you in the process? Is there a point where I can contribute? If we can agree a starting / ending places, perhaps we can work in separate areas at the same time?

[AnneDru]

Hi, this sounds like something i just MIGHT be able to help with - not a techie as you know. And I see we have people working on it. So, if wmortada, abihazakariya and dvhirst need another person on this one - and you think I can do it - add me to the team and give me the start/end points and any other instructions.

[seancolsen]

I've got a Google doc spreadsheet set up for this now, so it's easier to divide up...
https://docs.google.com/spreadsheets/d/1iFDia9pzoSaSc9TlaszyZC32aU-JJe2gSBRN3zwkOdI/edit?usp=sharing

[dvhirst]

As of 2018 03 24; 22:45 US/PDT there are 16 open items in seanmadsen's spreadsheet with stevekessler's name attached. The remainder are closed or have PRs against them. Significant progress!

[seancolsen]

I have a little bit of bad news. That spreadsheet I created... Well, it turn out it wasn't quite comprehensive enough. Originally I was running that regex through PhpStorm which treats \s as matching newlines. Seems like grep doesn't match newlines with \s so there were a bunch of false negatives that grep didn't display (and I used the grep output to produce the spreadsheet). I just spent a little time trying to make an improved spreadsheet by playing with the -z and -o grep options, but it's not easy. I might spend some more time on this later.

Here's an improved regex which now ignores cases that have already been fixed. It throws some false positives, but generally seems to produce good results.

(see|refer\sto|go\sto|check\sout|read)\sthe\s([^\]]{0,50}\s)?(chapter|section|page)(?![^\[\]]{0,50}(\[|\]))

Current results count is 65, after a handful of fixes I made in 777552c.

Using PhpStorm to fix these is really easy because you can edit the results within the find window. But it's still work to figure out what the URL should be and to adjust the language to account for the link.

I think we should keep working on this, but we'll either need: (a) people comfortable running this regex search locally, or (b) a better way to generate the spreadsheet in order to hand off these small tasks.

[AnneDru]

Hi Sean Oh well - at least we achieved what we achieved. I’m happy to continue to do a few now and then to get to the end, but I think I will need someone else to tell me which ones need fixing (ie the spread sheet was good - but I don’t know if I am up to doing a regex locally as I don’t know what that means …..). And although I will hopefully improve my skills as I go along, I am OK if you tell me it’s more work for you if I help and therefore ‘don’t’! With warm regards, Anne Dru South West & Dru IT 01579 351385 07818 625567 southwest@druworldwide.com

…

On 25 Mar 2018, at 19:47, Sean Madsen ***@***.***> wrote: I have a little bit of bad news. That spreadsheet I created... Well, it turn out it wasn't quite comprehensive enough. Originally I was running that regex through PhpStorm which treats \s as matching newlines. Seems like grep doesn't match newlines with \s so there were a bunch of false negatives that grep didn't display (and I used the grep output to produce the spreadsheet). I just spent a little time trying to make an improved spreadsheet by playing with the -z and -o grep options, but it's not easy. I might spend some more time on this later. Here's an improved regex which now ignores cases that have already been fixed. It throws some false positives, but generally seems to produce good results. (see|refer\sto|go\sto|check\sout|read)\sthe\s([^\]]{0,50}\s)?(chapter|section|page)(?![^\[\]]{0,50}(\[|\])) Current results count is 65, after a handful of fixes I made in 777552c <777552c>. Using PhpStorm to fix these is really easy because you can edit the results within the find window. But it's still work to figure out what the URL should be and to adjust the language to account for the link. I think we should keep working on this, but we'll either need: (a) people comfortable running this regex search locally, or (b) a better way to generate the spreadsheet in order to hand off these small tasks. — You are receiving this because you commented. Reply to this email directly, view it on GitHub <#254 (comment)>, or mute the thread <https://github.com/notifications/unsubscribe-auth/Af4HGc239xHZCXtRafeTUp6-e-XU9B6Uks5th-ZfgaJpZM4SclkH>.

[dvhirst]

Hi Sean, with a bit of coaching, I'm game to try running the regex locally. I've read a bit about the process of creating regexes, so have some basic understanding; I'd not consider myself in any ways skilled at creating such, but believe I have enough knowledge to use them (and possibly to be a bit dangerous). So, let me know what looks like a good next step. Don

[aydun]

@seanmadsen I've fiddled with the regex and added a second tab on the Google sheet with more references.

May be a bit late, but is it worth defining a preferred format for the text around references? "See the XYZ chapter" is common, but also "See the chapter on XXX", "refer to ", "check", "read" etc. Some use quotes, some bold, some capitals etc.

[seancolsen]

@aydun Nice! Looks like all the rows in you new sheet contain multiple lines. To me that means that the two sheets should be mutually exclusive. Is it okay with you if I combine them into one sheet?

is it worth defining a preferred format for the text around references?

Good idea. I guess I just assumed everyone would want to do it like I do it! Ha! My personal preference is to find a way to work the hyperlink into a sentence, like this.

If need be, you can use [Custom Fields](/organising-your-data/creating-custom-fields.md)
to associate additional data with each activity.

But I don't feel too strongly about this, and I don't really have time to facilitate a group decision around it right now.

Side note: I just glanced over Wikipedia's Linking style guidelines thinking they would have a guideline about working links into prose, but they don't seem to — although there is some other good stuff in there, like overlinking and underlinking.

[aydun]

@seanmadsen That's fine to combine the sheets. A side-effect of the multi-line matching (in perl) is that the extracts don't have line numbers, but I have kept the line breaks the same to aid locating them in the text.

I too like the approach of working the link into a sentence - although our regexp's attempts would not have found your example!

[seancolsen]

@aydun

our regexp's attempts would not have found your example

Hmm I'm confused by this. Isn't that what we want? The regex is supposed to find places in the docs that are missing links. My example has a link, so we want the regex to ignore it, right? Maybe I'm missing something.

[aydun]

@seanmadsen Yes, you're right that we are looking for missing links and the example as it stands should not be picked up.

However, I was meaning (but didn't say clearly!) that if that style of reference is currently used without a link then the regexp would not pick it up: ie "... you can use Custom Fields to associate ..." does not include the expected 'chapter' or 'section' words.

[wmortada]

That's true @aydun but I think these scripts are picking up the majority of the links. We can always come back to refine this in future. We may have to manually read through the pages to pick up some of the outliers. Its a continuous process of improvement!

[github-actions]

This issue has had no activity in 60 days and has been marked as stale, it will be closed in 10 days.