From: Bevan Stanely <email@example.com> To: Peter Stephenson <firstname.lastname@example.org>, "email@example.com" <firstname.lastname@example.org> Subject: Re: Proposal: Use Markdown syntax for README and other documentation Date: Thu, 19 May 2022 15:10:47 +0000 [thread overview] Message-ID: <MAXPR01MB2878D9C1AA678996A79DFB3FE9D09@MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM> (raw) In-Reply-To: <email@example.com> [-- Attachment #1: Type: text/plain, Size: 2089 bytes --] I think that's a good idea to move with aim and plan. But could you clarify few things. 1. What do you mean by rendering carefully formatted package documentation? Is it similar to literate programming or something like doxygen? Or markdown will be separate from source files. 2. I thought yodl was the tool currently being used to generate the documentation website. I'm not sure if it's also handling man page generation. Are you considering a substitute for that approach? I do use markdown to write my static website and aware of a couple of good frameworks which uses the markdown as a standard for content. But that can only be a long-term strategy. I considered the markdown formatting and pruning of readme in this pr because it could act as first step in making the documentation more accessible. We could also extend it to all the remaining text files in the root of the repo which do not affect the source or man page generation and bring a structure to the documentation. Note: I'm assuming that these files do not affect the source or man pages. Bevan Stanely bevs.xyz<https://bevs.xyz/> ________________________________ From: Peter Stephenson <firstname.lastname@example.org> Sent: Thursday, May 19, 2022 2:25:18 PM To: Bevan Stanely <email@example.com>; firstname.lastname@example.org <email@example.com> Subject: Re: Proposal: Use Markdown syntax for README and other documentation External Email Markdown's fine for what it's does --- the only requirement I'd suggest before we start using it is that there is a firm plan to do something with it, e.g. integrate it into a website. I've been a bit bemused before staring at carefully formatted package documentation and wondering how I'm supposed to render it and having done a bit of research tentatively concluded I'm probably not supposed to and then wondered what's the point and why I had to go through this exercise in the first place... If there *is* a point, that's another matter. Pruning down README sounds sensible, too, though that probably needs a separate thread. pws [-- Attachment #2: Type: text/html, Size: 3316 bytes --]
next prev parent reply other threads:[~2022-05-19 15:11 UTC|newest] Thread overview: 13+ messages / expand[flat|nested] mbox.gz Atom feed top 2022-05-18 15:41 Bevan Stanely 2022-05-19 1:10 ` Lawrence Velázquez 2022-05-19 4:02 ` dana 2022-05-19 4:26 ` Lawrence Velázquez 2022-05-19 6:04 ` Bevan Stanely 2022-05-19 8:55 ` Peter Stephenson 2022-05-19 15:10 ` Bevan Stanely [this message] 2022-05-19 15:16 ` Peter Stephenson 2022-05-19 15:22 ` Bevan Stanely 2022-05-19 18:23 ` Bevan Stanely 2022-05-19 18:42 ` Bart Schaefer 2022-05-20 5:43 ` Bevan Stanely 2022-05-19 4:29 ` Bart Schaefer
Reply instructions: You may reply publicly to this message via plain-text email using any one of the following methods: * Save the following mbox file, import it into your mail client, and reply-to-all from there: mbox Avoid top-posting and favor interleaved quoting: https://en.wikipedia.org/wiki/Posting_style#Interleaved_style * Reply using the --to, --cc, and --in-reply-to switches of git-send-email(1): git send-email \ --in-reply-to=MAXPR01MB2878D9C1AA678996A79DFB3FE9D09@MAXPR01MB2878.INDPRD01.PROD.OUTLOOK.COM \ --firstname.lastname@example.org \ --email@example.com \ --firstname.lastname@example.org \ --subject='Re: Proposal: Use Markdown syntax for README and other documentation' \ /path/to/YOUR_REPLY https://kernel.org/pub/software/scm/git/docs/git-send-email.html * If your mail client supports setting the In-Reply-To header via mailto: links, try the mailto: link
Code repositories for project(s) associated with this inbox: https://git.vuxu.org/mirror/zsh/ This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for NNTP newsgroup(s).