~sircmpwn/sr.ht-discuss

14 8

Markdown, readmes and project pages.

Stephen Malone <srmalone@fastmail.fm>
Details
Message ID
<0f3be17d-2ac4-4c3b-83cf-efe0d588bcd4@www.fastmail.com>
DKIM signature
missing
Download raw message
> I think both of these things already work as you describe. Maybe try
capitalizing the file as README.md, as I'm sure that works for me.
> 
> Could you link the particular repo/project page that you're having
trouble with?

The project is https://sr.ht/~rattlerake/sonse/, and it could be that I'm
using Mercurial instead of Git. But I don't think capitalisation should be
a hurdle, surely it's not to difficult to detect readmes case-insensitively?
Details
Message ID
<CJANVJ17JMZ4.333NN0B64GD27@taiga>
In-Reply-To
<0f3be17d-2ac4-4c3b-83cf-efe0d588bcd4@www.fastmail.com> (view parent)
DKIM signature
missing
Download raw message
On Fri Apr 15, 2022 at 7:08 AM CEST, Stephen Malone wrote:
> > I think both of these things already work as you describe. Maybe try
> capitalizing the file as README.md, as I'm sure that works for me.
> > 
> > Could you link the particular repo/project page that you're having
> trouble with?
>
> The project is https://sr.ht/~rattlerake/sonse/, and it could be that I'm
> using Mercurial instead of Git. But I don't think capitalisation should be
> a hurdle, surely it's not to difficult to detect readmes case-insensitively?

We decided not to accomodate every pet naming convention users can come
up with. You should standardize on one of the supported common
conventions.
Stephen Malone <srmalone@fastmail.fm>
Details
Message ID
<cbb91bd7-6683-4da5-b786-67a71aef1b28@www.fastmail.com>
In-Reply-To
<CJANVJ17JMZ4.333NN0B64GD27@taiga> (view parent)
DKIM signature
missing
Download raw message
> We decided not to accomodate every pet naming convention users can come
up with. You should standardize on one of the supported common
conventions.

Forgive me, but a) the only difference is case, and b) the common
conventions are outdated. I'm not trying to be difficult, but in any
reasonable programming language this is a one-line fix. 

I'm guessing you just have a "is this filename in this list of approved
names" check, so couldn't you tack on a .lower() and get this done? 

-- 
Stephen Malone
srmalone@fastmail.fm
Details
Message ID
<CJAO2LNH5M4G.1GYQI6SMKCRNH@taiga>
In-Reply-To
<cbb91bd7-6683-4da5-b786-67a71aef1b28@www.fastmail.com> (view parent)
DKIM signature
missing
Download raw message
The answer is no.
Stephen Malone <srmalone@fastmail.fm>
Details
Message ID
<1a20d00c-28ec-478d-a204-dd88ad4589e4@www.fastmail.com>
In-Reply-To
<CJAO2LNH5M4G.1GYQI6SMKCRNH@taiga> (view parent)
DKIM signature
missing
Download raw message
> The answer is no.

Cool, I'll just switch to GitHub. See you in a couple years when you've achieved minimum functionality.
Details
Message ID
<CJAO8G2NYOGO.1QPWVKTAC78GG@Archetype>
In-Reply-To
<cbb91bd7-6683-4da5-b786-67a71aef1b28@www.fastmail.com> (view parent)
DKIM signature
missing
Download raw message
On Fri Apr 15, 2022 at 10:19 AM CEST, Stephen Malone wrote:
> Forgive me, but a) the only difference is case, and b) the common
> conventions are outdated. I'm not trying to be difficult, but in any
> reasonable programming language this is a one-line fix.

Just my two cents:

a) since case matters in filenames on every platform I am aware of
except Windows, what would happen if we get readme.md, Readme.md, and
ReadMe.md? While the "fix" might be simple, it may have unintended
side-effects which would be a bad idea.

