Re: [Libguestfs] [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(a)redhat.com>:
> On Tuesday, 13 August 2019 05:17:10 CEST Katsura Hiroyuki wrote:
> >
> > > 2019/08/13 1:01、Pino Toscano <ptoscano(a)redhat.xn--com>-1e4f10b4csi:
> > >
> > > 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
Attachments:
- attachment.html (text/html — 4.2 KB)