Add ability to link to chapter/section

[eihli]

To link to a chapter/section: [anchor text](@chapter or section title)

This change adds a slot to the weaver to store a map of chapter/section titles to their IDs.

Then when we're weaving, we search for these links and replace them with their anchor text.

This commit is a work-in-progress that I want to at least get out to start bouncing ideas around.

[justinmeiners]

I have only looked at this briefly. What do you think about the idea of making @chapter-name (whatever the syntax is) expand to the anchor/relative link, regardless of whether it's in a markdown link or not?

From my experience there are actually a lot of subtle rules about how markdown is expanded (likely there are edge cases), and a lot of the complexity here seems to be parsing those links.

[eihli]

I have only looked at this briefly. What do you think about the idea of making @chapter-name (whatever the syntax is) expand to the anchor/relative link, regardless of whether it's in a markdown link or not?

I think I like that. Keeps a clear separation between what's weave and what's markdown.

Rather than [foo](@foo) --weave--> [foo](#c1) --markdown--> <a href...> it's just @{## foo} --weave--> <a href...>.

As for syntax, I like the idea of keeping parity with the code blocks by re-using the same @{...} syntax. But to differentiate between the name of a code block and the name of a section/chapter, maybe include the # and ## in the reference to a section/chapter.

So @{foo} for the code block named foo and @{## foo} for the section titled foo.

[justinmeiners]

@eihli great! Let me take an in-depth look tonight and give you more appropriate feedback.

[justinmeiners]

@eihli

My comments are probably hard to read out of order, so here is a summary:

1. If you don't see any problems, let's go ahead with a reference which expands to an anchor (using syntax just like the one you proposed), rather than attempting to parse markdown link syntax.
2. Make sure you do all the regex finding in the parse step. You should have a structured command with symbols by the time it gets to the weave.
3. I think you can utilize the toc structure to get what you want, if not let's improve it.

[justinmeiners]

Thinking out loud. There is a slight inconsistency in our proposed syntax. For a block, using @{block name} always produces a link (an tag), but what we are proposing for sections produces just the anchor/href. Perhaps we should have one syntax for producing anchors/hrefs (for blocks, chapters, and sections) and another one which wraps that functionality to produce full links.

Perhaps @{block name} @{# heading} @{## section} is appropriate to expand to a link, and something like @anchor{block name} @anchor{# heading} @anchor{## section} would expand to the href. Just an idea.

Excited to see where this goes. Just following up to see if you need anything from me.

[eihli]

Excited to see where this goes. Just following up to see if you need anything from me.

No questions or anything yet. Just haven't had much free time lately.

[eihli]

Just a status update as of commit cb4e960.

Most of the diff is either space changes that can be ignored or comment blocks with scratch code that helped me explore. There's only a few lines of new code.

I've been using paredit-reindent-defun to manage indentation. My config must be different from yours because it results in a lot of space edits. I'm not going to worry about them for now. You can view a diff that ignores space changes by adding ?w=1 to a Github URL: https://github.com/justinmeiners/srcweave/pull/28/files?w=1

This create-global-toc-linkmap function creates a mapping of chapter/section name to the file.html#s0:1 url path of the woven output.

https://github.com/justinmeiners/srcweave/pull/28/files?w=1#diff-932b4bb5bad7e82585c83d4d8fcaf295e66649c16f2c949a2e02e915438d1623R52

And then the :ANCHOR gets woven into an a href at https://github.com/justinmeiners/srcweave/pull/28/files?w=1#diff-4f8d805adf8da1e80d7ab36038b531fb74ac5aba28588c867ef469785e837facR271.

Not great yet. Can't provide link text for the anchor that's different from the chapter/section name that you're linking to.

But getting there.

I've been using some scratch files to test/iterate. Will update the tests once things settle down.

srcweave --weave dist --formatter srcweave-format dev.lit scratch.lit

[justinmeiners]

Really excited! I will review this in detail soon.

[justinmeiners]

@eihli Just letting you know I had another personal delay.

As an aside, I tried to find your contact information on your site. If you are interested in providing that feel free to send me an email (on my github page).