ietf-tools / ietf-tools/xml2rfc

seeking a better way to have a blank line followed by an indented dl

Open
#985 3 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
HTML
Stars
124
Forks
79
Avg merge
6h 30m
Merged PRs (30d)
3

Description

Description

Summary: We used <t><br/></t> to get the desired output. Seems that ideally we wouldn't use <br/> for this case. Would be helpful to be able to indent a whole <dl>.
Example: https://www.rfc-editor.org/authors/rfc9381.html (e.g., section 4, 4.1, 4.2, 4.3, and others)

Details:
For example (original):

   Parameters used:

      (n, e) - RSA public key

      K - RSA private key (its representation is implementation-
      dependent)

      k - length in octets of the RSA modulus n (k must be less than
      2^32)

   Fixed options (specified in Section 4.4):

      Hash - cryptographic hash function

      hLen - output length in octets of hash function Hash

      suite_string - an octet string specifying the RSA-FDH-VRF
      ciphersuite, which determines the above options

With the assumption that we'd like the nested lists to be <dl> bc it's accurate semantically, here are some options: (test files were updated only for the portion above above)
A) <dl> for outer items, then nested <dl>

B) <ul bare="true" empty="true"> <li> for outer items, each of which has a nested <dl>

C) <t> for outer items, then a <dl>.

What was done in the original (draft-irtf-cfrg-vrf-15.xml)
D) <t> for outer items, then a <ul empty="true">

  • Cons: not accurate semantically; definitions that are longer than one line do not wrap as desired; past guidance to the RPC was to not use <ul empty="true"> to create indentation.

Potential improvements here

  • better documentation around acceptable use for <br/>
  • B seems to be a bug bc the other outputs should match.
  • a new attribute on <dl> to indicate "put a blank line after dt" (this is not accomplished with newline="true")
    (FWIW, testing of changes to the spacing attribute, did not help here.)
  • the ability to have an indented <dl> without nesting it at all. perhaps as a new attribute. (Note: the indent attribute on a dl currently has to do with indenting the lines after the first line. it does not have to do with indenting the dl as as whole.)
Code of Conduct

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start by reviewing the current file for RFC 9381 section 4 and compare the test9381_t_dl.html, test9381_bad_ul_in_html.html, and test9381_bad_ul_in_html.txt examples with the original draft. Determine which nested dl spacing and indentation behavior should be supported, then update the relevant tests and documentation so the HTML, text, and PDF outputs match the agreed result.

Written by the indexing model from the issue text.

Assessment

Tech stack
html, xml
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.