[new feature] SCDOC format

[AndersonTorres]

SCDOC git repo at sourcehut is a document format similar to Markdown, primarily used to be converted to manpages.

Describe your proposed improvement and the problem it solves.

Add scdoc format, as described at https://git.sr.ht/~sircmpwn/scdoc/tree/master/item/scdoc.5.scd

Describe alternatives you've considered.

None. The idea is, precisely, add it as an input that Pandoc can recognize and work with

[jgm]

I guess my questions would be:

1. when was this made?
2. is it still maintained?
3. how widely used is it?
4. why would it be helpful to have a pandoc reader for this format? It seems to be a special-purpose tool for creating man pages. Of course, you can do that with pandoc, but why not just use scdoc to convert this format to man pages?

[AndersonTorres]

when was this made?

Seven years since the first commit, a4193949ec755b3848a803a9b02364eeddbb1455 at scdoc git.

is it still maintained?

Most recent commit from 6 months.

how widely used is it?

I believe many projects from Sourcehut use it. A quick grep at Nixpkgs codebase returned 100 packages.

why would it be helpful to have a pandoc reader for this format? It seems to be a special-purpose tool for creating man pages. Of course, you can do that with pandoc, but why not just use scdoc to convert this format to man pages?

Hum, let me explain.

There is a project, say Cardboard, that is using Pandoc to convert a Markdown file to a manpage.

Pandoc is awesome for converting Markdown to manpage, it goes without saying. However, Pandoc is too overkill for this. Pandoc has a big dependency, namely GHC. Bringing all this machinery for the sole purpose of generating a manpage looks like the proverbial bazooka to kill a fly.

On the other hand, scdoc is crafted to be, according to its creator, "a man page generator that had no more dependencies than man itself".

So, the idea here is:

1. use Pandoc to convert from Markdown to scdoc
2. eventually clean and tidy up the resulting output manually
3. remove the original Markdown input and commit the new scdoc
4. change the build scripts in order to call scdoc instead of pandoc

[jgm]

Thanks. Note: if you just want a lightweight, no dependency man page generator that uses markdown (commonmark) source, cmark itself can do this. https://github.com/commonmark/cmark/blob/master/man/man1/cmark.1

[jgm]

In your first comment you seem to want to use scdoc as an input format; in your reply, you talk of using pandoc to produce scdoc which would then be processed by scdoc itself. Seems that an scdoc writer would be more useful than a reader.

The format seems straightforward and fairly simple, if underspecified. (e.g. how much indent is required for a sublist? Can you include multiple paragraphs under list items, and if so how? if you can't, then what would a pandoc writer do with a list item containing multiple paragraphs?)

[AndersonTorres]

The format seems straightforward and fairly simple, if underspecified. (e.g. how much indent is required for a sublist?

From what I read, indents are hard tabs (no 4 spaces). I have noticed this style in many scdoc pages.

Can you include multiple paragraphs under list items, and if so how?

Following the indentation, I suppose:

Here comes a list

- Item 1

  Here is a text describing item 1

- Item 2

  Here is a text describing item 2

  - Subitem 2.1

    Text describing subitem

  Back to item 2 description

- Item 3

[jgm]

Following the indentation, I suppose:

Have you tried it, though?

[AndersonTorres]

To be honest I did not test this. A truckload of things were in my way this week. I conjectured it by reading the source codes of a small sample of packages that employed scdoc.

Here is a quick test I did:

testfile.scd output.3