Page 1 of 8

Puppy documentation needs updated or replaced

Posted: Sat Nov 05, 2022 6:03 pm
by bigpup

This will be the topic to try and fix this!

All the documentation for Puppy Linux is getting very outdated.

All the files are the ones in /usr/share/doc

Only a few of them have had any edits to have them provide updated info.

user1234 is person working on this.

Any info on what still needs worked on he is providing in the last pages of this topic.

Remember, we are Puppy.
What it is, will be controlled, by what we make it!


Re: Puppy documentation needs updated or replaced

Posted: Sat Nov 05, 2022 11:17 pm
by Wiz57

What "format" would be a preference? Currently most of the documents are in HTML format, requiring some at least minimal
web browser or HTML viewer (do these still exist? Last I used was in MS DOS 6.22 days.) Perhaps if the format was changed to
say RTF (Rich Text File) then most any document editor could display them? Or plain text? Perhaps bog standard DOC (not
DOCX or other proprietary format)?
Wiz


Re: Puppy documentation needs updated or replaced

Posted: Sun Nov 06, 2022 3:17 am
by williwaw

can woof-ce build the capability to view a man page?


Re: Puppy documentation needs updated or replaced

Posted: Sun Nov 06, 2022 5:17 am
by williams2

an woof-ce build the capability to view a man page?

I think the dev sfs file has tools to work with man pages.
I'm not sure whether you can read man pages with the dev sfs file loaded.

The software to read man files can be installed, like any other software, so yes, I think woof could be configured to include the man software files.

And man2html is often installed in the base sfs file(s).
I don't remember if it works OOTB.


Re: Puppy documentation needs updated or replaced

Posted: Sun Nov 06, 2022 7:07 am
by dimkr
williwaw wrote: Sun Nov 06, 2022 3:17 am

can woof-ce build the capability to view a man page?

Yes, but AFAIK Vanilla Dpup is the only Puppy that takes advantage of that.

Why not replace the "help" menu entry with a link to viewforum.php?f=184?


Re: Puppy documentation needs updated or replaced

Posted: Sun Nov 06, 2022 4:54 pm
by mikeslr

dimkr +1.

Then the only 'internal' help file you'd need is one explaining 'how to obtain a web-browser' if one isn't already provided.

Fun isn't work and doing whatever you want with any Puppy is fun; even explaining about what you've done. Otherwise writing documentations is hard work; re-writing them is even harder.


Re: Puppy documentation needs updated or replaced

Posted: Sun Nov 06, 2022 6:16 pm
by bigpup

Why not replace the "help" menu entry with a link to the puppy forum?

That would work for what information is provided their.

If you had a working web browser and an established Internet connection.

As the menu -> Help now is.

Only need a working browser.

It accesses a file that can be read, with out having a network Internet connection.

All the links on it will bring up other files that are in usr/share/doc

---------------------------------------------------------------------------------------------------------------------------------------------

Puppy OS info and help files, were originally made in HTM and HTML type, so that they could have clickable links to other files or web sites.

-------------------------------------------------------------------------------------------------------------------------------------------------

A lot of the files have web site links that are pointing to old Puppy forum or Barry K specific web sites that no longer exist.
Correcting those should not too hard.


Re: Puppy documentation needs updated or replaced

Posted: Sun Nov 06, 2022 7:53 pm
by Clarity

This thread is an excellent request. To get more views and contributions, should this be placed in this forum area verses here in this Users area?

If this thread is moved to the General area, please ALSO remove this post!


Re: Puppy documentation needs updated or replaced

Posted: Tue Nov 08, 2022 3:59 pm
by wizard

If you have not looked at the HELP files for Friendly-Fossa64 (a remaster of Fossapup64 9.5), attached is a link (to help files only). https://sourceforge.net/projects/wizard ... z/download

The files are in .DOC format created with Libreoffice Writer and can be "viewed" with Abiword. These could easily be modified to work with a Fossapup64-9.6-CE. Compared to the "native" HTML help files, they cover additional topics to help new user and they include graphic images. They are larger than the native files, but are still only 1.3 mb total.

The existing files do include references to programs that are not part of Fossapup64 9.5 and would need to be changed accordingly if these were not in Fossapup64-9.6-CE

Also included is the document, Programs_Installed.xls, which gives the user some idea of the wide variety of tools available. I would suggest including and expanding this list to all programs in the menus. This is one of Puppy's strengths OOTB and deserves an icon on the desktop.

Thanks
wizard


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 6:56 am
by williams2

If you are looking for documentation about kernel boot parameters,

see viewtopic.php?t=5818

This forum > Board index > General Information > Getting Started and System Requirements > How Puppy Linux Works.


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 4:08 pm
by mikewalsh

Once again, I notice nobody is in fact volunteering.....but of course, lots of people are posting with suggestions for somebody else to do the actual work.

Why is that that it always seems to fall to the same small "pool" of members to carry everybody else, hmm? Surely the rest of the community aren't quite that helpless, are they?

Mike. :roll:


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 4:38 pm
by puppy_apprentice

