Some of the current naming conventions are misleading #875

New Issue

reinhard · 2019-04-05T12:59:47Z

reinhard commented

2019-04-05 12:59:47 +00:00

Some of the naming conventions currently used in the source files are misleading and have been a source of misunderstandings and confusion. If the current build system is still going to be used for the upcoming years, it might be worth considering the following changes:

Filename extension of HTML page source files

Currently, the files are named *.xhtml, which naturally leads to the impression that their content is XHTML. However, it isn't. I suggest renaming the files to *.page.

Top level elements of HTML page source files

The current general structure of such a file is:

<html>
  <head>
    <title>...</title>
  <head>
  <body>
    Content goes here
  </body>
  <sidebar>...</sidebar>
  <followup>...</followup>
</html>

This is misleading in a two ways:

The root element is called <html> even though the content is not plain HTML
Some elements which are outside the <body> in the source file will end up inside the <body> in the HTML output.

I propose the following new structure:

<page>
  <title>...</title>
  <content>
    Content goes here
  </content>
  <sidebar>...</sidebar>
  <followup>...</followup>
</html>

Note that I also propose to make a <title> possible without explicitly adding the <head> tag, although a <head> might remain an option for other stuff that should end up in the HTML head.

Filename extension of files with data for dynamic page content

These files currently are named *.xml, which is a bad name because the other files are also XML files.

Since they provide data which is fed into one or more HTML pages, I propose to rename them into *.feed *.data.

Root element of files with data for dynamic page content

Currently, the root element of such files is using a variety of names, like <newsset>, <eventset>, <itemset>, <personset>, and so on. This leads to the impression that there is a meaning behind these names, which actually is not the case. Also, in many cases, the files actually contain only one element as a matter of principle, so "set" is a bad word anyway.

I therefore propose to call that root element simply ~~<feed>~~ <data> in all these files.

Some of the naming conventions currently used in the source files are misleading and have been a source of misunderstandings and confusion. If the current build system is still going to be used for the upcoming years, it might be worth considering the following changes: ## Filename extension of HTML page source files Currently, the files are named *.xhtml, which naturally leads to the impression that their content is XHTML. However, it isn't. I suggest renaming the files to *.page. ## Top level elements of HTML page source files The current general structure of such a file is: ```html <html> <head> <title>...</title> <head> <body> Content goes here </body> <sidebar>...</sidebar> <followup>...</followup> </html> ``` This is misleading in a two ways: * The root element is called `<html>` even though the content is not plain HTML * Some elements which are outside the `<body>` in the source file will end up inside the `<body>` in the HTML output. I propose the following new structure: ```html <page> <title>...</title> <content> Content goes here </content> <sidebar>...</sidebar> <followup>...</followup> </html> ``` Note that I also propose to make a `<title>` possible without explicitly adding the `<head>` tag, although a `<head>` might remain an option for other stuff that should end up in the HTML head. ## Filename extension of files with data for dynamic page content These files currently are named *.xml, which is a bad name because the other files are also XML files. Since they provide data which is fed into one or more HTML pages, I propose to rename them into <strike>*.feed</strike> *.data. ## Root element of files with data for dynamic page content Currently, the root element of such files is using a variety of names, like `<newsset>`, `<eventset>`, `<itemset>`, `<personset>`, and so on. This leads to the impression that there is a meaning behind these names, which actually is not the case. Also, in many cases, the files actually contain only one element as a matter of principle, so "set" is a bad word anyway. I therefore propose to call that root element simply <strike>`<feed>`</strike> `<data>` in all these files.

max.mehl commented

2019-04-08 09:32:27 +00:00

Sounds all fine for me, except the <title>. I would still leave it inside <head> since there are more than a handful of pages which make use of extra elements like meta descriptions. Having the title outside of the head then would feel awkward for people who are proficient with HTML.

On the other hand, I see the benefit of removing this nesting, especially if there is no additional element inside head.

Sounds all fine for me, except the `<title>`. I would still leave it inside `<head>` since there are more than a handful of pages which make use of extra elements like meta descriptions. Having the title outside of the head then would feel awkward for people who are proficient with HTML. On the other hand, I see the benefit of removing this nesting, especially if there is no additional element inside head.

reinhard commented

2020-05-28 19:03:26 +00:00

As to the data files, in the long run I think we will want to remove the extra root element in many cases, so for example for a news items, <news> is directly the root element.

As to the data files, in the long run I think we will want to remove the extra root element in many cases, so for example for a news items, `<news>` is directly the root element.

Sign in to join this conversation.

No Milestone

No Assignees

2 Participants

Notifications

Due Date

The due date is invalid or out of range. Please use the format 'yyyy-mm-dd'.

No due date set.

Dependencies

No dependencies set.

Reference: FSFE/fsfe-website#875