[LUDOC-28] improve documentation examples for liblustreapi functions

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

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-1606 lustre_idl.h does not compile in user-space
• is related to: LU-926 llapi_file_fget_lov_uuid() is broken in 2.1
• is related to: LUDOC-63 liblustreapi examples have bad include statement

Comments

[Richard Henwood (Inactive)]

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

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

[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!

[Christopher Morrone (Inactive)]

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

[Christopher Morrone (Inactive)]

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

[Andreas Dilger]

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

[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]

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.

[Christopher Morrone (Inactive)]

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]

http://review.whamcloud.com/1879

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

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