b) Citation needed. Why do you think they are outdated? Especially in
regards to having a README.md (in this case)?

--
Moritz Poldrack
https://moritz.sh
Details
Message ID
<CJBA4CHA4WH9.3CMOH15ZJL2YA@grinningcatface>
In-Reply-To
<CJANVJ17JMZ4.333NN0B64GD27@taiga> (view parent)
DKIM signature
missing
Download raw message
On Fri Apr 15, 2022 at 4:13 AM EDT, Drew DeVault wrote:
> On Fri Apr 15, 2022 at 7:08 AM CEST, Stephen Malone wrote:
> > > I think both of these things already work as you describe. Maybe try
> > capitalizing the file as README.md, as I'm sure that works for me.
> > > 
> > > Could you link the particular repo/project page that you're having
> > trouble with?
> >
> > The project is https://sr.ht/~rattlerake/sonse/, and it could be that I'm
> > using Mercurial instead of Git. But I don't think capitalisation should be
> > a hurdle, surely it's not to difficult to detect readmes case-insensitively?
>
> We decided not to accomodate every pet naming convention users can come
> up with. You should standardize on one of the supported common
> conventions.

So standardize it.
I fully support requiring users to comply with standards, but this
expectation is unreasonable and unfair when there is no such standard —
especially when the fix is as simple as toupper().

Cheers,
-- 
DJ Chase
They, Them, Theirs
Details
Message ID
<CJBAAGAKPVWX.1A8FBLFNMLH79@grinningcatface>
In-Reply-To
<CJAO8G2NYOGO.1QPWVKTAC78GG@Archetype> (view parent)
DKIM signature
missing
Download raw message
On Fri Apr 15, 2022 at 4:30 AM EDT, Moritz Poldrack wrote:
> On Fri Apr 15, 2022 at 10:19 AM CEST, Stephen Malone wrote:
> > Forgive me, but a) the only difference is case, and b) the common
> > conventions are outdated. I'm not trying to be difficult, but in any
> > reasonable programming language this is a one-line fix.
>
> Just my two cents:
>
> a) since case matters in filenames on every platform I am aware of
> except Windows, what would happen if we get readme.md, Readme.md, and
> ReadMe.md? While the "fix" might be simple, it may have unintended
> side-effects which would be a bad idea.

Good point. We could probably get around this by doing something like:

	find repo/ -name 'README*' || find repo/ -iname 'README*'

(I'm aware that Sourcehut is not implemented in shell — it's just an
example.)

Cheers,
-- 
DJ Chase
They, Them, Theirs
Details
Message ID
<CJBC426849SQ.2A8HQSHO3H7LQ@nix>
In-Reply-To
<CJBAAGAKPVWX.1A8FBLFNMLH79@grinningcatface> (view parent)
DKIM signature
missing
Download raw message
On Sat Apr 16, 2022 at 1:47 AM +0000, DJ Chase wrote:
> On Fri Apr 15, 2022 at 4:30 AM EDT, Moritz Poldrack wrote:
> > what would happen if we get readme.md, Readme.md, and ReadMe.md?
>
> Good point. We could probably get around this by doing something like:
>
> 	find repo/ -name 'README*' || find repo/ -iname 'README*'

I think Moritz Poldrack was referring to the case where there are
multiple case-insensitive matches.

On Sat Apr 16, 2022 at 1:39 AM +0000, DJ Chase wrote:
> I fully support requiring users to comply with standards, but this
> expectation is unreasonable and unfair when there is no such standard

IMHO it would be more consistent with SourceHut philosophy if it lets
the users choose, just like how we can choose which repo's README
to be used for a project.  AFAICT SourceHut is only trying to outsmart
users here because other forges also do it.

As far as convention goes, README.md is relatively a new thing.
I understand that it is unwise to support every markup language,
but treating all others as second-class citizen by requiring HTML upload
is against the point of light markup, just like HTML emails.  Users
should be able to choose between content types, and the status quo
of text/plain and text/markdown should be good enough.

