Need better support for Windows line endings
nwoltman opened this issue · comments
Output docs are messed up because most of the jsdoc2md code (in all repos) only handles Unix line endings (\n).
For example, this line is splitting only on LF line endings. This particular line is giving me problems (examples with captions are missing the example code) because even though that line doesn't account for CRLF, splitting on LF should still give somewhat reasonable output, but in my case it doesn't because somewhere before that line all LFs were removed and now the string being split only contains CRs.
You could alter that one split to use /\r|\r\n|\n/ which would fix that specific problem, but it doesn't fix the real root of the problem, which is the lack of support for Windows line endings.
hiya.. i have reproduced the "missing example when caption present" bug and will fix, thank you..
are you having any other specific issues? if so, could you give me an example of something i can reproduce?
all line endings in the dmd handlebars partials are Unix LF characters.. so, on Windows this sometimes results in mixed-line-ending output (typically, the whole md file is LF except in user-input description fields where the user's original CRLFs will still be present)..
then, on checking into git, the line-endings are (by default) normalised so everything in the repo is LF (then converted to CRLF on check out) .. however, not everyone gets this latter normalisation process - it would be better if dmd handled that..
if you really need all CRLF output a quick workaround is to checkout the dmd project and npm link your jsdoc2md to it locally.. on checkout, Git will convert all dmd files from LF to CRLF.. meaning, next time jsdoc2md builds your docs, if it's linked to the local dmd checkout, output will be entirely CRLF.. this is just a short-term fix.
the example caption issue is fixed in dmd 1.3.6, please update your tool / plugin.. thanks again 👍
Thanks for fixing that so quickly! 😃 I hadn't realized that the partials have Unix line endings. I'll take this into account in the future 👍
you're welcome, keep me posted if there is anything else you need.. like i mentioned, i'm building v2 of the tool atm so good timing for new ideas..
The only thing I'd suggest is to operate assuming line endings of input text could be LF or CRLF. The fix for this issue used the regex /\r|\r\n|\n/ because some other part of the code that only assumed Unix line endings stripped the LFs and left the CRs. If you always assumed LF or CRLF, you'd just use a regex like this: /\r?\n/ (instead of \n strings).
because some other part of the code that only assumed Unix line endings stripped the LFs and left the CRs
i've never seen this happen, can you show me or help me reproduce?
the only other operation that touches line endings is this one which removes line-breaks from markdown table cell data.. could be that..
That operation looks correct. I actually haven't been able to find anything else that looks problematic. I bet the problem is actually with jsdoc and not any of your stuff. Sorry to bother you with this.
ok.. tbh, i could do without the jsdoc dep.. jsdoc2md doesn't directly depend on it, it depends on the adapter project jsdoc-parse (and its output data structure).. the moment a viable alternative to jsdoc comes out i will likely switch to it..
@75lb Just a heads up, I messed up the regex that I suggested for the fix. It should be /\r\n|\r|\n/, not /\r|\r\n|\n/. It doesn't matter right now, but if something changes and that function does end up getting a string that has CRLF line endings, it will break with the current regex.
no probs, fixed and released in dmd 1.3.7.. thanks for letting me know.