Conversation
- extract message, system, and time-related property docs into individual reference pages with summaries, metadata, and usage anchors - replace the overview lists with list-tables that include per-property summaries and add a hidden toctree for navigation - preserve all explanatory notes, alias details, and case-sensitivity guidance while pointing See also links to the overview AI-Agent: ChatGPT
Summary of ChangesHello @rgerhards, I'm Gemini Code Assist1! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed! This pull request significantly refactors and expands the rsyslog documentation by creating individual reference pages for each property. This change aims to improve the organization, navigability, and detail of the property documentation, making it easier for users to find specific information and understand property usage. The main properties overview page now dynamically pulls summaries from these new dedicated pages, providing a more comprehensive and structured reference. Highlights
Using Gemini Code AssistThe full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips. Invoking Gemini You can request assistance from Gemini at any point by creating a comment using either
Customization To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a Limitations & Feedback Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here. You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension. Footnotes
|
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request is a great step towards improving the structure and maintainability of the rsyslog documentation. By splitting the monolithic properties page into individual reference files, it becomes much easier to navigate and find information about specific properties. The use of list-table and include directives to build the overview page is a smart approach. I've found a few issues, mostly related to ReStructuredText syntax, formatting consistency, and typos. Addressing these will ensure the documentation renders correctly and is easy to read. Overall, this is a very positive change.
| Read how `rsyslog lead author Rainer Gerhards explains the naming | ||
| difference <https://rainer.gerhards.net/2020/08/rsyslog-template-variables-where-to-find-them.html">`_. |
There was a problem hiding this comment.
The hyperlink syntax is incorrect due to an extra "> at the end. This will likely cause a rendering error. Please remove the trailing ">.
| Read how `rsyslog lead author Rainer Gerhards explains the naming | |
| difference <https://rainer.gerhards.net/2020/08/rsyslog-template-variables-where-to-find-them.html">`_. | |
| Read how `rsyslog lead author Rainer Gerhards explains the naming | |
| difference <https://rainer.gerhards.net/2020/08/rsyslog-template-variables-where-to-find-them.html>`_. |
| All of these system properties exist in a local time variant (e.g. \$now) | ||
| and a variant that emits UTC (e.g. \$now-utc). The UTC variant is always | ||
| available by appending "-utc". Note that within a single template, only | ||
| the localtime or UTC variant should be used. While it is possible to mix | ||
| both variants within a single template, it is **not** guaranteed that | ||
| they will provide exactly the same time. The technical reason is that | ||
| rsyslog needs to re-query system time when the variant is changed. Because | ||
| of this, we strongly recommend not mixing both variants in the same | ||
| template. | ||
|
|
||
| Note that use in different templates will generate a consistent timestamp | ||
| within each template. However, as $now always provides local system time | ||
| at time of using it, time may advance and consequently different templates | ||
| may have different time stamp. To avoid this, use *timegenerated* instead. |
There was a problem hiding this comment.
There are several inconsistencies in how properties are formatted in this section. Property names like $now and timegenerated should always be enclosed in double backticks for inline code (e.g., ``$now``), rather than using backslash escapes, italics, or no formatting at all. This ensures consistency and adheres to the style guide.
| All of these system properties exist in a local time variant (e.g. \$now) | |
| and a variant that emits UTC (e.g. \$now-utc). The UTC variant is always | |
| available by appending "-utc". Note that within a single template, only | |
| the localtime or UTC variant should be used. While it is possible to mix | |
| both variants within a single template, it is **not** guaranteed that | |
| they will provide exactly the same time. The technical reason is that | |
| rsyslog needs to re-query system time when the variant is changed. Because | |
| of this, we strongly recommend not mixing both variants in the same | |
| template. | |
| Note that use in different templates will generate a consistent timestamp | |
| within each template. However, as $now always provides local system time | |
| at time of using it, time may advance and consequently different templates | |
| may have different time stamp. To avoid this, use *timegenerated* instead. | |
| All of these system properties exist in a local time variant (e.g. ``$now``) | |
| and a variant that emits UTC (e.g. ``$now-utc``). The UTC variant is always | |
| available by appending "-utc". Note that within a single template, only | |
| the localtime or UTC variant should be used. While it is possible to mix | |
| both variants within a single template, it is **not** guaranteed that | |
| they will provide exactly the same time. The technical reason is that | |
| rsyslog needs to re-query system time when the variant is changed. Because | |
| of this, we strongly recommend not mixing both variants in the same | |
| template. | |
| Note that use in different templates will generate a consistent timestamp | |
| within each template. However, as ``$now`` always provides local system time | |
| at time of using it, time may advance and consequently different templates | |
| may have different time stamp. To avoid this, use ``timegenerated`` instead. |
| ----------- | ||
| The message "as is". Should be useful for debugging and also if a message | ||
| should be forwarded totally unaltered. Please notice | ||
| *EscapecontrolCharactersOnReceive* is enabled by default, so it may be |
There was a problem hiding this comment.
The configuration parameter EscapecontrolCharactersOnReceive should be formatted as inline code using double backticks (...) rather than italics, as per the project's documentation style guide.
| *EscapecontrolCharactersOnReceive* is enabled by default, so it may be | |
| ``EscapecontrolCharactersOnReceive`` is enabled by default, so it may be |
|
|
||
| Aliases | ||
| ~~~~~~~ | ||
| - hostname — alias for source |
There was a problem hiding this comment.
The alias description is incorrect. Since this page is for the source alias, it should state that hostname is the canonical property it refers to. The current text is self-referential and confusing.
| - hostname — alias for source | |
| - hostname — canonical property referenced by source |
|
|
||
| Description | ||
| ----------- | ||
| *Only Available if rsyslog is build with --enable-uuid* |
There was a problem hiding this comment.
There's a small typo here. 'build' should be 'built'.
| *Only Available if rsyslog is build with --enable-uuid* | |
| *Only Available if rsyslog is built with --enable-uuid* |
| The current quarter hour we are in. Much like ``$HHOUR``, but values range from | ||
| 0 to 3 (for the four quarter hours that are in each hour). |
There was a problem hiding this comment.
There's a typo in the property name reference. It should be ``$hhour`` (lowercase 'h') to be consistent with its definition, not ``$HHOUR``.
| The current quarter hour we are in. Much like ``$HHOUR``, but values range from | |
| 0 to 3 (for the four quarter hours that are in each hour). | |
| The current quarter hour we are in. Much like ``$hhour``, but values range from | |
| 0 to 3 (for the four quarter hours that are in each hour). |
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
1 participant
Summary
Testing
make -C doc html(fails: sphinx-build: not found)https://chatgpt.com/codex/tasks/task_e_68d50e33ffb88332a8da2059853efa25