Documentation improvement

sidetone

sidetone

As for documentation, the way it is, is inefficient. Different people are responsible for different pages of it, so when you suggest an improvement, they, understandably, aren't there for periods of time. The Handbook becomes stagnant, in this state.

There is a stigma about wikis, because many believe they can't have official releases, but there can be official or audited fixed versions of it. A benefit of wikis, is that it appears those who wrote in the Handbook want to be attributed, thus a wiki allows flexibility of many editors, and them being attributed.

The FreeBSD Handbook should do away with sections of Gnome, KDE, XFCE and their components GDM and KDM for the Desktop. JWM, i3, XDM and others should be focused on instead.


I'd like to see the Porter's Handbook improved. For instance don't have two repeated sections for porting, one of quick porting and one of slow porting. If there will be a quick porting section, condense it further and move it to an appendix. Encourage use of LLVM or PCC over GCC from the Porter's Handbook when possible.

It is problematic where it suggests, if a cluster of libraries is needed, to generally not package libraries together as a metaport, but to pull in another non-library dependency instead, which pulls in other non-library dependencies. The reasoning given was, if a port breaks, it's more difficult to rely on that library. There can be few exceptions of meta-port libraries that are kept in good condition, which many ports already rely on that cluster for use.

It should offer suggestions, like for heavily dependent ports, to keep separations of audio port dependencies from graphical port dependencies, when possible. There doesn't need to be upstream interference to do this; several ports can be built from one program's sourcecode, each with different defaults of builds and dependencies. Two different port build dependencies of one piece of sourcecode can coexist.

Oko said:
  • Improve man pages. For starter move to mdoc format. Adopt the policy that lack of man pages is a bug. No code should be enabled in the generic installation without god mdoc man pages.
  • Improve the quality of the Handbook. Focus on fewer important topics but make sure that things are updated for the releases.
...
  • Support only the last two releases and update Handbook accordingly.
Click to expand...

Mdoc uses XML, which can offer improvements for documentation.

Related: Thread FreeBSD Handbook Online Documentation Editor.57738
 
sidetone said:
The FreeBSD Handbook should do away with sections of Gnome, KDE, XFCE and their components GDM and KDM for the Desktop. JWM, i3, XDM and others should be focused on instead.
Click to expand...

It's only a few lines, so don't see the point in removing them, but adding the others is a good idea.
 
I'd like to separate the section about Gnome, KDE and XFCE off, into its own document, then add about XDM, .xsession and .xinit. The markup, is not an issue for me. If only I knew, I can do it without, it being offered, then sitting stagnant.

On the Handbook, if the person that maintains a section is not there, suggestions don't go anywhere, then it gets discouraging to do anything, that just sits there.
 
I think that the documentation is very good, including the porters handbook and everything. It is almost perfect if not even more.
 
The use of the shell case, esac statements can be suggested in place of many extensive elseif elif's in if, else statements in Makefile's.

Code: 
AUDIO=sndio
case “$AUDIO” in
sndio) echo "sndio” ;;
pulseaudio) echo “pulseaudio” ;;
alsa) echo “alsa.” ;;
esac
 
Last edited by a moderator:
That makes sense to me for shell scripts, but not for Makefiles. Can you maybe show an example Makefile before and after switching to case statements?

In ports there are options helpers which can replace a lot of the .if, .elif, .else mazes.
 
Here's an example:

from Makefile of audio/xmms2
Code: 
.if defined(XMMS2_SLAVE)
CONFIGURE_ARGS+=   --without-xmms2d

.if   ${XMMS2_SLAVE} == "python"
CONFIGURE_ARGS+=   --with-optionals="python"
.elif ${XMMS2_SLAVE} == "ruby"
CONFIGURE_ARGS+=   --with-optionals="ruby"
.elif ${XMMS2_SLAVE} == "perl"
CONFIGURE_ARGS+=   --with-optionals="perl"
.elif ${XMMS2_SLAVE} == "ruby-ecore"
CONFIGURE_ARGS+=   --with-optionals="ruby" --with-optionals="xmmsclient-ecore"
.elif ${XMMS2_SLAVE} == "cpp"
CONFIGURE_ARGS+=   --with-optionals="xmmsclient++" \
       --with-optionals="xmmsclient++-glib"
.endif

.else # XMMS2_SLAVE
CONFIGURE_ARGS+=   --without-optionals="python" \
       --without-optionals="ruby" \
       --without-optionals="xmmsclient-ecore" \
       --without-optionals="xmmsclient++" \
       --without-optionals="xmmsclient++-glib" \
       --without-optionals="perl"
.endif # XMMS2_SLAVE

.if !defined(XMMS2_SLAVE)

# xmms2-ripper
.if ${PORT_OPTIONS:MVISUAL} && ${PORT_OPTIONS:MVORBIS}
LIB_DEPENDS+=   libvorbisenc.so:audio/libvorbis
.else
EXTRA_PATCHES+=   ${FILESDIR}/extra-patch-src-clients-vistest-wscript
.endif

.endif # !XMMS2_SLAVE
...
.else # XMMS2_SLAVE
CONFIGURE_ARGS+=   --without-optionals="python" \
       --without-optionals="ruby" \
       --without-optionals="xmmsclient-ecore" \
       --without-optionals="xmmsclient++" \
       --without-optionals="xmmsclient++-glib" \
       --without-optionals="perl"
.endif # XMMS2_SLAVE
Wouldn't part of it be something like:
Code: 
case ${XMMS2_SLAVE} in
python) CONFIGURE_ARGS+=   --with-optionals="python" ;;
ruby) CONFIGURE_ARGS+=   --with-optionals="ruby" ;;
perl) CONFIGURE_ARGS+=   --with-optionals="perl" ;;
!defined(XMMS2_SLAVE)  ) = ... ;;
...
esac
Pardon me, if the case/esac example is far from perfect.

