Hi, Background: ----------- I've been working on a manual for GNU Boot to lower the amount of technical expertise needed to use GNU Boot and me and neox ended up with a dilemma about an important technical aspect of the manual itself.
I used texinfo to do the manual as it's relatively standard and easy to
convert it to various format while also remaining relatively easy to
contribute (it's probably somewhere between LaTex and markdown). Also
note that I'm completely new to texinfo.
One of the issue we have is that we would like to have help with the
documentation, and working on some areas of the the documentation is not
very risky (it would be hard to break your computer while doing that)
and it doesn't require a very technical technical expertise either.
So we are trying to make it as easy as possible for people to work on
it.
Beside being able to build the documentation (which can be improved a
bit on our side) another main limiting factor is the documentation
format which is what this mail is about.
The precise problem we have:
----------------------------
What we have below is very intuitive for someone not familiar with
texinfo at all:
> In some cases GNU Boot even runs nonfree software not provided by GNU
> Boot like nonfree GPUs drivers provided by the removable GPU card.
> See @ref{Supported computer parts and peripherals} for more details
> about this issue and how to avoid running such nonfree software.
But if we follow the texinfo manual, as I understand it we're supposed
to do that instead:
> In some cases GNU Boot even runs nonfree software not provided by GNU
> Boot like nonfree GPUs drivers provided by the removable GPU card.
> @xref{Supported computer parts and peripherals} for more details
> about this issue and how to avoid running such nonfree software.
Then this requires contributors to lookup what xref is just to
contribute some small modification to the manual.
So we end up with a dilemma here as I assume that xref do exist for a
good reason and that we're supposed to use it in cases like the one
above. Since we're looking for contributors it also raises the question
of people used to know texinfo as using ref instead might look awkward
to them.
Are there project that avoided things like xref/pxref in favor of ref?
Did that create issues (with translations to other formats or languages
for instance)?
Are there ways to have things that are compatible with both the manual
and people completely new to texinfo?
What would you advise us to do?
Denis.
pgpQ_vg_IGZX3.pgp
Description: OpenPGP digital signature
