Hello everyone.
This is an enhancement that has been needed for a long time. I post this on both lists because, even if it is an issue to be dealt with within the list for development, it affects every user (developer or not). I would appreciate if every response or contribution to this thread was sent exclusively to the normal Cherokee support list, so that we could keep this somehow centralized.
As stated in http://code.google.com/p/cherokee/issues/detail?id=80 , the documentation is far better than it used to be, but we should design a master plan with clear milestones of what we need to make everyone happy with the docs available.
Every little piece of advice and feedback is more than welcome. It would be great if we could do something about this for the upcoming 0.8 release, but this is definitely something that will need constant work (for this and all future releases).
Needs:
----------
* [1] Improve the navigability of the documentation.
* [2] Define a convenient hierarchical structure, generate a TOC, etc.
Currently the structure reflects more the internal architecture of
Cherokee rather than a traditional manual.
* [3] Integrate the current docs into the new tree.
* [4] Define and document a series of typical configuration tasks.
Tasks to be documented:
-------------------------------------
* [1] How to configure virtual hosts from beginning to end, step by step.
* [2] How to tune scalability (IO cache & file, number of threads...)
* [3] How to setup authenticated resources
Actual Structure:
------------------------
Currently there is a way to generate a combined documentation with a TOC,
but navigability is less than optimal. A combined.html file can be created
using Asciidoc with the doc/build/build_combined.sh script, but internal
navigability is less than optimal. There might be a way to fix this other
than combining the whole documentation into a unique TXT file for Asciidoc
to process. The mentioned script creates the following Table of Contents:
1. Download
2. Cherokee Documentation
2.1. Compiling and Installing
2.2. Configuration Interface
2.3. General configuration
2.4. Virtual Servers
2.5. Encoders
2.6. Icons
2.7. Advanced topics
2.8. Other advanced topics
2.9. Internal configuration system
3. Compiling and installing on Unix
3.1. Required
3.2. Optional
3.3. Quickstart
3.4. Advanced parameters
3.5. Autostart
4. Cherokee Admin
5. General Configuration
5.1. Binding
5.2. IPv6 support
5.3. Timeout
5.4. KeepAlive
5.5. Server Tokens
5.6. Execution User and Group
6. Virtual Server
6.1. Add a new Virtual Server
6.2. Basics
6.3. Domain names
6.4. Behavior
6.5. Error Handler
6.6. Logging
6.7. Security
7. Authentication
7.1. Htpasswd Validator
7.1.1. Parameters
7.1.2. Compatibility
7.1.3. Example
7.2. Htdigest Validator
7.2.1. Parameters
7.2.2. Compatibility
7.2.3. Example
7.3. Mysql Validator
7.3.1. Parameters
7.3.2. Compatibility
7.3.3. Example
7.4. Pam Validator
7.4.1. Parameters
7.4.2. Compatibility
7.4.3. Example
7.5. Plain Validator
7.5.1. Syntax
7.5.2. Parameters
7.5.3. Compatibility
7.5.4. Example
8. Virtual Server Rule
8.1. OnlySecure
8.2. Allow From
8.3. Examples
8.4. Authentication
9. Icons
10. Advanced Configuration
11. Debugging Cherokee
12. How to cross compile Cherokee
12.1. Cherokee-Win32 from Linux
12.2. Cherokee-Win32 from OS X
13. How to generate SSL keys
13.1. Locate CA.pl or CA.sh
13.2. Create a new CA
13.3. Generate a certificate request
13.4. Sign the certificate request
13.5. Self signed certificates
13. Cherokee Tweak
14. Internal Configuration
14.1. Introduction
14.2. Server
14.3. Server Encoders
14.4. Virtual Server
14.5. Defining a virtual server behavior
14.6. Logs
14.7. Inclusion of Configuration
15. Loggers
15.1. Combined
15.2. NCSA
15.3. W3C
16. Handler: CGI
16.1. Parameters
16.2. Examples
17. Handler: List & Send
17.1. Parameters
17.2. Examples
18. Handler: Directory Listing
18.1. Parameters
18.2. Examples
19. Handler: FastCGI
19.1. Parameters
19.2. Examples
19.3. Configuring PHP
19.4. Note for developers
20. Handler: File sending
20.1. Parameters
20.2. Examples
21. Handler: Redirections
21.1. Parameters
21.2. Examples
22. Handler: SCGI
23. Balancer: Round Robin
24. Enconder: Gzip
Future structure:
------------------------
To be determined. Navigability strategy must be drafted.
--
taher at unixwars.com
http://unixwars.com
This is an enhancement that has been needed for a long time. I post this on both lists because, even if it is an issue to be dealt with within the list for development, it affects every user (developer or not). I would appreciate if every response or contribution to this thread was sent exclusively to the normal Cherokee support list, so that we could keep this somehow centralized.
As stated in http://code.google.com/p/cherokee/issues/detail?id=80 , the documentation is far better than it used to be, but we should design a master plan with clear milestones of what we need to make everyone happy with the docs available.
Every little piece of advice and feedback is more than welcome. It would be great if we could do something about this for the upcoming 0.8 release, but this is definitely something that will need constant work (for this and all future releases).
Needs:
----------
* [1] Improve the navigability of the documentation.
* [2] Define a convenient hierarchical structure, generate a TOC, etc.
Currently the structure reflects more the internal architecture of
Cherokee rather than a traditional manual.
* [3] Integrate the current docs into the new tree.
* [4] Define and document a series of typical configuration tasks.
Tasks to be documented:
-------------------------------------
* [1] How to configure virtual hosts from beginning to end, step by step.
* [2] How to tune scalability (IO cache & file, number of threads...)
* [3] How to setup authenticated resources
Actual Structure:
------------------------
Currently there is a way to generate a combined documentation with a TOC,
but navigability is less than optimal. A combined.html file can be created
using Asciidoc with the doc/build/build_combined.sh script, but internal
navigability is less than optimal. There might be a way to fix this other
than combining the whole documentation into a unique TXT file for Asciidoc
to process. The mentioned script creates the following Table of Contents:
1. Download
2. Cherokee Documentation
2.1. Compiling and Installing
2.2. Configuration Interface
2.3. General configuration
2.4. Virtual Servers
2.5. Encoders
2.6. Icons
2.7. Advanced topics
2.8. Other advanced topics
2.9. Internal configuration system
3. Compiling and installing on Unix
3.1. Required
3.2. Optional
3.3. Quickstart
3.4. Advanced parameters
3.5. Autostart
4. Cherokee Admin
5. General Configuration
5.1. Binding
5.2. IPv6 support
5.3. Timeout
5.4. KeepAlive
5.5. Server Tokens
5.6. Execution User and Group
6. Virtual Server
6.1. Add a new Virtual Server
6.2. Basics
6.3. Domain names
6.4. Behavior
6.5. Error Handler
6.6. Logging
6.7. Security
7. Authentication
7.1. Htpasswd Validator
7.1.1. Parameters
7.1.2. Compatibility
7.1.3. Example
7.2. Htdigest Validator
7.2.1. Parameters
7.2.2. Compatibility
7.2.3. Example
7.3. Mysql Validator
7.3.1. Parameters
7.3.2. Compatibility
7.3.3. Example
7.4. Pam Validator
7.4.1. Parameters
7.4.2. Compatibility
7.4.3. Example
7.5. Plain Validator
7.5.1. Syntax
7.5.2. Parameters
7.5.3. Compatibility
7.5.4. Example
8. Virtual Server Rule
8.1. OnlySecure
8.2. Allow From
8.3. Examples
8.4. Authentication
9. Icons
10. Advanced Configuration
11. Debugging Cherokee
12. How to cross compile Cherokee
12.1. Cherokee-Win32 from Linux
12.2. Cherokee-Win32 from OS X
13. How to generate SSL keys
13.1. Locate CA.pl or CA.sh
13.2. Create a new CA
13.3. Generate a certificate request
13.4. Sign the certificate request
13.5. Self signed certificates
13. Cherokee Tweak
14. Internal Configuration
14.1. Introduction
14.2. Server
14.3. Server Encoders
14.4. Virtual Server
14.5. Defining a virtual server behavior
14.6. Logs
14.7. Inclusion of Configuration
15. Loggers
15.1. Combined
15.2. NCSA
15.3. W3C
16. Handler: CGI
16.1. Parameters
16.2. Examples
17. Handler: List & Send
17.1. Parameters
17.2. Examples
18. Handler: Directory Listing
18.1. Parameters
18.2. Examples
19. Handler: FastCGI
19.1. Parameters
19.2. Examples
19.3. Configuring PHP
19.4. Note for developers
20. Handler: File sending
20.1. Parameters
20.2. Examples
21. Handler: Redirections
21.1. Parameters
21.2. Examples
22. Handler: SCGI
23. Balancer: Round Robin
24. Enconder: Gzip
Future structure:
------------------------
To be determined. Navigability strategy must be drafted.
--
taher at unixwars.com
http://unixwars.com