LEDE / OpenWrt wiki merge

There are warnings implemented in the wiki which will notify users who visit a language-ns page about possibly outdated information, compared with the english original. -> native users can interact and update the specific language page.

I would have liked to show you how it looks like, however, language namespaces are currently not working at all with the openwrt theme, or more precisely: The language selector is not shown for some unknown reason. Needs some investigation.

re: zh-cn and zh-tw. My belief is that they should be kept separate. I suspect that people can read both, but they do use many different characters for the same words. (I learned this perusing a github repo that showed the same document in both scripts. Many of the characters were the same, but many were different.) So I think it would be presumptuous (if not potentially insulting) to put them together.

re: language namespaces. I too feel this is unsustainable, but I don't think there's anything we can do about it. People really get a buzz from translating a page to their language. (But it's grueling... I worked at a company that produced localized versions of the software. Each new version's translations shipped a month or more after the English version, since we sent it to our translators when the software was in late beta, and they had to get around to updating the translations which we could incorporate into the next point release.)

re: doc/docs. I have no preference as to the final name (doc vs docs). As long-term goal, I wonder if we could just redirect /doc/xxx to /docs/xxx (or vice versa) so that either name will work. BUT... to get there, we would need to merge content of pages with identical names (but using the doc or docs prefix).

re: process for merging identically-named files... What is our ability to add a small message to a large set of files? For example, it might be good to prompt a merger of those two identically-named files by including a message something like this at the top of each of the pages:

Note: As of February 2018, this page has similar content to a page from the other wiki (at [[doc:other page]]). Please review the content of both pages, merge the most up-to-date information into one of the pages, and then delete the other page. Thanks.

This would be good because:

  • It flags that there's potentially duplicate content that may provide more info
  • It tells where to find it
  • It tells you what to do to fix it, should you be so inclined
  • It immediately shows the timeliness of the info. If you encounter this notice three years from now, you will realize that the page probably doesn't contain current info.

@tmomas I added the tags requested in all package-related pages in the script, this sunday (when it is run) you should see the change.

merge doc/docs namespaces (which one to keep, doc or docs?)
which pages in doc/ are redundant (already present in docs/) and can be deleted, and which pages need to be kept/merged?

Assuming we reached the consensus on keeping the LEDE wiki structure, I'll probably keep the "docs" namespace. I don't really care of what namespace is kept, I can use "doc" if you prefer too.

I'll move around or delete the articles with redundant info myself during this weekend, then people can start fixing them up to get them more in line with the wiki guidelines.

I'll also do that myself over time in the future, but I think I'm going to be busy enough with moving around articles for this weekend.

From the mailing list it seems to be only Imre Kaloz from the old openwrt team.

http://lists.infradead.org/pipermail/lede-dev/2017-May/007342.html

When we are done on the wiki merge, I'll like to discuss this on the mailing list with him and others that actually requested the old look to see if we can get it to look more modern. I mean pretty much all the wiki "maintainers" and quite a bit of users agree on this, it should have some kind of weight.

If you decide to start that discussion, please cc me.

If you decide to make a better wiki with blackjack and hookers (movie citation) also notify me because I would like that too.

1 Like

We could simply make it user-selectable via the Loadskin plugin, so the user can choose himself how he wants to see the wiki.

Choices:

  • bootstrap3 theme (=former LEDE wiki theme)
  • OpenWrt theme
  • new OpenWrt theme (experimental; refresh of OpenWrt theme as already discussed, but not finally decided)

Downside: Two templates to maintain, possibly a bit more work adapting css for two templates, but that should be rarely necessary (apart from initial setup).

Something like this?

I imported the infoboxes from wiki.openwrt.org today and modified them to avoid usage of html by creating new WRAP classes.

See https://openwrt.org/meta/infobox/start for the overview.

  • Other infoboxes (different text) can easily be created: just create a new page with the desired infobox content and formatting
  • Other infoboxes (different icon) can also be created, but need css adaption

re: add small message to large set of files: sed is your friend :slight_smile:, so, yes - we can.

