Subject: Re: [xml2rfc] what to do about missing cites and encouraging better citing

From: Randy Bush <[email-masked]>
Date: Sun, 01 Jul 2018 18:33:36 -0700

[ moved from ietf list ]

> Adding a bibliography line of the form
> 
>   SHAIKH2002: DOI.10.1145_637201.637236
> 
> to the YAML header, so you can then simply reference it as
> [SHAIKH2002], is optional.

can you be explicit about the hack?  i have a doi of

    DOI:10.1145/2975159

and i am in xml2rfc.

randy

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Jul 2018 07:55:36 +0200

See <https://xml2rfc.tools.ietf.org/>:

> The following citation libraries are generated on demand when referenced, with a cache maintained for 24 hours.
> citation
> library 	Example URLs
> DOI 	http://xml2rfc.ietf.org/public/rfc/bibxml7/reference.DOI.12.1234/12345.12345.xml
> http://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.12.1234/12345.12345.xml
> IANA 	http://xml2rfc.ietf.org/public/rfc/bibxml8/reference.IANA.example-table-name.xml
> http://xml2rfc.ietf.org/public/rfc/bibxml-iana/reference.IANA.example-table-name.xml
> The anchors are automatically generated based on the DOI or IANA table name. The anchor may be overridden by adding a "?anchor=EXAMPLE" argument to the URL. 

Best regards, Julian

---

From: Michael Tuexen <[email-masked]>
Date: Mon, 2 Jul 2018 09:15:00 +0200

> On 2. Jul 2018, at 07:55, Julian Reschke <[email-masked]> wrote:
> 
I'm trying to deal with DOI:10.1145/1496091.1496095.

I can reference it by using

<xref target='DOI_10.1145_1496091.1496095'/>

and have to put

<?doi include='bibxml7/reference.DOI.10.1145/1496091.1496095' ?>

in the references section, where I also use

<?rfc include='reference.RFC.4960' ?>

I'm wondering why I have to use the 'bibxml7/' prefix. I expected it to be
prepended automatically. To be precisely, I expected

<?doi include='reference.DOI.10.1145/1496091.1496095' ?>

to work...

Best regards
Michael 
> Best regards, Julian
> 
> _______________________________________________
> xml2rfc mailing list
> [email-masked]
> https://www.ietf.org/mailman/listinfo/xml2rfc

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 05:11:24 -0700

> See <https://xml2rfc.tools.ietf.org/>:

uh, stil banging head trying to cite the cacm paper

    https://doi.org/10.1145/2975159

with
 
  <references title="Informative References">
    <"?http://xml2rfc.ietf.org/public/rfc/bibxml7/reference.DOI.10.1145/2975159.xml"?>
    </references>

and refer to it as

    <xref target="DOI:10.1145/2975159"/>

i get

 <string>: Line 985: StartTag: invalid element name

on the references entry

randy

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 05:21:54 -0700

>     <"?http://xml2rfc.ietf.org/public/rfc/bibxml7/reference.DOI.10.1145/2975159.xml"?>

sigh.  same for getting the syntax a little better :)

    <?"http://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml"?>

and if i

    <?doi include="bibxml7/reference.DOI.10.1145/2975159"?>

then the

gets

 <string>: Line 82: Syntax of value for attribute target of xref is not valid
 <string>: Line 82: IDREF attribute target references an unknown ID "DOI:10.1145/2975159"

---

From: Bill Fenner <[email-masked]>
Date: Mon, 2 Jul 2018 10:03:46 -0400

Hey Randy,

I browsed to
https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml
and see that the generated anchor is <reference
anchor="DOI_10.1145_2975159">, so try <xref target="DOI_10.1145_2975159"/>?

If you don't want this to be the reference name, the web page says

The anchors are automatically generated based on the DOI or IANA table
name. The anchor may be overridden by adding a "?anchor=EXAMPLE" argument
to the URL.

and I tried
https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=yippee
and it gave me <reference anchor="YIPPEE">.

  Bill

On Mon, Jul 2, 2018 at 8:22 AM Randy Bush <[email-masked]> wrote:

> >     <"?
> http://xml2rfc.ietf.org/public/rfc/bibxml7/reference.DOI.10.1145/2975159.xml
> "?>
>
>     <?"
> http://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml
> "?>
>
> and if i
>

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 07:45:19 -0700

> target="DOI_10.1145_2975159"/>?

neat trick.

worked, but gave me the ugly ref

thanks!

> and it gave me <reference anchor="YIPPEE">.

        <?doi include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=JUPITER"?>
or
       <?doi include="bibxml7/reference.DOI.10.1145/2975159.xml?anchor=JUPITER"?>

with

    <xref target="JUPITER"/>

