> 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?
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.
> 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
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
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
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
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.
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.
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
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.
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
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%3Ehttps://lists.sr.ht/~sircmpwn/sr.ht-discuss/%3Cfe7aa296-9c90-463d-b4e6-50eeb7e57428%40localhost%3E#%3CC15MWAA4L1V4.37TIKIXPHV02J@homura%3E
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