Handbook WG - Basics chapter and Ports chapter

[carlavilla]

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:

• https://www.carlavilla.es/freebsd/basics.html
• https://www.carlavilla.es/freebsd/ports.html

[arrowd]

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

445–450

What are these strange whitespaces?

[karels]

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

1058

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

1058

I see no subdirectories instantiated after install.

1118

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.

1126

See above about /var being memory-based.

1206

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.

[karels]

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

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

1198–1201

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.

1206

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

1366

This is UFS-specific. I propose this.

1771

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.

[karels]

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

1198–1201

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

[karels]

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

888–895

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

948–955

As above.

979–987

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

[carlavilla]

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

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

445–450

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

1206

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.

[arrowd]

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.

[jrm]

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

241–242

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

375

585

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

598

736

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.

822

[jrm]

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

736

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

[carlavilla]

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

585

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]

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