Minimal skills

Polytropon freebsd at edvax.de
Thu Jun 4 05:41:40 UTC 2020


On Wed, 03 Jun 2020 21:52:37 -0600, Brandon Helsley wrote:
> You said there is different areas of documentation. Does this
> separation of areas just go by the handbook's sections?

Please check the links I provided. Primarily FreeBSD documentation
contains the handbook / FAQ / books / articles you also find on
the web page, and then there is the manpages that accompany the
OS install. Ports contain their own documentation, independent
from FreeBSD, and usually maintained by the port's upstream.



> Could this mailing list please elaborate on the subject of
> updating documentation? and what it takes to do this?

As I mentioned, one part of the _FreeBSD_ documentation is what
you find in the documentation port (freebsd-doc), and the other
part is in the OS (/usr/src).

For FreeBSD documentation:

To obtain a current ports tree, use the following commands
(typical example):

	# portsnap fetch extract
	# cd /usr/ports/misc/freebsd-doc-en
	# make
	# make install

You can then go ahead and work with the sources in the work
directory, and use tools like diff to create your patches to
submit.

The FreeBSD ports collection is explained here:

	https://www.freebsd.org/doc/handbook/ports-using.html

For manpages:

You usually use the freebsd-update tool to install and update
the "src" component (it should be the default already). But in
this specific case, using the most current version of the
sources probably is the better way, and this is done using the
Subversion tool. Get the latest sources. Then you'll find
manpages in /usr/src's subdirectories for all the components
and sections. Again, you can use diff to create patches.

The OS updating procedures are explained here:

	https://www.freebsd.org/doc/handbook/makeworld.html

Of course you don't need to install the kernel and the OS
userland - you just want the manpage source files. :-)

Sidenote: You can obtain the most current ports tree with
svn (Subversion) as well, but for a first impression, I'd
say the convenient binary methods are a good point to start.
However, in actual contribution, you'll always want the
latest (!) version available, and that is what svn delivers.



> For a specific area that I'm interested in, that would be the
> Network servers, firewall and advanced networking chapters,
> since this is what I want to learn. I'm assuming that's what
> you had meant about being interested in a particular area or
> documentation.

That is a broad topic. :-)

FreeBSD itself offers several aspects of networking servers,
firewalls, and of course the whole networking stacks and
drivers; and there are ports that contain stuff, first of
all things like web servers.



> Thank you for all the advice so far. Now I can get on track
> with the right direction for my education. I will make sure
> I learn a little programming, learn unix and study some kind
> of computer science that supports all the rest. And then of
> course continue to use FreeBSD with the updating handbook. 

If you don't mind, I'd suggest to dedicate a workstation PC
or a laptop for FreeBSD, while having a second computer (or
a smartphone) for web access (documtnation, mailing lists,
or web forums). Start by installing FreeBSD. Set up your
working environment. On the way of doing so, you will already
learn a lot. Then examine what you _can_ contribute, and
decide what you _want_ to contribute to. Depending on that
decision, the steps to take (as mentioned above) are a bit
different, still they share a certain skillset and tools.

It also helps if you read (or at least skim through) the
documentation that already exists, to get a feeling of what
you will be dealing with. As I said, the FreeBSD documentation
basically works with the port that turns input files into
a variety of output formats, while the manpages use their
own "language". You can easily check how those look like.
You can also get an impression of the writing style and
terminology used. Example manpage files can be found on
any FreeBSD install in /usr/share/examples/mdoc/ where
template files can be found.


-- 
Polytropon
Magdeburg, Germany
Happy FreeBSD user since 4.0
Andra moi ennepe, Mousa, ...


More information about the freebsd-questions mailing list