Re: Examples of online documentation written with Org-mode

Re: Examples of online documentation written with Org-mode

[Sébastien Gendre]

[[PGP Signed Part:Good signature from B586F7C77239E29E Sébastien Gendre <seb@k-7.ch> (trust ultimate) created at 2024-08-11T04:44:32+0200 using RSA]]
[1. text/plain]
It's a very good example.

Is it more common to make a single file documentation ?

András Simonyi <andras.simonyi@gmail.com> writes:

> Dear All,
>
>> Sébastien Gendre <seb@k-7.ch> writes:
>> > And I search for example of online documentation made with Org-mode. As
>> > inspirations.
>
> AFAIU, the online documentation of the Magit and Borg Emacs packages
> by Jonas Bernoulli were also made using Org (probably with the texinfo
> exporter), see https://magit.vc/manual/magit.html and
> https://emacsmirror.net/manual/borg/ -- their sources can be found at
> https://github.com/magit/magit/blob/main/docs/magit.org and
> https://raw.githubusercontent.com/emacscollective/borg/main/docs/borg.org.
>
> best wishes,
> András

[[End of PGP Signed Part]]

Re: Examples of online documentation written with Org-mode

[Sébastien Gendre]

[[PGP Signed Part:Good signature from B586F7C77239E29E Sébastien Gendre <seb@k-7.ch> (trust ultimate) created at 2024-08-11T04:41:57+0200 using RSA]]
[1. text/plain]
Thank you very much.

I will take a look.


Ihor Radchenko <yantar92@posteo.net> writes:

> Sébastien Gendre <seb@k-7.ch> writes:
>
>> I start to explore Org-mode and org-publish to built online
>> documentation.
>>
>> And I search for example of online documentation made with Org-mode. As
>> inspirations.
>>
>> But after some search, I have only found the Org-mode Worg [1]. Other
>> found are no more online.
>
> One orthodox approach is exporting to .texi -> .html. It is how
> https://orgmode.org/manual/ and
> https://elpa.gnu.org/packages/doc/modus-themes.html are generated.
>
> Another common approach is writing elaborate README.org in
> repositories. There are many examples on GitHub, like
> https://github.com/alphapapa/org-ql/
>
> Many blogs are also made with Org mode. Not sure if it qualifies for
> documentation.
>
> You may also take a look at https://github.com/fniessen/org-html-themes
> (ReadTheOrg), https://orgmode.org/tools.html, and https://orgmode.org/worg/org-blog-wiki.html

[[End of PGP Signed Part]]

Examples of online documentation written with Org-mode

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 360 bytes --]

Hello,

I start to explore Org-mode and org-publish to built online
documentation.

And I search for example of online documentation made with Org-mode. As
inspirations.

But after some search, I have only found the Org-mode Worg [1]. Other
found are no more online.


Best regards

-------
Gendre Sébastien


[1] https://orgmode.org/worg/

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Examples of online documentation written with Org-mode

[Samuel Loury]

