[syslinux] hello world

[Ady]

> Hi,
> 
> As someone who just recently came to the Syslinux project, with a
> different agenda but still a Syslinux noob maybe I can add my
> perspective.
> 
> The Doc/Wiki makes perfect sense from a DEVELOPERS point of view, but
> I think the point here is maybe from a USERS point of view not so
> much.
> 
> Even approaching syslinux with the purpose of building a custom .c32
> module and leveraging the core syslinux boot infrastructure:
> 
>  I didn't get/see the VARIANT/variant distinction.  When I read that
> it was an "of course" moment but I do think that it could be
> emphasized to help other noobs. Yes I see it now on the wiki home page
> but I initially thought that was an artifact of some wiki page naming
> convention.
> 
> I too was bit by the library code issue but saw it as a lack of
> knowledge on my part.  That's not how some (most?) USERS would see it
> though.
> 
> I really don't know what to say about the active partition issue, That
> is how most boot loaders work and you will run into the issue with
> just about any other boot loader.
> 
> Finally, if LILO is going EOS at the end of the year it might not be a
> bad idea to create a migrating from LILO page and featuring it
> prominently on the wiki home page.  I'm not suggesting a huge HOWTO
> may be just a simple here are the basic differences we know about, the
> VARIANT/variant convention, modules/libraries are located in
> <bios|efi32|efi64>/com32/modulename, most (all?) com32 modules will
> require the library code and if you're booting from a dos fs use
> syslinux, if you're booting from a Linux fs use extlinux, etc.
> ----------
> Mike
> _______________________________________________
> Syslinux mailing list
> Submissions to Syslinux at zytor.com
> Unsubscribe or set options at:
> http://www.zytor.com/mailman/listinfo/syslinux
> 

 
FWIW, most wiki pages I have mentioned in this email thread were 
written targeting common users.

For example the "Library modules" wiki page uses language and terms for 
common users, and it includes the "whys" and the "wheres". This page 
answers (or at least tries to) some of the issues that common users 
have with c32 dependency modules, independently of the bootloader 
variant (since the matter is, indeed, relevant for c32 modules and not 
dependent on which Syslinux variant is being used). Users in forums, 
irc, mailing lists, bug reports... can follow links to this page. It 
also mentions some differences regarding prior versions.

And, talking about versions, this is another factor in documentation. 
For example, listing library modules needed by menu.c32 (or for each 
c32 module) in its own page would be very confusing for users of prior 
versions, in which each c32 module is (for common users) "standalone". 
Moreover, it would be prone to misunderstandings when one c32 module 
might change its (c32 library modules) dependencies according to the 
Syslinux version, or when the reader's prior knowledge varies.

Instead of repeating information in several places (which makes it much 
harder to maintain), links were added, pages were classified into wiki 
Categories, and pages such as "Common Problems" and "Hardware 
Compatibility" were expanded. Updating the information about the c32 
dependencies in one wiki page is much easier than updating dozens of 
pages, and readers can follow links, if they need/want to.

Please keep in mind that different types of users, with different 
levels of knowledge, require different types of reading, wording, etc. 
Therefore, as I said, there is no way to simultaneously satisfy all 
these types of readers. It requires a balance.

For example, the "Library modules" wiki page might seem too-long for 
some readers, and not enough for others. Similarly, the "Install" wiki 
page.

Another example: the wiki pages for the installers (commands) mention 
"mount", "umount", "format file system", "FAT"... Some users might 
think these issues should also be covered in the Syslinux wiki, in 
spite of not being part of Syslinux itself. There should be some base 
line, somewhere. Otherwise, we could end up documenting simple math too 
:D.

Considering that all the Syslinux subjects are technical by nature, 
there is a practical limit to how much the wiki pages can be simplified 
in wording style and expanded in length. Again, balance. There is 
certainly a valid place for a variety of auxiliary user-friendly tools 
using Syslinux in the back, so users having problems with Syslinux 
might want to use such tools.

Please let me reiterate:
_ feedback is very important and it is very much taken into 
consideration; and,
_ the wiki indeed needs several improvements.

>From those users that are authorized to edit pages in the wiki, not 
many are actively updating it. From those authorized to edit pages in 
the Syslinux wiki in general, very few are authorized to edit the main 
page(s) (which is the main answer to this feedback). There are even 
less people allowed to edit the official documentation included in the 
official archives (which is why the latter is more outdated than the 
wiki).

Distros such as Gentoo, Arch, Puppy... also have their own 
documentation about Syslinux, or about Syslinux packages. There are 
many articles, blogs, auxiliary tools... This is also a very useful way 
of improving documentation. And when something specific is not clear, 
here we are, in this Syslinux Mailing List.

I am not rejecting the feedback about documentation. As I said, we 
_know_ there is place for improvements (and I am not just saying this 
in a generic way; I know of specific points for improvements). On the 
other hand, and in no way opposing or impeding documentation's 
improvements, I'd rather see the Syslinux developers actually writing 
code. In theory, user documentation should be part of development. In 
practice, The Syslinux Project simply lacks of enough resources.

So, the intention of this email is not to reject nor disregard the 
provided feedback. It _will_ be considered.

BTW, using the "search" feature in the wiki is usually helpful.

Please, do not be discouraged by my words; on the contrary. I am 
sincerely 
hoping and wishing for more feedback and more contributions (specially 
resolving bugs), not less.

Thank you and Regards,
Ady.