welcome

[arademaker]

I created this team to write to all administrators/owners of the organization. Do you agree? To keep everything consistent, since I am not one of the organization owners, I would need to be removed of this team or we can revise the list of owners considering that we are moving more content to here (= GitHub).

But anyway, I am working with @olzama in the moving of http://moin.delph-in.net/wiki/ to GitHub, I would like to create a new repo called doc. This will initially host all files from the MoinMoin, a new wiki, and all attached files, images... in the wiki pages. Do you all agree? Without the owners' rights, I need one of you to make it happen.

[arademaker]

I made few rewritings above to make myself clear.

[goodmami]

Thanks, @arademaker

A team for the admins is a good idea, mainly for this discussion space.

And the repository sounds good. I have a slight preference for docs instead of doc as it's a bit more standard. Do you plan to use the repository to host GitHub Pages content (so it will be visible at https://delph-in.github.io/docs), or just use the wiki?

[arademaker]

docs works for me. Initially, the plan is to organize the content in the standard wiki provided to all git repositories in GitHub. Later, the use of static pages published in the GitHub Pages can be considered.

[olzama]

(Not sure if this is the best place for this to go to?) What are we going to do about links to the moin moin wiki which are already included in dissertations and such? Would we be able to do something about them, some kind of redirect, eventually?

[goodmami]

@olzama Good point. The first step is identifying all those links. We might post to developers/discourse and request people to self-report their links, or perhaps Stephan has some site analytics that can tell us something about URL visits coming from outside the domain.

Alternatively, since the moin moin wiki URL was prefixed with moin.delph-in.net/wiki, one possible solution is to create a wiki repository (maybe instead of docs?) in the delph-in organization, then we get Stephan to agree to use a CNAME to point moin.delph-in.net to delph-in.github.io. This tells the browser that the server hosting the subdomain moin.delph-in.net is at delph-in.github.io instead of where it is currently. If you mirror the wiki structure in the wiki repository, you might not even need redirects.

[goodmami]

Also worth noting for that alternative is that those mirrored pages would need to be published with GitHub Pages and not from the repo's wiki. If you prefer to use the wiki functionality instead of having users edit repo files directly, then maybe we could make those mirrored pages contain the actual redirects, e.g., from delph-in.github.io/wiki/ErgTop (shown as moin.delph-in.net/wiki/ErgTop with the CNAME set up) to delph-in.github.io/wiki/wiki/ErgTop. The CNAME thing only works for sites published with GitHub Pages and not for the actual wiki.

The advantages of using GitHub's wiki instead of editing repo files are:

• contributors don't need to be members (we could also allow all organization members to edit repo files)
• slightly better editing interface for wikis than regular files in the browser

[guyemerson]

I think it would be confusing to use /wiki if it's not a GitHub wiki. And I think /wiki/wiki/ in a url would also be confusing.

Couldn't moin.delph-in.net/wiki/* redirect to delph-in.github.io/docs/* or delph-in.github.io/docs/wiki/* or www.github.com/delph-in/docs/wiki/*?

[goodmami]

I think it would be confusing to use /wiki if it's not a GitHub wiki. And I think /wiki/wiki/ in a url would also be confusing.

The problem is that each repository can have a wiki at github.com/user/repo/wiki, and it's not hosted by GitHub Pages so it will always display the github.com/... URL and be displayed with the GitHub site interface. The wiki repository name is just so the URLs match up, assuming we got the CNAME configured. If we don't do the CNAME thing, then I think we would just have docs/wiki/ and not wiki/wiki/.

Couldn't moin.delph-in.net/wiki/* redirect to delph-in.github.io/docs/* or delph-in.github.io/docs/wiki/* or www.github.com/delph-in/docs/wiki/*?

CNAMEs aren't exactly redirects, and they can only point to domains and subdomains, not subdirectories. But what you're asking could be done with a server-side redirect, meaning that someone would need to maintain a server hosting moin.delph-in.net and setup the, e.g., Apache2 configs with those redirects. I think the domain name registrar might also allow users to define redirects without running a server themselves, but if so it might be more limited and now allow regex-based or glob-based patterns (I haven't looked into this for a while, so I could be wrong here).

[oepen]

hi all, even though i only have limited knowledge about GitHub wikis, i suspect there will be some benefits if we continue to run as a wiki (rather than as auto-generated pages), notably in-browser edit access and visibility of the evolution of pages? regarding backwards compatibility, i will be able to redirect the old addresses to the new ones, i.e. for the next several years at least there will be a UiO-hosted web server for the 'delph-in.net' domain, where i have full control over how incoming requests for e.g. 'moin.delph-in.net' wiki pages should be processed. once there is a replacement wiki on GitHub, i would be happy to redirect there. this would also mean that fewer and fewer links will go to the old addresses over time, as the redirect would indicate to the client that these pages have permanently moved ... oe

[arademaker]

Hi all, I am happy to see the discussion here; I must confess that I was waiting for some reaction before my next steps! ;-)

