Add cross-reference hyperlinks about civicrm-user-guide HOT 17 OPEN

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

from civicrm-user-guide.

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...

from civicrm-user-guide.

I'm taking a stab at this now.

from civicrm-user-guide.

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?

from civicrm-user-guide.

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.

from civicrm-user-guide.

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

from civicrm-user-guide.

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!

from civicrm-user-guide.

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.

from civicrm-user-guide.

from civicrm-user-guide.

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

from civicrm-user-guide.

@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.

from civicrm-user-guide.

@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.

from civicrm-user-guide.

@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!

from civicrm-user-guide.

@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.

from civicrm-user-guide.

@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.

from civicrm-user-guide.

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!

from civicrm-user-guide.

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

from civicrm-user-guide.