Improvements to Documentation #999
Comments
We want to make it clear that BenchExec is not only benchexec and one can use runexec on its own as a replacement for time. This is not mentioned in the README and also not prominently in the documentation, and has led to misunderstandings about BenchExec in the past. In particular, we want to advertise runexec for users who already have their own benchmarking scripts, while still advertising benchexec as the main and recommended solution in general for most users. For this it seems useful to make the connections between the tools more explicit in the documentation. This commit is an outcome of the discussion in #1031 and implements a part of what is suggested in #999 and #1031. Co-authored-by: Tobias Meggendorfer <[email protected]>
|
For the record: Some improvements clarifying that Current plan for further improvement is a quickstart tutorial that reviewers can link for "how to do better benchmarking easily" as discussed in #1031 (comment) and the following comments. |
|
Is there anything left that was not covered by #1044? |
|
I will double check the following:
|
|
Making all links relative should definitely be done, but is trivial. Content wise, the following would still be available:
(modulo the formatting changes) |
|
I unfortunately don't have a lot of time to pursue this further, and from the linked diff it is hard to see the exact changes and their benefits. So I won't actively work on this. But if you think this is worthwhile and would like to submit a PR, I will of course review it. Please do keep our current style of formatting text, though, I think there is still a misunderstanding. We do not do hard line wraps at x characters per line. We format text more like code, just without indentation: One sentence (statement) per line, and if the sentence (statement) is too long for that because it is longer than ca. 72-80 characters, it is split across several lines according to its internal structure (AST), i.e., with line breaks between subclauses (subexpressions) such that the most closely related parts of a sentence (statement) stay together on a line (line breaks as far towards the root of the AST as possible). When rewriting a part of a long sentence, do not change the line wrappings of the complete sentence. This has the effect of being both readable and minimizing diffs. We have very good experience with this for example also when writing papers. |
Yes, the question is mainly which of these points you consider interesting / relevant. I would then (eventually) write the points we settle on.
Yes, its an old diff. I still don't fully understand the AST rule but that's for later. |
In principle I am not opposed to any of them, but in the current state I also don't really see the benefit. Separating the Python API becomes nice if it grows. With the current size of the file I guess we can just leave it. |
I want to provide some improvement suggestions to the documentation after understanding more about benchexec.
In particular, add a clearer overview of what which tool is doing, how it can be used, etc. in README and a concise user guide.
This issue is mainly to track that I want to do this and don't forget it :)
The text was updated successfully, but these errors were encountered: