diff --git a/doc/docs.md b/doc/docs.md
index 6b82e1c7cd..7b58e02785 100644
--- a/doc/docs.md
+++ b/doc/docs.md
@@ -3312,8 +3312,6 @@ If a file has an environment-specific suffix, it will only be compiled for that
 - `.c.v` => will be used only by the C backend. These files can contain C. code.
 - `.x64.v` => will be used only by V's x64 backend.
 - `_nix.c.v` => will be used only on Unix systems (non Windows).
-- `_d_customflag.v` => will be used only if you pass `-d customflag` to V.
-That corresponds to `$if customflag ? {}`, but for a whole file, not just a single block.
 - `_${os}.c.v` => will be used only on the specific `os` system.
 For example, `_windows.c.v` will be used only when compiling on Windows, or with `-os windows`.
 - `_default.c.v` => will be used only if there is NOT a more specific platform file.
@@ -3352,6 +3350,15 @@ With the example above:
 - when you compile for any other platform, you will get the
 non specific 'Hello world' message.
 
+- `_d_customflag.v` => will be used *only* if you pass `-d customflag` to V.
+That corresponds to `$if customflag ? {}`, but for a whole file, not just a
+single block. `customflag` should be a snake_case identifier, it can not
+contain arbitrary characters (only lower case latin letters + numbers + `_`).
+NB: a combinatorial `_d_customflag_linux.c.v` postfix will not work.
+If you do need a custom flag file, that has platform dependent code, use the
+postfix `_d_customflag.v`, and then use plaftorm dependent compile time 
+conditional blocks inside it, i.e. `$if linux {}` etc.
+
 ## Compile time pseudo variables
 
 V also gives your code access to a set of pseudo string variables,