gave me

    <string>: Line 82: IDREF attribute target references an unknown ID "JUPITER"

but

    <reference anchor="JUPITER"/>

on line 82 gave me

     <string>: Line 79: Element reference is not declared in t list of possible children
     <string>: Line 82: Element reference content does not follow the DTD, expecting (front , seriesInfo* , format* , annotation*), got nothing.

clearly, i am not really understanding, shooting wildly, and hoping to
hit something; with the usual success rate for this tactic.

randy

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Jul 2018 17:21:45 +0200

On 2018-07-02 09:15, Michael Tuexen wrote:
> ...

There is no "<?doi>" processing instruction.
> ...

Well, nobody said that that works, right?

The PI is called "rfc", and the include needs the full URI. So

<?rfc 
include='https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=yippee' 
?>

should get you something that can be referenced with (ack Bill F.)

  <xref target"yippee"/>

Best regards, Julian

---

From: Michael Tuexen <[email-masked]>
Date: Mon, 2 Jul 2018 17:44:25 +0200

> On 2. Jul 2018, at 17:21, Julian Reschke <[email-masked]> wrote:
> 
Correct. Just guessing...
> The PI is called "rfc", and the include needs the full URI. So
OK. However for RFCs I always used

instead of

<?rfc include='http://xml2rfc.ietf.org/public/rfc/bibxml/reference.RFC.4960' ?>

which I find a very handy. I can just leave out http://xml2rfc.ietf.org/public/rfc/bibxml/.
> 
> <?rfc include='https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=yippee' ?>
> 
Using
<?rfc include='https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues' ?>
results in

Unable to Validate File

Parsing file INPUT
Resolving entity... /usr/local/lib/python2.7/dist-packages/xml2rfc/templates/rfc2629.dtd
Resolving entity... /usr/local/lib/python2.7/dist-packages/xml2rfc/templates/rfc2629-xhtml.ent
Resolving entity... /usr/local/lib/python2.7/dist-packages/xml2rfc/templates/rfc2629-other.ent
Resolving entity... /usr/local/lib/python2.7/dist-packages/xml2rfc/templates/rfc2629.dtd
Resolving entity... /usr/local/lib/python2.7/dist-packages/xml2rfc/templates/rfc2629-xhtml.ent
Resolving entity... /usr/local/lib/python2.7/dist-packages/xml2rfc/templates/rfc2629-other.ent
Resolving include... /home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml/reference.RFC.2119.xml
Resolving include... /home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml/reference.RFC.4895.xml
Resolving include... /home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml/reference.RFC.4960.xml
Resolving include... /home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml/reference.RFC.5061.xml
Resolving include... /home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml/reference.RFC.6096.xml
Resolving include... https://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues'
Resolving include... https://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml'
Resolving include... https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues'
Resolving include... https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml'
Resolving include... https://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues'
Resolving include... https://xml2rfc.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml'
Resolving include... https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues'
Resolving include... https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml
URL retrieval failed with status code 404 for 'https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues.xml'
ERROR: Unable to parse the XML document: INPUT
 INPUT: Line 1852: Unable to resolve external request: "https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095?anchor=Issues"

Using XML_LIBRARY=/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml2:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml3:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml4:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml5:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml6:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml7:/home/www/tools.ietf.org/tools/xml2rfc/web/public/rfc/bibxml8

whereas using

<?rfc include='https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/1496091.1496095' ?>

works in combination with

Any reason why I just can't use
<?rfc include='reference.DOI.10.1145/1496091.1496095' ?>
and the tool guesses that a prefix of https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/ is needed like
in the case of RFCs?

Best regards
Michael

PS: You recommend https:// whereas the https://xml2rfc.tools.ietf.org recommends http://

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 09:16:48 -0700

> should get you something that can be referenced with (ack Bill F.)
               ^

but

    <?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=JUPITER"?>

    <xref target="JUPITER"/>

perhaps the difference is in my heaer?

    <?xml version="1.0" encoding="utf-8"?>
    <!DOCTYPE rfc SYSTEM "rfc2629.dtd">

randy

---

From: Julian Reschke <[email-masked]>
Date: Mon, 2 Jul 2018 18:22:14 +0200

> which I find a very handy. I can just leave out http://xml2rfc.ietf.org/public/rfc/bibxml/.

Too much magic for my taste.

> and the tool guesses that a prefix of https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/ is needed like

Because nobody wrote that code yet-

If <?rfc include> doesn't work with parameters, I recommend using proper 
XML inclusion instead. See 
<https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#examples.internalsubset>.

Best regards, Julian

---

From: Michael Tuexen <[email-masked]>
Date: Mon, 2 Jul 2018 20:26:13 +0200

