Re: [PATCH] Add man pages for some libelf functions

[Mark Wielaard <mark@klomp.org>]

Hi Aaron,

On Wed, 2024-06-26 at 20:22 -0400, Aaron Merey wrote:
> > 
> > In general I wonder how useful the description text generated by
> > chatgtp is. It looks very generic and I am a little worried it seems to
> > happily generate "descriptions" for none-exiting libelf functions.
> > 
> > > The prompt used to generate the man pages was:
> > >   Write a linux man page for the function called <FUNCTION> in the open
> > >   source project called elfutils.
> > 
> > I think it would be easier if you make the prompt less specific. How
> > about just asking for a template that you can then fill in yourself?
> > 
> >    Write a template man page for the function called <FUNCTION>  for the
> >    libelf library in the elfutils project for the "libelf Programmer's
> >    Manual"
> 
> I tried this prompt and chatgpt generated man pages very similar to
> the chatgpt originals I attached to a previous email.  Personally I
> find that I save time editing chatgpt descriptions compared to writing
> my own from scratch (although it's not a huge difference).
> 
> I understand your concerns about chatgpt generating plausible yet false
> content but if I'm editing its descriptions sufficiently then the
> content should be true, I can claim copyright, and time is saved.

I am slightly confused because I think we are using the "template"
prompt differently somehow. I would assume the above prompt makes it so
that you only let chatgpt generate one template man page where you then
insert your own descriptions because the llm only generated the general
outline.

My concern is not just that trying to pretend the llm "knows" the
actual function makes the descriptions possibly come from input where
the copyright holders can claim rights. But also that it will just
invent very generic but plausible sounding specifics about a named
function which are just not true and do miss actual specific
(important, but maybe corner) cases.

Personally I wouldn't trust any "specifics" generated by an llm chatbot
and would not use it, except maybe to create a generic template for the
man pages. Then it would still save time, but I wouldn't be concerned
about the actual descriptions being bogus.

> > > +.SH DESCRIPTION
> > > +.B elf32_getehdr
> > > +retrieves the ELF header for the given 32-bit ELF descriptor
> > > +.I elf.
> > > +The ELF header contains crucial metadata about the ELF file, such as the type, machine, version, entry point, program header table offset, and section header table offset.
> > 
> > Should it list the actual Elf32_Ehdr struct from elf.h here?
> 
> I included "See elf(5) for more information regarding the elf header"
> to the description and added elf(5) to SEE ALSO.
> 

Good idea. I assume this refers to
https://man7.org/linux/man-pages/man5/elf.5.html
I must admit I didn't know man-pages contained an elf.5 entry.
We should probably also have a generic libelf.3 overview man page.

> Thanks for the review, the updated patch is below.

Looks good.

I would leave out the history section of there is none (first appeared
in elfutils 0.0 isn't really history imho :)

One small comment on elf_version below.

> diff --git a/doc/elf_version.3 b/doc/elf_version.3
> new file mode 100644
> index 00000000..4d3f18d8
> --- /dev/null
> +++ b/doc/elf_version.3
> @@ -0,0 +1,27 @@
> +.TH ELF_VERSION 3 2024-06-26 "Libelf" "Libelf Programmer's Manual"
> +
> +.SH NAME
> +elf_version \- set the ELF library version
> +
> +.SH SYNOPSIS
> +.B #include <libelf.h>
> +
> +.BI "unsigned int elf_version(unsigned int " version ");"
> +
> +.SH DESCRIPTION
> +The \fBelf_version\fP function sets the library's ELF version to the specified value. This function must be called before any other libelf functions are used.
> +
> +.SH PARAMETERS
> +.TP
> +.I version
> +An \fIunsigned int\fP value specifying the desired ELF library version. This is should be set to \fBEV_CURRENT\fP to indicate the current version of the library. At this time the only supported \fIversion\fP values are \fBEV_CURRENT\fP and \fBEV_NONE\fP.

EV_CURRENT is the only supported version.
When given EV_NONE it won't initialize the library, but return the
highest supported version (which is EV_CURRENT obviously).

> +.SH RETURN VALUE
> +The \fBelf_version\fP function returns \fBEV_CURRENT\fP when \fIversion\fP is supported. If the specified version is not supported, it returns \fBEV_NONE\fP.

^ If the version given is not EV_NONE.
If the version given is EV_NONE it will return EV_CURRENT.


Cheers,

Mark