Re: gtk-doc output options
On 11/12/2017 06:24 PM, Philip Withnall wrote: > On Sun, 2017-11-12 at 17:08 +0100, Stefan Sauer wrote: >> Since people regular illy complain about the slowness of gtk-doc I'd >> like to evaluate some options. First the slowness is due to using the >> docbook-xsl stylesheets to produce html/pdf and optionally man pages. >> One main to get a huge speedup would be to drop the whole docbook >> toolchain and generate the html output directly from the comment >> blocks >> in the code. A nice side effect would be much higher portability. >> >> Below is a link to a survey to learn how important pdf/man support >> would >> be. Please note that man support means outputting one man-page for >> each >> refentry. This is not about dropping output of man-pages for PROGRAM >> sections (though we need to rethink the tooling here). Please fill >> the >> poll, it will be up until end of this year. >> >> http://www.polljunkie.com/poll/tiazer/gtkdoc-output-formats >> >> Getting there is quite a bit of work. I am working on coming up with >> a >> smooth transition plan. For questions, feel free to ask, come to >> #gtkdoc >> to discuss etc. > Thanks for putting time and thought into this, Stefan. I appreciate > your continued efforts on gtk-doc. > > Perhaps the poll could be clarified by pointing to some example output > in each format (HTML, PDF, man). Pointing to some man output, > especially, would help, since I suspect many people aren’t familiar > with what’s available there. HTML: The intention is the mimic the current html output. I would turn the current html output into python templates and produce the same output (more or less). Some work-in-progress thoughts are here: https://git.gnome.org/browse/gtk-doc/tree/doc/design-2.x.txt#n79 PDF: One options to keep pdf output would be to render a pdf from html. I am looking at various tools to see how viable this would be. MAN: To clarify this, right now some projects write man-pages in docbook and also xi:include them into the gtk-doc reference and output this to html/pdf. I'd like to support this conceptually, but most likely we'll write the man page as markdown instead. What gtk-doc supports historically is gtkdoc-mkman. This tool is not run by default in the makefiles we ship and it wasn't enabled there since I took over gtk-doc maintainership. This would produce single man pages for *each* symbol. In the survey one respondant selected man support and whoever this was, please talk to me. Stefan > > Philip > > > ___ > desktop-devel-list mailing list > desktop-devel-list@gnome.org > https://mail.gnome.org/mailman/listinfo/desktop-devel-list ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
Re: gtk-doc output options
On Sun, 2017-11-12 at 17:08 +0100, Stefan Sauer wrote: > Since people regular illy complain about the slowness of gtk-doc I'd > like to evaluate some options. First the slowness is due to using the > docbook-xsl stylesheets to produce html/pdf and optionally man pages. > One main to get a huge speedup would be to drop the whole docbook > toolchain and generate the html output directly from the comment > blocks > in the code. A nice side effect would be much higher portability. > > Below is a link to a survey to learn how important pdf/man support > would > be. Please note that man support means outputting one man-page for > each > refentry. This is not about dropping output of man-pages for PROGRAM > sections (though we need to rethink the tooling here). Please fill > the > poll, it will be up until end of this year. > > http://www.polljunkie.com/poll/tiazer/gtkdoc-output-formats > > Getting there is quite a bit of work. I am working on coming up with > a > smooth transition plan. For questions, feel free to ask, come to > #gtkdoc > to discuss etc. Thanks for putting time and thought into this, Stefan. I appreciate your continued efforts on gtk-doc. Perhaps the poll could be clarified by pointing to some example output in each format (HTML, PDF, man). Pointing to some man output, especially, would help, since I suspect many people aren’t familiar with what’s available there. Philip signature.asc Description: This is a digitally signed message part ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
gtk-doc output options
Since people regular illy complain about the slowness of gtk-doc I'd like to evaluate some options. First the slowness is due to using the docbook-xsl stylesheets to produce html/pdf and optionally man pages. One main to get a huge speedup would be to drop the whole docbook toolchain and generate the html output directly from the comment blocks in the code. A nice side effect would be much higher portability. Below is a link to a survey to learn how important pdf/man support would be. Please note that man support means outputting one man-page for each refentry. This is not about dropping output of man-pages for PROGRAM sections (though we need to rethink the tooling here). Please fill the poll, it will be up until end of this year. http://www.polljunkie.com/poll/tiazer/gtkdoc-output-formats Getting there is quite a bit of work. I am working on coming up with a smooth transition plan. For questions, feel free to ask, come to #gtkdoc to discuss etc. Thanks, Stefan ___ desktop-devel-list mailing list desktop-devel-list@gnome.org https://mail.gnome.org/mailman/listinfo/desktop-devel-list