But first of all, we need to consider our communication channels in addition to the infrastructure change. If we continue to use the 'teams' from GitHub, we may need to create teams to reflect the DELPH-IN organization. Are all here aware that only 7 members are reading this forum?

Regarding the wiki, I agree with @oepen, and I believe that our first and easier move is to migrate to the GitHub default wiki system inside a docs repository that I will create. I have some reasons for that:

I already have the code to make it happen. It is not perfect, but no information will be lost (we can keep the dump from MoinMoin saved in the docs repository. Some manual editions will eventually be necessary to fix format issues (e.g., tables) or decide about the restricted pages. But for 99% of the cases (e.g., links, lists, code blocks, images), I was able to obtain a good result. Images require a few manual steps (add them in the docs repo before mention than in the wiki, change the link markup, etc.), but with extra benefits (currently some pages of MoinMoin reference images in SVN repositories... it is hard to keep the sync right?)

We need to rethink the wiki, organized and clean up the content. Many pages are useless or not following the expected pattern (e.g., the meetings' pages), some contents are fundamental and, maybe, more suitable for being moved to the docs repository as a self-contained report (e.g., the Erg Semantics, the ACE documentation, etc.). All this organization can be done collaboratively before additional aggressive movement to a more costly (regarding effort and human resources) solution.

Regarding the preservation of links. Mirroring all URLs will not be 100% possible. GitHub wiki doesn't support the nesting of pages (e.g. Page/SubPage). Fortunately, this is one among many powerful MoinMoin features that few people are aware of. But if we carefully analyze the pages, we can have a more manually curated list of redirects. So I don't really believe we need an automatic solution for all pages. I also agree with @guyemerson that wiki/wiki is a confusing address. I tend to prefer doc, but I can live with docs! ;-)

I was using a private repository for testing, under my account. I have just moved it to the DELPH-IN organization and made it public (we need to apply for GitHub support to be able to have private repos in DELPH-IN). Here are two examples of pages:

https://github.com/delph-in/docs-test/wiki/FrontPage
https://github.com/delph-in/docs-test/wiki/Essence

Please DONT EDIT THIS WIKI, this is only for testing, I will delete and recreate the final docs repository.

[oepen]

https://github.com/delph-in/docs-test/wiki/FrontPage https://github.com/delph-in/docs-test/wiki/Essence

many thanks, alexandre, that is beginning to look nice! even if GitHub wikis cannot interpret hierarchical pages, does that mean that page names cannot contain slashes at all? if so, i would suggest rewriting 'ErgSemantics/Essence' to something like 'ErgSemantics ∕ Essence' (that is U+2215, so not an ASCII slash), or maybe 'ErgSemantics|Essence' if you would rather stick to ASCII symbols. that way, we avoid namespace collisions, preserve the thematic grouping (even if we lose the hierarchy), and the automatic redirects will be easy to setup. looking at that page, inline images from a remote URL are not displayed? or is there maybe some additional markup that will be required to actually show the images rather than the links? for the example you picked, the MRSs are maintained as part of each ERG release, so serving these images from SVN really is what we would want to preserve. on an aesthetic note: how about something like https://github.com/delph-in/core/wiki/ or https://github.com/delph-in/main/wiki/ as the prefix? if neither of these, my mild personal preference would also be for 'doc' rather than 'docs' :-). best wishes, oe

[goodmami]

A lot to reply to...

there will be some benefits if we continue to run as a wiki (rather than as
auto-generated pages), notably in-browser edit access and visibility of the
evolution of pages?

I'm not advocating one way or the other, but to be clear about our options, GitHub Pages can be "auto-generated" from Markdown, Mediawiki, etc., and don't require an explicit build step. That is, they can be viewed, rendered, from github.com/org/repo/..., or from the org.github.io/repo/... published site. You can set the "base role" of a repository such that all members of the delph-in org can edit the files. Repository files can be edited in the browser. So using an actual wiki instead of repository files really only gets you intra-wiki [[links]] (in regular repository files, you'd need more explicit links, absolute or relative to the current file), and little buttons on the editor so you click the "B" and it puts ** before and after the highlighted text (depending on markup flavor). The benefits of using repository files are a custom URL, nested pages, and custom styling/javascript if necessary.

Yet another alternative is to have users edit the wiki (delph-in/docs/wiki), and we setup an action to build the published site (delph-in/wiki) from it. This way we get the benefits of both, with some initial complexity to configure it. Upon building, we could insert an "edit" button that points to the appropriate delph-in/docs/wiki URL.

Are all here aware that only 7 members are reading this forum?

Yes, this is the discussion space for people administering the delph-in organization. Seems appropriate to me?

I also agree with @guyemerson that wiki/wiki is a confusing address

Sorry, that was just a bad explanation. I meant that a wiki repository could be used to recreate the old URLs if we setup a CNAME so moin.delph-in.net is served by delph-in.github.io. If we do not do that, we would redirect to the GitHub wiki pages, which would not need to be in a repo called called wiki, so docs/wiki or something. Please forget the wiki/wiki thing.

Here are two examples of pages:

Those look good! I notice the others are not converted in the same way. Was this a manual conversion or do you have script to do it?

i would suggest rewriting 'ErgSemantics/Essence' to something like
'ErgSemantics ∕ Essence' (that is U+2215, so not an ASCII slash), or
maybe 'ErgSemantics|Essence' if you would rather stick to ASCII
symbols.

I would strongly prefer something that won't be confusing if printed in a paper. Also, depending on the browser, the address bar would show the unicode character percent-encoded as ErgSemantics%E2%88%95Essence. And the pipe also needs to be escaped, resulting in ErgSemantics%7CEssence. I don't think we need to worry about name collisions, so why not join those parts with ~, -, or _, which do not need escaping?

my mild personal preference would also be for 'doc' rather than 'docs' :-)

doc is shorter and there's no s in documentation, but docs has stronger precedent, I think: docs.github.com, readthedocs.org, mkdocs.org, docs.docker.com, docs.microsoft.com, sqlite.org/docs.html, developer.mozilla.org/docs/, etc. Although there are examples of doc, too: pandoc.org, sphinx-doc.org, doc.rust-lang.org, perldoc.perl.org, asciidoc.org, etc. I'm happy either way.

@arademaker, I would remove the BadContent wiki (maybe others?) which I think was used for spam detection. Since it's no longer used that way, it just contains offensive/inappropriate text and maybe links which could get the repo flagged.

[guyemerson]

I agree it's looking good!

At this point, I'm leaning towards using the built-in wiki, because it doesn't require any additional setup to add links to edit pages and see revision history.

Apart from the ErgSemantics pages, are there other pages where nesting is important? The ErgSemantics pages aren't normal pages (e.g. I believe they had restricted edit access in the past), and I wonder if we should treat them differently. Perhaps those pages (and perhaps a few others) could be converted to a static site? In which case, we could have a division between the "normal" pages (migrated to wiki pages), and the "special" wiki pages (migrated to project files). Potentially, the static site could display both types of file in the same way. There's some added complexity in doing this, but it would mean we get wiki functionality for the normal pages, and nesting for the special pages. (As far as I understand, if we want to have different access permissions, we would need multiple repos.) I don't know if this is the right way to go, but I thought I'd raise the idea.

If we migrate the nested pages to wiki pages, I would prefer an easily human-readable character, to avoid confusion.

One criticism I have of the GitHub wiki format is the default sidebar. The alphabetic list of pages (before you even enter a search term) means that some obscure pages are immediately accessible from the homepage. I can't find any obvious way of modifying the sidebar. I suppose this is only a minor inconvenience, though.

I have mild preference for "docs". I don't read it as an abbreviation for "documentation", but rather as a word in its own right (admittedly a little more informal).

[emilymbender]

I'm not sure how deeply nested something has to be to count as nested, but there are definitely other spaces within the DELPH-IN Wiki that have characteristic prefixes in their URLS:

http://moin.delph-in.net/wiki/MatrixDocTop
http://moin.delph-in.net/wiki/GrammarEngineeringFaq

And then I think also:

http://moin.delph-in.net/wiki/WeSearch

[arademaker]

Hi @emilymbender, MoinMoin has the ability to group pages with the same prefix in a hierarchy of directories and files. Pages should follow the CamelCase convention and putting a / between page names creates this nesting of pages that we are talking about. No limits. But very few pages in the week use it.

% find . -type d | grep -v git | wc -l
      39

In your examples, all pages are single pages with names in CamelCase. But my idea was precisely to convert the hierarchy structure into a flat one just removing the / and preserving the CamelCase convention.

So instead of the pages ImplicitNominals and Terminology inside the ErgSemantics:

ErgSemantics/ImplicitNominals.rst
ErgSemantics/Terminology.rst

We can make it two pages in the root flat structure with the same prefix.

ErgSemanticsImplicitNominals.rst
ErgSemanticsTerminology.rst

In that way, we don't need any of the special characters proposed by @oepen or @goodmami.

[arademaker]

Hi @guyemerson,

At this point, I'm leaning towards using the built-in wiki, because it doesn't require any additional setup to add links to edit pages and see revision history.

Thank you. That is my main argument too.

Apart from the ErgSemantics pages, are there other pages where nesting is important? The ErgSemantics pages aren't normal pages (e.g. I believe they had restricted edit access in the past), and I wonder if we should treat them differently. Perhaps those pages (and perhaps a few others) could be converted to a static site? In which case, we could have a division between the "normal" pages (migrated to wiki pages), and the "special" wiki pages (migrated to project files). Potentially, the static site could display both types of file in the same way. There's some added complexity in doing this, but it would mean we get wiki functionality for the normal pages, and nesting for the special pages. (As far as I understand, if we want to have different access permissions, we would need multiple repos.) I don't know if this is the right way to go, but I thought I'd raise the idea.

For the permissions, we will need to manually check. I have listed them to @oepen and he mentioned that he will take a look. most of the cases are pages from projects related to him.

For the normal vs special pages, did you read my previous comment? I said

some contents are fundamental and, maybe, more suitable for being moved to the docs repository as a self-contained report (e.g., the Erg Semantics, the ACE documentation, etc.).

You are right, we can move them to a static site. I was thinking of LaTeX documents maybe. There are contents that are stable, well structured, and with a well-defined scope.

One criticism I have of the GitHub wiki format is the default sidebar. The alphabetic list of pages (before you even enter a search term) means that some obscure pages are immediately accessible from the homepage. I can't find any obvious way of modifying the sidebar. I suppose this is only a minor inconvenience, though.

Good point, I will try to investigate if we have any alternative.

I have mild preference for "docs". I don't read it as an abbreviation for "documentation", but rather as a word in its own right (admittedly a little more informal).

We have 2 votes for doc and 2 votes for docs! ;-)