> On 2. Jul 2018, at 18:22, Julian Reschke <[email-masked]> wrote:
> 
OK. I prefer consistency... If it should not be supported, it should not work...
> Because nobody wrote that code yet-
OK. But according to your above statement, it should not be written and the
RFC abbreviation support should be removed... As long as I know what is working
I can deal with it.
> 
> If <?rfc include> doesn't work with parameters, I recommend using proper XML inclusion instead. See <https://greenbytes.de/tech/webdav/rfc2629xslt/rfc2629xslt.html#examples.internalsubset>.
I don't need a particular way of reference. My position is that I provide the
logical links and the tool provides the output as preferred by the RFC editor.
That way I don't have to deal too much with the layout stuff.

Thanks for your help!

Best regards
Michael

---

From: Bill Fenner <[email-masked]>
Date: Mon, 2 Jul 2018 14:30:04 -0400

Randy,

I tried the following:

   <section title="Blah">
    <t>totally <xref target="JUPITER"/> tubular</t>
   </section>
...
 <back>
...
   <references title="Informative References">
      <?rfc include="
https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=JUPITER
"?>
...

and I got

8.  Blah

   totally [JUPITER] tubular

and

   [JUPITER]  Singh, A., Germano, P., Kanagala, A., Liu, H., Provost,
              J., Simmons, J., Tanda, E., Wanderer, J., HAP.lzle, U.,
              Stuart, S., Vahdat, A., Ong, J., Agarwal, A., Anderson,
              G., Armistead, A., Bannon, R., Boving, S., Desai, G., and
              B. Felderman, "Jupiter rising", Communications of the
              ACM Vol. 59, pp. 88-97, DOI 10.1145/2975159, August 2016.

Is your <?rfc include...?> inside the references section? Location in the
file is my only guess about what could be going wrong for you here.

  Bill

On Mon, Jul 2, 2018 at 12:17 PM Randy Bush <[email-masked]> wrote:

> > include='
> '
>     <?rfc include="
> https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=JUPITER
> "?>
>
>     <xref target="JUPITER"/>
>

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 13:11:23 -0700

>       <?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=JUPITER"?>

i copy pasted the above and blew chunks

> Is your <?rfc include...?> inside the references section?

    </section>
  </middle>
<back>
  <references title="Normative References">
    <?rfc include="reference.RFC.2119"?>
    <?rfc include="reference.RFC.3032"?>
    <?rfc include="reference.RFC.4271"?>
    <?rfc include="reference.I-D.ietf-lsvr-bgp-spf"?>
    <?rfc include="reference.RFC.5226"?>
    <?rfc include="reference.RFC.7752"?>
    <?rfc include="reference.I-D.ietf-idr-bgpls-segment-routing-epe"?>
    <?rfc include="reference.I-D.ietf-idr-bgp-ls-segment-routing-ext"?>
    </references>
  <references title="Informative References">
    <?rfc include="https://xml2rfc.tools.ietf.org/public/rfc/bibxml-doi/reference.DOI.10.1145/2975159.xml?anchor=JUPITER"?>
    </references>
  </back>

yes, i still use wirth pascal indentation :)

> Location in the file is my only guess about what could be going wrong
> for you here.

no prob with other refs

randy, looking at the clock

---

From: Michael Tuexen <[email-masked]>
Date: Mon, 2 Jul 2018 22:20:30 +0200

> On 2. Jul 2018, at 22:11, Randy Bush <[email-masked]> wrote:
> 
>> I tried the following:
>> 
>>   <section title="Blah">
More than 2 hours left...
Are you both using the same version, let's say the online version from
https://xml2rfc.tools.ietf.org

Best regards
Michael

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 13:28:13 -0700

> https://xml2rfc.tools.ietf.org

good idea

 The server encountered an internal error and was unable to complete
 your request. Either the server is overloaded or there was an error in
 a CGI script.

twice  :)

on my laptop

% xml2rfc --version
xml2rfc 2.9.9

---

From: Henrik Levkowetz <[email-masked]>
Date: Mon, 2 Jul 2018 22:35:10 +0200

Hi Randy

>  your request. Either the server is overloaded or there was an error in

The server _is_ heavily loaded, I see.  Will look at that.  But assuming
that your laptop has internet connectivity, there should be no difference
using the web service compared with the latest local xml2rfc, which is the
one you have.

Bill's text should work; I've just verified that the reference generated
at:

does return a reference with anchor="JUPITER".

However, if you've already run xml2rfc with that url but without the queryarg,
it may have cached the result.

Please clear the cache with

  $ xml2rfc --clear-cache

and try one more time.

Best,

	Henrik

---

From: Randy Bush <[email-masked]>
Date: Mon, 02 Jul 2018 13:37:09 -0700

> Please clear the cache with

yay!!!!  tack.

randy