You are viewing a plain text version of this content. The canonical link for it is here.
Posted to docs@httpd.apache.org by bu...@apache.org on 2015/04/15 22:38:23 UTC
[Bug 57819] New: Need a conventions document
https://bz.apache.org/bugzilla/show_bug.cgi?id=57819
Bug ID: 57819
Summary: Need a conventions document
Product: Apache httpd-2
Version: 2.5-HEAD
Hardware: All
OS: All
Status: NEW
Severity: normal
Priority: P2
Component: Documentation
Assignee: docs@httpd.apache.org
Reporter: coar@apache.org
We should have a document that defines conventions for the documentation, and
then apply & follow it. For example, in some places <em> is used where <var>
occurs elsewhere; occasionally <strong> appears *inside* code segments, "<br
/>" sometimes appears in code blocks, etc.
I suggest we come up with conventions patterned after those already pioneered
by books (like O'Reilly), or man pages, or *some*thing.
We probably need two documents: one for the documentation writers
defining how stuff should be written, and one for users explaining
how to interpret styles in the documentation.
* Distinguish between keywords and arbitrary user-supplied text;
* What arguments should be quoted? (I vote for filesystem paths,
URLs, AuthName values, and regexes..) Sometimes it's unclear when
quotation marks are optional, recommended, or required -- and when
they're illegal (think RAW_ARGS directive arguments).
* When to use <em> as opposed to <var>.
* Consistent indentation.
This is just a start..
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 57819] Need a conventions document
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=57819
--- Comment #1 from Rodent of Unusual Size <co...@apache.org> ---
Oh, and come up with (and use) some consistent argument-type keywords, like
* FILE-PATH (and describe in the user conventions that these are ServerRoot-
relative if not absolute)
* KEYWORD (like "temp", "permanent", "ExecCGI", ...)
* REGEX or PATTERN
* GLOB (do we have anything that does this?)
* EXPRESSION
* IDENTIFIER (like the name given to a rewrite map specification)
* URL (local or full)
There should be a way of indicating that an argument can interpolate
variables or regex group values, such as the first argument to RewriteCond
or the second argument to RewriteRule (or any of the *Match directives).
Noodling in the bug report..
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 57819] Need a conventions document
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=57819
--- Comment #2 from Rich Bowen <rb...@apache.org> ---
This should go in the https://httpd.apache.org/docs-project/ site, which is
mostly still accurate, but is somewhat light on detail, and doesn't make it
exactly easy to get started. A style/convention guide would indeed be a very
good start to that.
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org
[Bug 57819] Need a conventions document
Posted by bu...@apache.org.
https://bz.apache.org/bugzilla/show_bug.cgi?id=57819
--- Comment #3 from Godrej Woodscape <gw...@gmail.com> ---
https://www.bloglovin.com/@prestigesomerville9
https://www.bloglovin.com/@prestigesomerville9/specifications-in-prestige-somerville
https://www.spreaker.com/podcast/prestige-somerville--6117018
https://www.discogs.com/user/somervilleprice
https://www.indiegogo.com/individuals/37206022
https://www.signupgenius.com/go/10C0B48ACA92AA6FEC25-48535511-prestige
https://prestigesomervilleunit.wistia.com/medias/qshwzr7i69
https://www.cafepress.com/profile/somervillepricee
https://forums.autodesk.com/t5/user/viewprofilepage/user-id/15192900
https://taylorhicks.ning.com/profile/PrestigeRaintreePark378
https://answers.ea.com/t5/user/viewprofilepage/user-id/40616627
https://padlet.com/prestigeraintreeparkbangalore/prestige-raintree-park-rv2zlaopwm8acvps
https://dev.epicgames.com/community/profile/Kk9p2/PRaintreePark
https://gitlab.gnome.org/praintreepark
https://participa.gencat.cat/profiles/raintree_parkprice
--
You are receiving this mail because:
You are the assignee for the bug.
---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org