[Texmacs-dev] Re: "hello world" for converter plugin wanted

[Joris van der Hoeven]

> currently I struggle with writing a converter as plugin.
> Unfortunately I can't find an example from where I could
> learn all steps. I know that there are these examples of plugins
> in "example/plugins", but none of them are converters

Ha, it would be nice if you could add such a minimal example,
when you will understand how things work ;^)

> (btw. the "world" plugin does not work in texmacs 1.4.1,
> as "insert-string" is an unbound variable).

Thanks for noticing this to me; I just corrected this.
Please report any other bugs like this in the documentation.

> On the other hand I can find converters in "progs/convert",
> but these  are not plugins.
>
> So in my opinion a kind of hello world converter as plugin
> would be a nice thing! Let me try this with your help:
>
> Assume we have:
> ls $TEXMACS_HOME_PATH/plugins/my-converter/prog
> init-my-converter.scm
> my-converter.scm
>
> And the content of init-my-converter.cm would be:

---------------------------------------

(define-format xyz
  (:name "Xyz")
  (:suffix "xyz")
  (:recognize xyz-recognizes?))

(converter xyz-document xyz-stree
  (:function parse-xyz-document))

(converter xyz-stree xyz-document
  (:function serialize-xyz))

(converter xyz-snippet xyz-stree
  (:function parse-xyz-snippet))

(converter xyz-stree xyz-snippet
  (:function serialize-xyz))

(converter xyz-stree texmacs-stree
  (:function xyz->texmacs))

(converter texmacs-stree xyz-stree
  (:function texmacs->xyz))

---------------------------------------

> And all the functions referred by ":function" would be defined in
> my-converter.scm.
>
> Appearently this is not sufficient to make the converter
> accessable in TeXmacs!

You also need a line to make init-my-converter.scm aware
where to find your routines xyw-recognizes?, etc.
This can be done in two ways: by simply loading
the file my-converter.scm using

        (use-modules (my-converter))

However, this is not the best method, because you typically
want to load the module only if you actually need one of
your routines. A better way is therefore to use statements like

        (lazy-define (my-converter) xyz-recognizes?)
        ....

You also need to put the lines

        (texmacs-module (my-converter)
          (:export xyz-recognizes? ...)

at the top of your file my-converter.scm.

> What is missing such that I can use my converter as user in TeXmacs
> like for instance the html converter? More precisely: I want to be able
> to import/export files via the "File/Import/Xyz" and "File/Export/Xyz"
> menu. And I want to be able to copy and paste via "Edit/Copy to/Xyz"
> and "Edit/Paste from/Xyz". How is this done?

This should be automatic, when TeXmacs will able to find your routines.

> Further: If I want to use inside of my-converter.scm a function foo
> which resides in a file my-helpers.scm (in the dir of my-converter.scm),
> how do I make this foo accessable in my-converter? To put this question
> more general: There is this "texmacs-module" macro and also an
> "import-from" and I don't know exactly how to use that (and I could not
> find help docs).

See above ^^^.

The use-modules primitive is only for use from the top-level
init-my-plugin.scm file. When you recursively need modules
inside modules, you should rather use the (:use ...) or
(:inherit ...) directives inside your texmacs-module header.
See the standard Scheme modules with come with TeXmacs
for examples.

Yours, Joris