docs: Add a manual / language reference / man page

[fbs]

The reference_guide was meant to be a short guide to quickly see how a
feature works. It was never meant to be the place where all technical
details are discussed but as there was no better place that is where it
ended up.

This introduces a new place for all the technical details. It is
written in asciidoc as that, improves plain text readability (slighly
personal) and it is easy exportable to a lot of other formats which
makes it possible to use this for our man-page and website.

---

This is still work in progress but hoping to get some feedback on it.

Open questions:

• do we want to render the asciidoc into man and add it to the repository or do we ask packages to add asciidoctor as a dependency?
• do we want this to be one manpage or should we split it up into bpftrace and bpftrace-language (i'd prefer one page for now)
• is there a reason to not use asciidoc and go to back to man instead? I chose adoc as its easier to read/write imo and it is readable in github.

TODO:

• finish calls
• finish probes
• go over styling of html and man
• strip details from the ref guide

Note that I don't expect this to be completely finished when the todo items are done. I'm hoping its good enough for a first version so we can expand later. We also have some behaviour that isn't clearly defined, I hope we can define them before we put it in the manpage.

[danobi]

do we want to render the asciidoc into man and add it to the repository or do we ask packages to add asciidoctor as a dependency?

I'd prefer if we only had source files. Less confusion and less stuff to forget to update. Also it looks like most distros have it already: https://pkgs.org/search/?q=asciidoctor

do we want this to be one manpage or should we split it up into bpftrace and bpftrace-language (i'd prefer one page for now)

One seems fine to me

is there a reason to not use asciidoc and go to back to man instead? I chose adoc as its easier to read/write imo and it is readable in github.

I'd really rather not write raw man pages. That sounds too painful. adoc seems appealing b/c it can generate reasonable .htmls and man pages.

[danobi]

Will review some more later

[danobi]

I'm not sure what "and that you pay the toll again inside printf() (whilst it ....)". Is this referring to the string constant or the scratch space needed for submitting an event to the perf event buffer?

If it's the latter, not sure we need to describe implementation details (as it might change later)

[fbs]

this is copy/pasta from the refguide, ill just leave it out :)

[brendangregg]

Yes, the reference guide is intended to be brief. As a general rule, I don't like to see a wall of text anywhere: there should be at least one heading visible on the screen at all times. This forces all sections to be less than one screenful.

I wouldn't delete things entirely from the reference guide, as it'll still be the number one place people do searches on. So things like BPFTRACE_STRLEN should still be mentioned, even if it's just a list of keywords and a reference. E.g., "For environment variables BPFTRACE_STRLEN, ..., ..., ..., see the xxx.doc". Then people can still search on it.

I don't understand bpftrace.adoc: it says its a man page. I think that's the right place for man page things, but not "all technical details." Right now we have:

• Reference guide: brief summary of everything
• Tool example files: where you can discuss anything about the tools.
• internal_development.md: where you can discuss anything about the code.

So if we have a bunch of technical details including code snippits or command outputs that doesn't fit into those locations, then we can create another file for it. I hope we can come up with a name that makes sense. I'm not sure what though. The "bpftrace Appendix?" The "bpftrace Encyclopedia"?

It could also be a more of a community developed wiki, where people are free to dump stuff in there that might be useful for searching later on. Whereas we carefully review what goes into the official reference guide.

[fbs]

Yes, the reference guide is intended to be brief. As a general rule, I don't like to see a wall of text anywhere: there should be at least one heading visible on the screen at all times. This forces all sections to be less than one screenful.

I wouldn't delete things entirely from the reference guide, as it'll still be the number one place people do searches on. So things like BPFTRACE_STRLEN should still be mentioned, even if it's just a list of keywords and a reference. E.g., "For environment variables BPFTRACE_STRLEN, ..., ..., ..., see the xxx.doc". Then people can still search on it.

Yes i want to link to the env section of the manpage

I don't understand bpftrace.adoc: it says its a man page. I think that's the right place for man page things, but not "all technical details." Right now we have:

* Reference guide: brief summary of everything

* Tool example files: where you can discuss anything about the tools.

* internal_development.md: where you can discuss anything about the code.

So if we have a bunch of technical details including code snippits or command outputs that doesn't fit into those locations, then we can create another file for it. I hope we can come up with a name that makes sense. I'm not sure what though. The "bpftrace Appendix?" The "bpftrace Encyclopedia"?

The manpage I wrote documents:

• flags
• env vars
• all the language details (builtins, calls, probetypes, types & pointers)
• all the details about using bpftrace, address space, etc

It doesn't say anything about the internals or about the tools we ship, we have separate docs for it.

It could also be a more of a community developed wiki, where people are free to dump stuff in there that might be useful for searching later on. Whereas we carefully review what goes into the official reference guide.

Sounds good

[fbs]

thanks @danobi

[fbs]

Feel like more words describing actions should go here, but i lack inspration

[fbs]

Took a while but I think im almost there. I still need to do the details of a few probe types but other than that I think its good enough for a first version.

[fbs]

Added the int syntax from #1900

[fbs]

I fixed the section naming thing so linking is easier now. I uploaded a html version as well http://dump.madhax.nl/bpftrace.html#functions-reg , this is what it would look like if we put it on bpftrace.org

[fbs]

Ready for review @danobi @viktormalik @brendangregg . There is always more to add but I think its good enough for a first man page

$ asciidoctor  man/adoc/bpftrace.adoc
$ open man/adoc/bpftrace.html
$ asciidoctor man/adoc/bpftrace.adoc  -b manpage
$ man man/adoc/bpftrace.8

[viktormalik]

Just a bunch of formatting/spelling suggestions. The content itself looks good.

[danobi]

Also I think we need a cmake rule to generate man page using asciidoctor + install it

[danobi]

Make these bullet points instead?

[fbs]

Addressed the comments.

• all typos fixes are applied
• new strftime has been added
• function heading has changed from buf_t buf(...) to just buf
• all other small comments have been addressed too

If there are no objections im hoping to merge this as is. CI integration etc can be done in a follow up. Once this is in we can update it as part of PRs instead of having to sync this PR the whole time :)

[danobi]

Yeah, let's get this in now so we can all commit changes to it. Looks fairly complete already