RFC:"blue folder" for offline documentation links?

Software Native
#1

I have an old TrueType font collection that have some individualized requirements for some of the fonts regarding documentation. The license requires that I distribute it with the documentation. Of course this documentation is 30+ years old and will need a disclaimer added that information may be stale, but the font is still useful. I’d like to make some of these fonts available via HaikuPorts but the documentation requirement has me thinking about how documentation is presented to the end-user.

Currently the documentation that comes with Haiku is in the /boot/system/documentation/ directory. I think there should be a packages folder in this directory where the required historical data about the fonts installed and other package documentation. Also, the famous blue-folder system in the deskbar application could and should have a folder containing shortcuts with icons for each document.

Aesthetically, this will allow the BeBook link and the User Guide, likewise, to have an icon and not be left on the desktop with a generic HTML shortcut. The Quick Tour could be still on the desktop for the first boot but hopefully will stand out a little more without the other documents also there.

#2

I think that the rule is the same as for settings: To add a single file or a folder of the name of the package in documentation folder. If the doc is not useful and provided only because of the license, I would zip it and add a disclaimer explaining why it is here, how old it is and how to consult it (since you wouldn’t be able to expand the zip file in place).

The main problem with documentation, is that it can be redistributed on any format. For fonts, a simple text file can make sense and is quite common. But for other things, it’s jungle. I have even seen drivers provided with chm files… So, I’m not sure everyone will agree to present that mess.

#3

@Starcrasher thanks for your reply. I was thinking of supplying the docs in HTML format. They were originally text files but I changed the formatting slightly to make them into MarkDown format for GitHub. All I’d need to do is convert the MarkDown into GZipped HTML using a common converter and GZip, then see about making the browser view the file using MIME types to unpack the file transparently as modern browsers are able to do nowadays (I think).

#4

WebPositive already knows how to render text files, why bother making it into html? you only set yourself up to have to manually fix stuff like dark mode in each html file that webkit can do fine on text files already.

And as a second thing: converting it to html will increase the file size for no reason, and reduce the ammount of applications you can view it with

#5

I don’t understand why you would put it in a zip file. Hpkg files are already compressed, so there is not much to be gained, and it just makes things more inconvenient.

The situation with documentation is a bit confusing currently, we have both /system/documentation ande/system/data/doc, with t^e latter probably being a misconfiguration of some haikuports packages. And inside /system/documentation, some packages use a ./packages/$packageName subdirectory, but some others don’t.

So at the moment it’s a bit “whatever you want”.

Regarding “blue folders”, I’m not sure what you want to do with them. All they do is allow to merge several directories together. This is used in deskbar to avoid having separate “system applications”, “user applications”, “system non-pacbaged applications” and “user non-packaged applications” directories. It has nothing to do with symlinks, so, if you want to create a directory with symlinks or bookmarks, you can do that without a need for blue folders at all?

#6

Thanks for your explanation, @PulkoMandy , I’ll focus on the blue folders argument for now.

All the blue folders in the deskbar collect icons into a common menu. I was hoping to establish a common convention for documentation so that the package manager would only have to create a documentation link to a common folder so that the docs would be easier to find. As you’ve noticed, there isn’t an overarching convention of where or what format the documentation is stored in.

If the documentation is kept embedded in the package using the package filesystem to manage its presence or absence, it simplifies the situation considerably! Not only is it transparently uncompressed, but it is read-only! As long as there is a corresponding translator in translator kit, there should be an easy way to create documentation using StyledEdit or any other supported format.

Since @Starcrasher brought up CHM files (compressed hypertext markup?) from Windows, should there be a centralized format that Haiku uses? StyledEdit is rich text but not hypertext. The reason I was going to use HTML in my packages was that the MarkDown version used by GitHub doesn’t have a viewer for Haiku as far as I’m aware. The CMark parser is in HaikuPorts already for CommonMark MarkDown reading. Maybe that could be expanded into a translator?

#7

You could just use stylededits format if you only want some styling.

In any case, what is wrong with the text format you already have the docs as?

#8

I like text that is not formatted to fixed-width fonts. MarkDown rewraps text while prettying up the formatting options both. My only complaint about MarkDown is that it uses HTML as a backend requirement.

Also, there’s a graphical preview of the lettering style that can’t be linked from plain text.

#9

Stylededit doesn’t use fixed width fonts though? It’s not a code editor, line wrapping also works fine.

#10

https://github.com/FontCollection/Angelina is a link to one of the fonts. It has a GIF preview of the font. StyledEdit can’t embed pictures as far as I can tell.

#11

html is fine, or if you want to be fancy you can also use mhtml which is HTML wrapped into a multipart MIME file (like emails), that allow to have an “all in one” page including both the HTML and the resources (images, etc).

There is currently not really a standard for this, we have a mix of html, manpages, and text files with StyledEdit attributes, as well as a few PDFs. Personally I think HTML and MHTML are the most appropriate and that’s what I use for my apps. But if what you have is textfiles, that’s fine too.

#12

OK! Using the CMark command line utility on the server to convert from CommonMark MarkDown to HTML shouldn’t be a huge problem for the build bot. I’ll have to try that out soon.

Off topic stuff:

Unfortunately, I’m back on Linux for the moment so I can set up a x86 32-bit virtual machine to find out why Haiku X86-GCC2 is rejecting my W2C2 package’s Makefile. I’ll try setting it up in QEmu so I might be able to do it natively from Haiku x86_64 someday.

#13

“md4c” is also available on HaikuDepot, for md->html conversions (that package provides cmd:md2html).

#14

Thanks! I’d seen the library package but didn’t realize it also came with the md2html utility. It does look smaller than CMark and I’d imagine it’s also faster! I guess I’ll use that instead and save CMark for any time it needs to use a different backend like LaTeX.

#15

Just for completeness sake, this is how I use it: (function added to my bash “.profile”):

# Markdown Viewer
function mdview() {
	md2html --github -f --fpermissive-autolinks --fstrikethrough --ftables --ftasklists --funderline --fwiki-links $1 --output=/var/shared_memory/$1.html
	open /var/shared_memory/$1.html
}

and then from Terminal: > mdview some_file.md

1 Like