Document how individual programs shall be programmed

[arthurbacci]

Document:

• How programs shall err
• How usage messages shall be formated (alongside how the arguments shall be parsed)
• If and (if yes) how logging shall be done
• The handling of compilation flags for functionality
• If curses.h should be used directly or if libcommon.h will implement its own wrapper functions (either of curses.h or direct escape codes, since most programs don't need 90% of curses)

[arthurbacci]

Suggestion: implement logging (HEIRLOOM_NG_NO_LOGGING => no logging, functions do nothing; HEIRLOOM_NG_STDERR => print everything to stderr, HEIRLOOM_NG_USE_SYSTEM_LOG => try to work with journald or something, HEIRLOOM_NG_LOG_TO_TMP => create a tmp file called heirloom_logs.txt or something else and write/append to it) in libcommon.h or another shared library

[arthurbacci]

Other suggestion: implement command-line options parsing there too

[arthurbacci]

For now, trying to note how most of the programs do each one of those things may help decide how it will be implement

[arthurbacci]

libcommon alternatives for common stuff like atoi (but with error handling)

[takusuman]

Document:

• How programs shall err
• How usage messages shall be formated (alongside how the arguments shall be parsed)
• If and (if yes) how logging shall be done
• The handling of compilation flags for functionality
• If curses.h should be used directly or if libcommon.h will implement its own wrapper functions (either of curses.h or direct escape codes, since most programs don't need 90% of curses)

Well, about libcommon, it will not implement wrappers for curses since it can become a curse in the future, let's just call from curses.h and keep it portable. About how usage messages shall be formatted, it shall look like the UNIX "bread-and-butter". Logging wasn't really thought about, but I think most programs doesn't do this. About errors, I'm not sure yet. Anyway, with exception of the libcommon note, all these topics are interesting.

[takusuman]

Other suggestion: implement command-line options parsing there too

I think it already does, it has a implementation of getopts(), which is fairly enough for what this provides. We could try to implement a clone of Plan 9's ARGF, but I think it would end up in a mess because of different syntaxes with no apparent reason for mostly the same task.

[arthurbacci]

getopts() wasn't being used in your impl. of watch(1). If it's already implemented, it's better to have documentation about its usage somewhere.

[takusuman]

getopts() wasn't being used in your impl. of watch(1).

It is --- actually it's just getopt(). Check line 63.

If it's already implemented, it's better to have documentation about its usage somewhere.

It's on this file: https://github.com/Projeto-Pindorama/heirloom-ng/blob/master/libcommon/getopt.c

Apparently, according to the "Hacking the Heirloom Toolchest", it's a conservative implementation of getopt() aiming to attain the standard necessities of it, but I agree with the point that it necessitates more documentation. I was also thinking about mapping the code with something like doxygen, so it would be easier to other contributors and hackers on this project to see where the functions are defined on libcommon, libuxre etc.

[takusuman]

For now, trying to note how most of the programs do each one of those things may help decide how it will be implement

Usually, this was done by implementing what was written in the manual pages, but that sure created troubles regarding to different interpretations of the same text and/or ambiguity --- by way of illustration, we can see this with procps-ng's watch(1) manual page.

Nowadays, with most of (former) commercial UNIX code being open, we can take a look at what code actually was meant to do, functions etc.

When implementing a new program, we can add it to a to-do list and, from there, start to list what the said program will do and what needs to be implemented. GitHub Projects may be a good way to achieve this.

[takusuman]

Maybe #33 could be a good start --- although this would demand creating an entry on the mk.config to enable {Libre,Open}SSL and would, consequentially, add one more dependency on the project. Well, since we add an option to do not compile the aforesaid utility in specific, I don't see a problem.

[arthurbacci]

Why not having a big manual file for libcommon? Btw., if I were to create it what number (.X) should it use?

[takusuman]

Why not having a big manual file for libcommon? Btw., if I were to create it what number (.X) should it use?

Well, first of all, the libcommon is something internal of Heirloom. Unless we make it portable, it won't be outside of this project. It also implements functions found in many UNIX-compatible systems, so one manual page wouldn't be enough. It's more simple to write documentation in Markdown and/or plain-text citing which functions/wrappers are currently implemented and how it works --- it can be in something such as libcommon/DOCUMENTATION.

[takusuman]

Wrote an article in Portuguese on Heirloom's build system: https://takusuman.github.io/blog/2024/04/22/tentando-entender-a-montagem-do-heirloom.html

Hope this is useful for #49