[OpenAFS-Doc] Final (from Latex) pdf's and html's available

[Jeffrey Altman]

This is a cryptographically signed message in MIME format.

--------------ms050406010001000601060308
Content-Type: text/plain; charset=us-ascii
Content-Transfer-Encoding: 7bit

ted creedon wrote:
> If not I'll set up a CVS server here.
> 
> This project needs documentation that can be updated.
> 
> tedc

Ted:

we all agree that it does.  however, the documentation
needs to be updatable by people other than yourself.
one of the requirements is that the tools used to produce
and maintain the documentation must be deemed usable by
those responsible for the project.   Moose is the person
responsible for documentation.

While I am a strong believer that those who do the work
get significant points, there has been a significant lack
of consensus on the tools you selected to perform this work.
There have been complaints that the tools are too hard to use
and that they cannot be used to produce one of the required
outputs:  man pages.

There have been suggestions made that other tools are
better suited for this effort including:

 * POD files

 * DocBook

 * HTML

Of these my preference is either POD or DocBook.  I prefer DocBook
because it has been used extensively by other open source projects to
generate both man pages and online documentation.

I like DocBook because it can be used to produce Windows HtmlHelp files
as well as HTML and PDF.

The benefits of the use of any of these formats over Tex are ease of
use.  Tex is most definitely the best tool to use for generating precise
formatting for technical output.  However, that is not a requirement for
this effort.   For this effort, we need simplicity, the ability for all
contributors to understand the format, and the ability to to produce the
requisite outputs (preferably as part of the build system.)

POD files are nice in this respect since anyone that has Perl on their
system is able to generate man pages and html from POD files.

I require simplicity because I want to make it a requirement that all
source code contributions to the project are accompanied by
documentation updates.   I can't make that requirement if the
documentation language is too complex.

Regardless, the final decision belong's to Moose.

Jeffrey Altman

P.S. - Private discussions on this topic are inappropriate.  Please keep
all discussions on the subject of openafs documentation on the mailing list.



--------------ms050406010001000601060308
Content-Type: application/x-pkcs7-signature; name="smime.p7s"
Content-Transfer-Encoding: base64
Content-Disposition: attachment; filename="smime.p7s"
Content-Description: S/MIME Cryptographic Signature

