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

[Ian Jackson <ian.jackson@xxxxxxxxxxxxx>]

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@xxxxxxxxxxxxx
https://lists.xen.org/xen-devel