html documentation and man page about neoleo HOT 6 CLOSED

Documentation is something I've thought about, and I've yet to come up with a solution that works. This is the big question: what is the best form for documentation: man page, info, web page?

The standard GNU way of doing things is to have info pages, but I dunno, I'm not sure they're such a good idea.

man pages can be tricky, because they're often such big screeds of text and difficult to actually find what you're looking for. I'm beginning to think that a man page, designed to make things easily searchable, is actually the best idea.

I do think that complying with Debian distribution policies is, at the very least, a good idea. So I'll look into that.

It may interest you to know that the original GNU oleo can be made to compile without too much trouble. There are some issues, but they're relatively easy to fix. I actually tried to get in touch with the FSF (Free Software Foundation), but was unable to contact the maintainer. I have seen other people's repos where they make a distribution of their own, but they seem to generally make some mistake of one kind or another, so it never quite compiles in the vanilla way that people expect. That's why the original oleo doesn't seem to be incorporated into distros anymore. People try to compile it, find out there's some problem, and give up. The problmes are actually a relatively fixable, though.

from neoleo.

I can tell you from experience that man pages were no fun to write. They can be very finicky to format, and it consumed too much of my time to get everything formatted to spec.

I've never built info pages, but I have seen the documentation (including helpful examples), and it seems much easier than man pages, but still requires much manual(oops) intervention, and I don't see a facility for converting html to texinfo.

My vote is for a simple man page stub, pointing to already existing html pages, installed in /usr/share/doc/html.

If you like, I could write such a man page for you.

As far as the FSF is concerned, I think they do have a procedure for resurrecting "abandonware", so it might be worthwhile pursuing that and becoming the "official" new developer, if that's a responsibility you want.

from neoleo.

I experimented with creating a manpage, and it seems to work. A big advantage that I see with a manpage is that it's searchable, if done right, and can be callable from the spreadsheet itself. I had been kinda working on a mechanism for that, and it might be time to resurrect that idea.

The GNU docs were originally written in texinfo, which is what I adopted originally. The can be a pain to work with, too. At some time I actually abandoned the idea of texinfo. I got it to produce html pages, and then eliminated the texinfo pages.

There was logic behind this ... github's .io page shows html in the docs directory. BUT, the html was generated by texinfo, and not part of the repo. So I just decided to work with the html, as it was online, and convenient. It was more practical for me, and most people, I suspect. The loss of texinfo seemed like no big deal to me, and given the choice, I decided that html was the better option.

I certainly would like to comply with Debian standards, if it makes it more attractive for packagers to consider packaging it. So that would mean a man page and at least some html. Where Debian puts its html pages is something I'll look into a bit more closely. It's something I've never concerned myself too much about, as it tends to get tucked away and I never really recall offhand where it goes.

Hmmm. It's possible to put the webpages there, and have neoleo call them up if help is required. The trick is: which browser to use? The user may or may not have browers like links/elinks/lynx installed, but a manual pager is a sure thing.That would tend to swing the balance into having an elaborate manpage, but simple html pages.

It's something I've been pondering a long time, believe it or not, but hadn't reached any firm conclusion on.

from neoleo.

When I made I my prior comment, I did so not knowing the history that you mention. Now that you say that originally the project was in fact using texinfo, I would suggest reverting. My reasoning is that: 1) most of the texinfo overhead, the formatting, has probably already been done; 2) content is easier to change; 3) there do exist automated ways to convert from texinfo to html.

from neoleo.

The reason I abandoned textinfo is because I didn't want to automate the conversion from texinfo to html. The reason being is that https://blippy.github.io/neoleo/ looks in the repo's docs folder for html, and then serves them if it finds them. If the repo holds textinfo files rather than html, then nothing will be shown. In the end, I decided that html on github more valuable than texinfo.

Generally speaking, there are pros, cons and compromises to various approaches, and I've tried to navigate the pay-offs as best I could.

I'm still open to change, though.

from neoleo.

I have abandoned the idea of html and texinfo pages. Instead, there is a man page. It simplifies things.

from neoleo.