Page MenuHomeFreeBSD

Handbook WG - Basics chapter and Ports chapter
ClosedPublic

Authored by carlavilla on Dec 18 2022, 12:10 PM.
Tags
None
Referenced Files
Unknown Object (File)
Jan 29 2024, 8:23 AM
Unknown Object (File)
Dec 30 2023, 11:57 AM
Unknown Object (File)
Dec 28 2023, 11:16 PM
Unknown Object (File)
Dec 5 2023, 2:52 AM
Unknown Object (File)
Dec 1 2023, 5:21 AM
Unknown Object (File)
Nov 12 2023, 6:32 PM
Unknown Object (File)
Nov 8 2023, 6:52 AM
Unknown Object (File)
Oct 14 2023, 1:29 AM
Subscribers
None

Details

Summary

Changes in basics chapter:

  • Improve the rendering of the tables
  • Improve titles, show text instead of showing a command
  • Upgrade information about the "removing user procedure"
  • Upgrade "Directory Structure" based on hier.5
  • Run all the commands and check that the correct output is displayed

Changes in ports chapter:

  • Simplify the way you search for packages
  • Some minor changes in software packages examples, use Nginx instead of Apache, for example.
  • Improve the pkg bootstrap and show the current way. Remove references of FreeBSD 9 and 10.
  • Add information about how to configure pkg
  • Update information on how to handle packages: search, install, update, remove, etc.
  • Put the information on how to handle packets in order
  • Add information on how to block and unblock packages

Global:

  • Add alt text to all of the images
  • Improve the AsciiDoc text

Rendered:

Diff Detail

Repository
R9 FreeBSD doc repository
Lint
Lint Skipped
Unit
Tests Skipped

Event Timeline

carlavilla created this revision.
documentation/content/en/books/handbook/basics/_index.adoc
447–452

What are these strange whitespaces?

I got behind on these chapters; I'm part-way through. I'll send what I have now, and hopefully will finish later today.

documentation/content/en/books/handbook/basics/_index.adoc
1055

These are not libraries in the traditional sense; "Critical system files"?

1058

I see no subdirectories instantiated after install.

1115

Using a memory-based system for /var seems like a really bad idea; logs and accounting files should be preserved after a reboot. /var/run and maybe /var/tmp might be OK, although the latter would make vi file recovery impossible after a reboot. I think we should just delete the memory-based file system info. Oh, /var/mail is another example.

1123

See above about /var being memory-based.

1203

This naming is only true of bsdlabel-based partitions, which are used less and less (not with gpt). I'm not sure how to fix this without adding confusion, but maybe we need to mention MBR and GPT conventions.

I think I am finished with my pass on these two chapters.

documentation/content/en/books/handbook/basics/_index.adoc
1195–1198

I would add: A file system can only be expanded into free space in the partition in which it resides. If there is space after the partition, the partition can be expanded with man:gpart[8]. If the partition is the last one on a virtual disk, and the disk is expanded, the partition then be expanded.

1203

Followup: I propose doing some work on this in a separate review.

1363

This is UFS-specific. I propose this.

1768

Should be "is", not "are".

documentation/content/en/books/handbook/ports/_index.adoc
227–228

There is some strange spacing in this section.

232

s/do/done/

887–888

Looks like the period here should still be a comma.

968–969

Should this part be retained? 9.x is quite old now.

documentation/content/en/books/handbook/basics/_index.adoc
1195–1198

The last clause is missing a word; "can then be expanded".

I missed one area on my list of comments; I think we should document the use of the symbolic flags for set[ug]id and sticky, and do so before the octal method. It may be worth doing both for background information, although I could easily be convinced that we should document only the symbolic methods.

documentation/content/en/books/handbook/basics/_index.adoc
885–892

I think we should document the symbolic way to set this first, then include the octal.

945–952

As above.

976–984

Similar to set[ug]id, I think we should document the symbolic method first.

I'm gonna make the commit. Thanks for the review!

documentation/content/en/books/handbook/basics/_index.adoc
447–452

A mistake, hehe.
Fixed on commit.

1058

In my laptop:

ls /media
Generic_Flash_Disk_04D18A60 Generic_Flash_Disk_9F316B8F_s2
Generic_Flash_Disk_9F316B8F Generic_Flash_Disk_9F316B8F_s2_s2a
Generic_Flash_Disk_9F316B8F_s1

1203

Yes, I'm gonna commit this review and we can work on this in a separate review.

documentation/content/en/books/handbook/ports/_index.adoc
227–228

I'll fix this on commit. Some problem with copy&paste in Visual Studio Code.

968–969

Also removed the reference to FreeBSD 10.

carlavilla marked 3 inline comments as done.
documentation/content/en/books/handbook/basics/_index.adoc
1058

ls /media
Generic_Flash_Disk_04D18A60 Generic_Flash_Disk_9F316B8F_s2

These are leftovers from sysutils/bsdisks. Which I should fix and make it remove empty directories.

Here are a few minor comments. I've only partially made it through the chapter, but I'll submit now since I've run out of time for today

documentation/content/en/books/handbook/basics/_index.adoc
92
242–245

Is this the ideal location for the warning? It struck me as strange that we are warning about a group before groups have been introduced

377
587

Should we add something similar here about bsdconfig(8) for users who want to do this sort of thing with a curses interface?

600
733

Focusing on the line for myfile, the first character indicates whether this file is a regular file, a directory, a special character device, a socket, or any other special pseudo-file device.

819
documentation/content/en/books/handbook/basics/_index.adoc
733

I don't see how to edit my suggestion, but I meant to keep (leftmost) after first.

carlavilla added inline comments.
documentation/content/en/books/handbook/basics/_index.adoc
587

I'll add this in a separated review. Good idea to add this :)

1058

I got the text from https://www.freebsd.org/cgi/man.cgi?query=hier&sektion=7&format=html, if it's wrong, we need to upgrade the manual page too

carlavilla marked 2 inline comments as done.

I'm gonna close this review, @karels and @jrm we can work on the GPT and bsdconfig in another review

This revision is now accepted and ready to land.Jan 19 2023, 7:45 PM