[-- Attachment #1.1.1: Type: text/plain, Size: 786 bytes --]

Sébastien Gendre <seb@k-7.ch> writes:

[...]

> And I search for example of online documentation made with Org-mode. As
> inspirations.
>
> But after some search, I have only found the Org-mode Worg [1]. Other
> found are no more online.

I don't know if that helps, but the documentation of clk[fn:1] is in org-mode. I
try hard to use literate programming. All the use cases[fn:2] are made with
babel and tangled into tests so that I am very confidant that what I promise
(hence show in the documentation) is indeed what the end user will be able to
do.

My best,
-- 
Konubinix
GPG Key    : 7439106A
Fingerprint: 5993 BE7A DA65 E2D9 06CE  5C36 75D2 3CED 7439 106A

* Footnotes
[fn:2] https://clk-project.org/doc/use_cases/ 

[fn:1] https://clk-project.org/ 

[-- Attachment #1.1.2: Type: text/html, Size: 1710 bytes --]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 487 bytes --]

Re: Examples of online documentation written with Org-mode

[Sébastien Gendre]

[-- Attachment #1: Type: text/plain, Size: 1015 bytes --]

Thank you very much.

Samuel Loury <konubinix@gmail.com> writes:

> [[PGP Signed Part:No public key for 75D23CED7439106A created at 2024-08-10T14:41:26+0200 using RSA]]
> Sébastien Gendre <seb@k-7.ch> writes: 
>
> […] 
>
>  And I search for example of online documentation made with Org-mode. As inspirations. 
>
>  But after some search, I have only found the Org-mode Worg [1]. Other found are no more online. 
>
> I don't know if that helps, but the documentation of clk1 is in org-mode. I try hard to use literate programming. All the use cases2 are made
> with babel and tangled into tests so that I am very confidant that what I promise (hence show in the documentation) is indeed what the end
> user will be able to do. 
>
> My best, – Konubinix GPG Key : 7439106A Fingerprint: 5993 BE7A DA65 E2D9 06CE 5C36 75D2 3CED 7439 106A 
>
> Notes de bas de page: 
>
> 1
>
> https://clk-project.org/ 
>
> 2
>
> https://clk-project.org/doc/use_cases/ 
>
> [[End of PGP Signed Part]]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 849 bytes --]

Re: Examples of online documentation written with Org-mode

[Ihor Radchenko]

Sébastien Gendre <seb@k-7.ch> writes:

> I start to explore Org-mode and org-publish to built online
> documentation.
>
> And I search for example of online documentation made with Org-mode. As
> inspirations.
>
> But after some search, I have only found the Org-mode Worg [1]. Other
> found are no more online.

One orthodox approach is exporting to .texi -> .html. It is how
https://orgmode.org/manual/ and
https://elpa.gnu.org/packages/doc/modus-themes.html are generated.

Another common approach is writing elaborate README.org in
repositories. There are many examples on GitHub, like
https://github.com/alphapapa/org-ql/

Many blogs are also made with Org mode. Not sure if it qualifies for
documentation.

You may also take a look at https://github.com/fniessen/org-html-themes
(ReadTheOrg), https://orgmode.org/tools.html, and https://orgmode.org/worg/org-blog-wiki.html

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Examples of online documentation written with Org-mode

[András Simonyi]

Dear All,

> Sébastien Gendre <seb@k-7.ch> writes:
> > And I search for example of online documentation made with Org-mode. As
> > inspirations.

AFAIU, the online documentation of the Magit and Borg Emacs packages
by Jonas Bernoulli were also made using Org (probably with the texinfo
exporter), see https://magit.vc/manual/magit.html and
https://emacsmirror.net/manual/borg/ -- their sources can be found at
https://github.com/magit/magit/blob/main/docs/magit.org and
https://raw.githubusercontent.com/emacscollective/borg/main/docs/borg.org.

best wishes,
András

Re: Examples of online documentation written with Org-mode

[mbork]

On 2024-08-10, at 17:13, Ihor Radchenko <yantar92@posteo.net> wrote:

> Many blogs are also made with Org mode. Not sure if it qualifies for
> documentation.

If I may put a shameless plug here, one of my blogs
(https://crimsonelevendelightpetrichor.net, not terribly active ATM) is
written entirely in Org.  The whole content (with the exception of
binary assets like images and fonts) is produced from a single Org file
(this includes HTML templates and CSS) using my custom blog engine
(https://gitlab.com/mbork_mbork_pl/org-clive).  It is a testament to the
power of Org that Org Clive is less then 400 lines of Elisp - most of
the heavy lifting is done by Org itself.

Hth,

-- 
Marcin Borkowski
https://mbork.pl
https://crimsonelevendelightpetrichor.net/

Re: Examples of online documentation written with Org-mode

[Ihor Radchenko]

mbork@mbork.pl writes:

> On 2024-08-10, at 17:13, Ihor Radchenko <yantar92@posteo.net> wrote:
>
>> Many blogs are also made with Org mode. Not sure if it qualifies for
>> documentation.
>
> ... my custom blog engine
> (https://gitlab.com/mbork_mbork_pl/org-clive).  It is a testament to the
> power of Org that Org Clive is less then 400 lines of Elisp - most of
> the heavy lifting is done by Org itself.

Note that it is listed in https://orgmode.org/tools.html since long ago ;)

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Examples of online documentation written with Org-mode

[Phil]

* [2024-08-11 08:19] Ihor Radchenko:
> mbork@mbork.pl writes:
> 
>> On 2024-08-10, at 17:13, Ihor Radchenko <yantar92@posteo.net> wrote:
>>
>>> Many blogs are also made with Org mode. Not sure if it qualifies for
>>> documentation.
>>
>> ... my custom blog engine
>> (https://gitlab.com/mbork_mbork_pl/org-clive).  It is a testament to the
>> power of Org that Org Clive is less then 400 lines of Elisp - most of
>> the heavy lifting is done by Org itself.
> 
> Note that it is listed in https://orgmode.org/tools.html since long ago ;)
> 

Mine too (https://gitlab.com/7dnz/org-weblog) lands in this
category, with an emphasize on a — very verbose I admit — but strict
literate programming. It's a 99KB file, with tests, attempts,
explanations, explorations, etc.
The page documentation is produced as blog post by evaluating
directly from the code and documentation being redacted.

It doesn't use the tangle processor but evaluates one section
after the other. This is how I learned Lisp. It may stay as a
beginner's work forever but I don't mind, it works, and I like it.

Here are the functions it lacks to make it a complete blogging engine :
search, archival by year/month, previous/next post, pagination, one 
folder by post, and a few custom properties :
the author of a post and a custom stylesheet per post among others.

Cheers

--
Philippe Estival
https://7d.nz

Re: Examples of online documentation written with Org-mode

[Ihor Radchenko]

Phil <pe@7d.nz> writes:

>> Note that it is listed in https://orgmode.org/tools.html since long ago ;)
>> 
>
> Mine too (https://gitlab.com/7dnz/org-weblog) lands in this
> category, with an emphasize on a — very verbose I admit — but strict
> literate programming. It's a 99KB file, with tests, attempts,
> explanations, explorations, etc.
> The page documentation is produced as blog post by evaluating
> directly from the code and documentation being redacted.
>
> It doesn't use the tangle processor but evaluates one section
> after the other. This is how I learned Lisp. It may stay as a
> beginner's work forever but I don't mind, it works, and I like it.
>
> Here are the functions it lacks to make it a complete blogging engine :
> search, archival by year/month, previous/next post, pagination, one 
> folder by post, and a few custom properties :
> the author of a post and a custom stylesheet per post among others.

While reading it, I did not immediately figure out what that thing is
for and how to use it. There is even no license.

I recommend going through the process of publishing package via
ELPA/non-GNU ELPA. It will give you a chance to improve the code, docs,
and polish the package in general.

For now, it looks more like a personal config file; not like a project
to be used by others.

https://one.tonyaldon.com/docs/getting-started/ (one.el) project appears
to have a similar spirit. You may get an inspiration from there.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Examples of online documentation written with Org-mode

[Phil Estival]

* [2024-08-11 18:39] Ihor Radchenko:
> Phil <pe@7d.nz> writes:
> 
>> (https://gitlab.com/7dnz/org-weblog) lands in this
>> category, with an emphasize on a — very verbose I admit — but strict
>> literate programming. It's a 99KB file, with tests, attempts,
>> explanations, explorations, etc.
>> The page documentation is produced as blog post by evaluating
>> directly from the code and documentation being redacted.
>>
>> It doesn't use the tangle processor but evaluates one section
>> after the other. This is how I learned Lisp. It may stay as a
>> beginner's work forever but I don't mind, it works, and I like it.
>>
> 
> While reading it, I did not immediately figure out what that thing is
> for and how to use it.

Hi. An other reader interested in the topic got it right.
https://gitlab.com/7dnz/org-weblog/-/issues/1
We had a few words by email last year. CCing him.

> For now, it looks more like a personal config file; not like a project
> to be used by others.

Was your intent really to write that ?
Because you well know a personal config file is something else.

 > There is even no license.

Everybody is free to ask, preferably nicely, if someone else is
willing to license or re-license code. This is an open source community
after all and source is open indeed.

> https://one.tonyaldon.com/docs/getting-started/ (one.el) project appears
> to have a similar spirit. You may get an inspiration from there.

Saw the presentation at the last Emacs conf'.
The common ground is a static site generator for Emacs+org
but the spirit is different.

Don't get me wrong, I'm not looking for inspiration and I already wrote
and discussed requirements and specifications for such a project.
As I said /supra/ I don't mind letting it the current state.

 > I recommend going through the process of publishing package via
 > ELPA/non-GNU ELPA. It will give you a chance to improve the code,
 > docs, and polish the package in general.

Have I some energy and motivation left, I would do so. But Since I'm
not trying to shine among the community — and I'm not saying it's a bad
thing, I prefer to share raw materials for learning purposes rather
than go through one more standard procedure in the era of total
bureaucracy. I was just demonstrating what, IMHO, works smooth for
online documentation.

Phil

Re: Examples of online documentation written with Org-mode

[Ihor Radchenko]

Phil Estival <pe@7d.nz> writes:

>> For now, it looks more like a personal config file; not like a project
>> to be used by others.
>
> Was your intent really to write that ?
> Because you well know a personal config file is something else.

I guess I formulated it inaccurately - it is not obvious how to use it
from a quick glance.

I think that I also need to clarify the scope of my reply.  I am commenting
assuming that you want your project to be added to org-tools page. Is it
the case or did I misunderstand you?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: Examples of online documentation written with Org-mode

[Thomas Redelberger]

All pages of my personal web-site are written in Org (except for sitemap):
  https://web222.webclient5.de

I have documented how I use the built-in org to html export:
  https://web222.webclient5.de/doc/swdev/emacs/orgmode/html

I do not use org-publish.
The navigation, headers and footes of my site are generated using XSLT, CSS and a few python scripts, which are open source:
  https://web222.webclient5.de/prj/content/trgensit
A ZIP file contains also tree-like documentation (i.e. multiple HTML files), which was generated by the package...
I did /not/ include the org sources of the pages - only resulting HTML - to avoid confusing those that might want to use the site generator without org.

Best regards
Thomas
--
Thomas Redelberger
redetho@gmx.de

Am 11.08.2024 um 09:59 schrieb Phil:
>
>
>
>
>
> * [2024-08-11 08:19] Ihor Radchenko:
>> mbork@mbork.pl writes:
>>
>>> On 2024-08-10, at 17:13, Ihor Radchenko <yantar92@posteo.net> wrote:
>>>
>>>> Many blogs are also made with Org mode. Not sure if it qualifies for
>>>> documentation.
>>>
>>> ... my custom blog engine
>>> (https://gitlab.com/mbork_mbork_pl/org-clive).  It is a testament to the
>>> power of Org that Org Clive is less then 400 lines of Elisp - most of
>>> the heavy lifting is done by Org itself.
>>
>> Note that it is listed in https://orgmode.org/tools.html since long ago ;)
>>
>
> Mine too (https://gitlab.com/7dnz/org-weblog) lands in this
> category, with an emphasize on a — very verbose I admit — but strict
> literate programming. It's a 99KB file, with tests, attempts,
> explanations, explorations, etc.
> The page documentation is produced as blog post by evaluating
> directly from the code and documentation being redacted.
>
> It doesn't use the tangle processor but evaluates one section
> after the other. This is how I learned Lisp. It may stay as a
> beginner's work forever but I don't mind, it works, and I like it.
>
> Here are the functions it lacks to make it a complete blogging engine :
> search, archival by year/month, previous/next post, pagination, one folder by post, and a few custom properties :
> the author of a post and a custom stylesheet per post among others.
>
> Cheers
>
> --
> Philippe Estival
> https://7d.nz
>

Re: Examples of online documentation written with Org-mode

[Juergen Fenn]

Am 10.08.24 um 09:50 Uhr schrieb Sébastien Gendre:
> And I search for example of online documentation made with Org-mode. As
> inspirations.

FWIW, last autumn, I switched my introduction to TeX and Friends for my
personal website from XHTML to Org.

https://github.com/schneeschmelze/l2intro
http://juergenfenn.de/tex.html

Best regards,
Jürgen.

Re: Examples of online documentation written with Org-mode

[Steve Downey]

[-- Attachment #1: Type: text/plain, Size: 802 bytes --]

A lot of things aren't going to necessarily advertise themselves as org
mode source?
Almost every post at sdowney.org is org mode originally.
A few ISO C++ papers I've written are also, for example,
https://wg21.link/P3199R0, source and exporter at
https://github.com/steve-downey/wg21org/blob/main/homework-tokyo.org





On Sat, Aug 10, 2024 at 3:51 AM Sébastien Gendre <seb@k-7.ch> wrote:

> Hello,
>
> I start to explore Org-mode and org-publish to built online
> documentation.
>
> And I search for example of online documentation made with Org-mode. As
> inspirations.
>
> But after some search, I have only found the Org-mode Worg [1]. Other
> found are no more online.
>
>
> Best regards
>
> -------
> Gendre Sébastien
>
>
> [1] https://orgmode.org/worg/
>

[-- Attachment #2: Type: text/html, Size: 1366 bytes --]