Hi,
Harald Dunkel wrote on Wed, Sep 24, 2014 at 07:14:21AM +0200:
> This is something that could be added to /etc/examples.
> See the attachment suggesting a first version.
I hate that. Examples should not duplicate manual pages.
That merely causes double maintenance effort for developers.
Let's not make documentation maintenance harder on ourselves.
It also doesn't make things easier for users, quite to the contrary.
Chances are both copies of the documentation will eventually get
out of sync, and then it's overtly confusing. And even if we manage
to prevent explicit contradictions from creeping in, there will be
some stuff documented only in one of the places, some stuff only
in the other place. So now users have to look at *two* places where
formerly it was sufficient to look only at one. They now have to
read the double amount of text for almost the same information -
and they have to stay very attententive because either copy might
contain the bit of information they are searching for, buried among
boring duplication.
Even if we manage to keep the two completely in sync, such that
both contain exactly the same information, it still improves nothing.
Then we merely train users to not read the documentation, which we
certainly don't want to do: It would hurt them, because in almost
all other places, not reading the documentation usually leads to
screwing up.
In general, i think we should handle examples roughly as follows:
1. When something is completely trivial (like "fullwidth=yes")
and there is no way to not understand it from the text of the
manual itself, there shouldn't be any example, neither in the
manual nor in an example file. It would just make the
documentation longer for no gain.
2. Examples make sense when something has a minimum level
of complexity such that looking at the examples make understanding
easier. Examples should focus on the parts hard to understand
and never try to be exhaustive. If the total amount of examples
required comfortably fits into the EXAMPLES section of the
manual, that's where they should go, and there should be no
separate examples file.
3. Only when something is so difficult that it requires
a large amount of examples that would seem excessive in
the manual, I would deem a separate example file appropriate.
Don't take these as hard rules, each individual case requires
good judgement how it's easiest for the average user.
Note that some of the files in /etc/examples could use cleanup. It
was the right thing to just move them and *not* mix moving and
cleanup, but now it's time for cleanup. For example, from a *very*
superficial scan, exports, ftpchroot, hosts.lpd, mixerctl.conf,
rc.local, rc.securelevel, and rc.shutdown could be deleted outright,
and ntpd.conf, printcap, rbootd.conf, sasyncd.conf, sensorsd.conf
look suspicious. But that's a separate matter.
Anyway, i oppose the addition of the file /etc/examples/pkg.conf,
no matter what the content. I consider pkg.conf(1) a textbook
example of a file format so trivial that any examples would be
superfluous and distracting verbiage.
Yours,
Ingo
> # Set to yes if you really want to use the full width of the
> # terminal for the progressmeter.
> # fullwidth = yes
>
> # pkg_add(1) and pkg_delete(1) will syslog(3) installations,
> # updates and deletions by default. Set to 0 to avoid logging
> # entirely. Levels higher than 1 may log more information in
> # the future.
> # loglevel = 0
>
> # URL to package repository updated during installation. Used
> # for accessing packages if the environment variable PKG_PATH
> # is not defined and no further options are defined.
> # installpath =
>
> # Set to yes to waive checksums during package deletions.
> # nochecksum = yes
>
> # Set to yes to display (done/total) number of package
> # messages.
> # ntogo = yes
