Re: HELP with Cygwin docs needed
On Apr 24 14:21, Warren Young wrote: On 4/24/2013 12:52, Corinna Vinschen wrote: So, if XInclude is not in the distro XInclude isn't a program, it's typically a feature of an XSLT processor. (It's not part of XSL or XSLT, so it could live elsewhere in some toolchains.) Uh, I didn't know that (obviously). XInclude support has been in xsltproc since 2001, and xsltproc is in the Cygwin package repo. Since xmlto depends on it, you should have it on your system already. xmlto does seem to have enabled the feature. (vi +218 `which xmlto`) Nice. Obviously I'll know more once I attempt the conversion. Ok, I guess you'll try soon :) I think it's good to have a maintainer for the docs again, and pulling the doc build process up to a more modern basis certainly doesn't hurt. So, thanks for volunteering! It's much appreciated. Please send patches to the cygwin-patches list, just like for code changes. Thanks, Corinna -- Corinna Vinschen Please, send mails regarding Cygwin to Cygwin Maintainer cygwin AT cygwin DOT com Red Hat
Re: HELP with Cygwin docs needed
On 4/23/2013 09:20, Corinna Vinschen wrote: does anybody know sgml and xmlto? I see that you've solved the problem, but maybe this is a good excuse to switch all these SGML files to DocBook XML (DBX)? I've taken a quick glance at this subtree. I think you can replace doctool with XIncludes if you go with DBX. Yes, I'm kinda sorta volunteering, and am asking if there is a reason I shouldn't bother. :)
Re: HELP with Cygwin docs needed
On Apr 24 10:13, Warren Young wrote: On 4/23/2013 09:20, Corinna Vinschen wrote: does anybody know sgml and xmlto? I see that you've solved the problem, but maybe this is a good excuse to switch all these SGML files to DocBook XML (DBX)? I've taken a quick glance at this subtree. I think you can replace doctool with XIncludes if you go with DBX. Yes, I'm kinda sorta volunteering, and am asking if there is a reason I shouldn't bother. :) We actually would *love* to have a volunteer maintaining the Cygwin docs. Just two questions first: - What is the advantage of changing the format? You know, I mostly get the drift of sgml now and I write the docs in vi. So, considering that I'm lazy *and* don't want to use some GUI editor to get the docs done, I wouldn't want to have relearning how to write the docs, unless there's a definitive advantage here. - Will it work equally well to build the docs on Cygwin and on Fedora? Are the tools part of a default distro in both environments? Corinna -- Corinna Vinschen Please, send mails regarding Cygwin to Cygwin Maintainer cygwin AT cygwin DOT com Red Hat
Re: HELP with Cygwin docs needed
On 4/24/2013 11:20, Corinna Vinschen wrote: - What is the advantage of changing the format? Actually, a bit more looking makes me wonder if the docs actually *are* still SGML. All the processing now seems to go through xmlto, rather than OpenJade. Without digging through the CVS history, I suspect the conversion was already made, and the files just didn't get renamed to reflect their new format. Perhaps that's because Cygwin is still hosted in CVS, so that a rename would break revision history. Anyway, the advantage that prompted my question is that if you hadn't figured the problem out on your own, I think you would have gotten more help replies, faster, if you'd asked if anyone knew DocBook and xmlto instead of SGML and xmlto. SGML DocBook is essentially a legacy document format now, used by those who can't or won't convert. (I base that judgement on being a DocBook user for nearly a decade, and following the DocBook mailing list the whole time. DocBook SGML was already on its way out when I got started, so I never even bothered going down that path.) Other advantages of the XML dialect over the SGML dialect: - SGML predates Unicode, so the tools typically don't support it. XML was designed with Unicode in mind from the start. Umlauts without hackery! :) - The DocBook XSL stylesheets maintained by Norman Walsh are kept more up to date with the current DocBook dialect. In fact, it's looking like DocBook 5 will never be available in an SGML dialect. - The DocBook 4 and earlier specs were written so that the XML and SGML dialects are supposed to be treated identically by tools consuming them, but that guarantee has no substance without two equivalent sets of stylesheets. Because the SGML stylesheets aren't kept up to date, the compatibility guarantee from the spec is toothless, unless you're willing to maintain your own set of stylesheets. - The tools to process XML, XSL, XSLT, and XML-FO are also all kept in better shape than the old SGML based tools. - Having never used the SGML dialect of DocBook, I do not know for certain, but I suspect it's easier to hack DocBook XML. E.g. Via local XSLT stylesheet overrides. - I think you could avoid the need for all that amp; and lt; hackery in your C code snippets in the docs if you used XML's CDATA feature. I write the docs in vi. Me, too. :) don't want to use some GUI editor Sadly, the GUI tools for DocBook XML really aren't where they ought to be, even if you wanted to use them. For example, there *should* be a basic DocBook based word processor along the lines of LyX, but there isn't. Instead, those wanting a simplified WYSYWYG presentation have to deal with monstrous XML powerhouses like oXygen. And even then, WYSIWYG isn't the right term for for the experience. It's more like the bad old days of web development where no two browsers gave the same result for a given bit of markup. I wouldn't want to have relearning how to write the docs, unless there's a definitive advantage here. The XML and SGML dialects of DocBook really aren't that different, in the main. You still have your sect1 and para type stuff. Where they differ is in the toolchain and the customization layers. And as I now see, it looks like most of this work has been done already. It looks like the main things remaining would be to rename *.sgml to *.xml and *.dsl to *.xsl to reflect their actual current contents, wrap the SGML fragment documents in proper XML containers, and then probably switch from the nonstandard doctool to XIncludes. I suspect that if I did that, you won't immediately see a difference, except that all .sgml became .xml. - Will it work equally well to build the docs on Cygwin and on Fedora? Are the tools part of a default distro in both environments? The GNOME docs are split between DocBook XML and SGML[1]. So, yes, you can generally count on having the DocBook XML tools installed on Red Hattish Linuxes. And if not, say because you've got a minimalist install, the tools are in the stock repos. As for Cygwin, I've built my two DBX manuals under Cygwin before, just to prove it can be done. I tend to build on Linux and OS X for normal development, however, so it's been a while since I've tried this. [1] https://en.wikipedia.org/wiki/Xinclude [2] http://goo.gl/jDmuw
Re: HELP with Cygwin docs needed
Forgot to update the footnote references: On 4/24/2013 12:31, Warren Young wrote: probably switch from the nonstandard doctool to XIncludes. [1] The GNOME docs are split between DocBook XML and SGML[1]. [2]
Re: HELP with Cygwin docs needed
On Apr 24 12:31, Warren Young wrote: On 4/24/2013 11:20, Corinna Vinschen wrote: - What is the advantage of changing the format? [...] And as I now see, it looks like most of this work has been done already. It looks like the main things remaining would be to rename *.sgml to *.xml and *.dsl to *.xsl to reflect their actual current contents, wrap the SGML fragment documents in proper XML containers, and then probably switch from the nonstandard doctool to XIncludes. I suspect that if I did that, you won't immediately see a difference, except that all .sgml became .xml. - Will it work equally well to build the docs on Cygwin and on Fedora? Are the tools part of a default distro in both environments? The GNOME docs are split between DocBook XML and SGML[1]. So, yes, you can generally count on having the DocBook XML tools installed on Red Hattish Linuxes. And if not, say because you've got a minimalist install, the tools are in the stock repos. As for Cygwin, I've built my two DBX manuals under Cygwin before, just to prove it can be done. I tend to build on Linux and OS X for normal development, however, so it's been a while since I've tried this. Ok, that sounds pretty good. It's just important that *before* the transition, we have to make sure that all tools are in the Cygwin distro as well. I'm building my stuff on Fedora so I'm off the hook, but the basic idea is that everbody using the Cygwin tools should be able to build the Cygwin package, including the docs. So, if XInclude is not in the distro (I didn't check, actually), we need a volunteer to provide it before changing the Cygwin docs. I think I know just the right guy ;) Corinna -- Corinna Vinschen Please, send mails regarding Cygwin to Cygwin Maintainer cygwin AT cygwin DOT com Red Hat
Re: HELP with Cygwin docs needed
On 4/24/2013 12:52, Corinna Vinschen wrote: So, if XInclude is not in the distro XInclude isn't a program, it's typically a feature of an XSLT processor. (It's not part of XSL or XSLT, so it could live elsewhere in some toolchains.) XInclude support has been in xsltproc since 2001, and xsltproc is in the Cygwin package repo. Since xmlto depends on it, you should have it on your system already. xmlto does seem to have enabled the feature. (vi +218 `which xmlto`) Obviously I'll know more once I attempt the conversion.
Re: HELP with Cygwin docs needed
On Apr 23 17:20, Corinna Vinschen wrote:
Hi guys,
does anybody know sgml and xmlto? I just realized that our 1.7.18
documentation is broken. I have *no* idea why this suddenly happens.
This worked fine only a short time ago, the 1.7.17 docs on cygwin.com
were fine. All the xref links
... to utils.sgml are broken now.
Consider this xref in winsup/doc/setup2.sgml (about line 177):
(see xref linkend=regtool/xref)
In winsup/utils/utils.sgml is the link target (about line 1520):
sect2 id=regtooltitleregtool/title
This usually resulted in a text like this in place of the xref in the
generated html file:
(see a class=xref href=using-utils.html#regtool title=regtoolthe
section called “regtool”/a)
Now, when I try the same on the same Linux system as always, I'm getting
an error instead:
./doctool -m -d ${srcdir}/winsup/doc -d -d \
-s ${srcdir}/winsup/doc \
-o cygwin-ug-net.sgml \
${srcdir}/winsup/doc/cygwin-ug-net.in.sgml
xmlto --skip-validation --with-dblatex html \
-o cygwin-ug-net/ \
-m ${srcdir}/winsup/doc/cygwin.dsl cygwin-ug-net.sgml
[...]
ERROR: xref linking to regtool has no generated link text.
[...]
and the generated HTML looks like this:
(see a class=xref href=???/a)
Does anybody know how to fix this?
Help? Please?
Corinna
Corinna
--
Corinna Vinschen Please, send mails regarding Cygwin to
Cygwin Maintainer cygwin AT cygwin DOT com
Red Hat
Re: HELP with Cygwin docs needed
On Apr 23 17:26, Corinna Vinschen wrote:
On Apr 23 17:20, Corinna Vinschen wrote:
Hi guys,
does anybody know sgml and xmlto? I just realized that our 1.7.18
documentation is broken. I have *no* idea why this suddenly happens.
This worked fine only a short time ago, the 1.7.17 docs on cygwin.com
were fine. All the xref links
... to utils.sgml are broken now.
Consider this xref in winsup/doc/setup2.sgml (about line 177):
(see xref linkend=regtool/xref)
In winsup/utils/utils.sgml is the link target (about line 1520):
sect2 id=regtooltitleregtool/title
This usually resulted in a text like this in place of the xref in the
generated html file:
(see a class=xref href=using-utils.html#regtool title=regtoolthe
section called “regtool”/a)
Now, when I try the same on the same Linux system as always, I'm getting
an error instead:
./doctool -m -d ${srcdir}/winsup/doc -d -d \
-s ${srcdir}/winsup/doc \
-o cygwin-ug-net.sgml \
${srcdir}/winsup/doc/cygwin-ug-net.in.sgml
xmlto --skip-validation --with-dblatex html \
-o cygwin-ug-net/ \
-m ${srcdir}/winsup/doc/cygwin.dsl cygwin-ug-net.sgml
[...]
ERROR: xref linking to regtool has no generated link text.
[...]
and the generated HTML looks like this:
(see a class=xref href=???/a)
Does anybody know how to fix this?
Ok, never mind. I think I see what the problem is. The doc Makefile
depends on the variables utils_source and cygwin_source which were
originally set in winsup/Makefile.common. The latest round of changes
to the build systems removed these variables, but the doc Makefile.in
wasn't changed accordingly. I'll see that I fix that and then create
new docs for our documentation web site.
Sorry for the unneeded panic :)
Corinna
--
Corinna Vinschen Please, send mails regarding Cygwin to
Cygwin Maintainer cygwin AT cygwin DOT com
Red Hat