There aren't as many port Makefile's as I thought with more than 3 or more elif statements for the same variable. audio/mpg123, and cad/astk-serveur have other examples. From /usr/ports/, grep elif [a-c]*/*/Makefile can find a few of them.
 
God yes.

The Handbook goes from Installation to Basics to starting X: it NEVER mentions loading modules, how to load modules, or how to use /boot/loader.conf or /etc/rc.conf. Many people may try to start X/firefox before getting networking running (ouch). And when they try to start X are invariably scrambling for what to do about lack of lacking multi-media/AV support (modules that need to be loaded, and x11-drivers that need to be installed separate from xorg, let alone using Drive and Option so they get used - which is briefly mentioned in handbook though).

I only knew to keep looking for a way to do modules, then mostly unsucessfully googling which modules are for what (what's intelspi? not for me), because i'm a longtime linux user.

I could be wrong: perhaps freeBSD 11's kernel has multimedia for X built-in for "most modern machines" and i'm an exception. but i kinda doubt it. anyway these days most people start using a 'nix with an older box rather than their newest one - so loading modules is then again a likelyhood

And I'm sure I might have missed something because I'm new.

References in Appendix are needed. URL's that are kept up to date of where to find more info about getting X+firefox+sound running "well enough". (URLs are hard though because of lack of control of keeping them relevant and 404 syndrom). i see references are under Documentation on main site - perhaps that's good enough. a few important references should be in handbook though.

MOSTLY: kernel modules. never mentioned. difficult to google.

---------------------------

other than MODULES i find the Handbook very wise on what it says and doesn't say. too much clutter is bad for beginners. it's well written.
 
debguy said:
God yes.
The Handbook goes from Installation to Basics to starting X: it NEVER mentions loading modules, how to load modules, or how to use /boot/loader.conf or /etc/rc.conf. .
MOSTLY: kernel modules. never mentioned. difficult to google.
Click to expand...
Very good man pages are ready to use for that:
- rc.conf()
- loader.conf()

If you look at the bottom of both, amidst the 'Files' section, it tells you where to find samples for both configuration files, containing all modules/options briefly (but clearly) explained:
- /boot/defaults/loader.conf
- /etc/defaults/rc.conf
These two proved very useful to me

Also see sysctl.conf()

Regarding xorg.conf, its configuration is pretty much the same in any Unix-like system.

In FreeBSD, touching and editing an xorg.conf is discouraged, as system should take care of most of things, and all additional configuration is done through custom .conf files placed in xorg.conf.d folder.

From my personal perspective 5.4. Xorg Configuration explains that well enough, as contains all the basic configuration options which most new users should be satisfied with, however I agree with you when I say it may be improved.

Anyway, all .conf files you create still have to follow the 'standard xorg.conf syntax'. You can search the web for how to correctly set up your drivers/options, but I find OpenBSD's xorg.conf reference illuminating. Still apart from graphic cards, touchpad and keyboard layout, usually there's hardly anything left to configure manually ;)
 
As Sensucht94 said almost every configuration file on FreeBSD already has its own manualpage, so that's really not something for the handbook to cover in my opinion.

As to kernel modules: usually there's no need for this because modules tend to get loaded automatically the very moment you try to use a certain option. For example: if you start with a live cd and then issue # zpool import then the required modules (zfs.ko and opensolaris.ko) will get immediately loaded.

However, this aspect is covered in the handbook though very briefly; chapter 8.2 covers custom kernels, and also mentions kldload(8).

No pun intended here, but a very good command to start with is man man. Unlike with Linux the manpages on FreeBSD actually mean something; they're real manual pages. As such man -k <topic> (easier is using apropos(1)) can be quite useful to search for information. Loading stuff into the kernel? apropos load kernel and you'll come across kldload in no time, and a lot more.
 
ShelLuser said:
As Sensucht94 said almost every configuration file on FreeBSD already has its own manualpage, so that's really not something for the handbook to cover in my opinion.
Click to expand...
+1!

FreeBSD is following the UNIX tradition of providing very good, thorough, current and correct manual pages (most even with good example sections!) - something that is annoyingly uncommon on Linux nowadays, where a lot of packages have outdated, incomplete or even no manual pages at all. Therefore Linux-users tend to google for all their problems instead of just reading the man pages. The worst thing that could happen, is adapting to this behavior and bloating the Handbook to a massive dump of manual page content.

The Handbook is very good in that it gives a quick overview over a lot of topics to get started - everything beyond this is covered by the manual pages for the tools/programs/configfiles in question.
E.g. if you want to set up iSCSI on FreeBSD, this is IMHO covered perfectly condensed in the Handbook [1] so you can quickly and easily get started and know what services and config files are involved. For all the gory details and advanced options, just look up the manual pages. Adding all the trivia and edge-cases to the Handbook would completely destroy its character of a "one-stop quick introduction/refresher".

What would be more beneficial on the Handbook I think, would be referring/pointing to the manpages more often. Maybe even adding a footnote on each page, with a listing of all relevant manual pages to the topic(s) discussed on that page. This way the Handbook could make the people coming from "manpage wastelands" like Linux aware of the good manual pages on BSD/UNIX systems.
After all, the online handbook isn't available when your system/service is down and everyone behind you is screaming, but the manpages are. So knowing they are and how to use them is IMHO more crucial than any additional or extended section in an online handbook.


[1] https://www.freebsd.org/doc/handbook/network-iscsi.html
 
You must log in or register to reply here.
Back
Top