<div dir="ltr"><div>Good question. We don't have any that start at specific line numbers, currently, as it is indeed too brittle - I suspect I removed some that were there at one point. <br></div><div><br></div><div>The inclusions essentially all use :start-at: to specify a line to match. Ideally you'd also use :end-at: to specify where to stop, but some short snippets do instead specify a number of lines. Note that a practically handy option is :append:, as in this example where you are trying to excerpt the function PetscError(), and you can match on the PetscFunctionReturn(0) and then re-add the closing brace.<br></div><div><br></div><div><pre id="gmail-codecell1"><span class="gmail-p">..</span> <span class="gmail-ow">literalinclude</span><span class="gmail-p">::</span> /../src/sys/error/err.c
<span class="gmail-nc">:start-at:</span> <a href="https://petsc.org/release/docs/manualpages/Sys/PetscErrorCode.html#PetscErrorCode">PetscErrorCode</a> <a href="https://petsc.org/release/docs/manualpages/Sys/PetscError.html#PetscError">PetscError</a>(
<span class="gmail-nc">:end-at:</span> <a href="https://petsc.org/release/docs/manualpages/Sys/PetscFunctionReturn.html#PetscFunctionReturn">PetscFunctionReturn</a>(0)
<span class="gmail-nc">:append:</span> }</pre></div><div><br></div><div><br></div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">Am Fr., 5. Nov. 2021 um 15:00 Uhr schrieb Matthew Knepley <<a href="mailto:knepley@gmail.com">knepley@gmail.com</a>>:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr">Question about this. Do we have any literalincludes that are indexed by line number? I thought I have done this, and your discussion<div>below makes me realize that this is fragile. There is still some fragility with function names, but that ostensibly can be caught by the</div><div>mechanism itself.</div><div><br></div><div> Thanks,</div><div><br></div><div> Matt</div></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Fri, Nov 5, 2021 at 4:01 AM Patrick Sanan <<a href="mailto:patrick.sanan@gmail.com" target="_blank">patrick.sanan@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="ltr"><div>A big problem with documentation is that it goes out of date. This quickly takes something that was useful to something which is actually harmful. Showing the user things that don't work exactly as described is worse than showing them nothing.</div><div><br></div><div>So, it's good to aspire to writing docs in as future-proof a way as possible, especially given the broad scope and rapid rate of change in PETSc.<br></div><div><br></div><div>One step in this direction that we use currently is to avoid including explicit code blocks and output [2], but rather excerpt from the src/ tree for both code and the same output used for the test suite.</div><div><br></div><div>An example of where this is done is in the classic "hand-on" tutorials [1]: these used to be part of an HTML page with the output inline, but now the source uses syntax like this:<br></div><div><br></div><div><div style="color:rgb(0,0,0);background-color:rgb(255,255,254);font-family:Menlo,Monaco,"Courier New",monospace;font-weight:normal;font-size:12px;line-height:18px;white-space:pre-wrap"><div><span style="color:rgb(0,0,0)"> .. literalinclude:: /../src/ksp/ksp/tutorials/output/</span><span style="color:rgb(88,110,117)">ex50_tut</span><span style="color:rgb(0,0,0)">_3.out</span></div><div><span style="color:rgb(0,0,0)"> :language: none</span></div></div></div><div><br></div><div>This isn't a bulletproof approach yet - the output can still be out of date, but good enough to pass the test suite (though that can at least be bulk-updated with a single command), and the input command is still literally included. Still, it reduces the maintenance burden of documentation and reduces the chance of confusing the reader with stale information.<br></div><div><br></div><div>[1]: <a href="https://petsc.org/release/tutorials/handson/" target="_blank">https://petsc.org/release/tutorials/handson/</a></div><div>[2]: <a href="https://petsc.org/release/developers/documentation/#sphinx-documentation-guidelines" target="_blank">https://petsc.org/release/developers/documentation/#sphinx-documentation-guidelines</a></div><div><br></div></div>
</blockquote></div><br clear="all"><div><br></div>-- <br><div dir="ltr"><div dir="ltr"><div><div dir="ltr"><div><div dir="ltr"><div>What most experimenters take for granted before they begin their experiments is infinitely more interesting than any results to which their experiments lead.<br>-- Norbert Wiener</div><div><br></div><div><a href="http://www.cse.buffalo.edu/~knepley/" target="_blank">https://www.cse.buffalo.edu/~knepley/</a><br></div></div></div></div></div></div></div>
</blockquote></div>