why a txt format?

[redbow-kimee]

I've been looking over some of these creditstxt repositories, and most of them seem to advocate the tracking and distribution of a credits.txt format, even for web and other multimedia applications. How come a more structured format was not chosen, such as XML? While I understand the appeal of a txt format for a text application, I think that both a web and a text form could be generated from a single XML using XSL stylesheets?

[doriantaylor]

@kemitchell will have to confirm but my understanding of the mission of this thing is to behave something akin to humans.txt, i.e., be easy for ordinary people to write, deploy, read, and understand. As such, a structured, machine-readable attribution list is not only out of scope for this project, it's arguably orthogonal.

A structured format would indeed be valuable; it's a safe bet there is already coverage in RDF vocabularies for most if not all of the semantics. One could likewise imagine connecting the human-readable credits.txt to a machine-readable representation with a Link: header like so:

Link: </.well-known/credits.rdf>; rel="alternate"

[kemitchell]

@doriantaylor structured data is better than not structured data, but I wouldn't want to get too lost in the technical details. Unstructured credits have done very well in a variety of other creative fields, and would be a 90+% improvement over what software has now.

If we prescribed some kind of format, I'd rather do something extremely lightweight, in plain text, so that credits are still readable, in a non-alienating way, by people who aren't software developers. One of the vignettes I see in my mind's eye in thinking about credits.txt is something developers can point to on a screen during an interview, or show to their parents, to impress. I don't think XML (or JSON, or YAML, or TOML) would have the same effect.

[ioistired]

As much as I dislike YAML, I think it could work really well here. In fact, https://creditstxt.com/credits.txt is mostly already YAML. Parsing the contributors list (after the prelude) as YAML yields a dictionary mapping contributor names to the components they contributed. As for contributor lists, a minor change is needed to get them to parse as YAML lists.

- Ashe Connor: commonmarker, jekyll-commonmark-ghpages
+ Ashe Connor: [commonmarker, jekyll-commonmark-ghpages]

The prelude is more tricky. It seems that simply putting a " on a line on either side of it causes the yaml to be parsed as two documents, the first being the prelude as a string, and the second being a dict.

Here's creditstxt.com's credits.txt as YML (I had to use a .txt file extension because GitHub won't let me upload it otherwise.) If you want to get rid of the extra newlines that using " creates, replace the first one with | and the last one with ---.

[doriantaylor]

@kemitchell indeed I agree structured data should remain out of scope for this particular initiative, if the goal is indeed to just get people publishing this content onto the Web.

I mean, consider the stink raised around BCP 190; if this initiative was first and foremost a technical standard, it should probably start with that. (Note, I believe the current proposed location of credits.txt is just fine.)

[kemitchell]

@bmintz, I think I'd rather suggest something like:

Put each credited developer's name on its own line, followed by a colon and a list of projects they contributed to.

If anything at all.

fetch('https://licensezero.com/credits.txt')
  .then((response) => response.text())
  .then(function (text) {
    console.log(
      text
        .split('\n')
        .reduce(function (results, line) {
          var match = /^([^:]+): (.+)$/.exec(line)
          if (match) {
            return results.concat({
              name: match[1],
              projects: match[2].split(/,\s*/)
            })
          } else {
            return results
          }
        }, [])
    )
  })

Certainly if we do our job making tooling to generate credits.txt easy enough to adopt, we'll have plenty of opportunity for de facto standardization.

[kemitchell]

@doriantaylor I think we're aligned on broad purpose and strategy. This isn't a technical initiative, and technical standardization isn't the proper medium for it. Turning it into too much of a software project likely dilutes, rather than strengthens, its effectiveness.

[redbow-kimee]

Perhaps tooling to generate credits.txt (or credits.html etc) a side project for when this is more taken off.

[kemitchell]

@RedBow I've already built a tool for npm-based projects: https://www.npmjs.com/package/creditstxt

[redbow-kimee]

Neat. I might do similar for maven based projects.

[kemitchell]

@RedBow I'd love to have you and that project here in the creditstxt GitHub org!

[redbow-kimee]

yeah! absolutely!

[doriantaylor]

I've been meaning to dig out the relevant RDF vocabs to have adjacent to this project; RDF of course can produce JSON-LD, which is less frightening to the RDF-averse.