On 04/23/2014 09:50 PM, Viktor Dukhovni wrote:
> On Wed, Apr 23, 2014 at 07:21:23PM -0400, Daniel Kahn Gillmor wrote:
> 
>> A serious way to fix this is to have the documentation produced *from*
>> the code, so that it gets upgraded in sync.  For example, neither
>> x509(1ssl) nor "openssl x509 -help" ever mention the -sha256 option,
>> but that option has been supported for years.
> 
> No, that won't work well.

out of curiosity, why not?  At the very least the output of "openssl
x509 -help" should be derived from the same code that actually parses
the "openssl x509" command-line options.  shouldn't these be able to be
kept in sync within the code?

> A more serious way to fix this is to
> reject features or patches (no matter how appealing) that extend
> or modify functionality without corresponding documentation changes.

It's easy to know reject a patch because it has no documentation
changes.  I agree that would be a good policy, worth implementing and
abiding by.

But it's much harder to know that *all relevant documentation* has been
properly updated, especially with a project that covers as much ground
as OpenSSL does.

If the bulk of the relevant documentation was all very close to the code
(e.g. like doxygen or other structured formats automatically
extractable), i think it would make it easier to find most of it and
make sure that changes also include changes to the relevant documentation.

> Plus a parallel effort to backfill the documentation gaps and errors.

Looking at the size of the documentation overall, this is a *lot* of
work.  Is anyone interested in organizing a documentation sprint to do
this kind of backfill labor in an organized and complete way?

> A tiny contribution below:
> 
> diff --git a/doc/apps/req.pod b/doc/apps/req.pod
> index 51d3083..151fe8f 100644
> --- a/doc/apps/req.pod
> +++ b/doc/apps/req.pod
> @@ -490,7 +490,7 @@ be input by calling it "1.organizationName".
>  The actual permitted field names are any object identifier short or
>  long names. These are compiled into OpenSSL and include the usual
>  values such as commonName, countryName, localityName, organizationName,
> -organizationUnitName, stateOrProvinceName. Additionally emailAddress
> +organizationalUnitName, stateOrProvinceName. Additionally emailAddress
>  is include as well as name, surname, givenName initials and dnQualifier.
>  
>  Additional object identifiers can be defined with the B<oid_file> or

thanks for this fix!  I've just submitted it via github as:

 https://github.com/openssl/openssl/pull/76

        --dkg

Attachment: signature.asc
Description: OpenPGP digital signature

Reply via email to