Seeking :paralinks: attribute similar to :sectlinks: -

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Seeking :paralinks: attribute similar to :sectlinks: -

hydrostarr
I'm seeking a ':paralinks:' (paragraph links) attribute similar to ':sectlinks:' Does such a thing exist?

Motivation. Such a thing provides more-granular references to each paragraph in a document. Among other things, this enables excellent references for requirements-traceability projects. Here's an example paragraph link from the attached .html file (below).

Details:

I want it to do something similar to what's found in the the attached files (below), with one change: I want the link highlights to be "invisible" and the clickable link area to span all of the paragraph, rather than just the inserted '§'--and get rid of the '§'. Just like :sectlinks: does for section titles, but applied to each paragraph. This would all be generated automatically in Asciidoctor .html output by setting:

:paralinks: 1

or some, similar construct.

Workaround if no feature exists:

If no automated feature/pre-processor/gizmo/etc (I'm not yet familiar with pre processors or other, detailed Asciidoctor features) currently exists, I plan to write a Python script to automatically add the following code to each paragraph in a Asciidoctor source file (as per the example files below):

[id='101']
<<101,§>> Paragraph text...

example_paralinks.txt
example_paralinks.html
Reply | Threaded
Open this post in threaded view
|

Re: Seeking :paralinks: attribute similar to :sectlinks: -

mojavelinux
Administrator
This feature is not provided out of the box...but of course, anything is possible :)

I strongly encourage you to consider using the Asciidoctor extension API to implement this feature. The best choice is probably a Treeprocessor. There is no need to hack stuff in downstream because we created the extension API to enable exactly this sort of enhancement.

There are a bunch of examples of extensions in the extension lab: https://github.com/asciidoctor/asciidoctor-extensions-lab/tree/master/lib


You'd want to search for all paragraph blocks, which you can do using

document.find_by :paragraph

Then, you can add an autogenerated id to the paragraph and inject extra text in the beginning of the source text to create an anchor point. You may also need to weave in some extra CSS, which you can do with a DocinfoProcessor.

To get this started, I recommend filing an issue for the idea in the extension lab repo. That sort of establishes the goal. Then, people in the community who are interested can jump in and help you formulate a solution.

Cheers,

-Dan

On Fri, Jun 12, 2015 at 9:45 AM, hydrostarr [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I'm seeking a ':paralinks:' (paragraph links) attribute similar to ':sectlinks:' Does such a thing exist?

Motivation. Such a thing provides more-granular references to each paragraph in a document. Among other things, this enables excellent references for requirements-traceability projects. Here's an example paragraph link from the attached .html file (below).

Details:

I want it to do something similar to what's found in the the attached files (below), with one change: I want the link highlights to be "invisible" and the clickable link area to span all of the paragraph, rather than just the inserted '§'--and get rid of the '§'. Just like :sectlinks: does for section titles, but applied to each paragraph. This would all be generated automatically in Asciidoctor .html output by setting:

:paralinks: 1

or some, similar construct.

Workaround no feature:

If no automated feature/pre-processor/gizmo/etc currently exists, I plan to write a Python script to automatically add the following code to each paragraph in a Asciidoctor source file (as per the example files below):

[id='101']
<<101,§>> Paragraph text...

example_paralinks.txt
example_paralinks.html



If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Seeking-paralinks-attribute-similar-to-sectlinks-tp3368.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Reply | Threaded
Open this post in threaded view
|

Re: Seeking :paralinks: attribute similar to :sectlinks: -

hydrostarr
This post was updated on .
Thanks Dan.

Updates:
  1. :paralink: feature? Have any :paralink: like features been added in asciidoctor or its extensions (within last ~2 years since I first posted on this topic)?
  2. my automation vs native asciidoctor. I wrote (2 years ago) a Python script to do this, seems to work well. But I'd much rather have asciidoctor/extension auto-generate this capability for me. Among other things, makes native github renderings work the way I want. Even if I did get an extension to do what I want, how do I get github to adopt this?
  3. market demand. Why is this not a more-popular feature request? Why am I the only one (seemingly) who wants this? Being able to automatically and easily link directly to paragraphs is essential for clear-line traceability for legal and software-requirements traceability, glossaries (reference each word definition with a link in other documents), and many more applications. What gives? The only thing I can imagine is that asciidoctor hasn't yet been adopted yet into "(corporate/large org) enterprise good practices prime time" even though Scott Chacon (github) and O'Reilly publishing seem to be behind it, and it's fighting the Docbook's and the DITA's and all the proprietary apps/software/services. But I massively speculate, as I've not research this space _at all_. And I'll further clarify: I *love* asciidoc/asciidoctor -- it's enabling "documentation the way it should be." Soooo valued. I just want this additional feature for my corporate scalability. :)
  4. extension usage. I'm not sure how to execute the steps below for the shell-session-treeprocessor extension (like, I don't know where to start). I'm missing some "newbie user" info. I take it the extension-usage stuff is found somewhere in here. If not, can someone provide pointers? In any case, I'm not sure how close shell-session-treeprocessor is to providing what I seek, but it's a start.
  5. no issue post... yet. I've not yet posted feature request issue in the extension lab repo per Dan's suggestion below, because I was lazy, my bad. If extensions are not loaded into github, then I may not be that motivated to do so.
mojavelinux wrote
Here's one that is pretty close to what you want to do: https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/shell-session-treeprocessor/extension.rb

You'd want to search for all paragraph blocks, which you can do using

document.find_by :paragraph

Then, you can add an autogenerated id to the paragraph and inject extra text in the beginning of the source text to create an anchor point. You may also need to weave in some extra CSS, which you can do with a DocinfoProcessor.
Reply | Threaded
Open this post in threaded view
|

Re: Seeking :paralinks: attribute similar to :sectlinks: -

hydrostarr
Here's my preferred path to solution, if asciidoctor team is unable: my team submits a patch to the "core" (of asciidoctor). I'm hoping that the same (hopefully simply) code lines/method that implements section links can be modularized to apply to all paragraphs. And therefore not a big change.

Questions:
If we can do it, is it feasible on your (the asciidoctor's dev/admin team) end?
Do y'all have automated testing mechanism(s) that I can employ to test these changes?

(My team is not yet ruby savvy, but hoping that's not a big deal.)