From: Axel S. <A....@ke...> - 2005-04-17 09:03:33
|
Aurelio, On Fri, 2005-04-15 at 13:57 -0300, Aurelio Marinho Jargas wrote: > hi axel, > > > --- Axel Simon <A....@ke...> wrote: > > we are considering using txt2tags for a tutorial gtk2hs library > > ( http://gtk2hs.sourceforge.net/ ), a library that exposes Gtk+ to > > Haskll. We would like to keep it simple > > great! > > > however we need example programs and within these we would > > like to have syntax highlighting and link every library > > function to the corresponding documentation web-page. > > I thought that both can be achieved by defining macros for > > all Haskell keywords and macros for all library functions. > > However, in the documentation it says that macros are not > > expanded in the monospace environment, hence, monospace > > seems to me very similar to verbatim. So how do I print > > something in monospace and insert hyperlinks and boldface > > text? > > yes, the documentation told you right, *macros* are not > expanded inside verbatim. macros in t2t are %%date, %%infile > and friends. > > what you could use are *filters* like preproc and postproc > which are applyed to verbatim areas as well. and example: > > %!postproc: (keyword) <font color="green">\1</font> > > but that will be a boring task, and some common text can > be expanded as if it was haskell code. Oh, ok. I didn't make the distinction between filter and macros. In fact, the filter are probably sufficient for our purposes. While syntax highlighting is nice, what we are really after is to automatically hyperlink all the library functions in the example to the corresponding html documentation. Hence I though we would just generate filters for the 3000+ functions and include those. We could then live with a manual set of syntax-highlighting filters. > what i would do, is to use the %!include: ''file.hs'' > note the two ' around. this includes the external file > file.hs as it is, with no parsing. > > so all you have to do is to generate all the haskell code > samples as separated HTML files. you can do so using > specialized code2html tools. even in the Vim editor you > can do it with this script: > > /usr/share/vim/vim*/syntax/2html.vim > > this way any tool do its best and the code can be edited > separated from the documentation. That's nice as well, but we couldn't combine that with hyperlinking the library functions. I think we are looking at code fragments rather than at complete programs, so we can probably live without complete syntax highlighting. Thanks for the clarification, Axel. |
From: Duncan C. <dun...@wo...> - 2005-04-18 23:31:03
|
On Sun, 2005-04-17 at 10:02 +0100, Axel Simon wrote: > On Fri, 2005-04-15 at 13:57 -0300, Aurelio Marinho Jargas wrote: > > what you could use are *filters* like preproc and postproc > > which are applyed to verbatim areas as well. and example: > > > > %!postproc: (keyword) <font color="green">\1</font> > > > > but that will be a boring task, and some common text can > > be expanded as if it was haskell code. > > Oh, ok. I didn't make the distinction between filter and macros. In > fact, the filter are probably sufficient for our purposes. While syntax > highlighting is nice, what we are really after is to automatically > hyperlink all the library functions in the example to the corresponding > html documentation. Hence I though we would just generate filters for > the 3000+ functions and include those. We could then live with a manual > set of syntax-highlighting filters. [snip] > That's nice as well, but we couldn't combine that with hyperlinking the > library functions. I think we are looking at code fragments rather than > at complete programs, so we can probably live without complete syntax > highlighting. Here's a system for doing the hyperlinking. Since filters are not applied to verbatum sections we have to apply them to the final output instead which means doing it differently depending on wether we're producing tex or (x)html. If figured that instead of producing lots of filer directives it'd be simpler just to post-process the stuff directly. So, I wrote a little Haskell program... :-) Honnestly, it's very little (170 lines) and does tex,html and xhtml. It hyperlinks all the used symbols from gtk/Graphics/UI/Gtk.hi to the appropriate Haddock html file (with a configurable base URL). It doesn't do syntax highligting. See the attached files for details. Save them to gtk2hs/docs/tutorial or somewhere (if you put it somewhare else adjust the 'top' var in the Makefile) and run $ make to build the HelloWorld example. Duncan |
From: Duncan C. <dun...@wo...> - 2005-04-19 00:24:38
Attachments:
Makefile
|
On Mon, 2005-04-18 at 22:32 +0100, Duncan Coutts wrote: > See the attached files for details. Save them to gtk2hs/docs/tutorial or > somewhere (if you put it somewhare else adjust the 'top' var in the > Makefile) and run > $ make > to build the HelloWorld example. Attached is an updated Makefile that works with ghc 6.4 and builds the right files by default. Duncan |
From: Duncan C. <dun...@wo...> - 2005-04-19 01:09:40
|
On Mon, 2005-04-18 at 22:32 +0100, Duncan Coutts wrote: > See the attached files for details. Save them to gtk2hs/docs/tutorial or > somewhere (if you put it somewhare else adjust the 'top' var in the > Makefile) and run > $ make > to build the HelloWorld example. And this is what it looks like using our web style sheet: http://atmarama.org/gtk2hs/archives/2005/04/18/more-txt2tags-testing/ We'll want to tweak the CSS for the code section since the font and line spacing are not quite right for code. Also we'll have to be careful not to use code examples with lines longer than about 75ish columns. It looks like there is a WP bug that messes up href links inside <pre> elements. That may have been fixed in 1.5 final (the atmarama site is running a 1.5 pre-release). If that's still the case in 1.5 final we can work around it by using <div class="haskellcode"> and then setting the appropriate style via CSS. Duncan |
From: Axel S. <A....@ke...> - 2005-04-19 07:36:59
|
On Mon, 2005-04-18 at 22:32 +0100, Duncan Coutts wrote: > On Sun, 2005-04-17 at 10:02 +0100, Axel Simon wrote: > > On Fri, 2005-04-15 at 13:57 -0300, Aurelio Marinho Jargas wrote: > > > > what you could use are *filters* like preproc and postproc > > > which are applyed to verbatim areas as well. and example: > > > > > > %!postproc: (keyword) <font color="green">\1</font> > > > > > > but that will be a boring task, and some common text can > > > be expanded as if it was haskell code. > > > > Oh, ok. I didn't make the distinction between filter and macros. In > > fact, the filter are probably sufficient for our purposes. While syntax > > highlighting is nice, what we are really after is to automatically > > hyperlink all the library functions in the example to the corresponding > > html documentation. Hence I though we would just generate filters for > > the 3000+ functions and include those. We could then live with a manual > > set of syntax-highlighting filters. > > [snip] > > That's nice as well, but we couldn't combine that with hyperlinking the > > library functions. I think we are looking at code fragments rather than > > at complete programs, so we can probably live without complete syntax > > highlighting. > > Here's a system for doing the hyperlinking. Since filters are not > applied to verbatum sections we have to apply them to the final output > instead which means doing it differently depending on wether we're > producing tex or (x)html. That was actually why I wrote to the list. The post-processor hooks of t2t *are* applied to verbatim and monospace sections. But now that you've done it, I guess we'll stick to it. I'll try your approach later. Axel. |
From: Duncan C. <dun...@wo...> - 2005-04-19 11:12:24
|
On Tue, 2005-04-19 at 08:36 +0100, Axel Simon wrote: > That was actually why I wrote to the list. The post-processor hooks of > t2t *are* applied to verbatim and monospace sections. But that still isn't of much help since the post-processor applies to the latex/html/xhtml output so is more difficult anyway. And with the post-processor hooks there's no way to only link or highlight within code sections. I figured it was easier to write a program to do ths stuff directly rather than write a program to generate the appropriate txt2tags filter/hook directives. It's not quite as simple as just replacing "buttonNew" with "\href{http://...}{buttonNew}" since the latter is still interpreted literally within a \begin{verbatim} \end{verbatim} environment. What would have been easier would be to modify the input because then it'd would work for all output formats but since tags are not interpereted in verbatum sections that doesn't work. Duncan |
From: Duncan C. <dun...@wo...> - 2005-04-22 20:56:24
|
On Tue, 2005-04-19 at 08:36 +0100, Axel Simon wrote: > > Here's a system for doing the hyperlinking. Since filters are not > > applied to verbatum sections we have to apply them to the final output > > instead which means doing it differently depending on wether we're > > producing tex or (x)html. > > That was actually why I wrote to the list. The post-processor hooks of > t2t *are* applied to verbatim and monospace sections. But now that > you've done it, I guess we'll stick to it. > > I'll try your approach later. I've got an updated post-processor. It now does propper syntax highligting for XHTML (configurable via CSS) based on code from Malcolm Wallace's hscolour program (which is GPL making the utility GPL too, but that is fine I guess). If we figure out the right latex commands it'd be easy to add the same to the latex output. Should I add this stuff then? docs/tools ? or straight into docs/tutorial ? Duncan |
From: Axel S. <A....@ke...> - 2005-04-23 13:13:44
|
On Fri, 2005-04-22 at 21:46 +0100, Duncan Coutts wrote: > > > That was actually why I wrote to the list. The post-processor hooks > of > > t2t *are* applied to verbatim and monospace sections. But now that > > you've done it, I guess we'll stick to it. > > > > I'll try your approach later. > > I've got an updated post-processor. It now does propper syntax > highligting for XHTML (configurable via CSS) based on code from > Malcolm > Wallace's hscolour program (which is GPL making the utility GPL too, > but > that is fine I guess). If we figure out the right latex commands it'd > be > easy to add the same to the latex output. > > Should I add this stuff then? Yes, go ahead. > docs/tools ? or straight into docs/tutorial ? So I assume docs is a new top-level directory in CVS with all the automake cruft? Axel. |
From: Duncan C. <dun...@wo...> - 2005-04-23 18:34:44
|
On Sat, 2005-04-23 at 14:12 +0100, Axel Simon wrote: > On Fri, 2005-04-22 at 21:46 +0100, Duncan Coutts wrote: > > > > > That was actually why I wrote to the list. The post-processor hooks > > of > > > t2t *are* applied to verbatim and monospace sections. But now that > > > you've done it, I guess we'll stick to it. > > > > > > I'll try your approach later. > > > > I've got an updated post-processor. It now does propper syntax > > highligting for XHTML (configurable via CSS) based on code from > > Malcolm > > Wallace's hscolour program (which is GPL making the utility GPL too, > > but > > that is fine I guess). If we figure out the right latex commands it'd > > be > > easy to add the same to the latex output. > > > > Should I add this stuff then? > > Yes, go ahead. Ok. > > docs/tools ? or straight into docs/tutorial ? > > So I assume docs is a new top-level directory in CVS with all the > automake cruft? So yes, we'll add a top level directory "docs" and change things sot that the haddock docs get built into docs/reference. Then we add docs/tutorial to cvs which is where the .t2t files will live. We will not add anything to the top level Makefile.am to have these built since we do not expect to include them in a distribuion and have people build them on their own machines. The doc sources will be in cvs only. We will build them ourselves and make them available as a download and for online viewing on our website (as WP posts hopefully with links to screenshots in our gallery). So we'll add a makefile to the docs/tutorial directory that just deals with building the tutorial docs. So then the only question is which dir to stick the post-processing tool sources. Are we likely to have any other dirs under docs, or will all this txt2tags stuff live under docs/tutorial ? Duncan |
From: Axel S. <A....@ke...> - 2005-04-24 12:29:15
|
On Sat, 2005-04-23 at 19:35 +0100, Duncan Coutts wrote: > > So I assume docs is a new top-level directory in CVS with all the > > automake cruft? > > So yes, we'll add a top level directory "docs" and change things sot > that the haddock docs get built into docs/reference. So that means then the normal gtk2hs tree does not contain any documentation or makefile support to build the documentation, right? > Then we add docs/tutorial to cvs which is where the .t2t files will > live. We will not add anything to the top level Makefile.am to have > these built since we do not expect to include them in a distribuion and > have people build them on their own machines. The doc sources will be in > cvs only. We will build them ourselves and make them available as a > download and for online viewing on our website (as WP posts hopefully > with links to screenshots in our gallery). So we'll add a makefile to > the docs/tutorial directory that just deals with building the tutorial > docs. > > So then the only question is which dir to stick the post-processing tool > sources. Are we likely to have any other dirs under docs, or will all > this txt2tags stuff live under docs/tutorial ? If you put it in docs/tools then we're safe in case something else needs documenting. Axel. |
From: Duncan C. <dun...@wo...> - 2005-04-24 17:07:31
|
On Sun, 2005-04-24 at 13:28 +0100, Axel Simon wrote: > On Sat, 2005-04-23 at 19:35 +0100, Duncan Coutts wrote: > > > > So I assume docs is a new top-level directory in CVS with all the > > > automake cruft? > > > > So yes, we'll add a top level directory "docs" and change things sot > > that the haddock docs get built into docs/reference. > > So that means then the normal gtk2hs tree does not contain any > documentation or makefile support to build the documentation, right? Yes. Except for the haddock reference docs which will continue to be (optionally) built as part of the normal ./configure --enable-docs; make; make install. > > So then the only question is which dir to stick the post-processing tool > > sources. Are we likely to have any other dirs under docs, or will all > > this txt2tags stuff live under docs/tutorial ? > > If you put it in docs/tools then we're safe in case something else needs > documenting. Yep, ok. Duncan |
From: Aurelio M. J. <aur...@ya...> - 2005-04-25 13:18:52
|
hi axel, --- Axel Simon <A....@ke...> wrote: > > While syntax highlighting is nice, what we are really after > is to automatically hyperlink all the library functions in > the example to the corresponding html documentation. Hence > I though we would just generate filters for the 3000+ > functions and include those. We could then live with a > manual set of syntax-highlighting filters. using a centralized configuration file and %!includeconf you can apply these 3000+ filters to all converted files. but i'm sure that using smart regular expressions on these filters, you can decrease dramatically this number. i know nothing about haskell, but supposing you have a group of functions whose name start with "str_" and their HTML documentation is on /doc/lib/string/<func-name>.html, you can do a catch-all filter for all of them: (the mailer will break, but it is a oneliner) %!postproc: '(str_[a-z]+)' '<a href="/doc/lib/string/\1.html">\1</a> ' if all the functions documentation reside on the same dir, then a single (complicated) regex can take care of all of them. feel free to ask if some help is needed. bye! -- Aurelio Marinho Jargas, Curitiba, Conectiva http://aurelio.net Yahoo! Acesso Grátis - Internet rápida e grátis. Instale o discador agora! http://br.acesso.yahoo.com/ |