tech-toolchain archive

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index][Old Index]

Re: adding src/

On 10.10.2018 12:36, wrote:
> On Wed, Oct 10, 2018 at 11:31:43AM +0200, Kamil Rytarowski wrote:
>> I'm in favor of plain text (README without .md extension) that is
>> syntactically markdown compatible and in the same time not hyped with a
>> currently popular format, file extensions or the currently popular set
>> of extensions for Markdown (GitHub uses so called "Flavored Markdown",
>> probably everybody uses a set of extensions).
>> This plain text will be forward compatible.
>> (Also Markdown is triggering some people, especially in the *roff
>> circles. Additionally Markdown is not the only one supported by GitHub,
>> there are rdoc, textile, org, creole, rst, asciidoc etc.)
> I don't have a strong opinion on documentation formats, other than
> carries a big benefit. I've mentioned that "introduction user
> time is very important", and markdown helps me shave a small amount of
> time by having [text](link), which allowed e.g. to insert an IRC webchat
> link at no cost, which benefits people who are not familiar with
> freenode on IRC.
> If GitHub tomorrow decides to only display text written backwards, I'll
> rewrite it backwards without even questioning it.
>> I would reuse the existing project description rather than crafting
>> something new from scratch with biased usage options.
>> I've copy-pasted project description and stored it here:
>> It contains quick introduction, explanation what is the project about,
>> building introduction, testing introduction and useful resources.
>> I've omitted: biased command line for building the release, currently
>> popular mirror and currently popular VCS.
> I am however very opinionated about the choices made here.
> - The existing project description is very long. The second section here
> is more characters than my entire, without even accounting
> for URLs.
> I've made a similar change to the homepage:
> - Similarly, you've spent 8 lines of text describing what tests are for,
> and 5 lines of text on implementation details of our testing framework.
> That kind of information is only relevant once I am interested in
> copying or modifying the tests.
> It isn't hard to reach information about test details once you know about
> 'atf-run |atf-report', all our documentation is available as man
> <command>, and man atf-run / atf-report cross-reference atf(7).
> - I realize that my own command is very opinionated, but I
> think it's more important to have a command that you can copy and will
> work or nearly work for many users than to be neutral.
> - The argument to dropping anoncvs makes sense if viewed from an active
> mirror already, but I am considering the case where the mirror becomes
> out of date (e.g. a fork).
> AnonCVS isn't a personal preference, but the closest thing to a
> canonical source that is publicly accessible.
> The very day we change away from CVS I will happily change it :-)
> - Ideally, for most users, building will work right away. I don't want
> to give them any indication it won't.
> If we want to warn them that a C++ compiler is necessary, I would
> prefer to do it via a quick sanity test in (or another
> script) than pay the cost in documentation.
> Similarly, I've made a change to warn if ./ -x is used without
> an appropriate xsrc.
> - I agree that a description of the source tree might be handy. I'd
> rather do it differently and take advantage of whitespace where
> possible, and only mention the directories more commonly edited, e.g. a
> first try:
> sys/		kernel sources
> sys/dev		device drivers
> sys/arch	architecture-specific code
> usr.bin/	sources for programs in /usr/bin
> external/	software maintained outside of NetBSD (like the compiler)
> [man hier(7)](valid URL to man hier) includes more detail.
> The intention here is:
> Omit usr.sbin/, bin/, sbin/ descriptions by mentioning only one of the
> cases, the rest can be inferred.
> tools/ is rarely something that people have to edit, so it's not worth
> mentioning.
> And so on.
> I hope that the additional details about why I make the opinionated
> decisions help to explain why I have done things that way. While my
> is short, it went through multiple revisions and received some
> feedback. I carefully thought about why to do things that way.

I would put biased quick introduction on wiki, on a page like 10minute-start or similar and keep
README for generic introduction what the source tree is about.

Attachment: signature.asc
Description: OpenPGP digital signature

Home | Main Index | Thread Index | Old Index