Paul et al, >> 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.
Then we need someone to decide whether its contents is okay or not. >> 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. If they both serve the same purpose (logically, not technically), why cannot we modify the build scripts so that the entered suffix would be concatenated with the article name before further processing? So that -Did=article -Dsfx=ru would be enough for the Russian version instead of specifying "ru" twice? > 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. And I've done it a few times :-) When you need to keep the language ID in sync in two parts of the command line many times, it becomes annoying. >> * 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. IMO, the manual work must be replaced with scripts as much as possible. If we need human readable names, let's have them inside the docs sources and adjust the build scripts accordingly. It would also allow the author to properly name its output instead of leaving it up to the webmaster. Just for the record, all the native language document names existing on the old site were replaced with English ones on the new site, as neither the site team nor myself speak all the supported languages at once ;-) >> * The PDF rendering sucks. And HTML CSS can be improved as well. > > I think both outputs are perfectly readable Sure. My point was not about fixing but about improving. > 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. I'm not sure we need really deep integration. Just some similarities in the colors/fonts, possibly with attached site header (graphics and top menu) in the html version. But anyway, new contents is surely ways more important than the rendering :-) >> * We have /rlsnotes generated as monohtml while all the rest is >> multi-file html. Is there any specific reason? > > Ask Helen :-) I've also noticed that if the complete book is generated as mono-html, it lacks index.html which exists when multi-html version is created. But mono-html doesn't mean single file! For the relnotes, we have a few resulting html files but without their index. > 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 I have no objections, although the demand in the downloadable HTML version is IMHO over-estimated. >> 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. Unstable or in-progress versions can be left on your side, no problems. But I was surprised to know that the version which is published on the official site was not committed. This should never happen! Commit the sources, set the tag and proceed with creating new contents. > 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. We can start with a simple solution. Just create a single "release" branch which gets modified the every time we publish something on the site. The HEAD branch must keep at least the same version as the "release" one. It may also have newer (immature) versions committed, but it is up to the author. Dmitry ------------------------------------------------------------------------------ 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
