Hi Dmitry, I'm Cc'ing this to the list so the others can see what's going on.
> I have just regenerated everything from CVS (except LangRef updates) and > re-uploaded the docs to the site. On the positive side, there's no > firebirdtest.com references anymore and all the links are old-style as > you wished. On the negative side, some of the links may be broken. > Sergey Mereutsa said that a few dozens of mostly used links were created > as redirects on the new site. Now I'm going to validate all the links to > provide him with a list of extra symlinks/redirects to create. > > I have committed a few required changes to CVS, so please update your > local copy. In particular, links "firebirdsql.org/?param" were replaced > with their complete form "firebirdsql.org/index.php?param" to please the > redirects on the new site (the shorter form doesn't work). Also, I've > fixed a few minor issues there (existing articles were missing in the > docs contents layout, etc). And the ISQL guide is now surfaced. I don't > know why it was missing on the old site. It was never published, either by mistake or because Norman decided that it wasn't ready for publication yet. > Speaking about the docs in general, here are the major problems as I see > them: > > * Now localization names have to be specified twice while building, e.g. > -Did=article-ru -Dsfx=ru. It's very inconvenient. If suffix is intended > to specify the language, why do we need a special article ID then? The article ID must always be specified, otherwise the entire documentation set is built, which is almost never what you want. (In the case of PDF, this even means that you get the entire set in one document.) The suffix is needed for non-English versions. Technically, it doesn't specify a language, but a subdirectory. It is necessary to find the right sources. If you mostly work in the same language, you can set it as a default in manual/src/build/build.xml. Mind you, normally you don't build lots of documents one after another. You build a document, check the outcome, and then possibly edit and rebuild until you are satisfied. You only type the build command once and use arrow-up for the rebuilds, so a few arguments more on the command line aren't a pain. Of course, if you build many documents, like you have just done, it IS a pain. But that's exceptional. > * It's PITA to have all the PDFs generated using their shortcut article > names and then manually rename them to human-readable names for > uploading. We should either be using the same cryptic names on the site > or introduce some new XML tag (e.g. public-name) in the sources that > will be used by the build script to name the generated files on disc PDFs are often downloaded, so they should keep their human-readable names. Here again, you only have to change the name once: when you are satisfied with your (final) build and ready to upload. It takes seconds. > * The PDF rendering sucks. And HTML CSS can be improved as well. I think both outputs are perfectly readable, but they can certainly be improved. What we have to do is: 1) Find a way to integrate the HTML output with the rest of the site (structurally and stylewise). 2) Then apply the same style to the PDF. Both are time-consuming, because lots of XSLT stylesheets will have to be edited. > * We have /rlsnotes generated as monohtml while all the rest is > multi-file html. Is there any specific reason? Ask Helen :-) Actually, we had plans to add monohtml as a standard output format anyway, so readers would have three choices for each document: - Multi-page HTML, for online browsing - Single-page HTML, for online reading and download - PDF/other, for online reading and download It's easy to implement, but we never got round to it. It's not very important, of course. > And finally, stop keeping contents on local drives :-) CVS/SVN has all > the facilities to deal with multiple versions (e.g. released and draft) > of the same document. People often keep contents on their local drives because they don't want immature versions to be built, uploaded or translated by accident. Myself, I do commit changes regularly, because ordinarily everybody only builds and uploads the docs they maintain. Now that you have rebuilt the lot, some things have gone wrong, so in this case the people who kept everything at home were right :-) As for those versioning facilities: I doubt if that's going to work for the docs. You see, with the core code you have a release from time to time. You tag the entire tree, and that's it. And then you have a couple of active branches. With the documentation, there's no overall release cycle. Every manual is published if and when it is ready. Creating tags for every new release of every single document is crazy. Creating branches for every document that's being worked on: same. I've thought about doing it for some of my own documents once or twice, but in the end I decided not to. Even if I would do it consistently, I doubt if all the others would. And if they would, we'd soon have a forest of tags and branches in the repository. Still, we can give it a try if the others feel like it. Formally, it is the right approach. Cheers, Paul Vinkenoog ------------------------------------------------------------------------------ All of the data generated in your IT infrastructure is seriously valuable. Why? It contains a definitive record of application performance, security threats, fraudulent activity, and more. Splunk takes this data and makes sense of it. IT sense. And common sense. http://p.sf.net/sfu/splunk-d2d-c2 _______________________________________________ Firebird-docs mailing list Firebird-docs@lists.sourceforge.net https://lists.sourceforge.net/lists/listinfo/firebird-docs
