https://jira.whamcloud.com This file is an XML representation of an issue en-us 9.4.14 940014 05-12-2023 https://jira.whamcloud.com/browse/LUDOC-28 Lustre Documentation <p>Per <a href="https://jira.whamcloud.com/browse/LU-926" title="llapi_file_fget_lov_uuid() is broken in 2.1" class="issue-link" data-issue-key="LU-926"><del>LU-926</del></a>: 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.</p> LUDOC-28

improve documentation examples for liblustreapi functions

Improvement Minor Closed Fixed Richard Henwood Andreas Dilger QContent Thu, 15 Dec 2011 01:06:04 +0000 Fri, 10 May 2013 19:53:25 +0000 Fri, 10 May 2013 19:53:20 +0000 0 2 <p>To be specific, the broken demo application is in section "34.6.Example Using the llapi Library". The first bug is here:</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> <pre class="code-java"> printf(<span class="code-quote">"Lov object group %llu\n"</span>, lump-&gt;lmm_object_gr); </pre> </div></div> <p>That structure has no lmm_object_gr member.</p> <p>And here is an obvious typo of a missing "p":</p> <div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent"> <pre class="code-java"> rintf(<span class="code-quote">"Write to the file\n"</span>); </pre> </div></div> <p>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.</p> <p>I made those changes last night after looking into this section of the manual for the first time.</p> <p>My only hesitation in submitting it directly is that I edited the program inside the manual and now it needs to be tested.</p> <p><a href="http://review.whamcloud.com/1879" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/1879</a></p> <p>I haven't tested the example code yet, but posting it so it doesn't get lost.</p> <p>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.</p> <p>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.</p> <p>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 (&lt;refentry&gt;)that can be directly converted into man page format.</p> <p>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.</p> <p>For a first draft at a regression test against Chris's <a href="https://jira.whamcloud.com/browse/LU-1606" title="lustre_idl.h does not compile in user-space" class="issue-link" data-issue-key="LU-1606"><del>LU-1606</del></a> fixes I have created a directory:</p> <p><tt>lustre/tests/clientapi/</tt></p> <p>I propose to put the examples from the manual in there.</p> <p>Assign to Richard, since he is mostly working on this.</p> <p>Richard, did you ever put the .c files somewhere?</p> <p>It might be better to use the &lt;programlisting&gt; docbook element for these program examples, instead of &lt;screen&gt;.</p> <p>Indeed! thanks for the prompt: not only does <tt>&lt;programlisting&gt;</tt> look perfect for this, I've found a page on including external code examples to allow breaking out the programs to simplify testing: <a href="http://www.sagehill.net/docbookxsl/ExternalCode.html" class="external-link" target="_blank" rel="nofollow noopener">http://www.sagehill.net/docbookxsl/ExternalCode.html</a>.</p> <p>Thanks for the prompt!</p> <p>i've refreshed the code examples to work with the current master:</p> <p><a href="http://review.whamcloud.com/#change,1879" class="external-link" target="_blank" rel="nofollow noopener">http://review.whamcloud.com/#change,1879</a></p> Related LU-926 LUDOC-63 LU-1606 Business Value 23.0 Development Rank 1|hzvl47: Rank (Obsolete) 7182 Story Points 1.0