Non-markdown markups should be at least treated as plain text (which
they are) and out-of-box rendering should be unsupported because
_it makes the software too complex_, not _we do not like the language_.
Allowing content type choice would also support the more standard
.markdown extension without having to hardcode it.
Details
Message ID
<20220416092505.vklxqmivw3egfncz@meneltarma.localdomain>
In-Reply-To
<CJBA4CHA4WH9.3CMOH15ZJL2YA@grinningcatface> (view parent)
DKIM signature
missing
Download raw message
On 22/04/16 01:39, DJ Chase wrote:
> So standardize it.
> I fully support requiring users to comply with standards, but this
> expectation is unreasonable and unfair when there is no such standard —
> especially when the fix is as simple as toupper().

While mostly being an unwritten tradition, parts of the convention for file 
names in a project directory and their contents, like NEWS, COPYING, AUTHORS, 
etc is documented in the GNU coding standard and manuals for make, autotools, 
etc. README (traditionally being just a plain text file) is part of that 
convention.
Details
Message ID
<CJBUQMRCB4RV.2RNT979AU2PHK@grinningcatface>
In-Reply-To
<20220416092505.vklxqmivw3egfncz@meneltarma.localdomain> (view parent)
DKIM signature
missing
Download raw message
On Sat Apr 16, 2022 at 5:25 AM EDT, Страхиња Радић wrote:
> On 22/04/16 01:39, DJ Chase wrote:
> > So standardize it.
> > I fully support requiring users to comply with standards, but this
> > expectation is unreasonable and unfair when there is no such standard —
> > especially when the fix is as simple as toupper().
>
> While mostly being an unwritten tradition, parts of the convention for file 
> names in a project directory and their contents, like NEWS, COPYING, AUTHORS, 
> etc is documented in the GNU coding standard and manuals for make, autotools, 
> etc. README (traditionally being just a plain text file) is part of that 
> convention.

Being partially documented in a style guide which is rarely followed
outside of its organization (I mean how often do you see

	if (foo)
	    {
	        printf("bar\n");
	    }

in the wild) is far from being standardized. The most common convention
is still just a convention — people can and do break them.

Plus, what about other languages? It's true that software is developed
in English, but personal projects needn't always be.

Forcing one style is redicouls when it's just a convention.

-- 
DJ Chase
They, Them, Theirs
Details
Message ID
<20220416181444.7ti6rtuzhu6xidmw@meneltarma.localdomain>
In-Reply-To
<CJBUQMRCB4RV.2RNT979AU2PHK@grinningcatface> (view parent)
DKIM signature
missing
Download raw message
On 22/04/16 05:48, DJ Chase wrote:
> in the wild) is far from being standardized. The most common convention
> is still just a convention — people can and do break them.

While the parts of GNU coding style dealing with styling C code are limited in 
the actual adoption scope, the convention about the file names is more widely 
used, especially when it comes to the naming of README.

> Plus, what about other languages? It's true that software is developed
> in English, but personal projects needn't always be.

See GNU gettext documentation. According to it, software should be developed 
with English  messages, with the option to be localized. Proponents of other 
programming  philosophies, such as suckless software, go even further and 
usually avoid even  localization as superfluous. 

> Forcing one style is redicouls when it's just a convention.

It is a widely accepted convention for decades among Free software developers, 
though.
Details
Message ID
<CJBVOP7Z9BBB.1VN0GQ800FJ8M@grinningcatface>
In-Reply-To
<20220416181444.7ti6rtuzhu6xidmw@meneltarma.localdomain> (view parent)
DKIM signature
missing
Download raw message
On Sat Apr 16, 2022 at 2:14 PM EDT, Страхиња Радић wrote:
> On 22/04/16 05:48, DJ Chase wrote:
> > Plus, what about other languages? It's true that software is developed
> > in English, but personal projects needn't always be.
>
> See GNU gettext documentation. According to it, software should be developed 
> with English  messages, with the option to be localized. Proponents of other 
> programming  philosophies, such as suckless software, go even further and 
> usually avoid even  localization as superfluous. 