ridiculous style ... old fashioned... not negotiable ! really?

3 Likes

Bit sad if it's one person holding onto the past that's keeping the old theme alive. Time to let if free, if it's really loved then it'll come back, if it isn't then my condolences to the few who loved it.

Thanks @bobafetthotmail for moving around pages and cleaning up!

We are now faced with quite an amount of broken links, see https://openwrt.org/wiki/maintenance/wanted_pages

If we focus on the first 30 wanted pages: What would be the equivalent page in the new OpenWrt wiki?
I would then update those links via the Batch Edit plugin.

Sorry for the mess, I'm around halfway of moving stuff around and I've not had much time today to do what I wanted to.

After I've finished with that, I'll set a few mainteneance page to monitor what pages are in the right place but not visible in the main wiki yet, so people can start fixing them up and then adding the link in the index page.

I'll list the equivalent pages below. Could you make an example of how to use that plugin? I'm also an admin in the wiki so I can use it on my own too if I understand how.

doc:howto:basic.config >> docs:guide-quick-start:factory_installation

doc:howto:obtain.firmware >> downloads

about:latest >> downloads

doc:uci:network >> docs:user-guide:base-system:network:start

doc:howto:build >> docs:guide-developer:build-system:start

doc:howto:generic.overview >> docs:user-guide:start

doc:uci:firewall >> docs:user-guide:base-system:firewall_configuration

doc:howto:firstlogin >> docs:guide-quick-start:factory_installation#check_flash_result

doc:uci:wireless >> docs:user-guide:wifi:start

doc:uci:system >> docs:user-guide:base-system:system_configuration

doc:howto:obtain.firmware.generate >> docs:user-guide:additional-software:imagebuilder

about:toolchain >> docs:guide-developer:build-system:start

doc:howto:generic.debrick >> docs:user-guide:generic.debrick

doc:howto:hardware.button >> docs:user-guide:hardware:hardware.button

doc:howto:buildroot.exigence >> docs:guide-developer:build-system:install-buildsystem

doc:howto:generic.flashing >> docs:user-guide:generic.flashing

doc:howto:start >> docs:start

doc:howto:usb.essentials >> docs:user-guide:storage:usb-drives

doc:howto:generic.failsafe >> docs:user-guide:failsafe_and_factory_reset

docs:user-guide:services:http.overview >> no link for this, was an overview for all http pages, and I don't think we need this. same for most other "overview" pages after this

doc:howto:vpn.openvpn >> docs:user-guide:services:openvpnserver.setup

doc:howto:client.overview >> same as above, no article for this

doc:devel:bugs >> bugs

doc:uci:luci >> broken link also in old wiki https://wiki.openwrt.org/doc/uci/luci

doc:howtobuild:tl-mr3420.build >> obsolete build example, just removed

doc:howtobuild:build.dockstar >> same as above, not even remotely applicable to modern OpenWrt

doc:howtobuild:start >> no idea what this was supposed to be, just removed https://wiki.openwrt.org/doc/howtobuild/start

meta:template_howtobuild >> useless, removed. https://wiki.openwrt.org/meta/template_howtobuild Might be replaced with docs:guide-developer:build-system:start

I'ld also like to note that I've found quite a bit of pages with html code in them, like this https://openwrt.org/docs/user-guide/generic.flashing

Thanks for the feedback! I will start to replace the links as per your list.

