Docs don't tell users exactly where to put special files and directories

[Ra2-IFV]

Bad

If a file called .chezmoi.$FORMAT.tmpl exists then chezmoi init will use it to create an initial config file.
If a directory called .chezmoitemplates exists,
If a file called .chezmoiversion exists,

Okay

If a file called .chezmoiexternal.$FORMAT (with an optional .tmpl extension) exists in the source state (either ~/.local/share/chezmoi or directory defined inside .chezmoiroot),
If a file called .chezmoidata.$FORMAT exists in the source state,
......

The phrase source state may be replaced with source directory, just as the variable sourceDir in configuration file.

My solution example:

.chezmoi.$FORMAT.tmpl

This file should be placed in the source directory.
This file will be used by chezmoi init to create an initial config file. $FORMAT must be one of the supported config file formats, e.g. json, jsonc, toml, or yaml. Templates defined in .chezmoitemplates are not available because the template is executed before the source state is read.

[Ra2-IFV]

I would be grateful if I could be given the opportunity to open a pull request.

[halostatue]

Please do. We'll review each contribution and accept, have suggestions, or reject as appropriate.

Do note that on Windows the locations will differ.

[Ra2-IFV]

Yes of course, this is just a example, just wondering if this idea would be accepted.
If so I wish to stay in touch with developers to make a good contribution 😉

[halostatue]

In general, we want to encourage all sorts of contributions, including documentation updates. There is always room for improvement. Whether a particular change is a good one depends on a number of factors that we can't judge in advance of seeing the proposed changes.

[twpayne]

The phrase source state may be replaced with source directory, just as the variable sourceDir in configuration file.

This is not correct. The source state is computed from the source directory, but they are not the same thing. Please read the section on concepts.

[Ra2-IFV]

The phrase source state may be replaced with source directory, just as the variable sourceDir in configuration file.

This is not correct. The source state is computed from the source directory, but they are not the same thing. Please read the section on concepts.

Yes source state can be changed in .chezmoiroot file, I'm a bit confused, sorry 😕

[Ra2-IFV]

I plan to do changes like this:

From

includeTemplate filename [data]

includeTemplate returns the result of executing the contents of filename with the optional data. Relative paths are first searched for in .chezmoitemplates and, if not found, are interpreted relative to the source directory.

To

includeTemplate filename [data]

Fields	Usage
filename	The file name you wish to use to include.
data	Optional, data to pass to the template.

includeTemplate returns the result of executing the contents of filename with the optional data. Relative paths are first searched for in .chezmoitemplates and, if not found, are interpreted relative to the source directory.

---

EDIT: Is the word path better than filename ? since it can be a relative path.
Just example, trying to make it easier to understand.
Also, I think we should move some contents like Usage and Syntax from User guide to Reference, like this:

From

.chezmoiroot

If a file called .chezmoiroot exists in the root of the source directory then the source state is read from the directory specified in .chezmoiroot interpreted as a relative path to the source directory. .chezmoiroot is read before all other files in the source directory.

To

.chezmoiroot file

Should be placed in the root of the source directory.
If this file exists, then the source state is read from the directory specified in this file, and interpreted as a relative path to the source directory. .chezmoiroot is read before all other files in the source directory.

*Placeholder for examples and explains, like Advanced/Customize your source directory*

---

Meanwhile, remove the section Use a subdirectory of your dotfiles repo as the root of the source state from Advanced/Customize your source directory
It may be not necessary, but if possible, write a page to explain words like source directory working tree source state to avoid confusion.

[halostatue]

I like the first changes — the main caveat is that for any description of template function parameters that is more than a few words, you would be better switching to <table>…</table> instead of markdown tables.

I do not care for the second change as it looks like a parameter, not a specification of the type of entry that .chezmoiroot is. There are also wording issues (as I understand it, it is not a "should be placed", but "must be placed") and I believe that it should be "root of the working tree", although that is fixing already existing documentation.

[twpayne]

I agree with @halostatue.

[Ra2-IFV]

Thanks for feedbacks.

you would be better switching to

… instead of markdown tables.

You mean the html <table> tag? Not sure if it could be rendered properly at here. I only know Github supports Markdown syntaxs. Also the docs are generated with MkDocs, does it support html tags?
EDIT: It does

I do not care for the second change as it looks like a parameter, not a specification of the type of entry that .chezmoiroot is

I agree, maybe we should put files and directories in two sub sections.

[halostatue]

Yes. Markdown processors must support a fairly large subset of HTML tags (see HTML Blocks in the CommonMark spec‡) which may suspend markdown processing°.

Splitting files and directories won’t really work well because of .chezmoidata. Regardless of whether you use a .chezmoidata directory or .chezmoidata.$FORMAT, the end result is the same.§

‡ I don't like the CommonMark spec, but it's a reasonably complete description of what most parsers do, even if the results are incompatible with Gruber's original Perl implementation.

° This is something worth testing. In GitHub, if you do something like:

<details><summary>Summary</summary>

Because there's a blank line *after* the **tag**:
- Markdown parsing is resumed.
- The closing tag can live with the text.</details>

You will get:

Summary

Because there's a blank line after the tag:

• Markdown parsing is resumed.
• The closing tag can live with the text.

You might be able to take advantage of this within a block tag (<td> and <details> are block tags) for tables that require multiple lines. It will do weird things in an inline tag (<summary> is an inline tag).

§ I do think it’s worth extending the chezmoidata documentation so it's clearer what .chezmoidata/ does differently and putting that in its own example. But I think that the directory and file documentation belong together.