Re: [Xen-devel] [PATCH 0/6] docs: convert manpages to pod

[Ian Jackson]

Olaf Hering writes ("Re: [PATCH 0/6] docs: convert manpages to pod"):
> On Mon, Jul 24, Ian Jackson wrote:
> > * There are a lot of other documents in docs/misc/ which are in
> > markdown format.  Some of them are internal.  I'm pretty sure we don't
> > want them _all_ converted.  So even if you convert the manpages, these
> > documents will remain.
> 
> I did not intent to change other files outside of docs/man/.
> Just the references to non-existant manpages triggered this series.

I see.

> Sometimes I wish that xen-command-line.5 exists, but google always
> helped in such occasions.

Do your packages not contain the text files, as text, in
/usr/share/doc ?  If not you could add them and I'm sure users would
appreciate it.

> > * It may be that there are other markdown processors which could be
> > substituted for pandoc - either at runtime or by changing the Xen
> > Project's default, upstream.
> 
> After a quick research there is a ruby "ronn" and go/ruby "md2man". Both
> would have the same dependency issue. Perhaps ruby is less troublesome
> because YaST is written in ruby.

An alternative would be to convert the md to html.

> > * I don't understand why promoting GHC would be a problem.  But, in
> > the worst case, rather than demoting Xen, you could simply not ship
> > certain docs (although - see above about plain text).
> 
> The package ghc is in the tree since nearly 5 years, pandoc since 3
> years. The hurdle is likely that a 4GB DVD is filled quickly. It is
> always a fight to get everyone happy, and ghc is seen as leaf package.

GHC is a compiler, not a leaf package.  Also, I have to say that
nowadays asking for everything to fit on a DVD seems odd.

Ian.

___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [Xen-devel] [PATCH 0/6] docs: convert manpages to pod

[Olaf Hering]

On Mon, Jul 24, Ian Jackson wrote:

> * There are a lot of other documents in docs/misc/ which are in
> markdown format.  Some of them are internal.  I'm pretty sure we don't
> want them _all_ converted.  So even if you convert the manpages, these
> documents will remain.

I did not intent to change other files outside of docs/man/.
Just the references to non-existant manpages triggered this series.

Sometimes I wish that xen-command-line.5 exists, but google always
helped in such occasions.

> * It may be that there are other markdown processors which could be
> substituted for pandoc - either at runtime or by changing the Xen
> Project's default, upstream.

After a quick research there is a ruby "ronn" and go/ruby "md2man". Both
would have the same dependency issue. Perhaps ruby is less troublesome
because YaST is written in ruby.

> * Our markdown documents are, I think, intended to be plain text which
> can be simply shipped as-is.  So for things other than manpages you
> can probably just ship them as if they were text files.  If the end
> user wants to read them in a fancy format (eg HTML) they could install
> the relevant processor.

Yes. I have to see what HTML we ship. So far it did not cause trouble.

> * I don't understand why promoting GHC would be a problem.  But, in
> the worst case, rather than demoting Xen, you could simply not ship
> certain docs (although - see above about plain text).

The package ghc is in the tree since nearly 5 years, pandoc since 3
years. The hurdle is likely that a 4GB DVD is filled quickly. It is
always a fight to get everyone happy, and ghc is seen as leaf package.


Olaf


signature.asc
Description: PGP signature
___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [Xen-devel] [PATCH 0/6] docs: convert manpages to pod

[Ian Jackson]

Olaf Hering writes ("Re: [PATCH 0/6] docs: convert manpages to pod"):
> On Mon, Jul 24, Ian Jackson wrote:
> > Olaf Hering writes ("[PATCH 0/6] docs: convert manpages to pod"):
> > > To remove the buildtime dependency to pandoc/ghc some manpages are
> > > converted from markdown to pod format. This will provide more manpages
> > > which are referenced in xl(1) and xl.cfg(5).
> > 
> > Sorry to ask this at this stage, but: did I miss some discussion of
> > why this was desirable ?
> 
> Likely yes: https://build.opensuse.org/request/show/511948
> The point is: if all manpages need to be build then Xen needs to depend
> on pandoc, which in turn depends on ghc. Neither of them is seen as a
> "core" package, while "Xen" is a core package. Either ghc becomes a core
> package, or Xen is moved out of core. In this context "core" means it is
> part of a install DVD, if I understand the concept of "rings" correctly.

I see.  That upstream packages might contain documentation in exciting
formats, and that documentation compilers can have big dependency
chains, are not new.  If I infer correctly from that bug report, the
approach taken by OpenSUSE seems quite ... prone to trouble.

Having said that:

> Do you see any downside of this series? There is currently a mix of pod
> and markdown format for the manpages. This change gets it closer to have
> them all as pod.

