Libguestfs - Aug 2019 - Re: [PATCH 1/2] Rust bindings: Add long description

> 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@redhat.com>:
> On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki wrote:
> >
> > > 2019/08/13 1:01、Pino Toscano <ptoscano@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

On Tuesday, 13 August 2019 15:02:10 CEST Hiroyuki Katsura
wrote:
> > 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
Oh no need to convert everything :-) The bits that matter at the moment
are the "longdesc" of APIs, writing them to guestfs.rs just like you
did with pod2text.

-- 
Pino Toscano

> Oh no need to convert everything :-) The bits that matter at the moment
> are the "longdesc" of APIs, writing them to guestfs.rs just like
you
> did with pod2text.
Ah, Yes I knew it. I just tested pod2markdown by the existing pod files.

Regards,
Hiroyuki

2019年8月13日(火) 22:12 Pino Toscano <ptoscano@redhat.com>:
> On Tuesday, 13 August 2019 15:02:10 CEST Hiroyuki Katsura wrote:
> > > 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
>
> Oh no need to convert everything :-) The bits that matter at the moment
> are the "longdesc" of APIs, writing them to guestfs.rs just like
you
> did with pod2text.
>
> --
> Pino Toscano