Add fencing mechanism for disabling help output auto line wrapping #4

New Issue

torque · 2023-09-01T23:58:05-06:00

torque commented

2023-09-01 23:58:05 -06:00

It makes sense to allow the user to preformat certain parts of their output.

torque added this to the 0.1.0 milestone 2023-09-01 23:58:05 -06:00

torque added the

Kind/Enhancement

label 2023-09-01 23:58:05 -06:00

torque self-assigned this 2023-09-01 23:58:05 -06:00

torque commented

2023-09-10 16:18:08 -06:00

I've thought about using STX (\x02) and ETX (\x03) as the preformatted bracketing characters. The problem is that these are nonprinting and cannot be easily represented in a multiline string, which does not allow escapes. Thus, it may make more sense to treat any line that starts with e.g. > as preformatted. The swanked up version of this would be to allow markdown in descriptions, which would then use a fenced code block for preformatted text. However, I would prefer to keep NOCLIP dependency free, and I prefer the line-oriented approach of always having a common prefix.

Consider:

.{
	.description = 
	\\This is a brief description
    \\
    \\As part of the full description, here's an example of a function
    \\that always returns the value 1 as a u8:
    \\
    \\> pub fn returnOne() u8 {
    \\>     return 1;
    \\> }
    \\
    ,
}

I've thought about using STX (`\x02`) and ETX (`\x03`) as the preformatted bracketing characters. The problem is that these are nonprinting and cannot be easily represented in a multiline string, which does not allow escapes. Thus, it may make more sense to treat any line that starts with e.g. `> ` as preformatted. The swanked up version of this would be to allow markdown in descriptions, which would then use a fenced code block for preformatted text. However, I would prefer to keep NOCLIP dependency free, and I prefer the line-oriented approach of always having a common prefix. Consider: ```zig .{ .description = \\This is a brief description \\ \\As part of the full description, here's an example of a function \\that always returns the value 1 as a u8: \\ \\> pub fn returnOne() u8 { \\> return 1; \\> } \\ , } ```

torque commented

2023-11-12 12:08:42 -07:00

Basic support for this was implemented in 768a81e2bd. While the help generation in general would benefit from some refactoring, it was easy enough to hack this in. This feature is good for formatting lists in descriptions as well.

The weird edge case is that lines starting with > are not interpreted as being preformatted. Only the > sequence starts a preformatted line. Supporting both would make the whitespace behavior inconsistent. I suppose only supporting > would be more consistent with zig's multiline strings, which treat all subsequent whitespace literally, but I do think that looks ugly. > is very slightly worse for preformatted things with leading whitespace, though, as it is easy to visually mistake the leading indentation off-by-one.

Anyway, this may be revisited in the future, but for now: working as intended.

Basic support for this was implemented in 768a81e2bdac45038ba553389be821783967aace. While the help generation in general would benefit from some refactoring, it was easy enough to hack this in. This feature is good for formatting lists in descriptions as well. The weird edge case is that lines starting with `>` are not interpreted as being preformatted. Only the `> ` sequence starts a preformatted line. Supporting both would make the whitespace behavior inconsistent. I suppose only supporting `>` would be more consistent with zig's multiline strings, which treat all subsequent whitespace literally, but I do think that looks ugly. `> ` is very slightly worse for preformatted things with leading whitespace, though, as it is easy to visually mistake the leading indentation off-by-one. Anyway, this may be revisited in the future, but for now: working as intended.

torque closed this issue

2023-11-12 12:08:42 -07:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: factotum/NOCLIP#4