Multi-line string docstrings seem broken on Windows

[CFiggers]

Using this sample file:

# scratch.janet

(def thing
  ``
  Multi 
  line 

  doc 
  string 
  ``
  123)

(defn main [& args]
  (pp (dyn 'thing))
  (doc thing))

On Linux (as expected):

[caleb@UBUNTU-24.04 ~/projects/janet/scratch] janet ./src/scratch.janet
@{:doc "Multi \nline \n\ndoc \nstring " :source-map ("./src/scratch.janet" 1 1) :value 123}

    number
    ./src/scratch.janet on line 1, column 1

    Multi line

    doc string

On Windows (weird):

PS C:\Users\cdfig\projects\janet\scratch> janet .\src\scratch.janet                                                                                         
@{:doc "\r\n  Multi \r\n  line \r\n\r\n  doc \r\n  string \r\n  " :source-map (".\\src\\scratch.janet" 1 1) :value 123}

    number
    .\src\scratch.janet on line 1, column 1

 string 

[sogaiu]

Possibly of interest might be this.

As far as practical advice is concerned, what I've been doing I think might be summarized as "only use long-strings that are not multi-line except in the case of docstrings".

Am curious if you've encountered a practical downside for their use as docstrings.

[CFiggers]

I haven't seen downsides to using long strings as docstrings. It seems to be a supported use case, given that many modules written by @bakpakin himself (e.g. spork's argparse) use multi-line docstrings.

Argparse's docstring looks like this on Windows:

PS C:\Users\cdfig\projects\janet\scratch> janet
Janet 1.35.2-local windows/x64/msvc - '(doc)' for help
repl:1:> (import spork/argparse)
@{_ @{:value <cycle 0>} argparse/argparse @{:private true}}
repl:2:> (doc argparse/argparse)

    function
    C:/Users/cdfig/AppData/Local/Apps/Janet/Library/spork/argparse.janet on line 15, column 1

    (argparse description &keys options)

 Parse (dyn :args) according to options. If the arguments are
 Each return nil and print usage information.
 for ption is a table or struct that specifies a flag or option
    the script. The name of the option should be a string, specified
    via (argparse/argparse "..." op1-name {...} op2-name {...} ...). A
 and usage text is automatically generated for you.
    The keys in each option table are as follows:

    * :kind - What kind of option is this? One of :flag, :multi,
 :accumulate. A flag can either be on or off, a multi
 multiple times, each time adding ed
 will be set in urned integer, an option is a key that
      the returned table, and accumulate means an option can be
 0 or more times, each time appending a value to an
      array.
    * :short - Single letter for shorthand access.
    * :help - Help text for the option, explaining what it is.
    * :default - Default value for the option.
    * :required - Whether or not an option is required.
    * :short-circuit - Whether or not to stop parsing if this option is
 Result will also contain the rest of the arguments under
      the :rest key.
    * :action - A function that will be invoked when the option is
      parsed.
    * :map - A function that is applied to the value of the option to
      transform it

 There is also a special option name :default that will be invoked
 that do not start with a -- or -. Use this option to
 arguments to your script. This is separate from
 After "--", every y in option specifiers.
 Once parsed, values ed as an unnamed argument.
 of the option. le in the returned table by the name
 flag is xample (result "verbose") will check if the verbose
 You may also use a custom args array when specified via
    the special option :args.

[sogaiu]

I haven't seen downsides to using long strings as docstrings. It seems to be a supported use case, given that many modules written by @bakpakin himself (e.g. spork's argparse) use multi-line docstrings.

Ah, sorry if that was unclear -- it's what I do, and I hadn't noticed any issues since filing the other issue. I believe multiline docstrings have been in use far before the other issue was filed (^^;

Argparse's docstring looks like this on Windows:

Thanks for sharing the output, that looks like a pretty signficant downside to me because some info appears to be missing.

I confirmed in a local Windows environment. Looks pretty similar here.

[sogaiu]

I don't recall clearly, but I think a work-around I was using in some of my repositories was to add an appropriate .gitattributes file like this:

* text eol=lf

Possibly adding this to the spork repository might help. Not sure (^^;

Though IIRC, one may need to reclone -- just pulling may not be enough for it to affect already cloned content.

[sogaiu]

A bit concerning work-arounds...

I recloned spork using:

git clone https://github.com/janet-lang/spork --config autocrlf=false

After installation, the docstring looked fine.

---

Not that great and for already cloned stuff I haven't yet figured out how to adjust things without recloning.