[syslinux] isohybrid has 2 variants

[Ady]

> On Tue, Jun 24, 2014 at 4:18 PM, Ady <ady-sf at hotmail.com> wrote:
> 
> >
> > > > > When
> > > > > information is too-technical, or the wording sounds too-technical,
> > > > > most users won't even read it.
> > >
> > > Although a "list lurker", I'd like to make a brief comment (stating the
> > > obvious).
> > >
> > > Documentation will have different audiences, ranging from [sometimes
> > > not-clueful] end-users to people trying to make distros bootable under
> > > different conditions, to those who may want to learn enough background to
> > > contribute to the project in some way.
> > >
> > > Each will complain differently when they use the Wiki, not only because
> > the
> > > information they're looking for is different, but because the background
> > > each brings with them is different.
> > >
> > > I believe that reorganization of the documentation keeping this in mind
> > > would be the "best" solution, rather than debating what to leave in or
> > cut
> > > out.  There have been multiple times I've been interested in a piece of
> > > software and wanted to find out its history so I could orient myself, and
> > > some "helpful" soul had decided that all the old stuff was unnecessary
> > and
> > > deleted it.  Conversations with long-time developers (when I could find
> > > any) were required to learn things.  It wastes time and is painful for
> > > everyone.
> > >
> > > (No, I'm not volunteering -- I knew you were gonna ask.  I don't know
> > > enough to be able to make good decisions, someone would have to review
> > and
> > > clean up after me.)
> > >
> > > Please don't delete "old" or "useless" stuff.  It *will* be useful to
> > > *someone*.
> > >
> > > Also, If I'm trying to learn more about booting, it makes sense to dig
> > into
> > > this project.  If you delete technical information that I need to know,
> > > could I Google for it?  Sure -- but it would be a lot easier if the
> > > information were already here.  It's a fine line between deciding what
> > > information should be included in the docs here and what should be
> > searched
> > > for.  But remember that searching isn't free in cost of the user's time.
> > >  If you delete information, at least insert a link to the information
> > > elsewhere on the web (even knowing the link might go stale or missing).
> > >
> > > As far as marking software frozen, I would suggest that "frozen" is a
> > value
> > > judgement:  if I want to work on it, then it's not frozen anymore, right?
> > >  If it's felt that it's deprecated or superseded for some reason, the
> > > software should be annotated as such, together with the reason(s) why and
> > > what would be required to make it up-to-date (if possible).  If I'm then
> > > attracted to use it or (God forbid!) work on it :-), then I would know
> > what
> > > I'm getting into and be able to intelligently decide if it's worth it and
> > > how I might be hurt in the process.
> > >
> > > Sorry to interrupt your conversation.  "Now back to our regularly
> > scheduled
> > > programming".  Thanks for reading.
> >
> > Unfortunately, there is no way to write "for everyone". If the text
> > is too-technical, common users won't read it, much less understand
> > it. If it is "too-superficial", experienced readers won't read it and
> > it would be almost useless for common users too.
> >
> > To be able to collaborate with writing helpful documentation, a
> > potential writer would need to understand at least a little more than
> > the common "incidental or "sporadic" user.
> >
> > To be able to collaborate with code, being capable of reading code is
> > not optional. If someone wants to look a little back in history,
> > looking at the git logs/diffs/commits is one possibility.
> >
> > So the wiki can't "contain everything", or use a "keep all info in,
> > include all, don't delete any detail" style. This is not exclusive to
> > the Syslinux wiki.
> >
> > Copying information that is available elsewhere is also not a good
> > idea. When one site updates its content, users reading both texts
> > can't decide which one is accurate. For these cases, linking to
> > several alternative sources is more appropriate.
> >
> > Just as example... If someone has problems with some tool that uses
> > Syslinux for building a USB bootable drive using FAT, he should ask
> > that tool's developers, or maintainers, or in the respective distro's
> > forum, before asking in #syslinux, or in this Syslinux Mailing List.
> > It shouldn't be expected for the Syslinux wiki to solve all the
> > issues for "something not booting". And yet, it is rare to see here
> > (or in #syslinux) someone receiving no answer at all.
> >
> > Certainly more development-time/brains/fingers are needed, specially
> > considering the expectations users frequently have about Syslinux.
> >
> > Regarding users that need to invest more time searching, "waa waa
> > booo..." :D. Someone has to invest time to write code, someone has to
> > invest time writing documentation, someone has to invest time
> > testing... I wish the Syslinux Mailing List content would be indexed
> > by respectable popular web search engines as it used to be (before
> > 2012-Oct), but other than that... Users can type some words too; they
> > will find the information.
> >
> > Let's move on to more practical matters.
> >
> > Regards,
> > Ady.
> >

> Ady --
> 
> Frankly, I was hoping for a somewhat less judgmental response, 
perhaps even
> a conversation.
> 
> My interest is in expanding the usefulness of the the documentation 
to
> various audiences.  I have noticed over a long period that there 
have been
> many questions to the list which presumably could have been avoided 
by
> having appropriate documentation. Many answers have been of the 
form "well
> the Wiki is incomplete and/or hasn't been updated and/or 
information is in
> the wrong place, and so you need to know (xyz)".
> 
> Since you don't know what work I've done, I'd like to let you know 
that
> your apparent assumption (based on your lecture) that I've not 
written
> code, haven't written documentation, and do not understand the 
trade-offs
> of information inclusion vs. linking vs. searching is presumptive, 
and,
> incidentally, false.
> 
> Please note that I DO consider the quality of documentation "a 
practical
> matter", that's why I posted.  If it is not, then why not just 
delete the
> Wiki and save time maintaining it?  Let the users read the code -- 
after
> all, it *is* the authoritative source!
> 
> Unlike you, I'm a lurker here, not a contributor, so I will be 
silent from
> now on.
> 
> 
> 
 
Hi Dave,

There is a chance I am misusing the English language.

I also consider documentation (and its discussion) a practical 
matter. We have been doing it for the last couple of days, and this 
is not the first time and not the only place.

When I said "let's move on to more practical matters", I don't mean 
to disregard / discard additional opinions.

If we were discussing some "one-time hard copy edition", we would 
need much more detailed discussion.

Different points of view have been expressed, and considering that 
the documentation we talk about is a wiki, we can improve it on time. 
So by "practical" I mean that Thomas could/should go ahead, and 
perhaps later comments and questions from users / readers would let 
us know how to improve it.

We can keep discussing, but if the page is not started then 
effectively we do "nothing". I mean "nothing" in terms of users.

As I said before in a prior email, my opinion has the same value as 
anyone's, so I don't understand why my prior email sounds judgmental. 
Again, perhaps I am misusing (or misunderstanding) the English (which 
is not my natural) language.

I still think that it is very difficult to write "for everyone", and 
sometimes writing (too many) technical details is not helpful for 
users. Let me give an example.

There is one ("error") message that has been asked about many 
(really, many) times, "not a COM32R image". Almost every 
Linux-related forum, mailing list... have seen this question. Common 
users by now could search the question and find its solution. And 
yet, they keep asking again.

The matter is documented in the wiki too. The solution (in succinct 
words): all files related to Syslinux shall match the same version.

Typically, the problem shows up with USB drives that were created by 
one tool for one distro, and now the user tries to use it for another 
distro that comes a different version of Syslinux. Some users end in 
"Syslinux doesn't work for me".

Now, some (somewhat rhetorical) questions (and I am writing this with 
respect and not with any "tone"). How much technical details should 
we provide in the wiki?

Should we just explain that all c32 files and the boot loader shall 
come from the same exact version of Syslinux?

Or perhaps we should list every single tool and method with its 
corresponding current Syslinux version and update the list with every 
change / update? In such case, should we also add a "howto" for these 
tools?

Or maybe we should explain that there are COMBOOT-16, COM32, COM32R, 
ELF formats, depending on the version of Syslinux and that they are 
incompatible between each other?

Perhaps we should evaluate which versions of certain c32 files "just 
happen" to be usable with other versions of the boot loader?

Should we get into the inner details about COMBOOT-16... ELF, so the 
user that just wants to be able to boot his USB drive with the new 
version of some Live distro can achieve his goal?

I think that all this information could be useful for some group of 
readers, but I also think that posting all this information together 
in one single wiki page would be a mistake.

Certainly the common user won't be interested in reading about the 
ELF format - after all, he just wants to try this new Live distro. 
Meanwhile, those with the ability and interest to understand the 
different formats of the Syslinux modules would be bored with at 
least part of the information that targets common users.

BTW, at least parts of the different matters I just mentioned happen 
to be in (individual, separated) pages or somewhere in the Syslinux 
docs.

Asking ourselves the question "who is the target reader for this 
particular 
information / wiki page" is relevant.

The documentation of The Syslinux Project is not as up-to-date as we 
all would 
want it to be, and (not all but) some of the comments about "this X 
mater 
should be updated in the wiki" are justified. Yet, someone has to 
dedicate time 
to actually write it, and in such a manner that would be effective 
for common 
users.

Now, if there is something specific that the new isohybrid page 
should include, 
or that it shouldn't, please speak up so we can all effectively 
improve it.

In fact, if there is anything about Syslinux anyone wants to 
contribute with / 
report / suggest..., please, please speak up.

Best Regards,
Ady.