Puppy documentation needs updated or replaced

[user1234]

It is amazing what others see that you do not!

Just the same for me as well. And I think its same for many others as well.

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

Like a webpage... I am afraid you can't, unless you want to drag the additional woof-CE code along with it. You though can see the changes made in html format, just go to the Files Changed tab of the aforementioned link. I will make this pull request available as a complete PR once I complete with most of the pages (those ones which I am able to).

Though I will keep you all updated by attaching the documentation files through posts on this topic. I am afraid I can't do that right now, still I'll do it tomorrow as soon as I switch on my computer.

[user1234]

I found one link that was no good.

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

Could you please tell which link is broken? And could you please provide what more information you think must be added?

[wizard]

@user1234

Everyone who wants to contribute to modifying the existing files should specify here which files they will work on, else we will end up with duplication of effort.

Thanks
wizard

[williwaw]

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?

can woof-ce build a simple markdown viewer?
I use mdview in easy, but it's not woof-ce

[bigpup]

To keep from having a bunch of man page files in Puppy Linux.

The script program pman is in most all Puppy versions.
man is a symbolic link to it.

Pman will open the default web browser, do a search on the web, and take you to a list of locations on the web, where you can see the man page for what you asked for.

This keeps Puppy from having to have a bunch of man files, plus it will always show the latest version of the man page.

Example:

Code: Select all

man fsck

Brings up this:

Screenshot.jpg (99.92 KiB) Viewed 895 times

.

Screenshot(1).jpg (111.92 KiB) Viewed 888 times

[dimkr]

can woof-ce build a simple markdown viewer?

No, but can be done https://github.com/puppylinux-woof-CE/w ... rom-source

[williwaw]

the puppy documentation in question should be onboard and not depend on a browser or internet connection, but have a simple way to view/access

puppy documentation, if put in man "format' could be viewed in the terminal
puppy documentation, if put in .md filetype could be viewed with the simple viewer mentioned above

.doc has been suggested, but depends on a .doc compatible "viewer", possibly a large or unwanted download in a minimal release.
rtf? ted?
notecase can link to or include pictures , but I do not know if it is still in woof-ce
helpsurfer renders local htm well and is small

[bigpup]

I found one link that was no good.

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

Could you please tell which link is broken? And could you please provide what more information you think must be added?

The devx.htm

The bad link is the first one (the Puppy Linux Home page) here:

Obtaining the devx

You can obtain the devx in a number of ways depending on your distro. Historically, and still relevant today, the devx can be obtaioned from any of the Puppy Linux Mirrors. There are mirror locations at the Puppy Linux Home page.

------------------------------------------------------------------------------------------------------------------------------------------------------------------------
what I suggest to add.
When downloading the devx.sfs It is best to put it in /mnt/home location.
SFS-Load-On-The-Fly program will only see SFS package files at that location.
Also, /mnt/home location is outside of the save file/folder.
It will not be dependent on also loading the save to use it.

[mikewalsh]

Me, I keep both DevX and kernel_sources in a sub-directory in /mnt/home. I then copy them into the parent directory when I want to use them, followed by deleting again when I'm finished.

Works for me, and it keeps /mnt/home "tidier"!

Mike.

[mikewalsh]

the puppy documentation in question should be onboard and not depend on a browser or internet connection, but have a simple way to view/access

puppy documentation, if put in man "format' could be viewed in the terminal
puppy documentation, if put in .md filetype could be viewed with the simple viewer mentioned above

.doc has been suggested, but depends on a .doc compatible "viewer", possibly a large or unwanted download in a minimal release.
rtf? ted?
notecase can link to or include pictures , but I do not know if it is still in woof-ce
helpsurfer renders local htm well and is small

.....and there you have it. There will always be dissension between those who want to move with the times and do everything online, and those who believe that everything should be kept "local".

Much as I'm an advocate of using online resources wherever possible, in this respect I concur with williwaw. These files are never going to be big, and with careful choice and use of appropriate format CAN be viewed with a minimal application that is itself pretty small.

It's still possible to use hyper-links without the need for writing things with HTML. If MyCrudSoft could do it with Word2000, all those years ago, I'm sure a basic word-processor should have that ability today.

Mike.

[user1234]

The devx.htm

The bad link is the first one (the Puppy Linux Home page) here:

Obtaining the devx

You can obtain the devx in a number of ways depending on your distro. Historically, and still relevant today, the devx can be obtaioned from any of the Puppy Linux Mirrors. There are mirror locations at the Puppy Linux Home page.

I am afraid, I am not able to understand which one is a bad link. Note that the content shown in red color in github is the 'removed' one, while the content in green color is the content that is 'added'. Please check again and then tell if the link is truly broken or not?

what I suggest to add.
When downloading the devx.sfs It is best to put it in /mnt/home location.
SFS-Load-On-The-Fly program will only see SFS package files at that location.
Also, /mnt/home location is outside of the save file/folder.
It will not be dependent on also loading the save to use it.

Thanks for the suggestion! I'll work on the same.

[wizard]

@williwaw