MIAGCSqGSIb3DQEHAqCAMIACAQExCzAJBgUrDgMCGgUAMIAGCSqGSIb3DQEHAQAAoIIJPzCC
AvowggJjoAMCAQICAw7NrDANBgkqhkiG9w0BAQQFADBiMQswCQYDVQQGEwJaQTElMCMGA1UE
ChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UEAxMjVGhhd3RlIFBlcnNv
bmFsIEZyZWVtYWlsIElzc3VpbmcgQ0EwHhcNMDUwNTI3MTc0MjQzWhcNMDYwNTI3MTc0MjQz
WjBrMQ8wDQYDVQQEEwZBbHRtYW4xFTATBgNVBCoTDEplZmZyZXkgRXJpYzEcMBoGA1UEAxMT
SmVmZnJleSBFcmljIEFsdG1hbjEjMCEGCSqGSIb3DQEJARYUamFsdG1hbkBjb2x1bWJpYS5l
ZHUwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQC+LutDu/YyHreNfoYd+ZtOjXsL
h67F2cmcVuBPBz+ZGDA+WpVEHrqXaZZO8acXBR5uAVfiwA1acE/kvD/CN5kAqx1VJuQ8Pvyk
iGHhUYTd27ZTliBIrptC7C/381gVwkS+a8jQFPJPO+OktZDzAYplGRY/MQCV8dIsvXUjucox
7TwTTdoLAJYRvHtfEcaCc6mO4ph6NeXQw8Grlx3IRAlTrkE5fBGyjH6R4fqnFTXRQAh1/bG+
i8hQvE6mud3mXdL2t7NP1Qxd9wW0/F/pnWY12IFP/luc3zEzIPvAe+nJluLuSEj0LZgP16mF
xBj1p+u9HPWcHRVX6q7+MQ0RWOv1AgMBAAGjMTAvMB8GA1UdEQQYMBaBFGphbHRtYW5AY29s
dW1iaWEuZWR1MAwGA1UdEwEB/wQCMAAwDQYJKoZIhvcNAQEEBQADgYEAUDUuzxiq8bbI8vq2
swRK513RphZp+fepyKU5mwBI6aF4GcmqITQILtfTG2SXnjSeY99d+bjOdK1DJFvVh9aOy8mh
2NbEnqMnJIZtg5+eEU64DIV5bQdDRpi99H9vA0sRATIquut+3YHba+zArj0VkVof2VI+ToBu
sHdtSrZYo0gwggL6MIICY6ADAgECAgMOzawwDQYJKoZIhvcNAQEEBQAwYjELMAkGA1UEBhMC
WkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1Ro
YXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBMB4XDTA1MDUyNzE3NDI0M1oXDTA2
MDUyNzE3NDI0M1owazEPMA0GA1UEBBMGQWx0bWFuMRUwEwYDVQQqEwxKZWZmcmV5IEVyaWMx
HDAaBgNVBAMTE0plZmZyZXkgRXJpYyBBbHRtYW4xIzAhBgkqhkiG9w0BCQEWFGphbHRtYW5A
Y29sdW1iaWEuZWR1MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAvi7rQ7v2Mh63
jX6GHfmbTo17C4euxdnJnFbgTwc/mRgwPlqVRB66l2mWTvGnFwUebgFX4sANWnBP5Lw/wjeZ
AKsdVSbkPD78pIhh4VGE3du2U5YgSK6bQuwv9/NYFcJEvmvI0BTyTzvjpLWQ8wGKZRkWPzEA
lfHSLL11I7nKMe08E03aCwCWEbx7XxHGgnOpjuKYejXl0MPBq5cdyEQJU65BOXwRsox+keH6
pxU10UAIdf2xvovIULxOprnd5l3S9rezT9UMXfcFtPxf6Z1mNdiBT/5bnN8xMyD7wHvpyZbi
7khI9C2YD9ephcQY9afrvRz1nB0VV+qu/jENEVjr9QIDAQABozEwLzAfBgNVHREEGDAWgRRq
YWx0bWFuQGNvbHVtYmlhLmVkdTAMBgNVHRMBAf8EAjAAMA0GCSqGSIb3DQEBBAUAA4GBAFA1
Ls8YqvG2yPL6trMESudd0aYWafn3qcilOZsASOmheBnJqiE0CC7X0xtkl540nmPfXfm4znSt
QyRb1YfWjsvJodjWxJ6jJySGbYOfnhFOuAyFeW0HQ0aYvfR/bwNLEQEyKrrrft2B22vswK49
FZFaH9lSPk6AbrB3bUq2WKNIMIIDPzCCAqigAwIBAgIBDTANBgkqhkiG9w0BAQUFADCB0TEL
MAkGA1UEBhMCWkExFTATBgNVBAgTDFdlc3Rlcm4gQ2FwZTESMBAGA1UEBxMJQ2FwZSBUb3du
MRowGAYDVQQKExFUaGF3dGUgQ29uc3VsdGluZzEoMCYGA1UECxMfQ2VydGlmaWNhdGlvbiBT
ZXJ2aWNlcyBEaXZpc2lvbjEkMCIGA1UEAxMbVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWlsIENB
MSswKQYJKoZIhvcNAQkBFhxwZXJzb25hbC1mcmVlbWFpbEB0aGF3dGUuY29tMB4XDTAzMDcx
NzAwMDAwMFoXDTEzMDcxNjIzNTk1OVowYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0
ZSBDb25zdWx0aW5nIChQdHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVl
bWFpbCBJc3N1aW5nIENBMIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQDEpjxVc1X7TrnK
mVoeaMB1BHCd3+n/ox7svc31W/Iadr1/DDph8r9RzgHU5VAKMNcCY1osiRVwjt3J8CuFWqo/
cVbLrzwLB+fxH5E2JCoTzyvV84J3PQO+K/67GD4Hv0CAAmTXp6a7n2XRxSpUhQ9IBH+nttE8
YQRAHmQZcmC3+wIDAQABo4GUMIGRMBIGA1UdEwEB/wQIMAYBAf8CAQAwQwYDVR0fBDwwOjA4
oDagNIYyaHR0cDovL2NybC50aGF3dGUuY29tL1RoYXd0ZVBlcnNvbmFsRnJlZW1haWxDQS5j
cmwwCwYDVR0PBAQDAgEGMCkGA1UdEQQiMCCkHjAcMRowGAYDVQQDExFQcml2YXRlTGFiZWwy
LTEzODANBgkqhkiG9w0BAQUFAAOBgQBIjNFQg+oLLswNo2asZw9/r6y+whehQ5aUnX9MIbj4
Nh+qLZ82L8D0HFAgk3A8/a3hYWLD2ToZfoSxmRsAxRoLgnSeJVCUYsfbJ3FXJY3dqZw5jowg
T2Vfldr394fWxghOrvbqNOUQGls1TXfjViF4gtwhGTXeJLHTHUb/XV9lTzGCAzswggM3AgEB
MGkwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQdHkpIEx0
ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENBAgMOzaww
CQYFKw4DAhoFAKCCAacwGAYJKoZIhvcNAQkDMQsGCSqGSIb3DQEHATAcBgkqhkiG9w0BCQUx
DxcNMDUwNjI3MjExMzM4WjAjBgkqhkiG9w0BCQQxFgQUcBuoPHZa7tY0aEXdaLWnwlgINR4w
UgYJKoZIhvcNAQkPMUUwQzAKBggqhkiG9w0DBzAOBggqhkiG9w0DAgICAIAwDQYIKoZIhvcN
AwICAUAwBwYFKw4DAgcwDQYIKoZIhvcNAwICASgweAYJKwYBBAGCNxAEMWswaTBiMQswCQYD
VQQGEwJaQTElMCMGA1UEChMcVGhhd3RlIENvbnN1bHRpbmcgKFB0eSkgTHRkLjEsMCoGA1UE
AxMjVGhhd3RlIFBlcnNvbmFsIEZyZWVtYWlsIElzc3VpbmcgQ0ECAw7NrDB6BgsqhkiG9w0B
CRACCzFroGkwYjELMAkGA1UEBhMCWkExJTAjBgNVBAoTHFRoYXd0ZSBDb25zdWx0aW5nIChQ
dHkpIEx0ZC4xLDAqBgNVBAMTI1RoYXd0ZSBQZXJzb25hbCBGcmVlbWFpbCBJc3N1aW5nIENB
AgMOzawwDQYJKoZIhvcNAQEBBQAEggEAmvV+uF8E1rXR41gMXf/fHdZzTA7qfv2kF3PGIvGq
wRxyW4QzK313xFo3gO2aEWnsN9KZjO5FLuDcRgvPaJhTN131IlejTl/v1MJX9ycPB1QUF449
74Nm1qmy3vZwSuMhDxoH2P4ZynT9jddlFkkbw/NLJ4p60RGAHAk76sHrlHFLYJcErGR5gOcu
Yw6WXmPxYw3St8ubhe1mknZptWdX6aHFgNin35Gy5hqHSughI5SMlcYmziC78bDBPwIt3JtJ
/ksI20mHAk/uLzWXeSwY85LtVOX6JFgxQYM063gkgqvAUd0vXJmCEEOCwJx7sQ69lrMgjWT+
HyPVwroXjdr68QAAAAAAAA==
--------------ms050406010001000601060308--