Get rid of .Xr in .Nd and make the .Nd itself more informative.

Thank you for the review!

I have not reviewed this because all I know about colors is how to turn them off, drives me crazy. Maybe... @dteske might know?

In D55333#1338496, @temcbun_gmail.com wrote:

@jilles Could you please accept this revision once again, just to move it into 'ready to land' category?

That is not necessary.

1. We do not really have tooling around that, so it does not make it any more discoverable.
2. Whoever lands it is responsible for handling the judgement. So, jilles approval stands unless he rescinds it or a change is made which we would deem requires his re-review per the context.
3. Someone might do that as a form of ping, since it sends out an email.

For example, since jilles is reviewing it in the context of being the lead shell maintainer, we could still make mechanical changes at this stage like fixing a typo or improving text alignment. However a content change that changes the meaning would, to me, invalidate his previous approval and require his re-review.

Thank you both, I think this is a great new feature for the sh manual and I am so excited to land this now!

@jilles Could you please accept this revision once again, just to move it into 'ready to land' category?

Ping.

Rebase the patch and bump .Dd.

Ping.

Ping.

Ping.

In D57720#1331295, @temcbun_gmail.com wrote:

@ziaee Could you please MFC this commit (I see the commit message says it is to be MFCed after 3 days, but it's still not).

@ziaee Could you please MFC this commit (I see the commit message says it is to be MFCed after 3 days, but it's still not).

Yes, as you said, change it.

https://docs.asciidoctor.org/asciidoc/latest/sections/bibliography/

In D58038#1331015, @olce wrote:

Removing the hyphen in the first line is fine, but then that should be mentioned in the commit message. I can add a sentence to that effect myself.

Removing the hyphen in the first line is fine, but then that should be mentioned in the commit message. I can add a sentence to that effect myself. Which mail do you want to use? The one that can be inferred from your Phabricator login? I also see a mail at "zohomail" in the tree that could match. If you have to disclose the full name and don't want to do that here, then please mail it to me (olce@).

Remove hyphen from the first comment line. Thanks @ziaee!

Ping for review.

In D57999#1330765, @vladlen wrote:

In D57999#1330255, @ziaee wrote:

Do you see any problems with them?

It seems you pushed this commit already and it is live on https://docs.freebsd.org/en/books/dev-model/, where the links work. However local build with cd documentation; make, the links do not work, whereas they links do work for local build in handbook. Also, the appearance is wrong for that page because there are padded spaces some places and not other places. Maybe we can do something like \[crossref:dev-model[ref-freebsd-trenches, Lehey 2002]\] for the appearance? I do not know why the links are broken in offline build though.

I will check it. I checked it locally with cd documentation; make run and
looked at it in a browser.

I tried using \[ , but the output rendered as \[ literally.

Probably we could change the link style. Links like [1] were used in old
books, and now they are mostly used in scientific articles. Square brackets
are special symbols in AsciiDoc, and we will spend more time fighting with
them than using them comfortably.

In D57999#1330255, @ziaee wrote:

Do you see any problems with them?

It seems you pushed this commit already and it is live on https://docs.freebsd.org/en/books/dev-model/, where the links work. However local build with cd documentation; make, the links do not work, whereas they links do work for local build in handbook. Also, the appearance is wrong for that page because there are padded spaces some places and not other places. Maybe we can do something like \[crossref:dev-model[ref-freebsd-trenches, Lehey 2002]\] for the appearance? I do not know why the links are broken in offline build though.

In D58001#1330236, @bcr wrote:

We can't make changes to past release notes once they are published. They become part of the release hash and would change in a number of places that reference them (even if they contain typos).

In D58001#1330236, @bcr wrote:

We can't make changes to past release notes once they are published. They become part of the release hash and would change in a number of places that reference them (even if they contain typos).

Do you see any problems with them?

We can't make changes to past release notes once they are published. They become part of the release hash and would change in a number of places that reference them (even if they contain typos).

In D57999#1330089, @vladlen wrote:

In D57999#1330069, @ziaee wrote:

In D57999#1330065, @carlavilla wrote:

In D57999#1330057, @ziaee wrote:

Dude you rock! Aside from dev-model, all the changes LGTM.

if the macro is broken, I need to fix it. But I created this macros coz we have these scenarios:

• Online website (freebsd.org, docs.freebsd.org)
• Offline website
• PDFs

It works everywhere else I checked except dev-model.

This links had 2 problems:
[crossref:dev-model[freebsd-send-pr, FreeBSD, 2002D]]

1. The same, as in website - it started and finished by square bracket

and simply disappeared from output (considered as AsciiDoc command).
I fixed this, they appeared, and I saw second problem:

2. The text FreeBSD, 2002D rendered as FreeBSD, everything

after comma were ignored. I removed comma and text is renderd correctly.
This comma is only for refference style, it does not have any special meaning.
With this changes all these links work correctly at least in HTML.

Do you see any problems with them?

P.S. Original article used reference style [FreeBSD, 2002D] long before AsciiDoc
was choosen for FreeBSD documentation, and now [ and ] chars need special treatment
in adoc files, or we are free to rename all these links.