search

taradinoc / mdl-docs

The MDL Programming Language by S. W. Galley and Greg Pfister
26 stars 8 forks source link

Name Index #50

Open jmdyck opened 5 years ago

jmdyck commented 5 years ago

I really miss having the Name Index (appendix "8") as part of the doc.

Currently, I keep the grotty PDF open on its Name Index. When I want to look something up, I scroll to that term in the Name Index, write down its page references, go to those pages in the PDF, find out what section numbers they're in, then go to those sections in the transcribed doc. At that point, it would be easier to just stick with the PDF, but it's hard on the eyes.

So I'm thinking of transcribing and then converting the Name Index into section-number references, which can then be automatically linkified.

One alternative (not sure if this is actually possible with GFM) would be to to embed anchors in the md at the points where the page-breaks occur in the original. Then page-based links in the Name Index would get you to roughly the right place. But I'm pretty sure I'd prefer to land at the top of a pertinent section, rather than in the middle of some section that might not be relevant.

(I see some mentions of indexing in issue #6, but no particular plan.)

taradinoc commented 5 years ago

My plan for indexing was to convert this over to Sphinx, which can generate the index page automatically. There's a sphinx branch here, but it's stale, and I don't know if I'll get back to it any time soon.

If you feel like typing up an index manually in the meantime, feel free.

jmdyck commented 5 years ago

I'm doubtful that an automatically-generated index would be any good. E.g., the word ATOM occurs over 500 times in the document. What are the chances that an auto-indexer would boil that down to the 5 references that the original Name Index gives?

Or do you mean: go into the document, find and mark those 5 occurrences (and similarly for every other index-worthy term), and then generate the index automatically, on the basis of those marks? That would result in a good index, but it's even more work than I'm contemplating.

jmdyck commented 5 years ago

If you feel like typing up an index manually in the meantime, feel free.

I've got this so far. If I don't get any further, I'll PR that as-is.

taradinoc commented 5 years ago

Or do you mean: go into the document, find and mark those 5 occurrences (and similarly for every other index-worthy term), and then generate the index automatically, on the basis of those marks? That would result in a good index, but it's even more work than I'm contemplating.

Yeah, this: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#index-generating-markup

It is more work than copying the page numbers, but might make it possible to e.g. hover over the references in the index to see them in context, without having to flip back and forth between the index and the document. At least, it would be the metadata we'd need to make that work.

jmdyck commented 5 years ago

[Sphinx index-generating-markup]

Yup, that looks good. Using my work on the Name Index, It would now be possible to automatically insert .. index:: directives such that Sphinx would generate an index that reproduced its functionality. All the directives would appear at (actually before) the start of each section, which would often be fine, but you could sometimes improve on that by shifting some directives down to a more appropriate point within the section.

It [...] might make it possible to e.g. hover over the references in the index to see them in context,

I'm guessing just a few lines of context?

without having to flip back and forth between the index and the document. At least, it would be the metadata we'd need to make that work.

Looks like you'd need to write a Sphinx extension for that.