You really want to do this yourself?
Well, you asked for it, but be warned, it might be no fun at all with a big number of replacements... :slight_smile:

  • Admin -> Additional Plugins -> Batch Edit
  • Namespace: Leave blank (you want to correct mistakes in the whole wiki, not restricted to a specific namespace)
  • Regular expression: e.g. /\[\[doc:start/ <- mind to escape certain characters like / etc.
  • Replacement: e.g. [[docs:start <- mind that there is no escaping necessary
  • Summary: The obvious, the change summary.
  • Click Preview -> A list with all affected pages and all the replacements is shown
  • Check each replacement and click the checkbox (that's the no-fun part). Yes, it is annoying to do that for 368 pages, but the author of this plugin doesn't want to implement a "check all" function. Too easily one can create a really big mess by inadvertend replacements...
  • After you have checked all checkboxes of the pages to which the change should be applied, Click Apply
  • Wait, may take some seconds to be done for large numbers of pages.
  • List as previous is shown, but now replacements are marked green (kind of confirmation what has been done).

The Batch Edit plugin has the advantage over wanted_pages that it shows some context.
With the context you can spot problematic replacements, e.g. links to subsections of a page, e.g. doc:howto:build#subsection. This subsection may not be present in the replcement page, therefore this page needs special handling (manual replacement or batch edit with adapted search string).

Context can also help to identify mismatches in content requested via context vs. content available in replacement page.

tl;dr
Before replacing a link, make sure the replacement link delivers the expected information.

I'm afraid, that doesn't fit.

Context of this link: "After flashing, proceed with this."

docs:guide-quick-start:factory_installation describes mainly the installation, not the basic configuration after installation (that appears only in section "Next steps", but we shouldn't link to subsections for maintenance reasons)

Yeah, it was supposed to go to the "next steps" paragraph.

Next steps can be moved to its own page (and expanded a bit maybe), then it can be linked.

Should we call it "basic.config" for the moment? This way the "wanted pages" would disappear, and should we want to rename that page afterwards, then the wiki will do the renaming of the links for us.

We should get rid of html wherever possible.
I already replaced the usage of html in the infoboxes with a CSS-only solution, but there are still several other html usages out there, which are not that easy to replace.

If you have non-html solutions for this, please let me know.

Done, then moved the article to the right place, and now the wiki is adjusting that link in all others.

I would like to ask some opinions about what to do with some articles.

There are articles containing mostly generic info about things that are kinda related but not much, and are more suited for wikipedia
For example these
https://openwrt.org/doc/hardware/cpu
https://openwrt.org/doc/hardware/mobile.wireless
https://openwrt.org/doc/hardware/ic
https://openwrt.org/doc/hardware/switch
https://openwrt.org/doc/techref/bootloader
and there are a bunch more in the Techref section.

I'm inclined to dump them as per the wiki rules (don't duplicate upstream information), but I'd like to ask your opinion first

I'm going to keep articles that have value for tinkering and modifications like GPIO, JTAG, serial ports and similar.

doc:howto:obtain.firmware >> downloads

Since you want that to have feature parity, I'll add a paragraph in downloads to link tutorials for building from source, the sdk and the imagebuilder.

about:latest >> downloads

This does fit. Only thing missing is the previous versions links. Do we even need that?

EDIT: ok, done. Now you can adjust links.

doc:uci:network >> docs:user-guide:base-system:network:start

What about the not-so-easy links? Does the replacement cover all these specific configurations (see them in the context of the page)?
[[doc:uci:network#protocol.pppoa.ppp.over.atm.aal5|PPPoA]]
[[doc:uci:network#protocol_pppoe_ppp_over_ethernet|PPPoE]]
[[doc:uci:network#protocol.dhcp|DHCP]]
[[doc:uci:network#protocol.static|Static IP]]
[[doc:uci:network#protocol.3g.ppp.over.ev-do.cdma.umts.or.grps|3G]]
[[doc:uci:network#protocol_l2tp_ppp_over_l2tp_pseudowire_tunnel]]
[[doc:uci:network#ipv4.routes|IPv4 Routes]]
[[doc:uci:network#protocol.3g.ppp.over.ev-do.cdma.umts.or.grps
[[doc:uci:network#interfaces|interface]]
[[doc:uci:network#protocol.ncm.usb.modems.using.ncm.protocol|here]]
[[doc:uci:network#protocol.6in4.ipv6-in-ipv4.tunnel|

For the detailedness of the linked sections, see e.g. https://wiki.openwrt.org/doc/uci/network#protocol_pppoe_ppp_over_ethernet

replacement for comparison: https://openwrt.org/docs:user-guide:base-system:network:start

I think that's no good replacement... :-/