Comments (6)
I believe you are correct here. I see the same thing in the rendered ronn.1
man page.
My understanding (mostly from the groff_man man page) is that .IP
is "indented paragraph", and .TP
is "tagged paragraph". AFAIK, there's no roff macro specifically for "definition lists", but a "tagged paragraph" is pretty much the same thing, just a more generalized form of it, and I think ronn
should be emitting definition lists as .TP
items.
The HTML rendering has a similar issue when I pop open ronn.1.html
in a browser.
That second format looks right to me, which supports your view that .TP
is the right way to do this.
Looks to me like the point where the ronn.1
output switches from .IP
to .TP
is where there's:
a) An additional intervening non-tagged/indented paragraph.
b) Oopsie, an unclosed <encoding
item in the definition-list item immediately preceding it.
* `-E`=<encoding>, `--encoding`=<encoding:
Specify the encoding that input files are in. Default is UTF-8, regardless
of user's locale settings. Input sent to STDIN is always treated as UTF-8,
regardless of whether `-E` is passed.
Format options control the files `ronn` generates, or the output format when the
`--pipe` argument is specified. When no format options are given, both `--roff`
and `--html` are assumed.
* `-r`, `--roff`:
Generate roff output. This is the default behavior when no <file>s are given
and ronn source text is read from standard input.
So probably this is a bug in the ronn
processing, and there's also a bug in the ronn.1.ronn
doco page which is maybe triggering it. I wonder if that unclosed tag is causing a parsing problem that is causing it to not properly recognize the preceding list as a definition list instead of a bullet list.
Have you observed this issue with other, simpler *.ronn
files?
References
We've had some other issues with list rendering in Ronn-NG:
from ronn-ng.
Oh, also there's an item in the should-be-a-definition-list-but-rendered-as-a-bullet-list in ronn.1.ronn
where the tag/definition-term item is lacking its trailing colon. That could be causing the type of list to be mis-detected, like there's some implicit "all(...)" logic in the list-type detection logic. See the missing trailing ":" in the "port" item here?
* `-S`, `--server`:
Don't generate files, start an HTTP server at <http://localhost:1207/> and
serve dynamically generated HTML for the set of input <file>s. A file named
[...]
* `--port`=<port>
When used with `-S`/`--server`, runs the server at the specified port instead
of the default port 1207.
* `--pipe`:
Don't generate files, write generated output to standard output. This is the
default behavior when ronn source text is piped in on standard input and no
<file> arguments are provided.
I'm thinking that if this is the problem, the right thing for ronn
to do is issue a warning when it has mixed types of list items.
from ronn-ng.
Adding the missing closing ">" on that encoding item did not fix the list-type rendering. It only fixed the italicization of the "encoding" bit.
Adding the missing trailing ":" on that "port" item does seem to fix the list-type rendering.
Notice that the literal colons in the bullet item texts disappeared too.
This required no code changes in Ronn-NG, just fixes to the bad ronn.1.ronn
markup. So that'll fix the formatting of the ronn
man page. Change to fix the ronn.1
man page is on branch bug/94_defn-lists-as-bullet-lists, in 9c0ce30 and then a doco regeneration in the next commit. I think I'll roll that in to v0.10.1.
But I think this still calls for a code fix: I think ronn
should be emitting a warning or error when it encounters a list with inconsistent bullet/tag/whatever items and there is some ambiguity about which type of list it's supposed to be. Planning that for v0.10.2.
from ronn-ng.
And I think here's the code problem/cause, in lib/ronn/document.rb
around line 408.
# Convert special format unordered lists to definition lists.
def html_filter_definition_lists
# process all unordered lists depth-first
@html.search('ul').to_a.reverse_each do |ul|
items = ul.search('li')
next if items.any? { |item| item.inner_text.strip.split("\n", 2).first !~ /:$/ }
[... then here's code to transform the `ul` list into a `dl` list ...]
I think that any?
in conjunction with the ...first !~ /:$/
means that if any if the items in the list are missing the trailing ":" colon from their first line/tag, then that whole list will be identified as a bullet or regular list, instead of a special definition list.
Now I'm actually a little unsure what to do here. Should ronn
issue a warning when there are inconsistent list item types? What if someone wants to make a bullet list where just some of the items' first lines have a trailing literal colon?
I think warning or erroring is still probably the right thing to do here, since the trailing :
is special markup in ronn syntax, which means you just can't really have list item introducer lines with trailing colons, unless you want them to be interpreted as definition items.
from ronn-ng.
I'm downgrading this bug to Low priority, since it's a not-too-large cosmetic issue, and there's a workaround that ronn
users can do currently.
from ronn-ng.
man ronn
is looking nicer now for the 0.10.1 release. Thanks, @narc-Ontakac2!
from ronn-ng.
Related Issues (20)
- Enable GitHub Pages
- Gobble up n-ronn fixes for 0.10.1 HOT 10
- Migrate to GitHub Actions from Travis CI HOT 1
- https links in man/* HOT 1
- My Ruby env is busted; bundle install permission errors HOT 6
- Add MacPorts installation instructions to doco
- Docker image for ronn-ng HOT 1
- bad link for ronn-format(7) HOT 2
- Failed to install ronn-ng because of ruby 3 HOT 1
- libxml 2.10+ compatibility for <dot.> and <foo:colon> angle-bracket syntax HOT 25
- Let's go, Pikachu! It's 0.10 and Ruby 3.x time HOT 5
- ronn vs ronn-ng: bare pipes and option descriptions missing HOT 1
- provide a Ronn rake task definition for clients to call
- `ronn --version` probs: no ".pre" part, bogus GitHub URL for untagged releases, doesn't reflect add'l commits/changes
- RPM build failure on Fedora 39/Rawhide (bc nokogiri libxml "foo:colon" thing) HOT 3
- Relax dependency versions to support more targets? HOT 7
- Rubocop offenses as of 2024-01-01 HOT 2
- Learn how to test in Fedora against system/RPM gem dependencies HOT 1
- Define lib/app separation and support
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from ronn-ng.