Bug 265246

Summary:	AsciiDoctor primer: make AsciiDoc examples of lists less ambiguous
Product:	Documentation	Reporter:	Graham Perrin <grahamperrin>
Component:	Books & Articles	Assignee:	Graham Perrin <grahamperrin>
Status:	Closed FIXED
Severity:	Affects Some People	CC:	carlavilla, fernape, salvadore
Priority:	---	Flags:	grahamperrin: maintainer-feedback? (debdrup)
Version:	Latest
Hardware:	Any
OS:	Any
URL:	https://github.com/freebsd/freebsd-doc/blob/main/documentation/content/en/books/fdp-primer/asciidoctor-primer/_index.adoc#4-lists

Description Graham Perrin freebsd_committer

2022-07-16 01:20:51 UTC

<https://www.freebsd.org/status/report-2022-01-2022-03/#_ports_collection> – with bullet points not presented as such – might be the result of following the second of these examples: 

<https://docs.freebsd.org/en/books/fdp-primer/book/#asciidoctor-ordered-lists>

<https://docs.freebsd.org/en/books/fdp-primer/book/#asciidoctor-unordered-lists>

Each example will be clearer if it includes a line of text preceding the first listing, and – essentially – the blank line in between. 

A blank line, because <https://docs.asciidoctor.org/asciidoc/latest/blocks/paragraphs/#create-a-paragraph>

> Adjacent or consecutive lines of text form a paragraph …

Comment 1 commit-hook freebsd_committer

2022-07-16 01:46:15 UTC

A commit in branch main references this bug:

URL: https://cgit.FreeBSD.org/doc/commit/?id=4e6d8da70fcb9015f42707b038950b2a2591c089

commit 4e6d8da70fcb9015f42707b038950b2a2591c089
Author:     Lorenzo Salvadore <salvadore@FreeBSD.org>
AuthorDate: 2022-07-16 01:41:23 +0000
Commit:     Lorenzo Salvadore <salvadore@FreeBSD.org>
CommitDate: 2022-07-16 01:45:34 +0000

    report-2022-01-2022-03/portmgr.adoc: Fix lists

    Add blank lines required to display bullet points properly.

    PR:             265246
    Reported by:    grahamperrin
    Approved by:    debdrup (status blanket)

 website/content/en/status/report-2022-01-2022-03/portmgr.adoc | 2 ++
 1 file changed, 2 insertions(+)

Comment 2 Lorenzo Salvadore freebsd_committer

2022-07-16 01:47:21 UTC

2022Q1 report has been fixed. Thanks Graham.

Comment 3 Fernando Apesteguía freebsd_committer

2022-10-09 16:04:23 UTC

^Triage: reporter is committer, assign accordingly.

If we are done with this PR, can the assignee close it?

Thanks!

Comment 4 Graham Perrin freebsd_committer

2022-10-09 18:12:28 UTC

(In reply to Fernando Apesteguía from comment #3)

> If we are done with this PR, 

We are not, please see <https://github.com/freebsd/freebsd-quarterly/pull/524#issuecomment-1272598550> concerning what seems to be a mistaken reference in the commit that was linked from comment 1.

Comment 5 Lorenzo Salvadore freebsd_committer

2022-10-09 19:22:57 UTC

The reference in the commit in comment #1 is not a mistake, but it is also true that it does not fix the main issue reported in this PR. Indeed it fixes only the issue reported in the first sentence of comment #0:

> <https://www.freebsd.org/status/report-2022-01-2022-03/#_ports_collection> – with bullet points not presented as such

After that commit bullet points are rendered correctly.

Comment 6 Graham Perrin freebsd_committer

2022-10-09 23:58:31 UTC

(In reply to Lorenzo Salvadore from comment #5)

Ah, OK, thanks for clarification. 

Some confusion, partly due to: 

* yesterday's use (above) of the phrase PR, which _always_ has  
  the commonplace GitHub meaning to me at first sight; and 

* yesterday's PRs from me, most (all?) of which are for quarterly 
  reports, one for which is for a report from portmgr – originally 
  PR 514 (a pull request) – but not the report from portmgr that is 
  corrected by yesterday's 4e6d8da70fcb9015f42707b038950b2a2591c089

I do understand that some people will have used the abbreviation PR to mean bug (in Bugzilla, a problem report that is a bug) for longer than some people have used the abbreviation PR to mean pull request (in GitHub). Still, it will really help me, if use of PR to mean bug can be minimised, especially in bug reports that overlap with pull requests. 

Thanks