Command `metanorma new`

[ronaldtse]

We need a command to generate a new skeleton for a new Metanorma document.

This is similar to the bundle gem and rails new commands. We want to generate a new Metanorma document skeleton, perhaps we can use git to download the skeleton (or include it in the gem).

The files that are necessary are:

• Gemfile
• index.adoc
• .travis.yml
• .github-ci.yml
• metanorma.env (the contents now go inside the metanorma file)
• Makefile (contents should go into metanorma-cli gem)
• sections/{nn}-{title}.adoc
• deploy.sh (contents should go into metanorma-cli gem)

and?

[ronaldtse]

ping @opoudjis @strogonoff

[strogonoff]

This would be awesome and simplify the quickstart a lot.

The exact templates to be used for generation could be provided by specific gems (e.g. Metanorma-ISO); Metanorma-CLI can depend on them and complain if e.g. you try to metanorma new --class iso without having metanorma-iso installed, although it’s not up to me how it’s done better.

Alternatives: metanorma init

IMO metanorma build is not the best as it hints at rendering final documents.

[opoudjis]

No, I have no idea what you're asking for, and I don't see the point of it.

• sections/{nn}-{title}.adoc? Absolutely not. This splitting up of a single document into 15 little pieces is something I have always found counterproductive (I have to go looking for content in 15 files), and if there is no content already in the document, I have no idea how many pieces to split it in. Forcing this way of working on everyone is wrong.
• .travis.yml, .github-ci.yml: why? Why are you presupposing this is going to become a github repository? And what is travis meant to do with it, other than compile it?
• deploy.sh: What workflow are you presupposing for deployment? Such a script would not be useful outside of the environment it has been developed for.
• metanorma.env: I have no idea what would go in here.

In fact, the only thing I see here being of any generalisable use is the index.doc skeleton. And we already have several of those.

[strogonoff]

Not my idea but I still like it.

I agree that Github/Travis stuff could only prompt more confusion for some users, deploy.sh is hard to generalize, and I have no comment about Metanorma project file layout.

What do you think of just bundling just the Makefile / Gemfile / index.adoc as an easy installable skeleton @opoudjis?

And we already have several of those.

Let’s say I’m an ISO author, how do I use one now? Sorry if it’s a silly/straightforward question

[opoudjis]

Grab an existing document, like the Rice document, and replace its contents. This doesn't deserve any more work than that.

I've assigned myself this task, but I'm assigning it back to you and Ronald, because I know nothing about the workflow that it presupposes, and there is not enough here for me to work on otherwise.

[strogonoff]

The skeleton model makes sense overall. I believe that’s the way create-react-app worked originally, for example. (That said I just discovered that in latest versions they seem to have switched to a model where the user runs a “create” command to create app skeleton.)

[ronaldtse]

@strogonoff and that's why we prefer a "metanorma create" command 👍

[ronaldtse]

I do agree now with @opoudjis that we don't want to split the sections. But the rest of the files are useful.

[ronaldtse]

So:

metanorma new -t iso my-doc-name
# => new directory `my-doc-name/` gets created with ISO document template

metanorma new -t iso my-doc-name --split-sections
# => new directory `my-doc-name/` gets created with ISO document template with split sections

The template will be downloaded from a place like:

• https://github.com/metanorma/metanorma-templates-{flavor}/{document-type}

(OGC already keeps separate templates for different document types)

[ronaldtse]

(@opoudjis NIST has requested to provide split sections in a template 😉 )

[opoudjis]

I find this predilection for split sections bizarre: given how pervasive cross-referencing is, having to skip between documents during authoring seems to me utterly counterproductive. But there's no accounting for taste. :-)

[ronaldtse]

It’s a matter of the text editor. If you find changing tabs better than scrolling, split files is easier (to me). If you like scrolling, a single file is easier.

I generally use editors that have good tab support, so I prefer split files (unless the document is short).

[ronaldtse]

And this is the related OGC task: https://github.com/metanorma/metanorma-ogc/issues/23

[abunashir]

@ronaldtse: Let me try to summarize what do we need for this, I'm taking iso as an example.

• The metanorma new -t iso doc-name will create a new doc-name document
• This doc-name will contains the minimum of a Gemfile, index.adoc in the project

Question:

• What are the gems that we should add in the Gemfile for iso project?
• Do we have any example document/repo with this similar structure?

cc: @opoudjis

[ronaldtse]

@abunashir going to push the templates in a few minutes 😉

It will be at https://github.com/metanorma/mn-templates-csd/

[ronaldtse]

@abunashir just for the record.

We will start off the first iteration by creating a separate script called metanorma-new in exe/.

The CSD template repository of https://github.com/metanorma/mn-templates-csd is already done (mostly) and up.

The command is metanorma-new -t {type} -d {doctype} [my-new-document-name]

• doc-type does not need validation, as long as the remote git repo has that directory it is fine.

In the future:

1. The command (in the future) can use a git template repo.
2. Users can use their own git template repo

[ronaldtse]

This is being done in #35

[ronaldtse]

35 is done and merged (pending #45). Closing this now.