Markers in Asciidoctor - status?

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

Markers in Asciidoctor - status?

wolandscat
Nice work on the latest releases, I've just upgraded to 1.5.4. Nothing broke ;-)

I'm slightly out of date on current live issues, and I'm not even sure where I mentioned this feature because, so I thought I would check here first, before raising an enhancement request - maybe the feature was implemented and I just need to learn how to use it.

The feature is the same as 'markers' in FrameMaker. Example asciidoctor-produced spec (HTML). See the first table on that front page, where it has Revision: [latest_issue] and also Date: [latest_issue_date], where those [] bits are links. In FrameMaker, I would have put a 'marker reference' that would be resolved to the text that the marker marks, not just the location where the marker is.

I.e. if you click on those links you'll find they jump a bit further down to the top of the Amendment record, and the latest_issue link points to something like 2.0.5. In Frame, the '2.0.5' had a 'marker' around it, and a reference  to that kind of marker elsewhere in the doc caused the marked text to be substituted in. i.e. the final result would be 'Revision: 2.0.5' at the top.

I think this must be nearly the same logic as the 'Figure N' referencing question, which AFAIK is still a live issue.

Apologies if I have forgotten where any original discussion of this lives, any pointers appreciated.

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

Re: Markers in Asciidoctor - status?

mojavelinux
Administrator
Thomas,

Isn't this just the same thing as an attribute reference combined with a xref. You can put an anchor at an arbitrary location in the document (with optional xreflabel) and then link to it using an xref.

I'm glad to here that the upgrade to 1.5.4 was a smooth one!

-Dan

On Tue, Jan 12, 2016 at 7:48 AM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Nice work on the latest releases, I've just upgraded to 1.5.4. Nothing broke ;-) I'm slightly out of date on current live issues, and I'm not even sure where I mentioned this feature because, so I thought I would check here first, before raising an enhancement request - maybe the feature was implemented and I just need to learn how to use it. The feature is the same as 'markers' in FrameMaker. Example asciidoctor-produced spec (HTML). See the first table on that front page, where it has Revision: [latest_issue] and also Date: [latest_issue_date], where those [] bits are links. In FrameMaker, I would have put a 'marker reference' that would be resolved to the text that the marker marks, not just the location where the marker is. I.e. if you click on those links you'll find they jump a bit further down to the top of the Amendment record, and the latest_issue link points to something like 2.0.5. In Frame, the '2.0.5' had a 'marker' around it, and a reference to that kind of marker elsewhere in the doc caused the marked text to be substituted in. i.e. the final result would be 'Revision: 2.0.5' at the top. I think this must be nearly the same logic as the 'Figure N' referencing question, which AFAIK is still a live issue. Apologies if I have forgotten where any original discussion of this lives, any pointers appreciated. - thomas


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



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Markers in Asciidoctor - status?

wolandscat
Dan,

the referencing point wouldn't look like a reference when finally processed - the target location text would be substituted at the source point. So the .adoc source that looks something like

Revision: <<some kind of ref here to marker at text '1.2.4'>>
.....
[[some kind of marker]]
1.2.4

has to get processed into:

Revision: 1.2.4

i.e. a literal substitution of the reference by the text 'marked' at the target.  The '1.2.4' could be linked, but I personally don't care about that - we just want the text substitution to occur.

Note that this needs to work without any knowledge of what that text is - i.e. I have no idea that it is '1.2.4' or any other specific string.

does that clarify?

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

Re: Markers in Asciidoctor - status?

mojavelinux
Administrator
The closest thing in AsciiDoc is as follows:

[source,aciidoc]
----
Revision: <<current_version_ref>>

...

[[current_version_ref,1.2.4]]1.2.4
----

You can avoid the duplication of the version number using an attribute:

[source,asciidoc]
----
:current-version: 1.2.4

Revision: <<current_version_ref>>

[[current_version_ref,{current-version}]]{current-version}
----

-Dan

On Wed, Jan 13, 2016 at 3:48 AM, wolandscat [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Dan,

the referencing point wouldn't look like a reference when finally processed - the target location text would be substituted at the source point. So the .adoc source that looks something like

Revision: <<some kind of ref here to ref at text '1.2.4'>>
.....
[[some kind of marker]]
1.2.4

has to get processed into:

Revision: 1.2.4

i.e. a literal substitution of the reference by the text 'marked' at the target.  The '1.2.4' could be linked, but I personally don't care about that - we just want the text substitution to occur.

does that clarify?

- thomas


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



--
Dan Allen | @mojavelinux | http://google.com/profiles/dan.j.allen
Reply | Threaded
Open this post in threaded view
|

Re: Markers in Asciidoctor - status?

wolandscat
Dan,
thanks for the response. Hm.... I'm not sure we would use this. Have a look at this - this is one of our actual amendment records (raw form on git).

If you scan carefully down the left side, you'll see the revision ids, i.e. '2.1.1', '2.1', '2.0' etc. You can see the '[latest_issue]]' in front of the first one near the top.

I actually couldn't manage to make this work. The source location is this boilerplate file, where you can see the two refs roughly in the middle - latest_issue and latest_issue_date.

For the target location, I changed one of our docs as follows:

[source, asciidoc]
----
= Amendment Record

:latest-issue: 2.0.5
:latest-issue-date: 13 Jan 2016

[cols="1,6,2,2", options="header"]
|===
|Issue|Details|Raiser, Implementer|Completed

|[[latest_issue,{latest-issue}]]{latest-issue}
|Rewrite Terminology Integration section. Add template section.
|T Beale
|[[latest_issue_date,{latest-issue-date}]]{latest-issue-date}
----

The result of this in the HTML generated output is:



i.e. there is still no substitution going on.

In any case, I think the method you provide may be too complicated and error-prone for authors to reliably get right - considering that on a new addition to the top of the amendment record, they would need to do quite a bit of cut and paste replacements / editing to reset the old top entry in the Amendment table to what it was literally, and then to create the new top row.

This isn't a blocker, we can certainly live without it, but I just thought I'd ask because it's a normal kind of publishing thing to want to do. Perhaps in a future release?

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

Re: Markers in Asciidoctor - status?

Ted
I'm able to get the substitution to work except when it comes to "latest-issue-date". There is a problem rendering that term. I'd recommend renaming "latest-issue-date" until they can sort out what's happening.

e.g. AsciiDoc tested with Asciidoctor 1.5.4

= Test
:latest-issue: 2.0.5
:latest-issue-date: 13 Jan 2016
:latest-issue-date-RENAMED: 13-JAN-2016

|===
|*Revision*: link:#{latest-issue}[{latest-issue}]
|*Date*: link:#{latest-issue-date}[{latest-issue-date}] Problem here with "latest-issue-date". Maybe it's a reserved term?
|===


*Date*: link:#{latest-issue-date-RENAMED}[{latest-issue-date-RENAMED}] This works.


- Ted @TedAtCIS