Third-party manual, doc-base side#324
Conversation
|
Comments and reviews wellcome. Build breakage is expected, as manual.xml still does not exist on doc-en. |
| $conf[] = "<!ENTITY % translation-snippets $langTwo2>"; | ||
| $conf[] = "<!ENTITY % translation-extensions $langTwo3>"; | ||
|
|
||
| file_put_contents( __DIR__ . "/../conf.ent" , implode( "\n" , $conf ) ); |
There was a problem hiding this comment.
This will break make in docker because this will write to /var/www, not doc-en. Can we perhaps write to temp instead. It's kinda meant for that.
file_put_contents( __DIR__ . "/temp/conf.ent" , implode( "\n" , $conf ) );
with it's companion:
<!ENTITY % configure SYSTEM "../doc-base/temp/conf.ent">.
If this conflicts, we could also write conf-$lang.ent.
There was a problem hiding this comment.
This will break
makein docker because this will write to /var/www, not doc-en. Can we perhaps write to temp instead. It's kinda meant for that.
The problem is that temp/ is relative to doc-base, but manual.xml now resides in doc-en. I was trying to remove the sibling restriction, but not considered this usage, and yes, it makes sense for now, as other parts/tools simply require doc-en and doc-base to be siblings. I will change it later.
That said, writing the output in /var/www is ok, but building manuals directly in /var/www is very unsafe, as it exposes all sorts executable scripts into the web. Even in local networks it is unwise to do so. Also permissions will get messy, very fast.
Consider setting up the docker with the internal superuser, but then decaying to a local user when doing any directory creations, git clonage and running build scripts. Only then publishing into /var/www that a superuser may be necessary. Running everything as root may cause all sorts of abnormal errors.
There was a problem hiding this comment.
Yes, but we should also assume that the docker for development is a tool, and writing to places other than the repositories would create files at places that are not desired.
Alternatively we could create a temp folder in doc-en and add it to gitignore.
There was a problem hiding this comment.
Add temp/ folder, .gitignor'ed, and changed doc-en side.
2 participants
This is the doc-base side of php/doc-en#5682 , for the splitting of third-party manuals from the main manual, with the minimal conventions possible. I took the path of also minimizing any XML output differences. In fact, the only output change occurs in the DOCTYPE node, the XML is identical. Also, the code is already prepared for any disappearance of actual DTD entity files.
As this is a big change, I plan to leave this open for almost two weeks.
The planned merge order is doc-en 5682 on July 30, and this in July 31. In the meantime, preparing for the actual disappearance of DTD entity files.