[LUDOC-28] improve documentation examples for liblustreapi functions

• Status: Closed
• Project: Lustre Documentation
• Type: Improvement
• Priority: Minor
• Reporter: Andreas Dilger
• Assignee: Richard Henwood (Inactive)
• Resolution: Fixed
• Labels: QContent
• Story Points: 1
• Business Value: 23

Description

Per LU-926: A user found problems by trying the llapi example in the lustre manual. There are at least two obvious bugs in that example (just try compiling it, you'll see them), so that should be fixed as well.

Issue Links

• is related to: LU-926 llapi_file_fget_lov_uuid() is broken ...
• is related to: LUDOC-63 liblustreapi examples have bad includ...
• is related to: LU-1606 lustre_idl.h does not compile in user...

Comments

[Christopher Morrone]

To be specific, the broken demo application is in section "34.6.Example Using the llapi Library". The first bug is here:

   printf("Lov object group %llu\n", lump->lmm_object_gr);

That structure has no lmm_object_gr member.

And here is an obvious typo of a missing "p":

 rintf("Write to the file\n");

While someone is fixing it, they should really also make it easier to use. It would be nice if editing macros in the program was not necessary to run it. Also it would be nice to accept a path on the command line instead of assuming that the CWD is in a lustre filesystem without any checks to that effect.

[Andreas Dilger]

I made those changes last night after looking into this section of the manual for the first time.

My only hesitation in submitting it directly is that I edited the program inside the manual and now it needs to be tested.

[Andreas Dilger]

http://review.whamcloud.com/1879

I haven't tested the example code yet, but posting it so it doesn't get lost.

[Christopher Morrone]

Also note that we'll need to update all of the man pages in lustre with the new examples as well. I would make a new LU ticket and link it to here, but I don't have linking ability as far as I can tell.

I think we should probably make all of the examples be buildable .c files to start with. I have seen examples where C code was directly included into docbook documents using special directives. We should see if we can do that without too much effort.

For now we'll probably just need to copy-and-paste the examples into the man pages. But perhaps in the future we'll put the manual in the Lustre tree, and let it build the man pages. Docbook defines a "reference page" type (<refentry>)that can be directly converted into man page format.

[Andreas Dilger]

I agree - having a subdirectory in the Lustre Git repo with all of the examples as .c files that are built every time would be the best way to ensure they continue to compile over time. Copying them into the manual occasionally is better than if they never get updated, and we can work on automating this process later, once we have examples that actually build and run.

[Richard Henwood (Inactive)]

For a first draft at a regression test against Chris's LU-1606 fixes I have created a directory:

lustre/tests/clientapi/

I propose to put the examples from the manual in there.

[Andreas Dilger]

Assign to Richard, since he is mostly working on this.

[Christopher Morrone]

Richard, did you ever put the .c files somewhere?

[Christopher Morrone]

It might be better to use the <programlisting> docbook element for these program examples, instead of <screen>.

[Richard Henwood (Inactive)]

Indeed! thanks for the prompt: not only does <programlisting> look perfect for this, I've found a page on including external code examples to allow breaking out the programs to simplify testing: http://www.sagehill.net/docbookxsl/ExternalCode.html.

Thanks for the prompt!

[Richard Henwood (Inactive)]

i've refreshed the code examples to work with the current master:

http://review.whamcloud.com/#change,1879