bench-forgejo/docs/content/doc
mpeter50 371dd96e3e
Clarify logging documentation (#21665)
My pull request changes the logging documentation that is visible here:
https://docs.gitea.io/en-us/logging-configuration/
The reason behind the changes is that for some time I've found the
logging documentation confusing, and wanted to give a try at making it
more clear.

---

If you find the existing changes to be ok, please don't merge yet, as I
have further ideas which I want to discuss with you before making the
changes.

### Swap the "Log Groups" and "Log outputs" sections.
I want to move the "Log outputs" section before the "Log Groups"
section. The reason is that the "Log Groups" section refers to ini
sections that are only later explained, and to concepts that are general
and should be documented in "Log outputs" or a different section.

This change is essentially a swap of the "Log Groups" and "Log outputs"
sections. That way the doumentation would follow the structure in which
the ini file is built: first explaining the outer sections, and then the
inner ones ([log], [log.name], [log.name.default], ...)

### Explain the workings of ambigous settings below the settings listing
Right now the basics of a setting is shown later than the explanation of
its special workings, for example with `FILE_NAME` at [the file output
mode](https://docs.gitea.io/en-us/logging-configuration/#file-mode)
(well, if the first changes are taken into account).

Currently I have `TODO` witten at 2 settings, which I have to figure out
how do they exactly work before I can document them.

### New section about [log]
New section after "Collecting Logs for Help" about how the top level
[log] itself works and what can go there.
Currently, variables that directly go into [log] are noted throughout
the whole document.

---

Please let me know what you think about the changes.

A counterargument that I myself see is that some of this is already
present in the cheatsheet, but I think it would be better to have [this
document](https://docs.gitea.io/en-us/logging-configuration/) as a
throrough explanation of how logging is configured, and the cheatsheet
would only have a short outline of the possible sections and variables.

Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com>
2022-11-22 09:04:29 +08:00
..
advanced Clarify logging documentation (#21665) 2022-11-22 09:04:29 +08:00
developers Refactor docs (#21627) 2022-10-31 23:16:19 +00:00
features Improve documentation for PAM and static deployment (#21866) 2022-11-20 20:14:03 +00:00
help Attempt clarify AppWorkPath etc. (#21656) 2022-11-09 20:22:31 -05:00
installation Fix "build from source" document to clarify the bindata tag is required. (#21853) 2022-11-18 14:34:39 +08:00
packages Add package registry cleanup rules (#21658) 2022-11-20 16:08:38 +02:00
translation Add plural definitions for German translations (#21802) 2022-11-13 11:58:21 -05:00
upgrade Add redirect of /upgrade/ to /upgrade-from-gitea/ on docs site (#21330) 2022-10-06 21:53:02 +01:00
usage Refactor docs (#21627) 2022-10-31 23:16:19 +00:00
advanced.en-us.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
advanced.fr-fr.md General documentation cleanup (#3317) 2018-01-08 23:48:42 +01:00
advanced.zh-cn.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
advanced.zh-tw.md [docs] Add zh-tw Translations (#14507) 2021-01-29 01:57:58 +01:00
developers.en-us.md Add Package Registry (#16510) 2022-03-30 16:42:47 +08:00
developers.zh-cn.md Refactor docs (#21627) 2022-10-31 23:16:19 +00:00
developers.zh-tw.md Add Package Registry (#16510) 2022-03-30 16:42:47 +08:00
features.en-us.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
features.zh-cn.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
features.zh-tw.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
help.en-us.md Implement documentation search (#8937) 2019-11-13 18:03:18 +00:00
help.fr-fr.md Implement documentation search (#8937) 2019-11-13 18:03:18 +00:00
help.zh-cn.md Implement documentation search (#8937) 2019-11-13 18:03:18 +00:00
help.zh-tw.md [docs] Add zh-tw Translations (#14507) 2021-01-29 01:57:58 +01:00
installation.en-us.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
installation.fr-fr.md General documentation cleanup (#3317) 2018-01-08 23:48:42 +01:00
installation.zh-cn.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
installation.zh-tw.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
packages.en-us.md Add Package Registry (#16510) 2022-03-30 16:42:47 +08:00
translation.de-de.md Add Package Registry (#16510) 2022-03-30 16:42:47 +08:00
translation.en-us.md Add Package Registry (#16510) 2022-03-30 16:42:47 +08:00
translation.zh-tw.md Add Package Registry (#16510) 2022-03-30 16:42:47 +08:00
upgrade.en-us.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
upgrade.fr-fr.md General documentation cleanup (#3317) 2018-01-08 23:48:42 +01:00
upgrade.zh-cn.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
upgrade.zh-tw.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
usage.en-us.md Import docs into main repository (#2874) 2017-11-26 23:44:32 +02:00
usage.zh-cn.md ZH-CN translation of Usage part (#5086) 2018-10-17 14:19:04 -04:00
usage.zh-tw.md [docs] Add zh-tw Translations (#14507) 2021-01-29 01:57:58 +01:00