Re: XML doc
Hi Dominik, * There is lots of markup in the examples which should not be there (commands and command options). It conveys extra information (about what is a builtin command). I consider it an improvement, but I can remove it if you feel strongly about it. * All section headers look the same. For example, the header Command Execution and the sub-headers Module and Function Commands or Delayed Execution of Commands look exactly the same. The sub-headers should be indented. Fixed. * The standard man page section headers are not printed in capitals as they should be (the format of GNU style man pages is standardized), e.g. NAME, SYNOPSIS, DESCRIPTION etc. Partially fixed. * The sections are not justified as they should be. Fixed. * The first line of the man page does not contain the usual information: FVWM(mansection) ... something ... FVWM(mansection) Fixed. * There are some examples with long lines ( 80 characters) or very funny formatting. Generally it looks like long lines broken with \\ are not typeset correctly. Fixed. * There is an inappropriate use of a single backtick in this line: undefine(`include') It's a verbatim copy of what's in the original man page. * A lot of text has been removed from the BUGS section. That's definitely an improvement. * THe section command expansion contains rubbish. I cannot reproduce this. Please let me know if you've still got this problem. Scott. :)
Re: XML doc
Hi Dominik, If you do not want to produce this documentation please use: ./configure --disable-htmldoc As the process take four times longer than building the executables, may I suggest that a) the html pages are not built unless you specifically ask for them, Ok. I will change this soon. b) the new man page stuff is disabled by default. Sorry, I don't understand what you mean. For developers, the XML source files supersede the old fvwm man page. Please make any documentation changes here NOT in the fvwm/fvwm.1.in file. Well, I'd be willing to try that, but I am *not* going to search through *400* files for the contents I want to edit (and all cross references). There *must* be a way to have just one file per man page. I'd like to be able to accomodate, but by having everything in one file we'd lose the ability to have separate HTML pages for each command. IMO, that's probably the most useful feature. See: http://members.optusnet.com.au/~scott.fvwm/allCommands.html It's natural to split up the documentation into smaller files. As an analogy, consider the FVWM source code - we don't have a single fvwm.c source file to make searching easier, but lots of separate source files with grouped functionality. I agree though, splitting up the documentation into multiple files has made searching a little harder. But, as Dan indicates, a few simple 'grep' commands should suffice. What about the other markup mentioned at the top of the man page? Ok. I will expand the doc/README file further to include these. Scott. :)
Re: XML doc
Hi Dan, Just woke up and had to try this... That's the kind of enthusiasm I like! :) When it got to the docs, it started printing this warning: make[3]: Entering directory `/home/dane/src/fvwm/build_fvwm2_5_20/doc/fvwm' Generating authors.html ../../../fvwm2_5_20/doc/fvwm/authors.xml:6: warning: failed to load external entity ../../../fvwm2_5_20/doc/fvwm.ent %myents; ^ Entity: line 1: %myents; For some reason, the new *.in files aren't being parsed. What command did you run? (./configure?) Do you still get this problem if you run utils/configure_dev.sh? I think breaking up the docs into one file per command is great. Grep should deal with finding things well enough. Agreed. Scott. :)
Re: XML doc
On Sun, Mar 11, 2007 at 09:57:58AM +1100, Scott Smedley wrote: Hi Dominik, If you do not want to produce this documentation please use: ./configure --disable-htmldoc As the process take four times longer than building the executables, may I suggest that a) the html pages are not built unless you specifically ask for them, Ok. I will change this soon. b) the new man page stuff is disabled by default. Sorry, I don't understand what you mean. There are still the normal man pages which are fine. The current state of the XML documentation prevents me from writing any documentation. As almost everything I do has to be documented, it prevents me to do almost anything. For developers, the XML source files supersede the old fvwm man page. Please make any documentation changes here NOT in the fvwm/fvwm.1.in file. Well, I'd be willing to try that, but I am *not* going to search through *400* files for the contents I want to edit (and all cross references). There *must* be a way to have just one file per man page. I'd like to be able to accomodate, but by having everything in one file we'd lose the ability to have separate HTML pages for each command. IMO, that's probably the most useful feature. See: http://members.optusnet.com.au/~scott.fvwm/allCommands.html It's natural to split up the documentation into smaller files. As an analogy, consider the FVWM source code - we don't have a single fvwm.c source file to make searching easier, but lots of separate source files with grouped functionality. We're not talking about source but documentation. In my eyes having split pages is the one feature in html docs that makes it completely unusable: you can not browse or search it in a sensible way. And it's hell to read. A single page with intra- document links is much more usable. In any case, we're talking about Unix, not windoze. It can't be *this* hard to make a script that extracts the individual files with the command documentation from one big master source file to generate the html docs. I agree though, splitting up the documentation into multiple files has made searching a little harder. But, as Dan indicates, a few simple 'grep' commands should suffice. Ciao Dominik ^_^ ^_^ -- Dominik Vogt, [EMAIL PROTECTED] signature.asc Description: Digital signature
Re: XML doc
Dominik Vogt [EMAIL PROTECTED] writes: We're not talking about source but documentation. In my eyes having split pages is the one feature in html docs that makes it completely unusable: you can not browse or search it in a sensible way. And it's hell to read. A single page with intra- document links is much more usable. I thought the separate files were great. Couldn't all the separate files be used to generate one big document? There does seem to be a pretty good index. I envision a time when the documentation is part of the source. During the build the documentation is extracted from the source and then built into the man page(s) and the html and other forms. (I'd also like to see the test cases in the source.) In any case, we're talking about Unix, not windoze. I didn't know Windows had a documentation system. I thought they gave up on CHM files. It can't be *this* hard to make a script that extracts the individual files with the command documentation from one big master source file to generate the html docs. I think that could be done but I don't see the advantage. -- Dan Espen E-mail: [EMAIL PROTECTED]
Re: XML doc
Hi Dan, I think the key is that I build from OUTSIDE the source dir. I still get the same problems. You are correct - fixed now. Thanks, Scott. :)
Re: XML doc
Hi Dominik, The current state of the XML documentation prevents me from writing any documentation. As almost everything I do has to be documented, it prevents me to do almost anything. I understand your concerns about the man-page output not being rendered perfectly I'll endeavour to fix them for you ASAP. But, that is just cosmetic. If there's a technical reason why you can't edit the XML documentation please let me know so I can address it. We're not talking about source but documentation. In my eyes having split pages is the one feature in html docs that makes it completely unusable: you can not browse or search it in a sensible way. And it's hell to read. A single page with intra- document links is much more usable. We have this too: http://members.optusnet.com.au/~scott.fvwm/fvwm/fvwm.man.html It's the bold link on the front page - it was the first thing I did. In any case, we're talking about Unix, not windoze. I'm confused. What has this got to do with anything? (Perhaps my confusion comes from not having used Windoze since ~1998.) Scott. :)
