Hi Michael,
On 2020-10-20 06:08, Michael Kerrisk (man-pages) wrote:
Hi Alex,
On Mon, 19 Oct 2020 at 17:29, Alejandro Colomar <colomar.6.4.3@xxxxxxxxx> wrote:
Hi Michael,
I'm working on moving and fixing code from queue.3 to different pages.
I'd like to send you patches against a separate branch,
if you would create one, to ask you some questions from time to time,
and maybe get suggestions.
Or maybe you could look at my branch on github
(https://github.com/alejandro-colomar/man-pages/commits/queue
(I may force push changes there sometimes))
I created a remote to remote to track your work. But you'll need to
ping me from time to tell me to take a look. Also, I think mail to
this list to discuss directions (as you are now doing) is great.
(BTW, if you have a look there,
you can see how I'm moving&fixing the code from queue.3
to the other pages and maybe suggest a different way).
This looks okay in principle.
Or maybe I can just show you small pieces of code (no patches),
like in this email.
Whatever works best for you.
Both ;-)
Fine :-)
But, I find the indentation confusing actually. When I see pieces such as
int LIST_EMPTY(LIST_HEAD *head);
LIST_ENTRY(TYPE);
It visually looks to me as though the LIST_ENTRY piece is some
extension of the LIST_EMPTY pest.
Agreed.
I think it's best not to do horizontal indentation, but instead just
use of vertical separation (.PP). We can perhaps revisit this later,
to see if we can come up with something better.
Okay, I changed it to use vertical separation (as the original one did).
Now the output is the following (I think the SYNOPSIS already looks
good, and I'll move to the DESCRIPTION):
[[
LIST(3) Linux Programmer's Manual
LIST(3)
NAME
LIST_EMPTY, LIST_ENTRY, LIST_FIRST, LIST_FOREACH,
LIST_HEAD,
LIST_HEAD_INITIALIZER, LIST_INIT, LIST_INSERT_AFTER,
LIST_INSERT_BE-
FORE, LIST_INSERT_HEAD, LIST_NEXT, LIST_PREV, LIST_REMOVE -
implementa-
tion of a doubly-linked list
SYNOPSIS
#include <sys/queue.h>
int LIST_EMPTY(LIST_HEAD *head);
LIST_ENTRY(TYPE);
LIST_ENTRY *LIST_FIRST(LIST_HEAD *head);
LIST_FOREACH(TYPE *var, LIST_HEAD *head, LIST_ENTRY NAME);
LIST_HEAD(HEADNAME, TYPE);
LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD head);
void LIST_INIT(LIST_HEAD *head);
void LIST_INSERT_AFTER(TYPE *listelm, TYPE *elm, LIST_ENTRY NAME);
void LIST_INSERT_BEFORE(TYPE *listelm, TYPE *elm, LIST_ENTRY NAME);
void LIST_INSERT_HEAD(LIST_HEAD *head, TYPE *elm, LIST_ENTRY NAME);
LIST_ENTRY *LIST_NEXT(TYPE *elm, LIST_ENTRY NAME);
void LIST_REMOVE(TYPE *elm, LIST_ENTRY NAME);
]]
The code for NAME and SYNOPSIS,
which are the sections that are ready in list.3,
is the following:
[[
.TH LIST 3 2020-10-19 "GNU" "Linux Programmer's Manual"
.SH NAME
LIST_EMPTY,
LIST_ENTRY,
LIST_FIRST,
LIST_FOREACH,
.\"LIST_FOREACH_FROM,
.\"LIST_FOREACH_SAFE,
.\"LIST_FOREACH_FROM_SAFE,
LIST_HEAD,
LIST_HEAD_INITIALIZER,
LIST_INIT,
LIST_INSERT_AFTER,
LIST_INSERT_BEFORE,
LIST_INSERT_HEAD,
LIST_NEXT,
LIST_PREV,
LIST_REMOVE
.\"LIST_SWAP
\- implementation of a doubly-linked list
.SH SYNOPSIS
.nf
.B #include <sys/queue.h>
.PP
.BI "int LIST_EMPTY(LIST_HEAD *" head ");"
.PP
.B "LIST_ENTRY(TYPE);"
.PP
.BI "LIST_ENTRY *LIST_FIRST(LIST_HEAD *" head ");"
.PP
.BI "LIST_FOREACH(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY " NAME ");"
.\".PP
.\".BI "LIST_FOREACH_FROM(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY
" NAME ");"
.\".PP
.\".BI "LIST_FOREACH_SAFE(TYPE *" var ", LIST_HEAD *" head ", LIST_ENTRY
" NAME ", TYPE *" temp_var ");"
.\".PP
.\".BI "LIST_FOREACH_FROM_SAFE(TYPE *" var ", LIST_HEAD *" head ",
LIST_ENTRY " NAME ", TYPE *" temp_var ");"
.PP
.B "LIST_HEAD(HEADNAME, TYPE);"
.PP
.BI "LIST_HEAD LIST_HEAD_INITIALIZER(LIST_HEAD " head ");"
.PP
.BI "void LIST_INIT(LIST_HEAD *" head ");"
.PP
.BI "void LIST_INSERT_AFTER(TYPE *" listelm ", TYPE *" elm ", LIST_ENTRY
" NAME ");"
.PP
.BI "void LIST_INSERT_BEFORE(TYPE *" listelm ", TYPE *" elm ",
LIST_ENTRY " NAME ");"
.PP
.BI "void LIST_INSERT_HEAD(LIST_HEAD *" head ", TYPE *" elm ",
LIST_ENTRY " NAME ");"
.PP
.BI "LIST_ENTRY *LIST_NEXT(TYPE *" elm ", LIST_ENTRY " NAME ");"
.\".PP
.\".BI "LIST_ENTRY LIST_PREV(TYPE *" elm ", LIST_HEAD *" head ", TYPE,
LIST_ENTRY " NAME ");"
.PP
.BI "void LIST_REMOVE(TYPE *" elm ", LIST_ENTRY " NAME ");"
.\".PP
.\".BI "void LIST_SWAP(LIST_HEAD *" head1 ", LIST_HEAD *" head2 ", TYPE,
LIST_ENTRY " NAME ");"
.fi
]]
I'll continue working on other sections;
please tell me if you find anything that could be improved.
I'll work on list.3 only, so that we then have a pattern for the rest.
Also, this way they can be merged to master separately,
resulting in shorter patchsets and times.
Cheers,
Alex