Automated conversion forum articles to PDF:
viewtopic.php?p=65919#p65919
Every Puppy has PDF viewer.


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 5:17 pm
by dimkr

It doesn't matter if the help files are converted to .odt, .pdf or whatever if the content is useless or even misleading :roll:


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 5:34 pm
by puppy_apprentice
dimkr wrote: Wed Nov 09, 2022 5:17 pm

It doesn't matter if the help files are converted to .odt, .pdf or whatever if the content is useless or even misleading :roll:

But those articles are up to date and will be revised if necessary?
viewforum.php?f=184
So they could be easily converted to PDF Manual via Prince.


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 5:49 pm
by user1234

So @bigpup, I'll try to help in the documentation stuff, wherever my knowledge applies.

Still I need that you tell where the documentation files are (in a github repo or in some specific puppy versions)? And how would you implement the changes (changes for to-be-built puppies or the ones which are already there)? If you want to implement them in the already built puppies, then how are you gonna make them available to the users?


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 6:36 pm
by dimkr
puppy_apprentice wrote: Wed Nov 09, 2022 5:34 pm

So they could be easily converted to PDF Manual via Prince.

Why convert the topics in this forum to PDF instead of changing the Help menu entry so it points to this forum?

If every Puppy ships with a .pdf snapshot of the current forum contents, the user is stuck with old documentation after a while. Also, .pdf files can be big and they're binary (less compressible).

user1234 wrote: Wed Nov 09, 2022 5:49 pm

Still I need that you tell where the documentation files are

https://github.com/puppylinux-woof-CE/w ... /share/doc


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 6:40 pm
by puppy_apprentice
dimkr wrote: Wed Nov 09, 2022 6:36 pm

Why convert the topics in this forum to PDF instead of changing the Help menu entry so it points to this forum?

Sometimes there are situations that you do not have access to the Internet or the forum is slow.

dimkr wrote: Wed Nov 09, 2022 6:36 pm

Also, .pdf files can be big and they're binary (less compressible).

Puppy is bigger and bigger so few MB more isn't problem (or is?). I will try to make a PDF with those articles (in the weekend). I think that it will not be bigger that 10MB.


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 7:23 pm
by bigpup

Size of Puppy is still something to consider.

Remember that all of Puppy gets loaded into memory.

There are still people around the world, that use computers with low amounts of memory, in them.

Are these pdf versions going to have clickable links?

Reinventing the wheel, making it bigger, is only a good idea, if it really needs to be bigger.

These documentation files, have been around for years, they work, and are integrated in Puppy program code.

What is needed is only making changes to the information in them, so it is current info.

Pick a file to look at.

Read it.

Change what you think needs changed.

Should be able to attach it to a post in this topic, so others can review it.

Just to have another set of eyes looking at what is submitted.

Then it can be elevated to placement into the repository at Woof -CE

No one is asking for just one person to work on all of these documentation files, unless you just want to!


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 7:31 pm
by puppy_apprentice
bigpup wrote: Wed Nov 09, 2022 7:23 pm

Are these pdf versions going to have clickable links?

There is an example file, you can check:
viewtopic.php?t=6714
or directly: Manual.pdf

Ok I don't insist. But from the developer's point of view it will be easier to make such an manual. It will be an automatic method.

bigpup wrote: Wed Nov 09, 2022 7:23 pm

There are still people around the world, that use computers with low amounts of memory, in them.

You can attach this PDF to the main directory of CD/ISO (or in Help directory) it doesn't have to be in Puppy system file.

On the other hand, the downloaded file you can use when you want. In Africa there may be problems with access to the Internet on demand.

bigpup wrote: Wed Nov 09, 2022 7:23 pm

No one is asking for just one person to work on all of these documentation files, unless you just want to!

I offer to convert and prepare Prince so that anyone can do it. I will not edit these forum articles.


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 9:56 pm
by wizard

@mikewalsh

You are right, most of the time we get a lot of talk and not much action. However, in this case, there are some added obstacles.
1. Most of the members don't use github
2. On the chance that they follow the link to the existing help files and figure out they can't click on the Help directory, then click on
an actual file they find themselves looking at a page of HTML code with no obvious way to download anything.

The fact is few members know how and are willing to deal with the files in HTML format.

So here's my point of view. The legacy help files are in HTML format and frankly are quite general in nature. New users need and benefit
from help files that show images and include step by step instructions. You can certainly do that in HTML, but it starts to get way more complicated. Using HTML does give you the advantage of using links, but linking to external sources has a great risk of having dead links. A prime example is the current help files in which the large majority of the links are dead.

PDF format has been discussed, but would require maintaining a editable "master" and it presents issues for translation to other languages.

The issue of size should not be a factor between HTML, PDF, or .DOC since it is quite small.

If we're going to up our game, we need to change to a format that can use embed graphics and that is easy to create and maintain by the members.

I went through all of this exercise when formulating the help files for Friendly-Fossa64 and concluded that the .DOC format best met the needs and criteria of "easy to create and maintain"

wizard


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 10:40 pm
by mikewalsh

