Log In  



Cart #infman-1 | 2024-03-27 | Embed ▽ | No License
18

IMPORTANT: Picotron 0.1.0c adds a new command called info. As such, this cartridge has been renamed to infman. Please update this command if you have an older version installed, then use rm /appdata/system/util/info.p64 to delete the old version!

This cartridge is a really simple utility that acts as a command list and manual. The goal of this utility is to make it so you don't have to worry if a command has a --help parameter or not (which I've noticed is wildly inconsistent, even among the builtin commands), and also to give an easily accessible list of commands (since help doesn't list them all)

Installation

First, load the cart with load #infman-1
After loading, you have two options for "installation" (these work for updating too):

  • Manual install: You can run save /appdata/system/util/infman.p64 to save it to your system tools (make sure the util folder exists first!) You can call it whatever you like, but it references itself as 'infman' in it's own manual
  • Automatic Install: You can simply press CTRL-R and the cart will try to install itself. Note that this will overwrite any file you might have named /appdata/system/util/infman.p64

Features

  • List all available commands
  • Built-in manual for the system commands
  • Support for custom manuals for user commands

Usage

You can run the utility with infman [options][command name][page]

Possible options are:

  • --system or -s to list only system commands
  • --user or -u to list only user (appdata) commands
  • --highlight or -h to highlight commands with no manual in red

If you run it without any arguments, it'll list both system and user commands.

If you supply a command name, it'll give a manual for that command. There's already manual pages built in for the default system commands, but manual pages have to be manually added (get it?) for user commands.

If no page is specified, it shows the first page by default. If the page is set to 0, it shows the entire manual, ignoring page breaks.

Adding custom manual pages

You have 3 options:

  • Make a file called [command]_manual.txt in the same folder as the command, where [command] is the name of the command. The utility will read whatever is in this text file.
  • Make a file called manual.txt inside the command's .p64 folder, if the command is a .p64 to begin with
  • Add a multiline comment to the top of the command's code (in [command].lua or main.lua)

You can add page breaks to your manuals by putting the text --- on a line all by itself. You can put as many newlines before or after the page break as you like.

Manual pages also support a limited set of p8scii formatting, allowing you to use features such as text colours!

Repository

The source code for this project can be found at https://github.com/kitsting/picotron-info-viewer
Have a bug to report? Want to add a feature I'm too lazy to add? This is the place to do that.

Changelog

1.2.4

  • Updated the metadata so it shows the correct version and name
  • Updated the infman manual (it was showing the old name before)

1.2.3 - Very quick fix

  • Renamed the command to infman to avoid a conflict with Picotron 0.1.0c's info. Please update if you haven't already!
    • Made some changes to allow for renaming to be easier in the future, if needed
  • Added manual pages for pwd, pwc, info (the new one), shutdown, and reboot
  • The cart metadata has the wrong version and name. I can't seem to fix this at the moment

1.2.2

  • Fixed a spacing issue (maybe?)
  • File extension parsing has been improved
    • Now files like mycommand.lua.[something] and coolutility.p64.[something] are ignored
  • Lots of other small code changes (i forgot what they are)

1.2.1

  • Improved page break parsing
    • Empty pages are now ignored
  • Added automatic installer (should work perfectly fine but use at your own risk)
  • Manual pages for system commands are now stored as individual text files instead of one big array

1.2

  • Added support for p8scii formatting (doesn't support all p8scii formatting, but enough to be functional)
    • Supported characters (as of now) are \f, \#, \v, and \^
  • Multiline comment parsing has been improved (thanks pancelor!)

1.1

  • Added support for pages
  • Added -h flag
  • General code cleanup (its not as hacky now (its still a little hacky))

Planned features

These features have no planned date. They could release tomorrow or a month from now.

  • View manuals in the system notebook program
  • Yotta support
18
1

Awesome!

- Make a file called [command]_manual.txt in the same folder as the command
- Make a file called manual.txt inside the command's .p64 folder

I really like this convention a lot, I'll be adding either [command]_manual.txt or [cart].p64/manual.txt files for my utilities.

I put a bit too much info into one of them and ended up scrolling. We don't have a pager or anything yet, so I might propose a convention for adding a marker in the manual ("\n\n---\n\n"?) that lets your tool separate a short usage block at the top (just usage info & basic desc) from an extended description with more info below?

Otherwise, an option for opening the manual in the text viewer might be nice, too.
1

Ooh, pages are a really good idea! I didn't even think about those. I'm not sure if that marker will work due to the way the utility parses multiline comment manuals, but I'll play around with it later this week.

Opening the manual in the text viewer is also a good idea, I'll also see if I can get that working.

Thanks for the feedback!
1

nice tool! the expected files make a ton of sense, I like the choice there. is there a github or something for this project? (I could download it and edit myself but a canonical repo could be nice)

the specific things I've changed so far:


main.lua:

 
	--Extract the manual from the multiline comment
	local i0,i1 = file:find("--[[", 1, true)
	if not i0 then
		return nil
	end

	local i2 = file:find("]]", i1+1, true)
	if not i2 then
		return nil
	end
	return sub(file, i1+1, i2-1)

and I changed manual.txt to say "Add a --[[multiline comment]] to the top of the command's code"

This is different from the current behavior, but I couldn't figure out what the old behavior was supposed to be -- everything's less buggy now that I'm passing plain=true to file:find
1

@pancelor There's no github or anything right now, but I might make one in the near future since that seems like a good idea.

Also I had no idea about plain=true! I'll definitely make sure to be using that from now on. I'll also incorporate your changes into the next release, if you don't mind. Thanks for the feedback!

of course, go ahead!
2

The "info" command was added to picotron 0.1.0c so there might be a conflict now.

@enterprisefzzbzz oh shoot thanks for letting me know. i'll fix that right away



[Please log in to post a comment]