Simplify project creation and recreate the default setup example.

[adamreichold]

Also avoids a TOCTOU issue when creating projects.

@mlange-42 I wonder if we should change the file extensions now that we are limited to Markdown: The document is usually almost-valid Markdown as well even if has unresolved transclusions and such. Hence it could make sense to drop README.md.md and just use README.md resp. <file> instead of <file>.md as the main file?

[mlange-42]

I was already thinking about simplifying the project as created by create, and also about getting rid of the .md.md. Now that features are well explained in the book, I also don't see the need for including a lot of features in it.

The problem with the double extension, however, is that the file: feature would be required for the entrypoint. It would thus already completely rely on a more advanced feature.

I think we now have two very different approaches how to structure a project. The "old" one (main.rs.md -> main.rs) is useful for small one-file projects, like a single algorithm, while the "new" one, for larget projects, would use a file README.md as the main document and do everything with file: or links and transclusions (the latter generating file: blocks).

So the question is which approach to chose for project setup.

[mlange-42]

Further, I was asking myself whether we should remove all the comments from the Yarner.toml tempate, now that all options are explained in the book. It looks quite cluttered and confusing. It may, however, still be useful to provide that information to users without requiring them to open the website. Not really sure...

[adamreichold]

So the question is which approach to chose for project setup.

I think we should stick we the README.md as the main file.

The problem with the double extension, however, is that the file: feature would be required for the entrypoint. It would thus already completely rely on a more advanced feature.

We could try to automatically detect the case where the document source already ends in .md just not remove the suffix in that case? If someone really needs .md being removed, they could use file:. Then again, this kind of implicit assumption might make the whole thing harder to understand?

It may, however, still be useful to provide that information to users without requiring them to open the website.

I think this is usually the motivation for including comments. So I'd say we should either provide a really minimal configuration template without comments or defaults, or stick to the full blown one we currently have. Personally, I prefer the minimal version because I like the defaults to update automatically, but this a bit of a cultural schism AFAIK.

[mlange-42]

We could try to automatically detect the case where the document source already ends in .md just not remove the suffix in that case?

Not sure if I understand correctly. Do you mean detect it during project creation, or during the build process?

It you are referring to the build process, shouldn't we detect the cases where there is no "double extension" and write to an .md file in these cases?

Otherwise, if our refer to project creation, it should be "where the document source already ends in .md just not add the suffix in that case"

Or rather, we need both then?

Personally, I prefer the minimal version but I like the defaults to update automatically...

Not really sure what you mean here

[adamreichold]

It you are referring to the build process, shouldn't we detect the cases where there is no "double extension" and write to an .md file in these cases?

I was referring to the build process. We currently "print" foo.bar.md.md into docs/foo.bar.md AFAIU. I would suggest to relax for Markdown files only and "print" foo.bar.md into docs/foo.bar.md as well.

Not really sure what you mean here

For example, all keys under [parser] have defaults and hence could be omitted from Yarner.toml. This would imply that if these defaults ever change, the user will automatically start working with the new defaults. This could be considered useful but also problematic as it might break the current document.

[adamreichold]

I was referring to the build process. We currently "print" foo.bar.md.md into docs/foo.bar.md AFAIU. I would suggest to relax for Markdown files only and "print" foo.bar.md into docs/foo.bar.md as well.

Now, I am very confused: We are actually writing docs/README.md.md? Why is that?

[mlange-42]

We currently "print" foo.bar.md.md into docs/foo.bar.md AFAIU.

No. From a file file.ext.md, with an unnamed code block, we generate:

• docs/file.ext.md
• code/file.ext

This could be considered useful but also problematic as it might break the current document.

I would definitely prefer to leave the default in there.

[mlange-42]

Now, I am very confused: We are actually writing docs/README.md.md? Why is that?

I was a bit too slow... 😄

It is for consistency only, and should become clear with another "first" extension as in my above example.

[adamreichold]

Now, I am very confused: We are actually writing docs/README.md.md? Why is that?

I think my confusion stems from writing "documentation", i.e. "README.md" into the "code" output. Maybe we should restructure the example to use "README.md" as the document source, creating "docs/README.md" as the documentation and "code/Cargo.toml" and "code/src/main.rs" as the code output?

Thinking a bit further, does the "code" and "docs" split really make sense for Markdown-based projects? Do we want to distribute those separately? Writing a "code/README.md" as-if this was no literate programming project at all?

[mlange-42]

Maybe we should restructure the example to use "README.md" as the document source, creating "docs/README.md" as the documentation and "code/Cargo.toml" and "code/src/main.rs" as the code output?

Yes, I think this is the best option. Although it "skips" the most simple usage pattern of an unnamed code block as entrypoint.

Thinking a bit further, does the "code" and "docs" split really make sense for Markdown-based projects? Do we want to distribute those separately? Writing a "code/README.md" as-if this was no literate programming project at all?

An interesting consideration. I think currently the best approach when documentation output is required (as with, e.g., transclusions) and the sources can't be used directly (as we did in the ECS tutorial) is like this:

• Have Markdown sources in a sub-folder of the project, e.g. lp. And then:
• root = "lp"
• code_dir = "../code" (may even be ignored be gitignore)
• doc_dir = "..", I.e. the output README.md would be at the toplevelof the project

project
  |-- lp (root)
  |    `-- README.md (source)
  |-- code (code output)
  |    |-- Cargo.toml
  |    `-- src
  |         `-- main.rs
  |-- README.md (doc output)
  `-- Yarner.toml

It would also be possible to have code_dir and code_dir point to the same directory, which would result in the behaviour you suggested. But I am not sure if that could result in any conflicts. But the above example could, too.

I am away now for an hour or so...

[adamreichold]

Yes, I think this is the best option. Although it "skips" the most simple usage pattern of an unnamed code block as entrypoint.

Will do. But shouldn't we just remove the "main_file" argument then as the name "README.md" is pretty much set then. "yarner create" would also be a bit simple to get started?

I think currently the best approach when documentation output is required.

I suggest we stick to modifying the default project structure as above and defer this discussion to the book?

[mlange-42]

Will do. But shouldn't we just remove the "main_file" argument then as the name "README.md" is pretty much set then.

You mean the CLI argument? If users want a different main file (e.g. main.rs.md), they would have to rename the file and change the files option in the toml.

But I agree to go this route. 👍

[mlange-42]

Or the main_file CLI argument could also be optional and default to README (without extension then?)

[adamreichold]

Or the main_file CLI argument could also be optional and default to README (without extension then?)

I would leave it out completely as the contents of the README will be useless for a "main.rs.md" which I think will be more confusing than just replacing the it manually.

[mlange-42]

But then, when it really takes no parameters, I would prefer to indeed rename create to init.

[adamreichold]

Ok, I tried to update as discussed. Please have a look. I guess we also need to update the guide... :-\

[adamreichold]

On second thought, I will back out the last commit as this implies much changes in other places than I am willing to commit to right now... So this stays limited to refactoring and only discussing on file creation needs to rechecked against the latest version.

[mlange-42]

So the massive changes go to another MR as I understand? Fine! For what changed here: approved!