Page MenuHomeFreeBSD
Differential D1237

address bug 195432
ClosedPublic
Actions

Authored by jgh on Nov 26 2014, 11:48 PM.
Tags
None
Referenced Files
Unknown Object (File)
Sun, Apr 14, 12:18 AM
Unknown Object (File)
Jan 31 2024, 12:28 PM
Unknown Object (File)
Jan 22 2024, 10:35 PM
Unknown Object (File)
Jan 2 2024, 2:09 AM
Unknown Object (File)
Dec 20 2023, 12:33 AM
Unknown Object (File)
Nov 15 2023, 9:06 AM
Unknown Object (File)
Nov 11 2023, 4:56 PM
Unknown Object (File)
Nov 9 2023, 9:43 PM
View All Files
Subscribers
None

Details

Reviewers
wblock
remko
bcr
Summary

I'm about to install FreeBSD for the first time, and started to read the lovely handbook.

I followed the link to send-pr(1) from:
https://www.freebsd.org/doc/handbook/history.html#development-committers

and was surprised to see:
https://www.freebsd.org/cgi/man.cgi?query=send-pr&sektion=1

Sorry, no data found for `send-pr(1)'. Please try a keyword search.

After some digging, I landed on:
https://www.freebsd.org/releases/10.1R/relnotes.html#userland

which explains it:

The FreeBSD Project has migrated from the GNATS bug tracking
system to Bugzilla. The send-pr(1) utility used for submitting
problem reports has been replaced with a stub shell script that
instructs to use the Bugzilla web interface. [r267734]

So this is a little tricky -- the latest FreeBSD doesn't use send-pr(1), but older versions do. Should the handbook still refer to send-pr(1)? If so, should the man links somehow reference the last version that supported it?

Thanks!

Test Plan

I am still validating if the 'commiters' mailing list still exists, but wanted to get this in for content review.

Diff Detail

Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

jgh updated this revision to Diff 2561.Nov 26 2014, 11:48 PM
jgh retitled this revision from to address bug 195432.
jgh updated this object.
jgh edited the test plan for this revision. (Show Details)
jgh added reviewers: bcr, remko, wblock.
jgh set the repository for this revision to rD FreeBSD doc repository - subversion.
jgh added a comment.Nov 26 2014, 11:50 PM

I snuck a spelling fix in here, but I can do that on another commit, if that is more appropriate.
-jgh

wblock added inline comments.Nov 27 2014, 3:00 PM
en_US.ISO8859-1/books/handbook/introduction/chapter.xml
422

...release cycle, and permissive license have led to..

424

s/including those from/including many from/

425

s/many of//

1146

There is no context shown, but this paragraph appears to be very old. The premise of bugs or changes being submitted to a single committers list is no longer accurate, at least.

1147

s/making submissions/submitting bugs or changes/

1148

s/the committers list/committers/

Really, this needs further rework. "Best" is subjective and send-pr is not available in some cases. How about just stating the objective and mentioning the possible methods? For that matter, do we need to mention send-pr at all?

Bug reports and changes can be submitted at <bugzilla link>.

1150

Avoid "you" and "your": "...With &os;&nbsp;10.0 and higher, please submit issues with the <link ..."

1153

Link text should not have whitespace before it:

<link xlink:href="https://bugs.freebsd.org/submit/">problem report form.</link>

1154

"jammed in the system" is... well, weak. And a committer mailing list is not the place to send bug followups any more.

"If a problem report has not received any attention, please contact the associated <link to handbook#eresources-summary> mailing list."

remko edited edge metadata.Nov 27 2014, 4:06 PM

We need to mention it because it is still supported on multiple releases. We can mention however that send-pr is supported for releases of FreeBSD =< 10.1. We did that in the past as well. People still read that if they need it.

For FreeBSD releases prior to 10.1 the send-pr utility can be used to submit bug reports. For releases starting at 10.1 the utility is no longer supported. The alternative is... yadayada

jgh updated this revision to Diff 2590.Dec 1 2014, 7:47 PM
jgh updated this object.
jgh edited edge metadata.
jgh added a comment.Dec 1 2014, 7:52 PM

Committers list is gone. I will be submitting a separate diff to drop it. I felt the best thing to do was point people to the community mailing list page, as it is difficult to point people to one particular list, as their bug could fall into many different categories with a potentially different list.

-jgh

wblock edited edge metadata.Dec 1 2014, 8:20 PM

Phabricator still shows two different diffs for this at the same time, both in the web form and even in the raw diff. I think I commented on the correct one.

I do not see a reason to separate out the removal of the committer's list into another commit.

introduction/chapter.xml
1150 ↗(On Diff #2590)

A space is missing after "our", but it seems informal anyway, so
s/our/the /

1151 ↗(On Diff #2590)

No whitespace between the opening tag and the content:

xlink:href="https://bugs.FreeBSD.org/submit/">problem

jgh updated this revision to Diff 2591.Dec 1 2014, 9:54 PM
jgh updated this object.
jgh edited edge metadata.
wblock added a comment.Dec 2 2014, 5:08 AM

I have no idea which of these two diffs is the real one. If it is the first, there are grammatical errors in the first sentence.

If we can't get this dual-diff problem fixed in Phabricator, I would prefer to go back to sending diffs by email. It takes longer, but at least there are not two alternate versions of the same thing.

jgh added a comment.Dec 2 2014, 5:24 AM

I'm not sure what you mean by multiple diffs. Left is original, and right is my change. Sending diff via mail.

wblock added a comment.Dec 2 2014, 3:02 PM

Yesterday, this link showed two separate diffs. One had the full path to the file, and the second, shown immediately afterwards, just showed the basename. They had different contents.

Today, I see only one diff.

wblock added inline comments.Dec 2 2014, 3:12 PM
chapter.xml
421 ↗(On Diff #2591)

s/and //

424 ↗(On Diff #2591)

This sentence is still way too long, and "those from" has been dropped, making it even more unclear. Please split the sentence after "products".

1152 ↗(On Diff #2591)

As previously commented, please remove the whitespace between the opening link tag and the link description. The link description should not include the period, either.

1155 ↗(On Diff #2591)

This link has the same problem. It should be (disregarding line wrap):

<link xlink:href="&url.base;community/mailinglists.html">community mailing lists</link>.</para>

jgh updated this revision to Diff 2610.Dec 3 2014, 12:20 AM

another stab at it.... i understood what you meant by removing whitespace before, however with formatting, I believe I may be more clear what this means now when going to another line.

jgh updated this revision to Diff 2622.Dec 3 2014, 6:31 PM
wblock added inline comments.Dec 3 2014, 6:47 PM
chapter.xml
1151 ↗(On Diff #2622)

There should be no added whitespace (spaces, tabs, or line breaks) between an opening tag and the contents, or the contents and the ending tag. For links, this is particularly important because the whitespace will be shown in the link:

<link ...>
a link
</link>

will render in HTML as _a link _, that is, with extra underlined whitespace. Instead, write the link like with the text up against the tags:
<link ...>a link</link>

(Note: if the whitespace is actually part of the contents, like a leading tab or space indent in a programlisting, that is fine. It is really meant to be there. But we do not add them to improve line wrapping.)

jgh updated this revision to Diff 2627.Dec 3 2014, 7:53 PM
wblock added a comment.Dec 3 2014, 8:57 PM

I have long ago lost track of the original and whether there are only whitespace changes to any line. I don't think so.

chapter.xml
17 ↗(On Diff #2627)

This line was okay before. This is the tag:
<link xlink:href="https://bugs.FreeBSD.org/submit/">

This is the contents of the tag:
problem report form

This is the closing tag:
</link>

It is the whitespace between the tags and the contents that is wrong:
<link xlink:href="https://bugs.FreeBSD.org/submit/">NOSPACESHEREproblem report formNOSPACESHERE</link>

In context, the way the original lines make it work out (indentation and wrapping is approximate):

issues using the <link
  xlink:href="https://bugs.FreeBSD.org/submit/">problem report
  form</link>.  If a problem report
has not received any attention, please engage the <link
  xlink:href="&url.base;community/mailinglists.html">community
  mailing lists</link>.</para>
jgh updated this revision to Diff 2630.Dec 3 2014, 10:46 PM
wblock accepted this revision.Dec 3 2014, 11:10 PM
wblock edited edge metadata.

Looks good. Please check with igor, build-test, and commit. Thanks!

This revision is now accepted and ready to land.Dec 3 2014, 11:10 PM
jgh closed this revision.Dec 3 2014, 11:22 PM

Revision Contents
Changeset List

PathSize
en_US.ISO8859-1/
books/
handbook/
introduction/
12 lines

Diff 2561

View Options

en_US.ISO8859-1/books/handbook/introduction/chapter.xml

Loading...