About make ports and freebsd handbook.

Alain De Vos

Alain De Vos

Recently i learned for ports there exists,
make clean-depends
make config-recursive
make package-recursive

Nothing in the handbook.
Still basic and interesting. No poudriere needed.
 
tembun said:
By the way, one may easily submit a patch for changes like this and get it in the tree. For example, I recently documented check-old-libs targets for build(7): https://bugs.freebsd.org/bugzilla/show_bug.cgi?id=284546
Click to expand...
Maybe just many of volunteers are not familiar enough with markups used in manpage sources like me.

As far as I know, volunteers for documentations (including manpages) are historically much fewer than coders. Maybe worse in other projects.

I'm submitting patches / opening reviews for Makefiles, C codes but not manpages.
 
Alain De Vos said:
Everything is clearly explained in a man page. But a mortal like me can not read all man pages. Sometimes we need a guide. Like try to do this in this way.
Click to expand...
Unfortunately, not everything is documented (mostly just way behind) as I described in my previous post.
The delay would be:
comments in source codes << manpages <<<<< other documents like handbook.

Not mine, but an example of reviews for Handbook.
Recently ziaee@ is working hard to catch up with.

Even on source codes, tracking macros are nightmares.
Not all functions are documented, much fewer for macros.

Not on base, but one of my nightmares here in the folded part, comment at May 2, 2025. This case, possibly nvidia has documents internally, though. But I don't have priviledge to access nvidia internal documents.
 
Alain De Vos said:
Freebsd handbook, is nice. Better than any documentation on linux. But it lacks some basic stuff.
Click to expand...
I think it would be what ziaee@ is trying to catch up with recently.

And an unfortunate example would be PR 280431. Time is limited, and "should be as such" are not always trivial enough to do. And this would still not in scope of doc team.
 
Alain De Vos said:
Everything is clearly explained in a man page. But a mortal like me can not read all man pages.
Click to expand...
You don't necessarily have to read all man pages. You can search in a single man page for keywords and phrases (like in a internet web search), or in all system and port man pages simultaneously.

This can be done with the system source code and ports tree as well.

The best utility for searching all man pages I found is textproc/ugrep (supports -z, --decompress Search compressed files and archives.) . See ugrep(1) for used options in the example below.

Search all system and ports manual pages for specific patterns:
Code: 
% manpath
/usr/share/man:/usr/local/share/man:/usr/local/man:/usr/share/openssl/man:/usr/local/lib/perl5/site_perl/man:/usr/local/lib/perl5/5.40/perl/man

% ug  -rIz   clean-depends /usr/share/man  /usr/local/share/man  /usr/local/man

% ug -rIzw config-recursive /usr/share/man /usr/local/share/man  /usr/local/man
/usr/share/man/man7/ports.7.gz
   246: .It Cm config-recursive

% ug -rIzw package-recursive /usr/share/man /usr/local/share/man  /usr/local/man
/usr/share/man/man7/ports.7.gz
   314: .It Cm package-recursive

Search in the ports tree /usr/ports/Mk make files (*.mk) directory:
Rich (BB code): 
% ug -rI clean-depends /usr/ports/Mk
/usr/ports/Mk/bsd.port.mk
   609: # clean-depends - Do a "make clean" for all dependencies.
  3843: CLEAN_DEPENDENCIES+=    limited-clean-depends-noflavor
  3844: limited-clean-depends-noflavor:
  3845:         @cd ${.CURDIR} && ${MAKE} limited-clean-depends
  3872: CLEAN_DEPENDENCIES+=    limited-clean-depends-${_f}
  3873: limited-clean-depends-${_f}:
  3874:         @cd ${.CURDIR} && ${SETENV} FLAVOR=${_f} ${MAKE} limited-clean-depends
  4126: .    if !target(clean-depends)
  4127: clean-depends:
  4133: .    if !target(limited-clean-depends)
  4134: limited-clean-depends:

/usr/ports/Mk/Scripts/depends-list.sh
    27:                         # 'make clean-depends'.
 
Alain De Vos said:
Everything is clearly explained in a man page. But a mortal like me can not read all man pages. Sometimes we need a guide. Like try to do this in this way.
Click to expand...

Alain De Vos said:
Freebsd handbook, is nice. Better than any documentation on linux. But it lacks some basic stuff.
Click to expand...

I absolutely agree with you that FreeBSD has outstanding documentation and it rocks. But in my opinion, the core of this outstandingness is in manual pages.

Code: 
$ apropos . |wc -l
   10252

There's more that ten thousand man pages (in my system) - that's a lot. An average manual page is hundreds of lines. That's a lot of text. That's a lot of people's time and labour. Time and labour just to type this text. Don't you forget you also have to make it graspable and easy-to-read. And FreeBSD keeps up.

Now, in my opinion, Handbook is a different thing. Man pages go into technical details, Handbook, as I see it, focuses more on giving a good introduction to a particular topic so to prevent people (mostly, newcomers to this particular topic) for giving up because they can't get the technicals. But I want to make it clear: you have to be able to read and understand language of man pages (and I mean not mdoc(7), but language of technical details) if you want to work with your system.

Don't get me wrong: Handbook is not bad. It's wonderful, it did help _me_ a lot. But essentially, Handbook for most part duplicates information from manual pages. Yes, it makes it much more clear and simple, but still, all this information can be found in mans. And bearing in mind that there are thousands of man pages in the system, it's a really-really big work to rephrase even 1% of this man pages into simpler language, come up with good examples and get it into the Handbook. In practice, man pages themselves need improvements and updates, it would be hard to sync the Handbook with them.

For me, running FreeBSD is like riding a bicycle and Handbook is like people who help you to learn ride a bicycle: they teach you basic things, stay near and support you, help you if you did fall and hurt yourself. But they don't do this forever. Eventually you have to go and ride yourself - that's your bicycle. And when you got the basics, you can continue learning: how to ride hills, how to do tricks and so on... But it comes with practice only. I guess you wouldn't ask your parents why didn't they show you how to do 360 flip :)

And Handbook does its job - it helps you at start and it does give you a perfect reference for further learning - it always points you to man pages. Try to read them, try to understand them, try to _find_ them (seriously, it's a skill to find appropriate manual page!), I guarantee, you inevitably will become fine with them.

But, if you think that Handbook misses some essential thing that would be nice to have - it's FreeBSD - it means you can go ahead and submit a patch (or, if you are not sure how to make the change itself, submit a bug report and ask other people to make it).
 
You must log in or register to reply here.
Back
Top