Page MenuHomeFreeBSD

Style revisions, accessibility enhancements, and ports statistics updates
ClosedPublic

Authored by pauamma_gundo.com on Apr 6 2020, 10:21 PM.

Details

Summary
  • Make pronouns truly gender-agnostic.
  • Correct typos and minor grammar errors.
  • Enhance screenreader friendliness of pictures.
  • Remove reference to deleted image.
  • Add link to FDP primer.
Test Plan

Tested with lynx, but should ideally be tested by someone using a screenreader.

Diff Detail

Repository
rD FreeBSD doc repository
Lint
Automatic diff as part of commit; lint not applicable.
Unit
Automatic diff as part of commit; unit tests not applicable.

Event Timeline

Ooops, forgot the Bugzilla PR #: 241814

Note 1: Images removed from the English version but still used by translations have been kept until the translations catch up. These images are: share/images/books/dev-model/hats-overview.png, share/images/books/dev-model/maintenance.png, share/images/books/dev-model/orghierarchy.png, share/images/books/dev-model/orghierarchy.sla, share/images/books/dev-model/orghierarchy2.png, and share/images/books/dev-model/proc-releng.png.

Note 2: I think it's OK to include a local copy of https://web.archive.org/web/20121223081637if_/http://www.freebsd.org/ports/growth/status.png in the document, since that image came from the FreeBSD website originally. But IANAL, so take that opinion with appropriate amounts of salt.

debdrup added a subscriber: debdrup.Apr 7 2020, 2:58 PM

For the entire document, please do s/screenreader-friendly/screen-reader friendly/g so that it uses the same verbiage.

en_US.ISO8859-1/books/dev-model/book.xml
737–738 ↗(On Diff #70280)

Would it be better to use <note>Refer to the table below for a screen-reader friendly version.</note>?

1468–1470 ↗(On Diff #70280)

This would also be a good use of <note>Refer to paragraph below for a screen-reader friendly version.</note>.

1643–1644 ↗(On Diff #70280)

Same as above with regard to use of <note></note>.

2409–2410 ↗(On Diff #70280)

Yet another instance where <note></note> is useful.

bcr added a comment.Apr 8 2020, 9:11 AM

Overall, this is a great addition and update. Thank you.
There are other things that need to be fixed, but that should come in a separate follow-up commit to not blow up this review with more changes.

en_US.ISO8859-1/books/dev-model/book.xml
2663 ↗(On Diff #70280)

For this overlong link, you can break it like this:
<link<ENTER
<TAB>xlink...>a<ENTER>
<TAB>primer</link>.

Refer to section 9.8.3. in the primer https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-links.html for details and examples.

Address changes requested by debdrup and bcr.

For debdrup's changes, I didn't use a note, but the textobject-in-mediaobject
method described in section 9.7.3 in
https://www.freebsd.org/doc/en_US.ISO8859-1/books/fdp-primer/docbook-markup-images.html
so as to have that text wind up in the alt= img attribute. (I also didn't
put in ASCII art because 1- my skill for it is minimal, 2- I hear it confuses
screen reader users, and 3- there wasn't any before anyway.)

Looks good to me now.

allanjude added inline comments.
en_US.ISO8859-1/books/dev-model/book.xml
339 ↗(On Diff #70413)

are there ~5500 or only ~3000?

en_US.ISO8859-1/books/dev-model/book.xml
339 ↗(On Diff #70413)

As far as I can see from the SVN log, the text has always said 5500, and the image (introduced with r24914 in 2005) 3000. I have no idea which figure is correct. That said, there's a comment a few lines below that says "Lost the script, TODO: recompute the estimate", so perhaps I should do that (with someone else's help) and this time add the script to the repo or as a comment here depending on how long it is. Or maybe that should be a separate commit. What does everyone think?

bcr accepted this revision as: bcr.Apr 30 2020, 11:03 AM

Looks good to me.

en_US.ISO8859-1/books/dev-model/book.xml
339 ↗(On Diff #70413)

I'd say if we don't have the script anymore, we can create a new one in a separate commit and commit this change with the original number. We can then update it with the more accurate number coming from the new script.

This revision is now accepted and ready to land.Apr 30 2020, 11:03 AM

Can a committer take care of it? I'm not one. (Also, reminder: the PR# is 241814 - I forgot it in the initial summary.)

This revision was automatically updated to reflect the committed changes.