Conversation
This uses html2markdown from https://github.com/JohannesKaufmann/html-to-markdown to convert quark.7 into README.md. This is what I wanted in the beginning, but the markdown converter from mandoc is not great. Needs a lot of massage to fix links to the HTML, and any .Em is still a broken link because of how mandoc generates html, but it looks good enough and the actual links do work.
There was a problem hiding this comment.
This might not be the place to leave this feedback given that this is generated content. So don't feel obligated to change it in this PR.
-
The title line mentions "unified". I was expecting the description to explain what is meant by "unified" in this context.
-
In the title line, consider changing "system" to "Linux" or "system-wide".
-
Capitalize "linux" throughout.
There was a problem hiding this comment.
The text is a bit old and I think it needs a revamp, I wouldn't even call it a unified system process telemetry library anymore.
I'll make a change to address these items soon, I'm actually open to suggestion on how to summarize it, since now it also provides socket, dns and file events, my current idea is "Linux system telemetry as a library".
There was a problem hiding this comment.
Pull Request Overview
This PR generates a new README.md from quark.7 using the html2markdown converter, replacing the previous mandoc-based output with a more comprehensive and navigable document.
- Introduces a restructured and detailed README with a new table of contents and section headings.
- Updates content formatting and command examples for building and testing quark.
Files not reviewed (1)
- Makefile: Language not supported
| # [DESCRIPTION](#DESCRIPTION) | ||
|
|
||
| quark is a library that provides a way to retrieve and listen to process events in linux systems. Its main purpose is to abstract different backends and to provide a common API for listening to system-wide events like [fork(2)](https://linux.die.net/man/2/fork), [exec(3)](https://linux.die.net/man/3/exec), [exit(3)](https://linux.die.net/man/3/exit) and others. | ||
|
|
||
| quark not only provides an API for listening to events, but also handles ordering, buffering and aggregation of said events. In its most basic form, a short lived process consisting of [fork(2)](https://linux.die.net/man/2/fork) + [exec(3)](https://linux.die.net/man/3/exec) + [exit(3)](https://linux.die.net/man/3/exit) will be aggregated into one `quark_event`. An internal process cache is also kept that can be looked up via [quark\_process\_lookup(3)](https://elastic.github.io/quark/quark_process_lookup.3.html). | ||
|
|
||
| # [QUICKSTART](#QUICKSTART) |
There was a problem hiding this comment.
Consider using a consistent header hierarchy in the README. The project title on line 1 is an H1, so subsequent major sections could be H2 to improve document structure.
| # [DESCRIPTION](#DESCRIPTION) | |
| quark is a library that provides a way to retrieve and listen to process events in linux systems. Its main purpose is to abstract different backends and to provide a common API for listening to system-wide events like [fork(2)](https://linux.die.net/man/2/fork), [exec(3)](https://linux.die.net/man/3/exec), [exit(3)](https://linux.die.net/man/3/exit) and others. | |
| quark not only provides an API for listening to events, but also handles ordering, buffering and aggregation of said events. In its most basic form, a short lived process consisting of [fork(2)](https://linux.die.net/man/2/fork) + [exec(3)](https://linux.die.net/man/3/exec) + [exit(3)](https://linux.die.net/man/3/exit) will be aggregated into one `quark_event`. An internal process cache is also kept that can be looked up via [quark\_process\_lookup(3)](https://elastic.github.io/quark/quark_process_lookup.3.html). | |
| # [QUICKSTART](#QUICKSTART) | |
| ## [DESCRIPTION](#DESCRIPTION) | |
| quark is a library that provides a way to retrieve and listen to process events in linux systems. Its main purpose is to abstract different backends and to provide a common API for listening to system-wide events like [fork(2)](https://linux.die.net/man/2/fork), [exec(3)](https://linux.die.net/man/3/exec), [exit(3)](https://linux.die.net/man/3/exit) and others. | |
| quark not only provides an API for listening to events, but also handles ordering, buffering and aggregation of said events. In its most basic form, a short lived process consisting of [fork(2)](https://linux.die.net/man/2/fork) + [exec(3)](https://linux.die.net/man/3/exec) + [exit(3)](https://linux.die.net/man/3/exit) will be aggregated into one `quark_event`. An internal process cache is also kept that can be looked up via [quark\_process\_lookup(3)](https://elastic.github.io/quark/quark_process_lookup.3.html). | |
| ## [QUICKSTART](#QUICKSTART) |
There was a problem hiding this comment.
Yo Mr.Copolitos, this might make sense, when I rewrite the main text I'll consider it.
| See [BUILDING](#BUILDING) for a list of dependencies if you're having trouble building. Also see [INCLUDED BINARIES](#INCLUDED_BINARIES) and [quark-mon(8)](https://elastic.github.io/quark/quark-mon.8.html). | ||
|
|
||
| # [FEATURES](#FEATURES) |
There was a problem hiding this comment.
[nitpick] Consider standardizing the anchor naming conventions. For example, using dashes consistently in anchor links (e.g. '#included-binaries') may improve readability and consistency.
| See [BUILDING](#BUILDING) for a list of dependencies if you're having trouble building. Also see [INCLUDED BINARIES](#INCLUDED_BINARIES) and [quark-mon(8)](https://elastic.github.io/quark/quark-mon.8.html). | |
| # [FEATURES](#FEATURES) | |
| See [Building](#building) for a list of dependencies if you're having trouble building. Also see [Included Binaries](#included-binaries) and [quark-mon(8)](https://elastic.github.io/quark/quark-mon.8.html). | |
| # [Features](#features) |
4 participants
This uses html2markdown from
https://github.com/JohannesKaufmann/html-to-markdown to convert quark.7 into README.md.
This is what I wanted in the beginning, but the markdown converter from mandoc is not great.
Needs a lot of massage to fix links to the HTML, and any .Em is still a broken link because of how mandoc generates html, but it looks good enough and the actual links do work.