Docutils: Documentation Utilities / Feature Requests / #61 Support for :BCP: role, similar

Günter Milde - 2019-04-15

A patch is welcome.

If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Roberto Polli - 2019-04-15

Where should I put it?

Should I reuse rfc code as the goal is similar;

or should I duplicate it?

Thx++,
R.
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Günter Milde - 2020-08-24

A patch can be added as attachment here.
I propose to re-use "rfc" code. (Maybe adding optional arguments there.)
If possible, please also add unit-tests, modelled on the rfc or pep tests.

If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Adam Turner - 2021-12-30

Hi Günter @milde
I'm not sure how to convert a git patch into svn, but I've attached said git diff below.

This adds an explicit bcp role, tests, and documentation.

I can also add a commit-by-commit patch, broadly I added the role, and then updated the RFC base URL, hence the larger number of files touched.

A

add-bcp.diff

If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
- Günter Milde - 2022-01-03
  
  Thank you for the patch.
  Any patch that can be applied with git apply or git am -3 is fine.
  Separate patches for the different commits may be better, you can generate a "commit patch" with git format-patch (or via some GUI tools). (Mind that due to SVN limitations, SVN will set the author to the "sponsor" running git-svn dcommit.)
  
  Small things:
  
  There is no need to translate the short alias 'bcp'. Similar to 'rfc' and 'pep' it may be mapped to 'bcp-reference' or omitted in the language files. (The difference is an info message if converting a foreign language document with --verbose).
  
  In "docs/ref/rst/roles.txt": changing the anchor to .. _rfc-role: allows simpler referencing with `RFC role`_.
  
  In test/test_language.py: Why do you raise SystemExit? It is current praxis to let the test suite run on (if possible) and collect all problems.
  
  Large question: How about the following (instead or in addition to a new bcp role)?
  
  There are many more similar document sets (Debian enhancement proposals or Django enhancement proposals, ..., maybe sometimes also Docutils enhancement proposals),
  but not all of them are important for everyone.
  One idea would be to allow deriving custom "RFC-like" roles from "rfc-reference" using the role directive with the base-URL given as customization option (similar to "language" for roles derived from code).
  A 'bcp' role could then created with
  
  .. role:: bcp(rfc-reference) :base-url: https://datatracker.ietf.org/doc/html/bcp
  
  This allows more flexibility. We could also use a placeholder for the actual number.
  
  If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
  - Adam Turner - 2022-01-04
    
    @milde
    
    I've updated the implementation, please see https://github.com/AA-Turner/docutils/pull/2.patch // https://github.com/AA-Turner/docutils/pull/2
    
    here is no need to translate the short alias 'bcp'
    
    OK, dropped
    
    Why do you raise SystemExit
    
    I can't remember, but I agree with you. Dropped this.
    
    How about the following ...
    
    I think I'd prefer keeping the change smaller for now -- one thing I did do in the most recent update is create a factory function rfc_like_role, so there is the option to extend Docutils to add custom things should people need it.
    
    A
    
    If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
    - Adam Turner - 2022-01-12
      
      @milde please may I request a re-review on this one?
      
      A
      
      If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
      - Günter Milde - 2022-01-12
        
        After the decision to accept a patch for a new "hardcoded" BCP role, I learned about more "PEP/RFC-like" document series (including the idea to use introduce Docutils Enhancement Proposals).
        Now, the jury is out whether a "role-builder" would be better than one ... x new pre-defined roles and whether "BCP" should be added to the pre-defined/hard-coded roles.
        This is why I would prefer to wait a bit with this addition and concentrate on the other irons in the fire.
        Sorry, and thanks for the work. Günter
        
        If you would like to refer to this comment somewhere else in this project, copy and paste the following link:
        
        Adam Turner - 2022-01-12
        
        Ok, no worries :)
        A
        
        If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Adam Turner - 2022-01-02

Hi, Engelbert suggested I open a PR for another patch so I'm doing the same here.

Please see https://github.com/AA-Turner/docutils/pull/2 for referenece, or https://github.com/AA-Turner/docutils/pull/2.diff for the full diff to apply locally.

A

If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Günter Milde - 2024-02-27

The Sphinx extension extlinks is a generic solution to the common pattern of having many external links that point to URLs on one and the same site.
So, with Sphinx one may define a :bcp: role by adding these contents to conf.py:

extlinks = { 'doi': ('https://tools.ietf.org/html/bcp%s', 'bcp:'), }

Last edit: Günter Milde 2024-02-27
If you would like to refer to this comment somewhere else in this project, copy and paste the following link:

Support for :BCP: role, similar

Group

Searches

Help

#61 Support for :BCP: role, similar

I wish

Notes

Discussion