https://bz.apache.org/bugzilla/show_bug.cgi?id=69549
Bug ID: 69549
Summary: ErrorLogFormat documentation inexact and unclear about
spaces and fields
Product: Apache httpd-2
Version: 2.5-HEAD
Hardware: All
OS: All
Status: NEW
Severity: minor
Priority: P2
Component: Documentation
Assignee: docs@httpd.apache.org
Reporter: chea...@gmail.com
Target Milestone: ---
The French documentation for ErrorLogFormat contains the following paragraph:
Il peut arriver que certains items de la chaîne de format ne produisent aucune
sortie. Par exemple, l'en-tête Referer n'est présent que si le message du
journal est associé à une requête et s'il est généré à un moment où l'en-tête
Referer a déjà été lu par le client. Si aucune sortie n'est générée, le
comportement par défaut consiste à supprimer tout ce qui se trouve entre
l'espace précédent et le suivant. Ceci implique que la ligne de journalisation
est divisée en champs ne contenant pas d'espace séparés par des espaces. Si un
item de la chaîne de format ne génère aucune sortie, l'ensemble du champ est
omis. Par exemple, si l'adresse distante %a du format [%t] [%l] [%a] %M n'est
pas disponible, les crochets qui l'entourent ne seront eux-mêmes pas
enregistrés. Il est possible d'échapper les espaces par un anti-slash afin
qu'ils ne soient pas considérés comme séparateurs de champs. La combinaison '%
' (pourcentage espace) est un délimiteur de champ de taille nulle qui ne génère
aucune sortie.
https://httpd.apache.org/docs/2.4/fr/mod/core.html#errorlogformat
The English version is:
It can happen that some format string items do not produce output. For example,
the Referer header is only present if the log message is associated to a
request and the log message happens at a time when the Referer header has
already been read from the client. If no output is produced, the default
behavior is to delete everything from the preceding space character to the next
space character. This means the log line is implicitly divided into fields on
non-whitespace to whitespace transitions. If a format string item does not
produce output, the whole field is omitted. For example, if the remote address
%a in the log format [%t] [%l] [%a] %M is not available, the surrounding
brackets are not logged either. Space characters can be escaped with a
backslash to prevent them from delimiting a field. The combination '% '
(percent space) is a zero-width field delimiter that does not produce any
output.
The fourth sentence of each version differs considerably, but both are unclear
and inexact.
The first issue is that this section uses "format string" to designate
fragments/variables in format strings, causing ambiguity and confusion. Most
software (such as PHP and Java) use the term "format specifiers":
https://docs.oracle.com/javase/8/docs/api/java/util/Formatter.html#syntax
Secondly, the fourth sentence calls the (actual) format string "the log line",
which causes confusion with actual lines in logs.
Thirdly, the fourth sentence is inexact due to "\ " (backslash space, non-field
delimiting space). Finally, its French version is wrong due to "% " (percent
space, the zero-width field delimiter that does not produce any output).
Since this topic is complicated, I recommend to add an example format string
showing how it is broken into fields.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscr...@httpd.apache.org
For additional commands, e-mail: docs-h...@httpd.apache.org
