Help me improve the DateFormat doc

Community Projects Documentation
,
#1

I find the docs for https://tiddlywiki.com/#DateFormat insufficient and I want to improve with a more general intro about date formats and also an explicit use example. I figure I’ll bounce it here before making a PR, so what do you say about the following modification ideas.

I want to change the initial paragraph from the current:

When used to display date values (with the format attribute set to ‘‘date’’), the ViewWidget accepts a template attribute that allows the format of the date values to be specified. The format string is processed with the following substitutions:

…into…

The created and modified fields contain a compact time format string such as 20211002153802059. Transcluding such a date field automatically applies a template for a more legible format, e.g Sat Oct 02 2021 17:40:50 GMT+0200 (Central European Summer Time).

For full control of the display format, the ViewWidget accepts a template attribute to specify a date value format. The format string is processed with the following substitutions:

[…]

IMO the doc also needs an explicit example, i.e the wikitext for it and the evaluated result. I figure this should be put at the very end of the tiddler:

<$view field=modified format=date template="DDth mmm YYYY 0hh:0mm:0ss" />

<$view field=modified format=date template=“DDth mmm YYYY 0hh:0mm:0ss” />

Thoughts?

Thanx.

#2

I think a lot of the docs, especially in the version that is indexed by Google search, really needs more explicit stuff included. This looks like a good improvement :+1:

Perhaps the other example to include is New Journal titles. I usually change it to:

[[MM DDth, YYYY]]

The docs should be something like: “The default new journal titles are XXX. You can change the date format using the template language. eg”

That way — this is immediately applicable in the very first page people touch, the Control Panel.

(On mobile, I can come back and properly format / write suggested doc changes later)

Secondly, I struggled for a long time in figuring out how to create such a time stamp. Don’t know where / how to mention that?

One more thought @twMat — you might actually format the posts here as a wiki so we can collab edit the actual text change so it can just be cut/pasted into GitHub.

#3

This. One thousand times THIS! Everywhere. For every core widget and macro.

Thanks @twMat

#4

Apropos my proposed “explicit example”; I just realized that the tiddler in question (i.e DateFormat) would be significantly easier to comprehend if the explicit example is put before the big table rather than at the end of the tiddler. This gives the reader a clear mental image to which the succeeding date formats are applied. And the very last “Examples” section is kept purely as examples of “date formats” and not the context in which they’re used.

@boris - IMO, information about how to modify “New Journal” dates should probably be part of a more introductory doc tiddler on how to set up ones TW and make changes to the “Basics” section in the Ctrlpanel. And such a tiddler should link to the DateFormat tiddler for further info about specific formats. Maybe there should also be a doc “How to work with Journals” or some such where it would make sense to detail how to change date formats.

Secondly, I struggled for a long time in figuring out how to create such a time stamp. Don’t know where / how to mention that?

You mean to set a field with a time? In some certain format? Or what do you mean? Regardless; I think the best approach for docs is the question “If a user has this problem, what will they type into the search box” and I’m not sure the discussed doc tiddler is the right one - but I do think there should be a “See also” section in the DateFormat tiddler where it should be mentioned.

One more thought @twMat — you might actually format the posts here as a wiki so we can collab edit the actual text change so it can just be cut/pasted into GitHub.

Whoa! Is that a feature in this forum software? I’ve wanted that feature forever. How would I do that for a new topic? I can’t see any “button” or similar to make a new post editable for others.

Thanx

#5

Note that the DateFormat templates are used elsewhere as well and not just by the ViewWidget:

https://tiddlywiki.com/prerelease/#format%20Operator

#6

Hey @twMat — I upgraded your user account. You now have a wrench icon under posts so that you can “make wiki”.

1 Like
#7

Here is an updated version of my OP. Please come with input. Among other things, I’m attempting to take @saqimtiaz comment into consideration.

The idea is now to only replace the text above the big table into:

The default date format is typically a compact string such as 20211002153802059. For example, the created and modified fields are stored in this format.

The display format for this string can be controlled with a template. For example, transcluding the modified field automatically applies a template to display the date as Sat Oct 02 2021 17:40:50 GMT+0200 (Central European Summer Time). A few widgets and operators allow you to manually specify a template, for example the ViewWidget:

<$view field=modified format=date template=“DDth mmm YYYY 0hh:0mm:0ss” />

The date string is processed with the following substitutions:

[table]

#8

Is it OK if I make a PR from this? It looks ready to go.

#9

The word “format” is used in two different sense in these paragraphs. Perhaps it’s clearer to reserve the word “format” only when referring to date format strings, and rephrase the first paragraph as “The default representation of dates is a compact string…”.

#10

Good point.

1 Like