DevHeads.net

Add installtion instruction

Good afternoon.

as some of you may know, i am currently working on a new design for the php.net website and i came across the installation page[1].

the page contains information about "how to compile php from source" but no "how to install it" and i think this is not a good for newbies.

when i started PHP as a kid, i remember using XMAPP on windows, not because i needed Apache or MySQL, but because the PHP site kept telling me that i need `C runtime`, `VC CRT11` and then i should compile the source code and i didn't know how to do that at the time and everything seemed just complicated.

for this, i suggest that w add a new "installation instructions" to the php website, and move the current pages to a new section called "compile from source".

i have added installation instruction page in the mock ups of the new design, you might take a look at it here : <a href="https://github.com/azjezz/web-php-mock-ups/blob/master/screenshots/windows-installation.png" title="https://github.com/azjezz/web-php-mock-ups/blob/master/screenshots/windows-installation.png">https://github.com/azjezz/web-php-mock-ups/blob/master/screenshots/windo...</a>

[1] : <a href="https://secure.php.net/manual/en/install.php" title="https://secure.php.net/manual/en/install.php">https://secure.php.net/manual/en/install.php</a>

Comments

Re: Add installtion instruction

By Peter Kokot at 02/09/2019 - 08:48

Hello,

On Wed, 6 Feb 2019 at 14:17, azjezz < ... at protonmail dot com> wrote:
The mockups in general looks great. Installation chapter itself is in
need of major refactoring for sure. Some things are not relevant
anymore and many are missing. Basically, what you're after in this
step is the way to go probably - to mention more options how to get up
and running fast. This probably needs to be synced with the options in
the manual or if a separate docs for only installation should be done
here. PHP installation itself is a very large topic. Compilation from
source is part of the PHP installation chapter. Also installing PHP on
Solaris, for example is also relevant. Goal of PHP is to be used on
any system, even Android and exotic things such as micro controllers.
How that works in practice at the moment, is another topic but for an
overview maybe.

Few quick tips:
- There is a migration to Git from SVN happening for the PHP manual.
Yes, the PHP manual is still in SVN at the moment. It is built from
the sources in XML files. Doing some major functionality changes to
the manual means also syncing things with this part and how the manual
is generated.
- There was a discussion happening about PHP.net mirrors getting
removed so that's one of the major things to be done probably with the
php.net site before other steps maybe. Mirrors at the moment block the
https migration and usage and upgrading the website code to PHP
7.2/7.3. There is still PHP 5.3 used. And mirrors mean 80+ webservers.

Re: Add installtion instruction

By azjezz at 02/09/2019 - 13:55

Hello

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

Today i bought a VPS so i can host the mockups for people to see instead of just looking at the screenshots.

I think removing mirrors would be a good step or at least the ones that are using PHP <= 7.2.

Another question i have in mind is, after migrating to GIT, is there any plan to switch to markdown instead of XML ? this would be a really great step for the PHP.net website, as we can host the documentation using GitHub Pages without having to worry about deployment etc. and we would just need to make a theme for Jeklly.

in the next few days i will host the mock ups, and start writing more about PHP installation in different systems and add the `compile from source` section.

as people would expect something like `apt install php` ( or similar command on other OSs ) when trying to install php and get started, not "download a compiler , x and y libraries then try to compile it"

Re: Add installtion instruction

By Ben Ramsey at 02/09/2019 - 17:57

This is a huge question that should involve input from the docs team on the phpdocs mailing list. The XML files are in DocBook format, which has a lot of tools to convert it into various formats (HTML, CHM, etc.), using many different translations. Any effort to switch to something else (Markdown, AsciiDoc, etc.) needs to support the functionality provided by DocBook and needs to ensure that the translations can be maintained.

It’s a lot of work to migrate the documentation project to Git because of the complexities around how the documentation is generated for all the translations. It’ll be even more work to migrate to a different documentation format. As Peter suggested, this might take years.

I suspect the documentation team will choose to stick with DocBook for the foreseeable future. (Though, since it’s all XML, someone could create tools to export the docs into Markdown or any other format, keeping the “source of truth” in DocBook.)

Cheers,
Ben

Re: Add installtion instruction

By azjezz at 02/11/2019 - 17:55

Hello,

Sent with ProtonMail Secure Email.

‐‐‐‐‐‐‐ Original Message ‐‐‐‐‐‐‐

I'm sorry but i don't see how the PHP.net manual is more complicated in any way than docs.microsoft.net ( they have been using GitHub pages for a long time now ).

Translation is not the issue, i think the bigger issue here is the migration from XML to MD.

if we keep on saying "migration is hard, lets wait" we will never do it.
the first step would be to create tools that enable us to migrate to MD and wait till migration to Git from SVN is finished.

Re: Add installtion instruction

By Ben Ramsey at 02/11/2019 - 18:01

I’m not against migrating the documentation to a different format, but like I said, this needs to involve input from the documentation team. It’s not merely a website issue.

Cheers,
Ben

Re: Add installtion instruction

By Peter Kokot at 02/09/2019 - 14:33

Hello,

On Sat, 9 Feb 2019 at 18:56, azjezz < ... at protonmail dot com> wrote:
GitHub pages can do that also fine. And they are simpler to use for
the case of mockups maybe. Only thing is to learn and understand
Jekyll themes and the Liquid template engine. Deployment and stability
works like a charm. Or even better one - Sculpin generator (works in
PHP, Twig templating engine, generates static files) [1].

To get a better overview, this is the PHP manual in XML sources (a
mirror, not for pull requests) [2].

Migrating the PHP manual sources to Markdown would take a very very
long time (I estimate it in several years). Markdown works ok for
smaller documentations. Where not so many references, links,
additional plugins are required. Markdown has options via custom or
3rd party parsers to make it work a bit like these Sphinx, AsciiDoc
and similar generators. One of the good examples is Pandoc. However,
here I would leave the final decisions to move from XML to something
else to other people who are more suitable and who know what this
means. It is a very big step. Too big for only the website remake
"task". Hosting on GitHub pages - I'm not sure this is something for
PHP.net manual... There is also some dynamics happening there, but
don't take me for granted on this part...

Important to understand in this concept is also, that a proper
installation chapter wouldn't discriminate against an Alpine Linux. Or
some FreeBSD. Or Fedora based distributions which don't use apt
package management. Can this be done via patches to existing
documentation first maybe or do you think that the docs format need to
be adjusted somehow for this?

We probably would need to define some frames what we'll be doing here
and what even needs to be done in approximate phases. I'm not sure
what would be the best way to go here yet. More later on...

Have a nice day...

[1] <a href="https://sculpin.io/" title="https://sculpin.io/">https://sculpin.io/</a>
[2] <a href="https://github.com/salathe/phpdoc-en" title="https://github.com/salathe/phpdoc-en">https://github.com/salathe/phpdoc-en</a>