.doc has been suggested, but depends on a .doc compatible "viewer", possibly a large or unwanted download in a minimal release.

The .doc format will of course open in Abiword which has been a standard included package in Puppy. We need a format that can include images, it's that "One picture is worth......." thing.

Also,in this particular case, Fossapup64 won't be a minimal release. Per Phil, recommended system is dual core, 2gb ram.

If I have misinterpreted, my apologies.

wizard

[bigpup]

Let's clear up one misunderstanding.

All the documentation files this topic is about are local to the Puppy install.
They are in /usr/share/doc directory that is provided in the Puppy ISO.

When Puppy is running you can find all of them in /usr/share/doc

They have clickable links that will open another file in /usr/share/doc
Example:
menu -> Help opens this file -> file:///usr/share/doc/index.html
click on one of the listed links
Example:
About Root
It opens this file ->file:///usr/share/doc/root.htm

How To Use Package Manager
It opens this file-> file:///usr/local/petget/help.htm
(still a file in Puppy, just in a different location in the file system)

They also, depending on what the file provides for info. can have clickable links to locations on the Internet.
That is all that this file is ->file:///usr/share/doc/forums.htm
Clickable links to all the Puppy specific web sites.

This file ->file:///usr/share/doc/home.htm
Usually try to make this the home page for the browser that comes in Puppy.
First time you start the browser, you see the list of Puppy web sites, that can click on, to go to them.
This one really needs the links updated.
Notice one of the links goes to ->file:///usr/share/doc/HOWTO_Internet.htm
HOWTO: Internet access
That one really needs to be updated to provide much more info!

[bigpup]

The devx.htm

The bad link is the first one (the Puppy Linux Home page) here:

I am afraid, I am not able to understand which one is a bad link. Note that the content shown in red color in github is the 'removed' one, while the content in green color is the content that is 'added'. Please check again and then tell if the link is truly broken or not?

I am taking the code you gave a link to for the devx.htm
Copy and paste it into a file named devx.htm
Click on it to open in the default web browser.
It comes up as a information page in the browser.

This is the link that does not work. See red arrows pointing to it in image.

Screenshot(3).jpg (96.89 KiB) Viewed 850 times

[williwaw]

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

seems reasonable to make updating easy

[bigpup]

@wizard

Give us an example.

Take this file /usr/share/doc/index.html

Turn it into a .doc file

Let us compare the two and see what everyone thinks.

[bigpup]

Anyone know a simple WYSIWYG editor for these htm and html files?

[wizard]

@bigpup

Bluegriffin 1.7.2 32bit does a reasonable job. I've used it in Fossapup64 with the 32 bit compatibility add on. Many of the WYSIWYG editors or conversion packages create a lot of gunky code. Bluegriffon is better in that respect Got the link from a post by @mikewalsh
https://mega.nz/folder/WPgx1Iab#tFu_eUVhNqnyZ4kvGWWCwA.

wizard

[williwaw]

html-notepad
viewtopic.php?t=7123
but
fixing links and changing a word here or there, adding or deleting a paragraph etc. of a html file is not so hard to do in a text editor. although a wysiwyg editor might be useful for more complex restructuring.

[user1234]

The devx.htm

The bad link is the first one (the Puppy Linux Home page) here:

I am afraid, I am not able to understand which one is a bad link. Note that the content shown in red color in github is the 'removed' one, while the content in green color is the content that is 'added'. Please check again and then tell if the link is truly broken or not?

I am taking the code you gave a link to for the devx.htm
Copy and paste it into a file named devx.htm
Click on it to open in the default web browser.
It comes up as a information page in the browser.

This is the link that does not work. See red arrows pointing to it in image.
Screenshot(3).jpg

Don't know particularly the reason, but this is not what I have done. I am attaching a .tar.bz2 file with this post. Please extract it and see if the problem still remains.
FILE:-

doc.tar.bz2

(255.95 KiB) Downloaded 28 times

(use tar -xvjf doc.tar.bz2 to extract).

[wizard]

@bigpup

Give us an example.

Take this file /usr/share/doc/index.html

Turn it into a .doc file

Let us compare the two and see what everyone thinks.

Can do, but will open a new topic for it as I don't want to dilute this effort further.

Thanks
wizard

[wizard]

@bigpup

I initially took this topic title "Puppy documentation needs updated or replaced" as a solicitation to include replacing the HTML format. You've since clarified that "update or replace" is focused on the existing HTML files and to remain in HTML. Here's what I understand at this point, please correct any mistakes.

-Fossapup64 9.5 distro
-Existing files are in HTML format located in: /usr/share/doc (see bigpup post on pg.5 of this topic)
-Corrected files should be submitted in HTML format (see note below)

Things that need clarification:
-Exactly which files in /usr/share/doc need review?
-Where should the corrected files be submitted?
-Is there a log of who/what files are in process or completed?

Note:
Anyone not familiar with HTML code who wants to contribute can consider using Bluegriffon
WYSIWYG HTML editor that works more like a word processor. Portable versions available here:
https://mega.nz/folder/WPgx1Iab#tFu_eUVhNqnyZ4kvGWWCwA