@wizard :-

I agree that HTML is far from intuitive for non-users. I've never used it myself, but my assumption is that the user would:-

  • Copy the page of HTML code, then

  • Open something like Kompozer, BlueGriffon or even the built-in editor in something like SeaMonkey, then paste the contents of the clipboard into an empty document. After that, well.....I don't know, exactly, but I believe you can make that HTML code display as a "finished" webpage to see what it looks like.

I assume you can then edit it, and finish up by reversing the process to convert it back into HTML code again. I'm probably wrong, and more than happy to be corrected... :D

------------------------------

(Thinking about it, hmmm; creating help documentation for one's own 'product' is a labour of love. Even I've done that with much of my more recent stuff. But producing extensive documentation for every aspect of Puppy itself - to be usable by the entire community, from noobs to veterans, if necessary in multiple languages.....mikeslr has hit the nail on the head. Puppy is fun. Creating valid documentation that everyone is happy with is just plain hard work. It's no wonder nobody's volunteering.) :|

Mike. ;)


Re: Puppy documentation needs updated or replaced

Posted: Wed Nov 09, 2022 11:39 pm
by wizard

@mikewalsh
Fair analysis, but give it a real try. Pick a file with some dead links, see if you can fix them, then add a couple of images AND then test it in 3 or 4 browsers to see if it renders correctly. Next, upload back and be sure your images (which are external) and their links will all still work when installed in the Puppy file system :lol:

I can tell you how to do a .DOC help file in about one paragraph, it will be WYSIWYG, single file, no code, and just about everyone already knows how to use a word processing programg :mrgreen:

Just sayin

wizard


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 4:32 am
by bigpup

The legacy help files are in HTML format and frankly are quite general in nature.

The general in nature is because the actual program you may use will have it's own help.

Example:
Most Puppy versions have 3 different programs that could be used for a network connection.


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 10:41 am
by mikewalsh
wizard wrote: Wed Nov 09, 2022 11:39 pm

@mikewalsh
Fair analysis, but give it a real try. Pick a file with some dead links, see if you can fix them, then add a couple of images AND then test it in 3 or 4 browsers to see if it renders correctly. Next, upload back and be sure your images (which are external) and their links will all still work when installed in the Puppy file system :lol:

I can tell you how to do a .DOC help file in about one paragraph, it will be WYSIWYG, single file, no code, and just about everyone already knows how to use a word processing programg :mrgreen:

Just sayin

wizard

@wizard :-

I've got more than enough on my plate, maintaining all the contributions I have made over the years. That's one side of things I have zero interest in getting involved with....

Sorry an' all that.

Mike. :|


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 10:45 am
by user1234

I have just created a 'draft' PR here. I have given information for which files I have updated. I have kept this as a draft to signify that there can be more things which I can update, just will have to see. That is likely all I will be able to contribute today, I suppose. But for sure will continue the work later on.

And yes, @mikewalsh, I have included links to few of your portable apps. I hope you're completely okay with this, are you?


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 2:01 pm
by bigpup

@user1234

Thanks for working on these documents.

Overall very good work!

I suggest whatever you come up with, please post it here first.
This will allow others to look it over before submitting it to Woof -CE

I looked at your devx.htm

I found one link that was no good.

Also have a suggestion for a small change or addition to the information.

I have found, over the years of producing info about Puppy Linux, and how to do things in it.

I am happy to have others, that have looked it over, offer suggestions or point out something I missed or stated wrong.

It is amazing what others see that you do not!


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 2:18 pm
by mikewalsh

@user1234 :-

user1234 wrote: Thu Nov 10, 2022 10:45 am

I have just created a 'draft' PR here. I have given information for which files I have updated. I have kept this as a draft to signify that there can be more things which I can update, just will have to see. That is likely all I will be able to contribute today, I suppose. But for sure will continue the work later on.

And yes, @mikewalsh , I have included links to few of your portable apps. I hope you're completely okay with this, are you?

No worries, mate. Feel free.....they are provided for all to enjoy..! :thumbup:

So.....how do you actually "view" these?

--------------------------

@bigpup :- That's entirely due to being too close to whatever it is you're doing.....or in plain English, "can't see the wood for the trees"! :lol:

Mike. ;)


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 2:38 pm
by wizard

@mikewalsh

You are correct and are one of my Puppy Heros for all you contribute :thumbup2: . Wasn't my aim to get you off course. It's Just an example of wizard's rule #6 "Everything that should be easy, isn't"

wizard


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 2:39 pm
by mikewalsh
wizard wrote: Thu Nov 10, 2022 2:38 pm

@mikewalsh

You are correct and are one of my Puppy Heros for all you contribute :thumbup2: . Wasn't my aim to get you off course. It's Just an example of wizard's rule #6 "Everything that should be easy, isn't"

wizard

^^^ :lol: :lol: :lol:

Mike. ;)


Re: Puppy documentation needs updated or replaced

Posted: Thu Nov 10, 2022 2:47 pm
by wizard

@mikewalsh

So.....how do you actually "view" these?

And another example :D