Re: FVWM Documentation
On Sun, Jan 12, 2003 at 10:21:57AM -0500, Dan Espen wrote: Olivier Chapuis [EMAIL PROTECTED] writes: On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote: Olivier Chapuis [EMAIL PROTECTED] writes: However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. I do not understand. Really, SGML, XML and HTML is very very similar at the editor level and you say that you would like to use HTML. The massive amount of markup in docbook format makes it hard to actually read the text. I realized that XEmacs wasn't highlighting the document by default. I made some adjustments and I got some of the stuff to highlight but theres still a huge amount of markup in the file. I see that SGML mode has a command to hide most of the markup which helps, but a quick test shows that you can't edit with the markup hidden. (Stuff gets put in the wrong place.) Right now I'd say that this is still a problem, but not a big one. I'd guess after I get used to sgml-mode, there might be more benefits than problems. What we can do (and I experiment this) is to add aliases. This involve to extand the dtd and to preprocess the document with a filter style-sheet. Currently: acronym -- ac emphasis -- em quote -- q command -- cmd envar -- ev filename -- f option-- opt optional -- otn parameter -- pmt and pr (for fvwm parameter reference) userinput -- ui ...etc. and we can add fc: for fvwm commands fcr: for fvwm commands references (see fcrKillModule/fcr) fp: for fvwm parameters fpr: for fvwm parameters references I think that smaller MarkUp may help reading/editing the source. Also, we may remove from the dtd some the Markup that we do not want to use. I see that Docbook supports images. I guessed that we still couldn't use images because we want to convert Docbook to manpage format. I haven't looked at the process to convert Docbook to man, but is there some way to mark text in such a way that it will not appear in the man page? I'm thinking of: inlineimageref The following shows how a HGradient appears: imageXXX/image /inlineimageref (The whole inlineimageref section would get dropped out when the man page was generated.) Yes this is possible. Olivier -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
On Sun, Jan 12, 2003 at 12:16:51AM -0500, parv wrote: in message [EMAIL PROTECTED], wrote Dan Espen thusly... - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I'd add, the ability to include images. Some of the documentation talks about visual effects, but there are no illustrations in our documentation. (la)tex -- dvi (--), ps, pdf XML/SGM + DocBook --- man page |-- html |-- (la)tex -- dvi (--), ps, pdf |-- texinfo (never succed) |-- whatever (needs some work) how about LaTeX (or TeX) then? I like a lot Latex. I wrote my PhD. Thesis with it and a lot of papers. For me it is the best language for printing output. However, we need the doc under man page and html format and using Latex as a common source for all these formats is not a good idea. Moreover, Latex is not so easy (you do not need to learn XML/SGML/HTML but Latex needs some practices). Olivier -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
On Sat, Jan 11, 2003 at 11:39:51AM +0100, Olivier Chapuis wrote: On Sat, Jan 11, 2003 at 01:16:57AM -0500, Eric Gillespie wrote: Olivier Chapuis [EMAIL PROTECTED] writes: I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. Everyone else has moved on to XML, using Norm Walsh's very nice docbook-xsl stylesheets. There is not a big difference between SGML and XML (DocBook doc say this). I will try it. I think that at the current step I just need to change some path and name in the head of the source files. But why XML is better than SGML for writing doc? Ok, XML is a subset of SGML. As XML is enought it is probably better. Olivier -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
On Sat, Jan 11, 2003 at 12:56:40AM -0700, Rob Park wrote: Alas! Olivier Chapuis spake thus: - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. Maybe I don't have all the facts, but using SGML seems like overkill to me. Were it up to me, I'd maintain the fvwm documentation as POD (perl's Plain Old Documentation). POD is a very simple format, and there already exists many scripts for converting POD to useful formats like man, html, etc. It's also rather trivial to write a perl script that will convert POD into some other useful language, if the script doesn't already exist. But, I'm just a big perl fan, so maybe I'm biased ;) I think that POD is too weak. I will quote an old msg of Mikhael: We already use the pod documentation format in FVWM in perl tools: * fvwm-menu-directory * fvwm-menu-headlines * fvwm-menu-xlock * fvwm-perllib * all perllib classes * FvwmPerl I would probably say more yes than no to use pod in all documentation, but I don't see a lot of reasons for this. Pod is pretty rich, but not as rich as the man page format. As for me, both the man page format and pod are easy to write and read. There are a lot of small things in pod (say, no center-justification in man pages) that I don't like, it is just not configurable enough. I myself even have somewhere a patched Pod::Man that fixes some annoyances, like converting run fvwm(1) to run the fvwm manpage, but it's not an option for everyone to install it. Also fvwm-perllib fixes one bug in pod2man. There is no easy way to define a plain-unformatted-lines text without first padding it with at least one space, this looks ugly in SYNOPSYS and other places. This padding feature is often misused, for example the pod used in Pod::Parser class itself hardcodes the 12 spaces indentation, which is bad if the output is html, not just man pages. Of course if I would not be a pod fan, I would not create fvwm-perllib that uses it in several interesting ways. I also don't have a problem with the current state of fvwm documentation... I just read through the manpage every now and then to make sure I'm getting the most out of my .fvwm2rc ;) - With the html version you will have a page which contains all fvwm commands with a small description: as doc/COMMANDS in 2.5.5. Then, to get the detailed description of a command you will just have to click on the command name. (With the ps version you will have the page of the detailed description). - With a man page you have in FvwmIdent See the Module Command section of fvwm (1). With the html version you will have a direct link. - With the html/ps version you will have various complete table of contents and an concept index (both automatically generated). - We may add images for a better explanation of some cmd. - You will have the man page in the current form! Olivier -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
I send an answer to this message but it does not appear. Maybe it was condidered as a SPAM as it contains html? I try again ... Olivier -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
On 10 Jan 2003 23:26:41 +0100, Olivier Chapuis wrote: I have a concrete proposition for improving FVWM documentation. Looks pretty good to me. I may write pod2xml convertor once I understand how it should work, so we don't need to worry about the existing pod documentation. If this helps, we may drop the current docs/ directory completely and start a new doc/ directory with subdirectories from scratch. Some text files (the current NEWS, AUTHORS come to mind) are only needed to be converted to html and not other formats, so xml is not needed. But this is not clear. As well as what to do (if at all) with fvwm.lsm, DEVELOPERS and ChangeLog~s. FAQ may be maintained as xml, it needs rewritting from scratch anyway. COMMANDS.xml (or CommandList.xml) may be autogenerated from a slightly modified fvwm/functable.c. I may do it later in a reusable way using autogenerated perllib class and clean API. Regards, Mikhael. -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
Olivier Chapuis [EMAIL PROTECTED] writes: On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote: Olivier Chapuis [EMAIL PROTECTED] writes: I'm sorry, what did Dominik say? Take a look at the thread which start with: 8 Aug 2002 Len Philpot Documentation (was: Re: FVWM: How do I start modules +automatically?) For example Dominik wrote: *Sigh* Yes, the documentation is one of the biggest open issues with fvwm, but we don't have the people and/or the infrastructure to do it right. We'd need somebody who is able and willing to set up en environment in which the man page and other doc formats can be generated from a single source. OK, thanks. This was a discussion about not havingduplicated information in the source code, man pages and a proposed tutorial. I suppose using docbook might help with that. The format is more regular which might make it easier to generate or parse. However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. I do not understand. Really, SGML, XML and HTML is very very similar at the editor level and you say that you would like to use HTML. The massive amount of markup in docbook format makes it hard to actually read the text. I realized that XEmacs wasn't highlighting the document by default. I made some adjustments and I got some of the stuff to highlight but theres still a huge amount of markup in the file. I see that SGML mode has a command to hide most of the markup which helps, but a quick test shows that you can't edit with the markup hidden. (Stuff gets put in the wrong place.) Right now I'd say that this is still a problem, but not a big one. I'd guess after I get used to sgml-mode, there might be more benefits than problems. The advantage of DocBook is that the MarkUp's are concepts and not direct formating instruction. Yep, thats a great advantage. The little POD that I've seen looked better. But I don't think POD allows for images either. I am afraid that POD is too weak. I will try to answer to Rob Park on this subject. OK, I'm convinced that POD isn't better than Docbook. I see that Docbook supports images. I guessed that we still couldn't use images because we want to convert Docbook to manpage format. I haven't looked at the process to convert Docbook to man, but is there some way to mark text in such a way that it will not appear in the man page? I'm thinking of: inlineimageref The following shows how a HGradient appears: imageXXX/image /inlineimageref (The whole inlineimageref section would get dropped out when the man page was generated.) -- Dan Espen E-mail: [EMAIL PROTECTED] -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote: Olivier Chapuis [EMAIL PROTECTED] writes: Hello, I have a concrete proposition for improving FVWM documentation. This has been discussed a number of time and I think that action is needed. I am really agree with the last mail of Dominik on the subject. I'm sorry, what did Dominik say? Take a look at the thread which start with: 8 Aug 2002 Len Philpot Documentation (was: Re: FVWM: How do I start modules automatically?) For example Dominik wrote: *Sigh* Yes, the documentation is one of the biggest open issues with fvwm, but we don't have the people and/or the infrastructure to do it right. We'd need somebody who is able and willing to set up en environment in which the man page and other doc formats can be generated from a single source. And: I'm a complete newbie inrespect to documentation formats. Some basic requirements are: - Must be convertible to various other formats (man page, ps, html and possible GNU Texinfo) and must look good in these formats. - The tools must works on any system and should run out of the box. Everybody must be able to edit the documentation. - The format should be reasonably easy to edit without any tools other than a text editor. I've just this mail in my brain but roughly speaking we need: - The current man pages - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). Right now we have links to external places, for example, for the libstroke package, and links to our other man pages, for example the modules like FvwmPager. I guess you mean you'd like to see links to other parts of the man page, for example when it mentions colorsets, you'd like a link to the colorset section. Yes link to other parts of any man page (and also to the FAQ). - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I'd add, the ability to include images. Some of the documentation talks about visual effects, but there are no illustrations in our documentation. A while back I suggested junking the man pages and going to straight html. There were objections so it never happened, but I'm still not convinced that man pages are necessary. I'm not convinced too that man page are necessary. But, I am afraid that a lot of people will be very disappointed if we remove the man page. Any way with my proposal you will have the fvwm doc with the format you want (texinfo is an issue but there are tools which convert DocBook to info; I just fail to setup these tools). Note that XML is basically a subset of SGML and that both look likes HTML. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. So, let us be concrete. Attached to this message a tar.gz ball which contains an experimentation: the conversion of a very small part of the FVWM doc into SGML. The source are sgml files and utilities: ... I need some comment before I do (or not) the full translation to the new format. The generated man pages and html look pretty good. However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. I do not understand. Really, SGML, XML and HTML is very very similar at the edition level and you say that you would like to use HTML. let us take an example the ChangeMenuStyle command Man page: .TP .BI ChangeMenuStyle menustyle menu ... Changes the menu style of .IR menu to menustyle . You may specified more than one menu in each call of .BR ChangeMenuStyle . .EX ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu .EE DocBook (you may add more space in between lines): !-- next line has no analog for man page -- anchor id=MenuStyle para synopsis commandChangeMenuStyle/command parametermenustyle/parameter parametermenu/parameter /synopsis Changes the menu style of parametermenu/parameter to parametermenustyle/parameter. You may specified more than one menu in each call of commandChangeMenuStyle/command. screen ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu /screen /para HTML (to get an hilighted synopsis command line): !-- next line has no analog for man page -- A NAME=MenuStyle P TABLE BORDER=0 BGCOLOR=#D7C79A WIDTH=100% TR TD BChangeMenuStyle/B Imenustyle/I Imenu/I /TD /TR /TABLE Changes the menu style of Imenu/I to Imenustyle/I. You may specified more than one menu in each call of BChangeMenuStyle/B. PRE ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu /PRE /P So DocBook and HTML look similar: para -- P command --B parameter -- I screen -- pre synopsis -- hilight the bg of the synopsis of MenuStyle The advantage of DocBook is that the MarkUp's are concepts and not direct formating instruction. So for example if you want to redefine
Re: FVWM Documentation
On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote: Olivier Chapuis [EMAIL PROTECTED] writes: Hello, I have a concrete proposition for improving FVWM documentation. This has been discussed a number of time and I think that action is needed. I am really agree with the last mail of Dominik on the subject. I'm sorry, what did Dominik say? Take a look at the thread which start with: 8 Aug 2002 Len Philpot Documentation (was: Re: FVWM: How do I start modules +automatically?) For example Dominik wrote: *Sigh* Yes, the documentation is one of the biggest open issues with fvwm, but we don't have the people and/or the infrastructure to do it right. We'd need somebody who is able and willing to set up en environment in which the man page and other doc formats can be generated from a single source. And: I'm a complete newbie inrespect to documentation formats. Some basic requirements are: - Must be convertible to various other formats (man page, ps, html and possible GNU Texinfo) and must look good in these formats. - The tools must works on any system and should run out of the box. Everybody must be able to edit the documentation. - The format should be reasonably easy to edit without any tools other than a text editor. I've just this mail in my brain but roughly speaking we need: - The current man pages - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). Right now we have links to external places, for example, for the libstroke package, and links to our other man pages, for example the modules like FvwmPager. I guess you mean you'd like to see links to other parts of the man page, for example when it mentions colorsets, you'd like a link to the colorset section. Yes link to other parts of any man page (and also to the FAQ). - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I'd add, the ability to include images. Some of the documentation talks about visual effects, but there are no illustrations in our documentation. A while back I suggested junking the man pages and going to straight html. There were objections so it never happened, but I'm still not convinced that man pages are necessary. I'm not convinced too that man page are necessary. But, I am afraid that a lot of people will be very disappointed if we remove the man page. Any way with my proposal you will have the fvwm doc with the format you want (texinfo is an issue but there are tools which convert DocBook to info; I just fail to setup these tools). Note that XML is basically a subset of SGML and that both look likes HTML. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. So, let us be concrete. Attached to this message a tar.gz ball which contains an experimentation: the conversion of a very small part of the FVWM doc into SGML. The source are sgml files and utilities: ... I need some comment before I do (or not) the full translation to the new format. The generated man pages and html look pretty good. However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. I do not understand. Really, SGML, XML and HTML is very very similar at the edition level and you say that you would like to use HTML. let us take an example the ChangeMenuStyle command Man page: .TP .BI ChangeMenuStyle menustyle menu ... Changes the menu style of .IR menu to menustyle . You may specified more than one menu in each call of .BR ChangeMenuStyle . .EX ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu .EE DocBook (you may add more space in between lines): !-- next line has no analog for man page -- anchor id=MenuStyle para synopsis commandChangeMenuStyle/command parametermenustyle/parameter parametermenu/parameter /synopsis Changes the menu style of parametermenu/parameter to parametermenustyle/parameter. You may specified more than one menu in each call of commandChangeMenuStyle/command. screen ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu /screen /para HTML (to get an hilighted synopsis command line): !-- next line has no analog for man page -- A NAME=MenuStyle P TABLE BORDER=0 BGCOLOR=#D7C79A WIDTH=100% TR TD BChangeMenuStyle/B Imenustyle/I Imenu/I /TD /TR /TABLE Changes the menu style of Imenu/I to Imenustyle/I. You may specified more than one menu in each call of BChangeMenuStyle/B. PRE ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu /PRE /P So DocBook and HTML look similar: para -- P command --B parameter -- I screen -- pre synopsis -- hilight the bg of the synopsis of MenuStyle The advantage of DocBook is that the MarkUp's are concepts and not direct formating instruction. So
Re: FVWM Documentation
Answer attached as I think it is rejected by the SPAM filter. Olivier On Sat, Jan 11, 2003 at 10:32:32PM -0500, Dan Espen wrote: Olivier Chapuis [EMAIL PROTECTED] writes: Hello, I have a concrete proposition for improving FVWM documentation. This has been discussed a number of time and I think that action is needed. I am really agree with the last mail of Dominik on the subject. I'm sorry, what did Dominik say? Take a look at the thread which start with: 8 Aug 2002 Len Philpot Documentation (was: Re: FVWM: How do I start modules automatically?) For example Dominik wrote: *Sigh* Yes, the documentation is one of the biggest open issues with fvwm, but we don't have the people and/or the infrastructure to do it right. We'd need somebody who is able and willing to set up en environment in which the man page and other doc formats can be generated from a single source. And: I'm a complete newbie inrespect to documentation formats. Some basic requirements are: - Must be convertible to various other formats (man page, ps, html and possible GNU Texinfo) and must look good in these formats. - The tools must works on any system and should run out of the box. Everybody must be able to edit the documentation. - The format should be reasonably easy to edit without any tools other than a text editor. I've just this mail in my brain but roughly speaking we need: - The current man pages - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). Right now we have links to external places, for example, for the libstroke package, and links to our other man pages, for example the modules like FvwmPager. I guess you mean you'd like to see links to other parts of the man page, for example when it mentions colorsets, you'd like a link to the colorset section. Yes link to other parts of any man page (and also to the FAQ). - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I'd add, the ability to include images. Some of the documentation talks about visual effects, but there are no illustrations in our documentation. A while back I suggested junking the man pages and going to straight html. There were objections so it never happened, but I'm still not convinced that man pages are necessary. I'm not convinced too that man page are necessary. But, I am afraid that a lot of people will be very disappointed if we remove the man page. Any way with my proposal you will have the fvwm doc with the format you want (texinfo is an issue but there are tools which convert DocBook to info; I just fail to setup these tools). Note that XML is basically a subset of SGML and that both look likes HTML. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. So, let us be concrete. Attached to this message a tar.gz ball which contains an experimentation: the conversion of a very small part of the FVWM doc into SGML. The source are sgml files and utilities: ... I need some comment before I do (or not) the full translation to the new format. The generated man pages and html look pretty good. However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. I do not understand. Really, SGML, XML and HTML is very very similar at the edition level and you say that you would like to use HTML. let us take an example the ChangeMenuStyle command Man page: .TP .BI ChangeMenuStyle menustyle menu ... Changes the menu style of .IR menu to menustyle . You may specified more than one menu in each call of .BR ChangeMenuStyle . .EX ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu .EE DocBook (you may add more space in between lines): !-- next line has no analog for man page -- anchor id=MenuStyle para synopsis commandChangeMenuStyle/command parametermenustyle/parameter parametermenu/parameter /synopsis Changes the menu style of parametermenu/parameter to parametermenustyle/parameter. You may specified more than one menu in each call of commandChangeMenuStyle/command. screen ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu /screen /para HTML (to get an hilighted synopsis command line): !-- next line has no analog for man page -- A NAME=MenuStyle P TABLE BORDER=0 BGCOLOR=#D7C79A WIDTH=100% TR TD BChangeMenuStyle/B Imenustyle/I Imenu/I /TD /TR /TABLE Changes the menu style of Imenu/I to Imenustyle/I. You may specified more than one menu in each call of BChangeMenuStyle/B. PRE ChangeMenuStyle pixmap1 \\ ScreenSaverMenu ScreenLockMenu /PRE /P So DocBook and HTML look similar: para -- P command --B parameter -- I screen -- pre synopsis -- hilight the bg of the synopsis of MenuStyle The advantage of DocBook is that the MarkUp's are concepts
Re: FVWM Documentation
Olivier Chapuis [EMAIL PROTECTED] writes: I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. Everyone else has moved on to XML, using Norm Walsh's very nice docbook-xsl stylesheets. docbook2man - a dramatic perl script that can convert the sgml file that I've written to manual pages. This need some works XSLT is a much better solution for this type of problem, and as a matter of fact the docbook-xsl package already includes a man page stylesheet. -- Eric Gillespie * [EMAIL PROTECTED] Build a fire for a man, and he'll be warm for a day. Set a man on fire, and he'll be warm for the rest of his life. -Terry Pratchett -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
Alas! Olivier Chapuis spake thus: - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. Maybe I don't have all the facts, but using SGML seems like overkill to me. Were it up to me, I'd maintain the fvwm documentation as POD (perl's Plain Old Documentation). POD is a very simple format, and there already exists many scripts for converting POD to useful formats like man, html, etc. It's also rather trivial to write a perl script that will convert POD into some other useful language, if the script doesn't already exist. But, I'm just a big perl fan, so maybe I'm biased ;) I also don't have a problem with the current state of fvwm documentation... I just read through the manpage every now and then to make sure I'm getting the most out of my .fvwm2rc ;) -- Rob Park http://www.ualberta.ca/~rbpark -- You're not drunk if you can lie on the floor without holding on. -- Dean Martin -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
On Sat, Jan 11, 2003 at 01:16:57AM -0500, Eric Gillespie wrote: Olivier Chapuis [EMAIL PROTECTED] writes: I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. Everyone else has moved on to XML, using Norm Walsh's very nice docbook-xsl stylesheets. There is not a big difference between SGML and XML (DocBook doc say this). I will try it. I think that at the current step I just need to change some path and name in the head of the source files. But why XML is better than SGML for writing doc? docbook2man - a dramatic perl script that can convert the sgml file that I've written to manual pages. This need some works XSLT is a much better solution for this type of problem, and as a matter of fact the docbook-xsl package already includes a man page stylesheet. I will prefer to have our own tool for docbook to man. Reason: When a doc update is needed the .sgml file should be edited and then the man page should be generated (make manpage). Then, both files should be committed and we may _not_ put the sgml files in the distribution (just the manpage). If we use XSLT we should impose to all FVWM developers to have all the XML/XSLT stuff (with the same version). This is not reasonable (as it is reasonable to impose Perl) For building the other formats (dvi/rtf/ps/html) one can use any appropriate tools (jade or openjade or XSLT with the foo or the xyz style-sheet ..etc.). Then we will distribute the best results. We may distribute the doc source and experimented user may build the doc with particular features. This is one of the advantage of the SGML/XML - DocBook stuff. BTW, does XSLT allow to build tex? Regards, Olivier -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
Olivier Chapuis [EMAIL PROTECTED] writes: Hello, I have a concrete proposition for improving FVWM documentation. This has been discussed a number of time and I think that action is needed. I am really agree with the last mail of Dominik on the subject. I'm sorry, what did Dominik say? I've just this mail in my brain but roughly speaking we need: - The current man pages - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). Right now we have links to external places, for example, for the libstroke package, and links to our other man pages, for example the modules like FvwmPager. I guess you mean you'd like to see links to other parts of the man page, for example when it mentions colorsets, you'd like a link to the colorset section. - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I'd add, the ability to include images. Some of the documentation talks about visual effects, but there are no illustrations in our documentation. A while back I suggested junking the man pages and going to straight html. There were objections so it never happened, but I'm still not convinced that man pages are necessary. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. So, let us be concrete. Attached to this message a tar.gz ball which contains an experimentation: the conversion of a very small part of the FVWM doc into SGML. The source are sgml files and utilities: ... I need some comment before I do (or not) the full translation to the new format. The generated man pages and html look pretty good. However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. The little POD that I've seen looked better. But I don't think POD allows for images either. -- Dan Espen E-mail: [EMAIL PROTECTED] -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
Re: FVWM Documentation
in message [EMAIL PROTECTED], wrote Dan Espen thusly... - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I'd add, the ability to include images. Some of the documentation talks about visual effects, but there are no illustrations in our documentation. (la)tex -- dvi (--), ps, pdf going to straight html. There were objections so it never happened, but I'm still not convinced that man pages are necessary. i suppose man pages could become pure reference instead of being both reference explanation of things. then, man pages could point to appropriate places to look for details. something like xv(1) but not as extreme. that way, those who need explanations could be better served, while keeping man pages light to the point foe those who are familiar w/ fvwm syntax. However the .sgml is really hard to read. The markup gets in the way. I don't know if I'd like trying to edit the sgml with emacs or vi. The little POD that I've seen looked better. But I don't think POD allows for images either. POD is easy almost like plain text. it, of course doesn't have facilities to include images. of course. how about LaTeX (or TeX) then? - parv -- -- Visit the official FVWM web page at URL:http://www.fvwm.org/. To unsubscribe from the list, send unsubscribe fvwm-workers in the body of a message to [EMAIL PROTECTED] To report problems, send mail to [EMAIL PROTECTED]
FVWM Documentation
Hello, I have a concrete proposition for improving FVWM documentation. This has been discussed a number of time and I think that action is needed. I am really agree with the last mail of Dominik on the subject. I've just this mail in my brain but roughly speaking we need: - The current man pages - Improved HTML version of the documentation (better inter-link that we have now with the man to html conversion). - Possibility to have a printable version of the documentation. I.e., a ps and/or pdf FVWM book. I think that what we need is SGML+DocBook. The LDP and numerous open source project use this now. So, let us be concrete. Attached to this message a tar.gz ball which contains an experimentation: the conversion of a very small part of the FVWM doc into SGML. The source are sgml files and utilities: fvwmdoc.sgml - a file to centralize all the doc fvwm.sgml- A SGML version of a very small part of the fvwm man page FvwmIdent.sgml - Full SGML version of the Fvwm Indent man page FvwmTaskBar.sgml - just the title for a SGML TaskBar doc CommandList.sgml - A SGML reduced version of doc/COMMANDS (can be autogenerated in an artificial way). docbook2man - a dramatic perl script that can convert the sgml file that I've written to manual pages. This need some works fvwm_print.dsl - Config file for building the ps/dvi/rtf version of the doc fvwm_html.dsl- Config file for building the html version of the doc doit.sh - A personal shell script to build the html and ps/dvi/rtf doc README - Some useful www link All the remaining stuff is auto-generated (but collateindex.pl which comes from docbook-dsssl-1.77.tar.gz). Man page are under man/, *nothing* is needed to build these man page but the ridiculous script I wrote docbook2man. The html version is under html/; you found the dvi and ps version under tex/ and the rtf version under rtf/ (all these need DocBook-4.2, docbook-dsssl-1.77, jade or openjade and tex for the dvi/ps version). So try it! BUTTT please do not take to much attention to the abstract and the 2nd paragraph of the Description section of the fvwm Chapter. This is an other subject (What is FVWM?). I would like to comment on this but later (at least an other thread should be started on this). I think that we can see with this small example that we can really improve FVWM documentation by switching from man page to sgml. In practice we should write the man pages using SGML+DocBook. Then, the real man page should be auto-generated (as the man page for our perl scripts are generated) using an improved version of docbook2man. So from the point of view of the distribution nothing is changed: the installed doc are the man pages. The other versions of the doc will be build by a fvwm worker and put for use (html) and download (html.tar.gz and ps.gz) on the web site. Maybe, in the future, we can release an fvwm-doc-x.x.x ball together with a fvwm-x.x.x release. I need some comment before I do (or not) the full translation to the new format. Regards, Olivier docbook.tar.bz2 Description: Binary data