[emilymbender]

Hi @arademaker -- I don't have any strong opinions. Just wanted to make sure that the nested pages that I knew about where included as the decision is being made.

[goodmami]

In your examples, all pages are single pages with names in CamelCase.

True for the GeFaq* pages, but for MatrixDocTop the subpages are, for example, http://moin.delph-in.net/wiki/MatrixDoc/GeneralInfo.

I can't find any obvious way of modifying the sidebar. I suppose this is only a minor inconvenience, though.

Good point, I will try to investigate if we have any alternative.

If you create a custom sidebar, it looks like the default one appears collapsed, although this is not documented. See, for example, https://github.com/angular/angular.js/wiki, which uses https://github.com/adriantanasa/github-wiki-sidebar/ to generate _Sidebar.md, but I don't think github-wiki-sidebar does anything special besides creating that file.

[fcbond]

We have 2 votes for doc and 2 votes for docs! ;-)

I have a mild preference for 'docs' (not sure if I already voted).

…

-- Francis Bond <http://www3.ntu.edu.sg/home/fcbond/> Division of Linguistics and Multilingual Studies Nanyang Technological University

[guyemerson]

For the normal vs special pages, did you read my previous comment? I said

some contents are fundamental and, maybe, more suitable for being moved to the docs repository as a self-contained report (e.g., the Erg Semantics, the ACE documentation, etc.).

You are right, we can move them to a static site. I was thinking of LaTeX documents maybe. There are contents that are stable, well structured, and with a well-defined scope.

@arademaker Thank you for highlighting that comment -- I think I'm losing track of the different issues! I like the criteria of being "stable, well structured, and with a well-defined scope".

[arademaker]

Hi all, sorry for the silence from my part. I hope wot finish the wiki migration until next week,