Good question.
The content at configuration page is very information dense and will make sense to someone who already understands the shorthand language used.
I guess was looking for something more explicit, like a recipe that didn’t force me to think too hard. Normally, when you’re exporting a document to PDF, one of the options you can control is the page size - either set through the default printer settings, or through an option available at export time. A user expectation is that something like this should be easy to change.
As this is not available through the current export options, and requires a non user level technical change, then something like this would have been helpful for the casual administrator:
there are X ways to change the defaults for the PDF export settings
1/ override the default xhtml2fo.xls file by
1.1/ step a
1.2/ step b
…
2/ Create and customize the XWiki.PDFClass object by …
3/ …
That said, the documentation does say list the ways to customize the pdf export, and now that I’ve done it, some of the other information is starting to make a bit more sense, but none if it is clear to anyone who hasn’t worked with XWiki on a much more technical level. The average wiki administrator will rarely have this level of expertise required to delve into that dense information dump and then go figure out what they need to learn in order to set the page size.
As I mentioned, some of the information is “shorthand”, in that it makes sense if you are already familiar with the subject. Take for example
… The default one, xhtml2fo.xsl, is packed in a core jar…
What does that mean? Well, it turns out that it means you can find the default transformation file in the one of the jar files, with a bit of searching, it turns out to be xwiki-platform-legacy-oldcore-12.8.jar in my case. (hindsight! the github link would have told me that, doh!)
Unpacking that version of the file, and the one I got from the github link shows that they are very different files. When I overrode the defaults with the github file (just page size), the resulting PDF came out VERY different (and wrong). When I found the bundled xsl file in the jar file, customized it and use it, the PDF came out exactly as I expected it to. Unexpected, but it’s obvious now in hindsight.
[Edit: Why were the files so different? Did I grab the wrong version from github? I don’t know, and I didn’t spend time investigating exactly what I did. I was sure I grabbed the one from the github link.]
Had there been documentation that said something like “extract the bundled xsl file, drop it in this directory and then restart your servlet container” then it would have been much easier to achieve what I was looking for (quick change with little thought required).
Instead, I spent a couple of hours puzzling things out and testing various changes until I knew the enough to make the changes I needed in the simplest fashion possible and then document it.
Does that answer your question?
It’s not a knock on the documentation, it’s more a statement that there are some areas that require a fair bit of technical knowledge before certain changes can be made to XWiki, even if those changes “should be simple to implement” (user level expectation).
Yes, those changes should be simple if you guys had unlimited developers working for you making everything nice a easy for everyone, but this is the reality we live in where help is not unlimited.
And that’s the purpose of these forums, to help solve these problems when they come up.