Add ability to link to chapter/section #28

eihli · 2022-09-14T04:40:08Z

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.

@chapter

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](#c:id). This commit is a work-in-progress that I want to at least get out to start bouncing ideas around.

eihli · 2022-09-14T04:41:36Z

dev.lit

+
+--- foobaz
+(format nil (* 2 2))
+---


Was using this as a scratch file to play around with in a REPL.

(let* ((file-defs (parse-lit-files '("dev.lit"))) (weaver (make-weaver-default file-defs))) (add-section weaver '("Some Chapter") "c2") ; ... )

eihli · 2022-09-14T04:44:25Z

weave.lisp

+
 (defun weave-prose-line (weaver line def)
  (loop for expr in line do
-        (cond ((stringp expr) (write-string expr)) 


I didn't intend to make this blank space change. I have a habit of running M-q for paredit-reindent-defun and saved/committed this and didn't want to bother with undoing it yet.

eihli · 2022-09-14T04:44:50Z

weave.lisp

+                (replace-sections-with-id-anchors
+                 (weaver-section-map weaver)
+                 expr))
+               (write-string expr)))


^ This is the new bit that is obscured by all of the blank space changes. This along with the comment below are the two core pieces. However it's implemented, these seem like the two most reasonable places to hook in to (1) map section/chapter titles to IDs and (2) replace the link references with their IDs.

Any regex scanning like this should happen in the parser. By the time it gets here it should be a structured command.
For example, all the here is a line with a @{reference} becomes "here is a line with a " (:INCLUDE "reference"). So similarly, this should be a command type like (:SECTION-REFERENCE "name").

eihli · 2022-09-14T04:58:24Z

utils.lisp

+;;
+;; I haven't yet gotten close to finishing that implementation. So it
+;; doesn't make much sense to have this data structure right now.
+;; But oh well. Whatever. It works for an MVP of the chapter/section linking stuff.


^ Of course that could also be done with simple string matching. I was also thinking this could be useful for something like letting you use [some section](@some section) if it's unique but [some section](@some chapter:@some-section) if the section title wasn't unique. (Etc. for @some file name). Basically... I had a very loosely woven idea that it might be useful and it seemed like a fun way to practice LISP. I don't think it's actually worthwhile for anything.

I had not thought of this idea. I am perfectly open to giving it a try and think its a cool idea. I am also just fine with forcing them to write out the title.

eihli · 2022-09-14T05:01:07Z

weave.lisp

+                      (section-id
+                       (weaver-section-counter weaver)
+                       (weaver-chapter-counter weaver)))
+              (add-section weaver (list (second expr)) (section-id (weaver-section-counter weaver)


Calling this out from all the noise. One core piece of this here on line 289 and 298.

This seemed like a good place to hook in and save off the mapping of chapter/section titles to IDs.

The table of contents toc structure on weaver should have all the information you need. It it will specify what all the chapters and sections are and which files they are in. (Just try printing it out and seeing). I would recommend making a pure function which takes the toc as input and produces whatever identifier trie you need.

I would also probably put that function in toc.lisp.

The table of contents toc structure on weaver should have all the information you need.

Ah! That's obvious now.

justinmeiners · 2022-09-14T05:06:33Z

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 · 2022-09-14T15:04:38Z

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 · 2022-09-14T19:42:41Z

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

justinmeiners · 2022-09-15T03:10:42Z

weave.lisp

+  ;;
+  ;; Right now, it doesn't work across files in a book.
+  ;; Heck... it barely works at all.
+  (section-map '() :type list)


Be conscious of multiple files. When a chapter/section is referenced in the same file it should be a relative link (just the anchor portion). When it is referenced in a different file, that file name will be prepended to the anchor. See how block reference anchors are produced.

justinmeiners · 2022-09-15T03:16:53Z

@eihli

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

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.
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.
I think you can utilize the toc structure to get what you want, if not let's improve it.

justinmeiners · 2022-09-15T03:30:20Z

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.

justinmeiners · 2022-09-30T01:51:52Z

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

eihli · 2022-10-01T18:00:30Z

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.

Detect # vs ## and use the list (:ANCHOR (:C "Ch Title")) or (:ANCHOR (:S "Section Title")) depending on which.

eihli · 2022-12-11T18:44:55Z

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 · 2022-12-15T02:31:31Z

Really excited! I will review this in detail soon.

justinmeiners · 2023-01-02T18:01:07Z

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

eihli commented Sep 14, 2022

View reviewed changes

justinmeiners reviewed Sep 15, 2022

View reviewed changes

eihli added 3 commits September 18, 2022 22:40

Revert

638e3a4

Refactor to parse to :ANCHOR

6dbbef9

Merge remote-tracking branch 'upstream/master' into link-to-sections

a6605c7

Update parse-anchor to include Chap/Section

768a5b6

Detect # vs ## and use the list (:ANCHOR (:C "Ch Title")) or (:ANCHOR (:S "Section Title")) depending on which.

eihli force-pushed the link-to-sections branch from 10fb425 to 768a5b6 Compare October 1, 2022 18:02

eihli added 6 commits November 26, 2022 21:35

indentation

b3f977c

Merge branch 'master' into link-to-sections

09a0065

Add function to map sections to href

23b9cb1

Weave anchor

6d57dbb

Fixes escape in code blocks

0d4a798

Update filepaths

cb4e960

Add ability to link to chapter/section #28

Are you sure you want to change the base?

Add ability to link to chapter/section #28

Uh oh!

Conversation

eihli commented Sep 14, 2022

Uh oh!

eihli Sep 14, 2022

Choose a reason for hiding this comment

Uh oh!

eihli Sep 14, 2022

Choose a reason for hiding this comment

Uh oh!

eihli Sep 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinmeiners Sep 15, 2022

Choose a reason for hiding this comment

Uh oh!

eihli Sep 14, 2022

Choose a reason for hiding this comment

Uh oh!

justinmeiners Sep 15, 2022

Choose a reason for hiding this comment

Uh oh!

eihli Sep 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

justinmeiners Sep 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eihli Sep 15, 2022

Choose a reason for hiding this comment

Uh oh!

justinmeiners commented Sep 14, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

eihli commented Sep 14, 2022

Uh oh!

justinmeiners commented Sep 14, 2022

Uh oh!

justinmeiners Sep 15, 2022

Choose a reason for hiding this comment

Uh oh!

justinmeiners commented Sep 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

justinmeiners commented Sep 15, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

justinmeiners commented Sep 30, 2022

Uh oh!

eihli commented Oct 1, 2022

Uh oh!

eihli commented Dec 11, 2022 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

justinmeiners commented Dec 15, 2022

Uh oh!

justinmeiners commented Jan 2, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

eihli Sep 14, 2022 •

edited

Loading

eihli Sep 14, 2022 •

edited

Loading

justinmeiners Sep 15, 2022 •

edited

Loading

justinmeiners commented Sep 14, 2022 •

edited

Loading

justinmeiners commented Sep 15, 2022 •

edited

Loading

justinmeiners commented Sep 15, 2022 •

edited

Loading

eihli commented Dec 11, 2022 •

edited

Loading

justinmeiners commented Jan 2, 2023 •

edited

Loading