[Libguestfs] [PATCH 1/2] Rust bindings: Add long description

[Hiroyuki Katsura]

> Can you explain which errors did you get? I tried pod2markdown on a
> couple of API longdesc's, and the result seemed OK.
> Most probably we will need to write our own pod2markdown though, as
> pod2markdown does not allow users to customize all the options that
> the Pod::Markdown module has.

Yes. Most of the results seemed OK. But, for example, translating
'docs/guestfs-internals.pod' dumps the following errors at the end of the
output file

```
# POD ERRORS

Hey! **The above document had some coding errors, which are explained
below:**

- Around line 17:

    Non-ASCII character seen before =encoding in '┌───────────────────┐'.
Assuming UTF-8
```

I do not know whether there are such non-ascii characters in API longdescs,
and I have no idea to find
such characters easily. So, I am not able to say whether pod2markdown is
usable or not for now...


> IMHO it is better to produce the code directly following
> the style conventions.

OK. I'll send the formatting patch.

Regards,
Hiroyuki


2019年8月13日(火) 19:44 Pino Toscano <ptoscano at redhat.com>:

> On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki wrote:
> >
> > > 2019/08/13 1:01、Pino Toscano <ptoscano at redhat.com>のメール:
> > >
> > > On Sunday, 11 August 2019 06:42:21 CEST Hiroyuki Katsura wrote:
> > >> `cargo doc` will generate docs with long descriptions.
> > >
> > > This is a nice start, although most probably it will not look that good
> > > though (since the plain text output may be misrendered as markdown).
> > >
> > > I remember we talked about converting the POD texts to markdown, and
> > > that there seems to be something we can use:
> > > https://metacpan.org/release/Pod-Markdown <
> https://metacpan.org/release/Pod-Markdown>
> > > Did you try to use it?  What were the results?
> >
> > Yes. As I mentioned before, it looked pretty good except for some
> encode-errors.
> > However, at first, I just translate pod to text by the exisiting
> function because using
> > pod2markdown looks a little tricky.
>
> Can you explain which errors did you get? I tried pod2markdown on a
> couple of API longdesc's, and the result seemed OK.
> Most probably we will need to write our own pod2markdown though, as
> pod2markdown does not allow users to customize all the options that
> the Pod::Markdown module has.
>
> > Question:
> > There are some places where the length of the line in the generated code
> > is over 100 characters. Of course, I can try to make the length of each
> line under 100
> > characters. However, there is a nice tool: ‘rustfmt.’ I want to use this
> as a ‘post-process’
> > of generating bindings. Is it OK?(I should have ask you when I sent the
> first patch)
>
> Considering we are generating most of the rust code using the
> generator, IMHO it is better to produce the code directly following
> the style conventions. I just checked the difference between our
> currently generated guestfs.rs and the "formatted" version of it, and
> fixing guestfs.rs does not seem too difficult. It can be done in steps,
> of course, no need to rush everything in a single fix.
>
> --
> Pino Toscano
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://listman.redhat.com/archives/libguestfs/attachments/20190813/5190f3d6/attachment.htm>