True. That is why I referred specifically to personal projects.

> > Forcing one style is redicouls when it's just a convention.
>
> It is a widely accepted convention for decades among Free software developers, 
> though.

Yes, but there are accepted variations, as mentioned in my most recent
email.

Cheers,
-- 
DJ Chase
They, Them, Theirs
Details
Message ID
<c527f447-da9a-4949-b3e3-530ce4ed9bb7@cosmoborsky.com>
In-Reply-To
<CJBVOP7Z9BBB.1VN0GQ800FJ8M@grinningcatface> (view parent)
DKIM signature
missing
Download raw message
I think it is good to have this discussion, however (as mentioned before) 
it has been reasonably answered multiple times: on the list, irc, and 
maybe other medium.

Apr 16, 2022 14:33:37 DJ Chase <u9000@posteo.net>:
> That document also specifies that...

The GNU document does not seem to be used as a direct source for 
Sourcehut's methology.

> Yes, but there are accepted variations, as mentioned in my most recent
> email.

It is sufficient for projects to choose their conventions, such as 
Sourcehut choosing which standards to follow and which preferences to 
have. README (et al) is a preference.

According to the sr.ht docs[0], README, README.md, and README.markdown 
are the only files accepted for rendering a repo's page (since this could 
be plain text, or use markdown with the parser/renderer that sr.ht 
supports). 
Alternatively, you may choose to render your repo's page and submit the 
HTML manually (which should be possible to automate in a build job if 
desired).

[0]: https://man.sr.ht/git.sr.ht/#readme-and-license-files

> Otherwise, convention is not standard, so we should at least
> do the bare minimum to support slight variations.

Sourcehut does support vartions already... But it does not do the work 
for you, which would only be an issue if it wasn't documented (see 
above).


Since I haven't seen it mentioned in this thread, here are the other 
threads mentioning this topic: 
https://lists.sr.ht/~sircmpwn/sr.ht-discuss/%3C8830212A-2DDD-4BCA-AB0C-534D9B6B1EC7%40traduction-libre.org%3E 
https://lists.sr.ht/~sircmpwn/sr.ht-discuss/%3Cfe7aa296-9c90-463d-b4e6-50eeb7e57428%40localhost%3E#%3CC15MWAA4L1V4.37TIKIXPHV02J@homura%3E
Details
Message ID
<CJBZ6G89S6Q8.3N5I44H919HAQ@grinningcatface>
In-Reply-To
<c527f447-da9a-4949-b3e3-530ce4ed9bb7@cosmoborsky.com> (view parent)
DKIM signature
missing
Download raw message
On Sat Apr 16, 2022 at 4:27 PM EDT, Cosmo Borsky wrote:
> Apr 16, 2022 14:33:37 DJ Chase <u9000@posteo.net>:
> > Yes, but there are accepted variations, as mentioned in my most recent
> > email.
>
> According to the sr.ht docs[0], README, README.md, and README.markdown 
> are the only files accepted for rendering a repo's page (since this could 
> be plain text, or use markdown with the parser/renderer that sr.ht 
> supports). 
> Alternatively, you may choose to render your repo's page and submit the 
> HTML manually (which should be possible to automate in a build job if 
> desired).
>
> [0]: https://man.sr.ht/git.sr.ht/#readme-and-license-files
>
> > Otherwise, convention is not standard, so we should at least
> > do the bare minimum to support slight variations.
>
> Sourcehut does support vartions already... But it does not do the work 
> for you, which would only be an issue if it wasn't documented (see 
> above).

Ah, I did not realize one could do this. This seems like an adaquate
solution; thank you for pointing it out.

Cheers,
-- 
DJ Chase
They, Them, Theirs
Reply to thread Export thread (mbox)