I think pod is a fine format for documentation (probably better than
md for manpages) and there is a definite advantage to using the same
format for all the manpages.

So I don't object to this series in principle.  However:

* If you want to do this, please make each patch convert one manpage,
by deleting the old file and creating the new one, and adjusting the
build.  So there should be 3 patches (plus possible pre- or
post-patches for prep or cleanup).

* There are a lot of other documents in docs/misc/ which are in
markdown format.  Some of them are internal.  I'm pretty sure we don't
want them _all_ converted.  So even if you convert the manpages, these
documents will remain.

* It may be that there are other markdown processors which could be
substituted for pandoc - either at runtime or by changing the Xen
Project's default, upstream.

* Our markdown documents are, I think, intended to be plain text which
can be simply shipped as-is.  So for things other than manpages you
can probably just ship them as if they were text files.  If the end
user wants to read them in a fancy format (eg HTML) they could install
the relevant processor.

* The OpenSUSE project should perhaps revisit the question of
documentation generator dependencies.  Debian has a different
categorisation of packages, but has faced the problem of documentation
generators in the context of bootstrapping, and has (more or less)
found a way round it.

* I don't understand why promoting GHC would be a problem.  But, in
the worst case, rather than demoting Xen, you could simply not ship
certain docs (although - see above about plain text).

I hope that makes sense.

Thanks,
Ian.

___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [Xen-devel] [PATCH 0/6] docs: convert manpages to pod

[Olaf Hering]

On Mon, Jul 24, Ian Jackson wrote:

> Olaf Hering writes ("[PATCH 0/6] docs: convert manpages to pod"):
> > To remove the buildtime dependency to pandoc/ghc some manpages are
> > converted from markdown to pod format. This will provide more manpages
> > which are referenced in xl(1) and xl.cfg(5).
> 
> Sorry to ask this at this stage, but: did I miss some discussion of
> why this was desirable ?

Likely yes: https://build.opensuse.org/request/show/511948
The point is: if all manpages need to be build then Xen needs to depend
on pandoc, which in turn depends on ghc. Neither of them is seen as a
"core" package, while "Xen" is a core package. Either ghc becomes a core
package, or Xen is moved out of core. In this context "core" means it is
part of a install DVD, if I understand the concept of "rings" correctly.


Do you see any downside of this series? There is currently a mix of pod
and markdown format for the manpages. This change gets it closer to have
them all as pod.


Olaf


signature.asc
Description: PGP signature
___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

Re: [Xen-devel] [PATCH 0/6] docs: convert manpages to pod

[Ian Jackson]

Olaf Hering writes ("[PATCH 0/6] docs: convert manpages to pod"):
> To remove the buildtime dependency to pandoc/ghc some manpages are
> converted from markdown to pod format. This will provide more manpages
> which are referenced in xl(1) and xl.cfg(5).

Sorry to ask this at this stage, but: did I miss some discussion of
why this was desirable ?

Ian.

___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel

[Xen-devel] [PATCH 0/6] docs: convert manpages to pod

[Olaf Hering]

To remove the buildtime dependency to pandoc/ghc some manpages are
converted from markdown to pod format. This will provide more manpages
which are referenced in xl(1) and xl.cfg(5).

This series does not cover xen-vbd-interface.7 because converting the
lists used in this manpage was not straight forward.

Olaf

Cc: Ian Jackson 
Cc: Wei Liu 
To: xen-devel@lists.xen.org

Olaf Hering (6):
  docs: add pod variant of xen-pv-channel.7
  docs: add pod variant of xl-network-configuration.5
  docs: add pod variant of xl-numa-placement
  docs: remove markdown variant of xen-pv-channel.7
  docs: remove markdown variant of xl-network-configuration.5
  docs: remove markdown variant of xl-numa-placement.7

 docs/man/xen-pv-channel.markdown.7 | 106 ---
 docs/man/xen-pv-channel.pod.7  | 189 
 ...n.markdown.5 => xl-network-configuration.pod.5} | 195 ++---
 ...lacement.markdown.7 => xl-numa-placement.pod.7} | 164 +++--
 4 files changed, 433 insertions(+), 221 deletions(-)
 delete mode 100644 docs/man/xen-pv-channel.markdown.7
 create mode 100644 docs/man/xen-pv-channel.pod.7
 rename docs/man/{xl-network-configuration.markdown.5 => 
xl-network-configuration.pod.5} (55%)
 rename docs/man/{xl-numa-placement.markdown.7 => xl-numa-placement.pod.7} (74%)


___
Xen-devel mailing list
Xen-devel@lists.xen.org
https://lists.xen.org/xen-devel