metanorma / metanorma-ogc

Metanorma processor for OGC documents
https://www.metanorma.com
BSD 2-Clause "Simplified" License
2 stars 3 forks source link

Custom Asciidoc document attribute with link not working in 1.8? #604

Closed alexrobin closed 12 months ago

alexrobin commented 1 year ago

I used to be able to define a custom document attribute with a link like this in 1.7.6:

:ogcapi-common: https://ogcapi.ogc.org/common[OGC API - Common]

And then refer to it as {ogcapi-common} in the text. See Asciidoc documentation.

This is not working anymore in the latest snap version (1.8.6). It now generates URLs surrounded with ++ and outputs the following error:

Malformed URI: ++https://ogcapi.ogc.org/common++
opoudjis commented 1 year ago

Thank you, I know what that bug points to (we're escaping links in internal processing, so they don't get distorted by smart formatting), but not why it's happening (the ++ should be getting picked up and stripped out in postprocessing.)

That said, I cannot replicate the error with the following document:

= X
:data-uri-images: false
:copyright-holder: Fred;Jack
:break-up-urls-in-tables:
:doctype: engineering-report
:ogcapi-common: https://ogcapi.ogc.org/common[OGC API - Common]

== Clause

{ogcapi-common}

As you can see, the Semantic XML that document generates is in order:

<clause id="_clause" obligation="normative">
<title>Clause</title>
<p id="_7e5bfa70-5d68-6668-6f00-b87b26b4dd00"><link target="https://ogcapi.ogc.org/common">OGC API — Common</link></p>
</clause>

Pleaase provide a document on which this is failing, for me to replicate the issue.

alexrobin commented 1 year ago

Hi, below is an example document to recreate the issue:

= Test Document
:doctype: standard
:encoding: utf-8
:lang: en
:status: draft
:committee: technical
:docnumber: 23-001r0
:received-date: yyyy-mm-dd
:issued-date: yyyy-mm-dd
:published-date: yyyy-mm-dd
:fullname: Metanorma User
:docsubtype: implementation
:keywords: test, bug, link
:submitting-organizations: OGC; 
:mn-document-class: ogc
:mn-output-extensions: xml,html,doc,pdf
:local-cache-only:
:data-uri-image:
:edition: 1.0

:my_link: link:https://www.metanorma.org/[metanorma]

== Clause 1

Some text where I include my link to {my_link}

I build it with metanorma compile --agree-to-terms -t ogc -x html test.adoc and get the following output:

Document Attributes: '' is not a permitted subtype of Standard: reverting to 'implementation'
Anchors: (ID _db0b5b69-50ff-6cd8-756c-07d8b77a123a): Malformed URI: ++https://www.metanorma.org/++
Malformed URI: ++https://www.metanorma.org/++
Style: Abstract is missing!
Style: Preface is missing!
Style: Submitters is missing!
Style: Prefatory material must be followed by (clause) Scope
Style: Document must contain at least one clause
Malformed URI: ++https://www.metanorma.org/++

It builds fine if I comment out the line starting with :my_link:

The version of Metanorma I have installed is the snap version at revision 181 that is advertised as version 1.8.6

alexrobin commented 1 year ago

I'm also able to build your test document without issue BTW.

alexrobin commented 1 year ago

Ok, after comparing the two documents, I found out that it works if I don't have blank lines between the my_link variable and the other variables on top! like this:

= Test Document
:doctype: standard
:encoding: utf-8
:lang: en
:status: draft
:committee: technical
:docnumber: 23-001r0
:received-date: yyyy-mm-dd
:issued-date: yyyy-mm-dd
:published-date: yyyy-mm-dd
:fullname: Metanorma User
:docsubtype: implementation
:keywords: test, bug, link
:submitting-organizations: OGC; 
:mn-document-class: ogc
:mn-output-extensions: xml,html,doc,pdf
:local-cache-only:
:data-uri-image:
:edition: 1.0
:my_link: link:https://www.metanorma.org[metanorma]

== Clause 1

Some text where I include my link to {my_link}
ronaldtse commented 1 year ago

@alexrobin that's correct -- no blank lines are meant to exist between document attributes as part of the document header in AsciiDoc. Sorry this wasn't clear!

alexrobin commented 1 year ago

Thanks @ronaldtse.

What's weird is that attributes work anywhere in the document in general. The problem occurs only when they contain links.

What I was trying to do is define attributes in separate files that are included in the main document, so that they are scoped to these files. Are you saying that's not possible with Asciidoc? FYI I used to be able to do that in v1.7.

alexrobin commented 1 year ago

@ronaldtse That's what the AsciiDoc spec says about document attributes:

The attribute must be set or unset by the end of the document header (i.e., set by the API, CLI, or in the document header). Otherwise, the assignment won’t have any effect on the document. If an attribute is not marked as Header Only, it can be set anywhere in the document, assuming the attribute is not locked by the API or CLI. However, changing an attribute only affects behavior for content that follows the assignment (in document order).

I would think that custom attributes should not be considered Header Only

opoudjis commented 12 months ago

Having endured Asciidoctor's syntax for the past 6 years, and still being surprised by random implementation choices like this, I'll just say that I wish I didn't have to deal with this placement of attributes, but I do.

The preprocessor that escapes links knows not to escape links in the header document attributes, sourcecode snippets, listings, literals, and passthroughs. It needs to also not escape links in mid-document document attributes.

opoudjis commented 12 months ago

Fix will be included in next release (Dec 11).

opoudjis commented 12 months ago

Compiling your document now gives the Metanorma Semantic XML:

<p id="_d6dc67e1-b322-e159-e62b-aac23af1fa5c">Some text where I include my link to 
<link target="https://www.metanorma.org/">metanorma</link></p>

and none of the malformed URI errors.

ghobona commented 12 months ago

@alexrobin The fix is expected to be available on docker next week beginning 2023-12-12.

alexrobin commented 11 months ago

@opoudjis @ghobona Thanks guys for the quick fix!

opoudjis commented 11 months ago

Thank us when it's live :-) , we have had difficulty with releases over the past month or so. I'm just sorry it took me a while to understand your issue...