search

ietf-tools / xml2rfc

Generate RFCs and IETF drafts from document source in XML according to the IETF xml2rfc v2 and v3 vocabularies
https://ietf-tools.github.io/xml2rfc/
BSD 3-Clause "New" or "Revised" License
71 stars 39 forks source link

--id-base-url vs. --id-reference-base-url options #618

Closed ietf-svn-bot closed 3 years ago

ietf-svn-bot commented 3 years ago

owner:krathnayake@ietf.org resolution_fixed type_defect | by arusso@amsl.com

Regarding options as documented on https://xml2rfc.ietf.org/xml2rfc-doc.html#name-html-format-options-2 -- For rendering an RFC, if the option is changed as follows in order to change the URL that appears for references to Internet-Drafts: 

OLD: --id-reference-base-url="https://tools.ietf.org/html/"
NEW: --id-reference-base-url="https://datatracker.ietf.org/doc/html/"

there's no effect in the output. (Past guidance was to use --id-reference-base-url for this purpose.) Tried using --id-base-url.

Assuming --id-base-url should be used, then can the ".txt" be removed from the output? See (C) below. (If --id-base-url should not be used, then please advise.)

Sample files (running the command with --id-base-url="https://datatracker.ietf.org/doc/html/") https://www.rfc-editor.org/v3test/test_base_url.html https://www.rfc-editor.org/v3test/test_base_url.pdf https://www.rfc-editor.org/v3test/test_base_url.txt https://www.rfc-editor.org/v3test/test_base_url.xml (input)

For example, looking at [TUNNELS]: (A) Output using "BEFORE" command:

<https://tools.ietf.org/html/draft-ietf-intarea-tunnels-10>

(B) The desired output:

<https://datatracker.ietf.org/html/draft-ietf-intarea-tunnels-10>

(C) Output using the command with --id-base-url="https://datatracker.ietf.org/doc/html/":

<https://datatracker.ietf.org/doc/html/draft-ietf-intarea-tunnels-10.txt>

Seems the ".txt" should be removed? (However: despite the ".txt", this URL resolves to an HTML page.)

Issue migrated from trac:618 at 2022-02-08 07:14:06 +0000

ietf-svn-bot commented 3 years ago

@arusso@amsl.com commented

correction to (B). The desired output: 

<https://datatracker.ietf.org/doc/html/draft-ietf-intarea-tunnels-10>
ietf-svn-bot commented 3 years ago

@rjsparks@nostrum.com _changed status from new to under_review_

ietf-svn-bot commented 3 years ago

@rjsparks@nostrum.com commented

Re (C). /doc/html is html-ized versions of the .txt files. The URL matcher is very lenient with what it will accept.

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org commented

Default value for both --id-base-url and --id-reference-base-url must be https://datatracker.ietf.org/doc/html/.

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org _changed status from under_review to assigned_

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org set owner to krathnayake@ietf.org

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org commented

--id-reference-base-url replaces references with seriesInfo with name attributes that have "Internet-Draft" as it's value. This example works as expected:

        <reference anchor="SEMANTICS" target="http://www.ietf.org/internet-drafts/draft-ietf-httpbis-semantics-14.txt">
          <front>
            <title>HTTP Semantics</title>
            <author initials="R" surname="Fielding" fullname="Roy Fielding">
              <organization/>
            </author>
            <author initials="M" surname="Nottingham" fullname="Mark Nottingham">
              <organization/>
            </author>
            <author initials="J" surname="Reschke" fullname="Julian Reschke">
              <organization/>
            </author>
            <date month="January" day="12" year="2021"/>
            <abstract>
              <t>The Hypertext Transfer Protocol (HTTP) is a stateless application- level protocol for distributed, collaborative, hypertext information systems.  This document describes the overall architecture of HTTP, establishes common terminology, and defines aspects of the protocol that are shared by all versions.  In this definition are core protocol elements, extensibility mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) schemes.  This document obsoletes RFC 2818, RFC 7231, RFC 7232, RFC 7233, RFC 7235, RFC 7538, RFC 7615, RFC 7694, and portions of RFC 7230.</t>
            </abstract>
          </front>
          <seriesInfo name="Internet-Draft" value="draft-ietf-httpbis-semantics-14"/>
        </reference>

This doesn't work when references are inserted as XInclude like in the input document in the original ticket.

Using XInclude for references seems to be the correct way because xml2rfc V2-V3 converter has following option: --add-xinclude replace reference elements with RFC and Internet-Draft seriesInfo with the appropriate XInclude element

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org commented

--id-base-url replaces the ID URL on XInclude correctly but add .txt extension as a safety feature if ID URL is different from tools.ietf.org

Comment from the source code:

# tools.ietf.org has code to deal with draft urls (text, html, and pdf) lacking
# extension, but others may not.  www.ietf.org/archive/id/ only has .txt versions:

By adding https://datatracker.ietf.org/doc/html/ as default URL and replacing above test with datatracker.ietf.org should allow --id-base-url to be used to get the desired ID URL output.

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org changed _comment0 which not transferred by tractive

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org changed _comment1 which not transferred by tractive

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org changed status from assigned to closed

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org set resolution to fixed

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org commented

Fixed in 448f9914a8002b0f3d51f5d7abab34c2377f9ca0:

Add https://datatracker.ietf.org/doc/html/ as default id-base-url and id-reference-base-url. Fixes #618. Commit ready for merge.

ietf-svn-bot commented 3 years ago

@rjsparks@nostrum.com commented

This looks good, but we should keep in mind that the bit of code that adds the .txt extension makes just as bad an assumption as not adding it. I don't think we need to address this now, but we may want to replace these two base-url flags with url-pattern flags that allow controlling the whole generated URL rather than just the prefix.

ietf-svn-bot commented 3 years ago

@kesara@staff.ietf.org commented

Should we be look into deprecating --id-reference-base-url flag and just replacing both with a single flag that controls output of generated ID URLs?

Because as I understand with V3, recommended way to references IDs is using XInclude. Is there a usecase for --id-reference-base-url in V3 references?

ietf-svn-bot commented 3 years ago

@rjsparks@nostrum.com commented

Fixed in fbdfea1d4add7531b92448f573d2d5c4ca6a8fae:

Merged in 448f9914a8002b0f3d51f5d7abab34c2377f9ca0 from krathnayake@ietf.org:\n Add https://datatracker.ietf.org/doc/html/ as default id-base-url and id-reference-base-url. Fixes #618.