This is an overdue project and as it relates to the creation of a Community Edition Puppy on Distrowatch gives us an opportunity to attract more users by making Puppy easier to adopt.

Thanks
wizard

[user1234]

@bigpup:-
Just updated HOWTO-regexps.htm. Here is the doc folder after update:-

doc.tar.bz2

(256.03 KiB) Downloaded 24 times

(use tar -xvjf doc.tar.bz2 to extract.)

One more thing that I want to ask:-
What about the application links in HOWTO-multimedia.htm which are just links to .htm files in the doc folder itself?
I mean, will it after building of a puppy, point to somewhere else specific to the documentation of that application, or will it remain just as-is? If it will remain as-is, then, just telling, the .htm files for the applications are not there. Will have to make those documentation files as well.

[williwaw]

it would be nice if the documentation recently posted in Getting Started and System Requirements is also available in /usr/share/doc

perhaps puppy documentation efforts should be consolidated into a single effort at a central location. It would make maintenance easier.

[bigpup]

@bigpup

I initially took this topic title "Puppy documentation needs updated or replaced" as a solicitation to include replacing the HTML format. You've since clarified that "update or replace" is focused on the existing HTML files and to remain in HTML. Here's what I understand at this point, please correct any mistakes.

-Fossapup64 9.5 distro
-Existing files are in HTML format located in: /usr/share/doc (see bigpup post on pg.5 of this topic)
-Corrected files should be submitted in HTML format (see note below)

Things that need clarification:
-Exactly which files in /usr/share/doc need review?
-Where should the corrected files be submitted?
-Is there a log of who/what files are in process or completed?

I know, what you think you are saying and what someone thinks you said.

The replace part is about a completely new file that provides the information.
Maybe a needed file is missing.
Best if you can use the same name already used and just edit the file.

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

Puppy documentation needs updated or replaced is about only the files in usr/share/doc

All of the files that are not in a directory need to be looked over and corrected.

Exactly which files in /usr/share/doc need review?

All the .htm or .html ones and maybe a few text files. (the directories are for specific programs and should be good)

.

Screenshot.jpg (124.58 KiB) Viewed 793 times

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

Where should the corrected files be submitted?

I guess the best thing would be post them here as an attachment to a post about it.

After others look it over for any needed correction.

Make it a pull request at Woof-CE to have it replace what is stored there in the repository.

I guess I could do the submitted pull request and offer the file.

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

Is there a log of who/what files are in process or completed?

Not yet, but I guess we need to make something.

I could have a list of all the files in the first post of this topic.
Maybe edit it as people offer to work on a file and edit to show who is working on it.
Edit the list to show completed.

I guess I will need to check this topic everyday to see what has been done.

If anyone has a better idea?

I guess I need to go and edit the first post of this topic.

[bigpup]

it would be nice if the documentation recently posted in Getting Started and System Requirements is also available in /usr/share/doc

I guess it could be all as separate individual files added to usr/share/doc

My thinking is just have whatever info file is needed to get a Internet connection.

After getting an Internet connection.
Then have a link on the Menu -> Help, that when clicked on, would take you to the forum section Getting Started and System Requirements.

[bigpup]

@bigpup:-
Just updated HOWTO-regexps.htm.

This is all you have to do when you have an updated file to provide.

Just attach that file.

Will have to compress it to get it to attach.
The forum security will reject a pure html or htm file as a security risk.
So here is the file you edited zip compressed.

HOWTO-regexps.htm.zip

(6.81 KiB) Downloaded 35 times

You know more about this files subject than I do.

So one document file completed, unless someone else wants to look at it and offer a change.

[bigpup]

Are we having fun yet!

[bigpup]

For editing thes html and htm files.

Seamonkey browser comes with a Composer editor that will work in WYSIWYG display.

It does take a little time to figure out how to make or change a clickable link, selecting save the changes.

But doing text editing is like using a word processor.
.

Screenshot(1).jpg (37.92 KiB) Viewed 779 times

.
Open one of the files in Seamonkey browser
Select file-> Edit page
It will now open in Composer to edit.
.
.
Seems to actually be making the files smaller, when completed and saved.
I tried a little changing on one html file, editing the link location, adding more text to the statements, etc....

[williwaw]

My thinking is just have whatever info file is needed to get a Internet connection, Then have a link on the Menu -> Help that when clicked on would take you to the forum Getting Started and System Requirements.

So /usr/share/doc should only include info to get the browser working? this presumes one always has the internet available? and what if "Getting Started and System Requirements" gets updated to be accurate for a different puppy?

Documentation for puppy has always suffered from lack of a comprehensive planning and maintenance and deserves a discussion of its own before calls are made for others to help update something you seem to think should be depreciated.

A central git hub repo for documentation could allow for documentation pertinent to prior official puppies to be easily accessed, should the dev choose to supply links instead of including pages in /usr/share/docs.

When official puppys change, "Getting Started and System Requirements" could also have links to the correct information at the central repo.