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

[Aaron Merey <amerey@redhat.com>]

Hi Mark,

On Fri, Jun 28, 2024 at 7:36 AM Mark Wielaard <mark@klomp.org> wrote:
> 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.

Ok I'll drop any descriptions from the chatgpt output and write them myself.

>
> > > > +.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.

I reworded DESCRIPTION and RETURN VALUE to better describe this.
Pushed as commit 2f08cb4846.

Aaron