Documentation sources and command online playground initiative

Questions and postings pertaining to the development of ImageMagick, feature enhancements, and ImageMagick internals. ImageMagick source code and algorithms are discussed here. Usage questions which are too arcane for the normal user list should also be posted here.
Post Reply
cancerberosgx
Posts: 10
Joined: 2019-07-02T18:53:00-07:00
Authentication code: 1152

Documentation sources and command online playground initiative

Post by cancerberosgx » 2019-07-31T18:55:14-07:00

Hello, I would like to contribute to ImageMagick documentation site but I'm not sure which repository is the "source of truth".

My concrete question is:

What are the sources of what it seems the oficial / updated reference at https://imagemagick.org/script/ . Is it https://github.com/ImageMagick/Website ? or is it https://github.com/ImageMagick/ImageMag ... master/www ? They both have to contain the same material but I would like to know which is the source. Also some rough description of how the documentation is published would be awesome (and for example some scripts, etc)

Also, is it correct to assume that Usage examples (https://www.imagemagick.org/Usage) is not open source ?

* What's the role of https://github.com/ImageMagick/usage-markdown ? Is that project active ? does it contain any relevant content?- what's the idea with that technology?

My motivation is the following.

I'm currently having good experiences with ImageMagick WebAssembly builds that perform acceptably in the browser and support all the libraries / formats / capabilities. The API is just plain old magick / convert / montage / etc commands. So I think is a nice initiative to see how the current documentation would look like if users are able to run and modify these commands directly in the browser. Something like a play button on each command line example that pup ups a playground like the following in the same page: https://cancerberosgx.github.io/demos/m ... layground/

For me, adding this feature to each example is a mechanical process. And if it seems too invasive it could be just a link to another page (with the example defined in the URL) instead of a dialog. The thing is, an interactive documentation like this would be awesome, will help people understand and learn this no-easy technology by just playing around online. And most importantly, is easy to implement.

I'm not interested on changing current technologies or processes, just to prototype this in a couple of pages and present it back to you to discuss, but first of all I would like to know what project should I clone. So,

Also I would like to add some of the examples from ttps://www.imagemagick.org/Usage, relevant to the page topicafter asking permission to the author. And finally I would like to add basic links for navigation to parent / related docs, in leaf pages like http://www.imagemagick.org/script/compare.php (you cannot "go back" - there's no clear documentation structure)

The project indeed has lots learning resources but IMO it's kind of spread and sometimes not clear the role of each kind of different page/website. I think this initiative (the playground one) could help to better relate / link reference like material and tutorials / examples.

Thanks!

User avatar
magick
Site Admin
Posts: 11016
Joined: 2003-05-31T11:32:55-07:00

Re: Documentation sources and command online playground initiative

Post by magick » 2019-08-02T16:04:58-07:00

The authoritative website source is @ https://github.com/ImageMagick/Website. We have a script that generates the ImageMagick website @ https://imagemagick.org from the authoritative website source. https://www.imagemagick.org/Usage is a contributed website that we do not maintain. Anthony does, a former ImageMagick developer. https://github.com/ImageMagick/usage-markdown is an attempt to convert https://www.imagemagick.org/Usage to MarkDown to make it amendable to user contributed edits.

To make changes to the authoritative website source, you can post a git pull request.

cancerberosgx
Posts: 10
Joined: 2019-07-02T18:53:00-07:00
Authentication code: 1152

Re: Documentation sources and command online playground initiative

Post by cancerberosgx » 2019-08-14T07:09:52-07:00

magick wrote:
2019-08-02T16:04:58-07:00
The authoritative website source is @ https://github.com/ImageMagick/Website. We have a script that generates the ImageMagick website @ https://imagemagick.org from the authoritative website source. https://www.imagemagick.org/Usage is a contributed website that we do not maintain. Anthony does, a former ImageMagick developer. https://github.com/ImageMagick/usage-markdown is an attempt to convert https://www.imagemagick.org/Usage to MarkDown to make it amendable to user contributed edits.

To make changes to the authoritative website source, you can post a git pull request.
In my case I really need to simulate the user experience locally but I couldn't generate a usable website from the sources at https://github.com/ImageMagick/Website Do you know which software / commands should I use ? I posted an issue asking this there too. The "script that you have" is it published there ? Could you please share the link if so? Or at least a workaround so the website is navigable as static pages ? Thanks

User avatar
fmw42
Posts: 25274
Joined: 2007-07-02T17:14:51-07:00
Authentication code: 1152
Location: Sunnyvale, California, USA

Re: Documentation sources and command online playground initiative

Post by fmw42 » 2019-08-14T08:56:10-07:00

You can install from source. Then modify it as you desire. See

https://imagemagick.org/script/install-source.php#unix
https://imagemagick.org/script/advanced ... lation.php
https://imagemagick.org/download/delegates/

What I do in that regard on my Mac is to install all the delegates from MacPorts. Then install ImageMagick from source. See https://www.imagemagick.org/discourse-s ... rts#p88202

Post Reply