Password Encryptions transformation

[Vincent Bray <no...@gmail.com>]

Hi kids,

Following from Tom Donovan's work on
http://wiki.apache.org/httpd/EncryptedPasswords I thought I'd have a
pop at converting it to xdocs. The result is attached.

It builds ok, and the result isn't too shaby, but ./build.sh
validate-xml fails with:

validate-xml:
[xmlvalidate] /Users/noodl/Apache/httpd-trunk/docs/manual/misc/password_encryptions.xml:158:15:
The content of element type "section" must match
"(title,related?,(section|p|example|note|table|ul|ol|dl|pre|blockquote)*)".
[xmlvalidate] /Users/noodl/Apache/httpd-trunk/docs/manual/misc/password_encryptions.xml
is not a valid XML document
[xmlvalidate] 456 file(s) have been successfully validated.

I'm having trouble see where I went wrong, as the first section
contains only title, section, p, and dl elements. What did I mess up?

Also, as this is my first go at producing a whole document, please
don't be shy telling me what I've messed up. In particular I think I
may have used too many nested section elements.

In my trunk working copy, this file is docs/manual/misc/password_encryptions.xml

Is that name ok? There's a few different combinations of
squishedworks, under_scored_names and hyphenated-gubbins in that
directory.

-- 
noodl

Re: Password Encryptions transformation

[Vincent Bray <no...@gmail.com>]

On 19/08/07, André Malo <nd...@perlig.de> wrote:
> Issues to consider:
> * The document needs to be entered into the sitemap

Ok, assuming you mean docs/manual/sitemap.xml, I'll list it under
misc? The only page listed under /misc/ in that file at the moment is
Relevant Standards (which seems incomplete), though it does link to
the /misc/ area directly. Should I add the rest of the documents in
/misc/ to sitemap too?

I had planned to add links to the mod_authn_dbd docs and anywhere else
relevant like /howto/auth.xml.

> * don't forget the set svn:keywords to LastChangedRevision on checkin.

Will do. Any others that should be set? I saw you commit a propchange
recently setting eolstyle to natural. Should that be performed for new
pages?

While I'm asking silly questions.. The copyright year on all the
generated docs I can see is still 2006. Where's that set?

And thanks for helping me resolve my mistaken commit identity booboo :-)

-- 
noodl

Re: Password Encryptions transformation

[André Malo <nd...@perlig.de>]

* Vincent Bray wrote:

> Hi kids,
>
> Following from Tom Donovan's work on
> http://wiki.apache.org/httpd/EncryptedPasswords I thought I'd have a
> pop at converting it to xdocs. The result is attached.
>
> It builds ok, and the result isn't too shaby, but ./build.sh
> validate-xml fails with:
>
> validate-xml:
> [xmlvalidate]
> /Users/noodl/Apache/httpd-trunk/docs/manual/misc/password_encryptions.xml
>:158:15: The content of element type "section" must match
> "(title,related?,(section|p|example|note|table|ul|ol|dl|pre|blockquote)*)
>". [xmlvalidate]
> /Users/noodl/Apache/httpd-trunk/docs/manual/misc/password_encryptions.xml
> is not a valid XML document
> [xmlvalidate] 456 file(s) have been successfully validated.
>
> I'm having trouble see where I went wrong, as the first section
> contains only title, section, p, and dl elements. What did I mess up?

It's later:

<p>C or C++</p>
Use the APR function: <a 
href="http://apr.apache.org/docs/apr-util/1.2/apr__sha1_8h.html#38a5ac487992a24e941b7501273829e8">apr_sha1_base64</a>

> Also, as this is my first go at producing a whole document, please
> don't be shy telling me what I've messed up. In particular I think I
> may have used too many nested section elements.

The xslt will bail if you've nested too deep :)

> In my trunk working copy, this file is
> docs/manual/misc/password_encryptions.xml
>
> Is that name ok? There's a few different combinations of
> squishedworks, under_scored_names and hyphenated-gubbins in that
> directory.

I personally tend to hyphens, but the trend seems to be underscores. I'd 
say, choose whatever you want, but keep it then (stable URLs are cool).

Issues to consider:
* The document needs to be entered into the sitemap
* don't forget the set svn:keywords to LastChangedRevision on checkin

(I didn't review the content)

Thanks, nd
-- 
"Umfassendes Werk (auch fuer Umsteiger vom Apache 1.3)"
                                          -- aus einer Rezension

<http://pub.perlig.de/books.html#apache2>

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Password Encryptions transformation

[Vincent Bray <no...@gmail.com>]

On 20/08/07, Joshua Slive <jo...@slive.ca> wrote:
> I'd add just a little more context at the top (in <summary>) about
> what this is useful for (perhaps with links back to the relevant
> modules).

As was pointed out on users@ there might also be a mention that apache
uses prefixes to work out what sort of 'cipher' it's looking at, but I
don't know that part of the code.

> I'd also remove the author stuff in the comment at the top.

Done. It was there because this isn't my work, but I can see that
keeping authorship references in comments can get unwieldy.

> That will go in the commit message. (And you should probably replace
> "which" with "that" most places in the doc. "Which" is rarely the
> right word to use unless it immediately follows a comma.)

Which is entirely correct :-)

> I fear the section at the bottom will be the instigator of infinite
> bug reports on better ways to do that in various languages, but I
> guess we'll live with it.

Again, it's a bit of a cop-out, I considered that there needn't be so
many programming language examples but this is Tom's work and I left
those parts be. I'd reduce it to a single language but which? Having
ruby in the manual makes me smile anyway.

> Then the next job is to link back to this doc from all the relevant
> places in the docs.

Yep. You prompted Tom to write this on users@ so know the relevance. I
figured that mod_authn_dbd and somewhere on /howto/auth.html would do,
anywhere else?

I've asked this several times (here and on IRC) and got no response,
but let's try again. Are there any other pages on the wiki that
qualify for translation, or are they largely off-topic/too temporal
for the main docs?

-- 
noodl

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Password Encryptions transformation

[Vincent Bray <no...@gmail.com>]

> I'd add just a little more context at the top (in <summary>) about
> what this is useful for (perhaps with links back to the relevant
> modules).

I'm done with it for now, please feel free to add to to the <usage>
element whatever you see fit. I get mental blocks with 'big picture'
things like this sometimes.

-- 
noodl

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org

Re: Password Encryptions transformation

[Joshua Slive <jo...@slive.ca>]

On 8/19/07, Vincent Bray <no...@gmail.com> wrote:

> Also, as this is my first go at producing a whole document, please
> don't be shy telling me what I've messed up. In particular I think I
> may have used too many nested section elements.
>
> In my trunk working copy, this file is docs/manual/misc/password_encryptions.xml
>
> Is that name ok? There's a few different combinations of
> squishedworks, under_scored_names and hyphenated-gubbins in that
> directory.

Looks fine to me. I don't care about the filename. Section nesting
down to two levels is fine.

I'd add just a little more context at the top (in <summary>) about
what this is useful for (perhaps with links back to the relevant
modules). I'd also remove the author stuff in the comment at the top.
That will go in the commit message. (And you should probably replace
"which" with "that" most places in the doc. "Which" is rarely the
right word to use unless it immediately follows a comma.)

I fear the section at the bottom will be the instigator of infinite
bug reports on better ways to do that in various languages, but I
guess we'll live with it.

Then the next job is to link back to this doc from all the relevant
places in the docs.

Joshua.

---------------------------------------------------------------------
To unsubscribe, e-mail: docs-unsubscribe@httpd.apache.org
For additional commands, e-mail: docs-help@httpd.apache.org